From 90431fcf6cc2554ad49dbc864ac59877a36e1091 Mon Sep 17 00:00:00 2001 From: Dave Liepmann Date: Sat, 29 Apr 2023 10:16:38 +0200 Subject: [PATCH] Weird characters: add names The "weird characters"/"Reading Clojure Characters" page's goal is to improve findability. Adding English names for these special characters makes it easier to search within a page as well as to use search engines (which can make it difficult to search with special characters). Referring to these characters by name is also helpful for Clojure users for whom English is not their native language. --- content/guides/weird_characters.adoc | 67 ++++++++++++++-------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/content/guides/weird_characters.adoc b/content/guides/weird_characters.adoc index 2aabf5fa..f56ea4a4 100644 --- a/content/guides/weird_characters.adoc +++ b/content/guides/weird_characters.adoc @@ -19,7 +19,7 @@ original https://yobriefca.se/blog/2014/05/19/the-weird-and-wonderful-characters [[lists]] == `( ... )` - List -Lists are sequential heterogeneous collections implemented as a linked list. +Parentheses are used for lists. Lists are sequential heterogeneous collections implemented as a linked list. * <> @@ -33,7 +33,7 @@ A list of three values: [[vectors]] == `[ ... ]` - Vector -Vectors are sequential, indexed, heterogeneous collections. Indexing is 0-based. +Square brackets indicate a vector. Vectors are sequential, indexed, heterogeneous collections. Indexing is 0-based. An example of retrieving the value at index 1 in a vector of three values: @@ -48,7 +48,7 @@ user=> (get ["a" 13.7 :foo] 1) [[maps]] == `{ ... }` - Map -Maps are heterogeneous collections specified with alternating keys and values: +Curly braces form a map. Maps are heterogeneous collections specified with alternating keys and values: [source,clojure] ---- @@ -61,7 +61,7 @@ user=> (keys {:a 1 :b 2}) [[dispatch]] == `#` - Dispatch character -You'll see this character beside another e.g. `\#(` or `#"`. +The number sign (aka "octothorpe" or "hash") is used in several ways. You'll see this character beside another e.g. `\#(` or `#"`. `#` is a special character that tells the Clojure reader (the component that takes Clojure source and "reads" it as Clojure data) how to interpret the next character using a _read table_. Although some Lisps allow the read table to be extended by users, Clojure <>. @@ -72,7 +72,7 @@ The `#` is also used at the _end_ of a symbol when creating <> for additional details. -`#{...}` defines a set (a collection of unique values), specifically a `hash-set`. The +A pair of curly braces prefixed with a number sign `#{...}` defines a set (a collection of unique values), specifically a `hash-set`. The following are equivalent: [source,clojure] @@ -98,7 +98,7 @@ Duplicate key: 1 See <> for additional details. -`#_` tells the reader to ignore the next form completely. +A number sign before an underscore `#_` tells the reader to ignore the next form completely. [source,clojure] ---- @@ -131,7 +131,7 @@ This can prove useful for debugging situations or for multiline comments. See <> for additional details. -`#"` indicates the start of a regular expression +A number sign before a double quotation mark `#"` indicates the start of a regular expression: [source,clojure] ---- @@ -150,8 +150,8 @@ Java string escaping is not required See <> for additional details. -`#(` begins the short hand syntax for an inline function definition. The -following two snippets of code are similar: +A number sign before an open-parenthesis `#(` begins the short hand syntax for +an inline function definition. The following two snippets of code are similar: [source,clojure] ---- @@ -174,7 +174,8 @@ user=> (macroexpand `#(println %)) == `#'` - Var quote -`#'` is the var quote which expands into a call to the `var` function: +A number sign before a single quotation mark `#'` is the var quote, which +expands into a call to the `var` function: [source,clojure] ---- @@ -241,7 +242,7 @@ Note that while `#inst` and `#uuid` are available in edn, `#js` is not. == `%`, `%n`, `%&` - Anonymous function arguments -`%` is an argument in an anonymous function `pass:[#(...)]` as in `#(* % %)`. +The percent sign `%` is an argument in an anonymous function `pass:[#(...)]` as in `#(* % %)`. When an anonymous function is expanded, it becomes an `fn` form and `%` args are replaced with gensym'ed names (here we use arg1, etc for readability): @@ -293,7 +294,7 @@ Anonymous functions and `%` are not part of edn. == `@` - Deref -`@` expands into a call to the `deref` function, so these two forms +The at sign `@` expands into a call to the `deref` function, so these two forms are the same: [source,clojure] ---- @@ -314,10 +315,10 @@ Note that `@` is not available in edn. == `^` (and `#^`) - Metadata -`^` is the metadata marker. Metadata is a map of values (with shorthand option) -that can be attached to various forms in Clojure. This provides extra information -for these forms and can be used for documentation, compilation warnings, -typehints, and other features. +The caret `^` is the metadata marker. Metadata is a map of values (with +shorthand option) that can be attached to various forms in Clojure. This +provides extra information for these forms and can be used for documentation, +compilation warnings, typehints, and other features. [source,clojure] ---- user=> (def ^{:debug true} five 5) ; meta map with single boolean value @@ -372,7 +373,7 @@ Note that metadata is available in edn, but type hints are not. == `'` - Quote -Quoting is used to indicate that the next form should be read but not evaluated. +The single quotation mark is used to indicate that the next form should be read but not evaluated. The reader expands `'` into a call to the `quote` special form. [source,clojure] @@ -394,7 +395,7 @@ user=> == `;` - Comment -`;` starts a line comment and ignores all input from its starting point to the end of the +A semicolon `;` starts a line comment and ignores all input from its starting point to the end of the line. [source,clojure] ---- @@ -416,7 +417,7 @@ but these are all the same to Clojure == `:` - Keyword -`:` is the indicator for a keyword. Keywords are often used as keys in maps and +A leading colon `:` is the indicator for a keyword. Keywords are often used as keys in maps and they provide faster comparisons and lower memory overhead than strings (because instances are cached and reused). [source,clojure] @@ -450,7 +451,7 @@ user => (get my-map :three 3) ; same as above, but using get [[autoresolved_keys]] == `::` - Auto-resolved keyword -`::` is used to auto-resolve a keyword in the current namespace. If no qualifier +Double colon `::` is used to auto-resolve a keyword in the current namespace. If no qualifier is specified, it will auto-resolve to the current namespace. If a qualifier is specified, it may use aliases in the current namespace: [source,clojure] @@ -543,7 +544,7 @@ is read the same as: == `/` - Namespace separator -`/` can be the division function `clojure.core//`, but can also act as a +A slash `/` can be the division function `clojure.core//`, but can also act as a separator in a symbol name to separate a symbol's name and namespace qualifier, e.g. `my-namespace/utils`. Namespace qualifiers can thus prevent naming collisions for simple names. @@ -551,7 +552,7 @@ for simple names. == `\` - Character literal -`\` indicates a literal character as in: +Backslash `\` indicates a literal character as in: [source,clojure] ---- @@ -568,7 +569,7 @@ The `\` can also be followed by a Unicode literal of the form `\uNNNN`. For exam == `$` - Inner class reference -Used to reference inner classes and interfaces in Java. Separates the +The dollar sign is used to reference inner classes and interfaces in Java. It separates the container class name and the inner class name. [source,clojure] ---- @@ -595,7 +596,7 @@ These are threading macros. Please refer to <> and <> for additional information. -`~` is unquote. Syntax quote, like quote, means that evaluation is not occurring within the syntax quoted form. +Tilde `~` is unquote. Syntax quote, like quote, means that evaluation is not occurring within the syntax quoted form. Unquoting turns off quoting and evaluates an expression inside the syntax quoted expression. [source,clojure] @@ -679,7 +680,7 @@ Syntax quoting and unquote are essential tools for writing macros, which are fun See <> and <> for additional information. -`~@` is unquote-splicing. Where unquote <> +Tilde followed by at sign `~@` is unquote-splicing. Where unquote <> evaluates a form and places the result into the quoted result, `~@` expects the evaluated value to be a collection and splices the _contents_ of that collection into the quoted result. @@ -702,7 +703,7 @@ Again, this is a powerful tool for writing macros. [[gensym]] == `#` - Gensym -A `#` _at the end_ of a symbol is used to automatically generate a new symbol. +A number sign `#` _at the end_ of a symbol is used to automatically generate a new symbol. This is useful inside macros to keep macro specifics from leaking into the userspace. A regular `let` will fail in a macro definition: @@ -753,7 +754,7 @@ user=> (macroexpand '(m)) Reader conditionals are designed to allow different dialects of Clojure to share common code. The reader conditional behaves similarly to a traditional -`cond`. The syntax for usage is `#?` and looks like this: +`cond`. The syntax for usage is a number sign followed by question mark `#?` and looks like this: [source,clojure] ---- @@ -767,7 +768,7 @@ to share common code. The reader conditional behaves similarly to a traditional == `#?@` - Splicing Reader conditional -The syntax for a splicing reader conditional is `#?@`. It is used to splice +The syntax for a splicing reader conditional is number sign, question mark, at sign `#?@`. It is used to splice lists into the containing form. So the Clojure reader would read this: [source,clojure] ---- @@ -785,7 +786,7 @@ as this: == `\*var-name*` - "Earmuffs" -Earmuffs (a pair of asterisk bookending var names) is a naming convention in +Earmuffs (a pair of asterisks bookending var names) is a naming convention in many LISPs used to denote _special vars_. Most commonly in Clojure this is used to denote _dynamic_ vars, i.e. ones that can change depending on dynamic scope. The earmuffs act as a warning that "here be dragons" @@ -800,7 +801,7 @@ and out streams for Clojure. == `>!!`, `!`, and `?` - Predicate Suffix -Putting `?` at the end of a symbol is a naming convention common across +Putting question mark `?` at the end of a symbol is a naming convention common across many languages that support special characters in their symbol names. It is used to indicate that the thing is a predicate, i.e. that it _poses a question_. For example, imagine using an API that dealt with buffer manipulation: @@ -922,7 +923,7 @@ last argument - the new value of the atom so we use `_` for the others. == `,` - Whitespace character -In Clojure, `,` is treated as whitespace, exactly the same as spaces, tabs, or newlines. +In Clojure, comma `,` is treated as whitespace, exactly the same as spaces, tabs, or newlines. Commas are thus never required in literal collections, but are often used to enhance readability: