diff --git a/doc/Introduction.md b/doc/Introduction.md index acb5282a..a87e77c3 100644 --- a/doc/Introduction.md +++ b/doc/Introduction.md @@ -76,8 +76,11 @@ Janet supports several varieties of types that can be used as labels for things your program. The most useful type for this purpose is the keyword type. A keyword begins with a semicolon, and then contains 0 or more alphanumeric or a few other common characters. For example, `:hello`, `:my-name`, `::`, and `:ABC123_-*&^%$` are all keywords. -Keywords are actually just special cases of symbols, which are similar but don't start with -a semicolon. The difference between symbols and keywords is that keywords evaluate to themselves, while + +Keywords, symbols, and strings all behave similarly and can be used as keys for tables and structs. +Symbols and keywords are optimized for fast equality checks, so are preferred for table keys. + +The difference between symbols and keywords is that keywords evaluate to themselves, while symbols evaluate to whatever they are bound to. To have a symbol evaluate to itself, it must be quoted. diff --git a/doc/Parser.md b/doc/Parser.md index f372b4e7..d55eeb12 100644 --- a/doc/Parser.md +++ b/doc/Parser.md @@ -31,7 +31,7 @@ false ## Symbols Janet symbols are represented a sequence of alphanumeric characters -not starting with a digit. They can also contain the characters +not starting with a digit or a colon. They can also contain the characters \!, @, $, \%, \^, \&, \*, -, \_, +, =, \|, \~, :, \<, \>, ., \?, \\, /, as well as any Unicode codepoint not in the ascii range. @@ -54,7 +54,7 @@ my-module/my-fuction ## Keywords -Janet keywords are really just symbols that begin with the character :. However, they +Janet keywords are like symbols that begin with the character :. However, they are used differently and treated by the compiler as a constant rather than a name for something. Keywords are used mostly for keys in tables and structs, or pieces of syntax in macros.