From 4aa1fb2b8caf7f6c376492ce5ed5d12d10cf4848 Mon Sep 17 00:00:00 2001 From: quildtide <42811940+quildtide@users.noreply.github.com> Date: Fri, 9 Apr 2021 14:18:09 -0400 Subject: [PATCH] Improve flow of documentation for non-standard strings (#40057) --- doc/src/manual/metaprogramming.md | 35 +++++++++++++++++-------------- doc/src/manual/strings.md | 15 +++++++------ 2 files changed, 28 insertions(+), 22 deletions(-) diff --git a/doc/src/manual/metaprogramming.md b/doc/src/manual/metaprogramming.md index 9880bf4417867f..fe9604183bcaf7 100644 --- a/doc/src/manual/metaprogramming.md +++ b/doc/src/manual/metaprogramming.md @@ -981,13 +981,13 @@ block: end ``` -## Non-Standard String Literals +## [Non-Standard String Literals](@id meta-non-standard-string-literals) Recall from [Strings](@ref non-standard-string-literals) that string literals prefixed by an identifier are called non-standard string literals, and can have different semantics than un-prefixed string literals. For example: - * `r"^\s*(?:#|$)"` produces a regular expression object rather than a string - * `b"DATA\xff\u2200"` is a byte array literal for `[68,65,84,65,255,226,136,128]`. + * `r"^\s*(?:#|$)"` produces a [regular expression object](@ref man-regex-literals) rather than a string + * `b"DATA\xff\u2200"` is a [byte array literal](@ref man-byte-array-literals) for `[68,65,84,65,255,226,136,128]`. Perhaps surprisingly, these behaviors are not hard-coded into the Julia parser or compiler. Instead, they are custom behaviors provided by a general mechanism that anyone can use: prefixed string @@ -1051,20 +1051,9 @@ constructed on each iteration. In the vast majority of use cases, however, regul are not constructed based on run-time data. In this majority of cases, the ability to write regular expressions as compile-time values is invaluable. -Like non-standard string literals, non-standard command literals exist using a prefixed variant -of the command literal syntax. The command literal ```custom`literal` ``` is parsed as `@custom_cmd "literal"`. -Julia itself does not contain any non-standard command literals, but packages can make use of -this syntax. Aside from the different syntax and the `_cmd` suffix instead of the `_str` suffix, -non-standard command literals behave exactly like non-standard string literals. - -In the event that two modules provide non-standard string or command literals with the same name, -it is possible to qualify the string or command literal with a module name. For instance, if both -`Foo` and `Bar` provide non-standard string literal `@x_str`, then one can write `Foo.x"literal"` -or `Bar.x"literal"` to disambiguate between the two. - The mechanism for user-defined string literals is deeply, profoundly powerful. Not only are Julia's -non-standard literals implemented using it, but also the command literal syntax (``` `echo "Hello, $person"` ```) -is implemented with the following innocuous-looking macro: +non-standard literals implemented using it, but the command literal syntax (``` `echo "Hello, $person"` ```) +is also implemented using the following innocuous-looking macro: ```julia macro cmd(str) @@ -1077,6 +1066,20 @@ but they are just functions, written entirely in Julia. You can read their sourc what they do -- and all they do is construct expression objects to be inserted into your program's syntax tree. +Like string literals, command literals can also be prefixed by an identifier +to form what are called non-standard command literals. These command literals are parsed +as calls to specially-named macros. For example, the syntax ```custom`literal` ``` is parsed +as `@custom_cmd "literal"`. +Julia itself does not contain any non-standard command literals, but packages can make use of +this syntax. Aside from the different syntax and the `_cmd` suffix instead of the `_str` suffix, +non-standard command literals behave exactly like non-standard string literals. + +In the event that two modules provide non-standard string or command literals with the same name, +it is possible to qualify the string or command literal with a module name. For instance, if both +`Foo` and `Bar` provide non-standard string literal `@x_str`, then one can write `Foo.x"literal"` +or `Bar.x"literal"` to disambiguate between the two. + + Another way to define a macro would be like this: ```julia diff --git a/doc/src/manual/strings.md b/doc/src/manual/strings.md index f65a5526a85518..743ce3caa3c0d5 100644 --- a/doc/src/manual/strings.md +++ b/doc/src/manual/strings.md @@ -739,13 +739,16 @@ Some other useful functions include: There are situations when you want to construct a string or use string semantics, but the behavior of the standard string construct is not quite what is needed. For these kinds of situations, Julia -provides [non-standard string literals](@ref). A non-standard string literal looks like a regular -double-quoted string literal, but is immediately prefixed by an identifier, and doesn't behave -quite like a normal string literal. Regular expressions, byte array literals and version number -literals, as described below, are some examples of non-standard string literals. Other examples -are given in the [Metaprogramming](@ref) section. +provides non-standard string literals. A non-standard string literal looks like a regular +double-quoted string literal, +but is immediately prefixed by an identifier, and may behave differently from a normal string literal. -## Regular Expressions +[Regular expressions](@ref man-regex-literals), [byte array literals](@ref man-byte-array-literals), +and [version number literals](@ref man-version-number-literals), as described below, +are some examples of non-standard string literals. Users and packages may also define new non-standard string literals. +Further documentation is given in the [Metaprogramming](@ref meta-non-standard-string-literals) section. + +## [Regular Expressions](@id man-regex-literals) Julia has Perl-compatible regular expressions (regexes), as provided by the [PCRE](http://www.pcre.org/) library (a description of the syntax can be found [here](http://www.pcre.org/current/doc/html/pcre2syntax.html)). Regular expressions are related to strings in two ways: the obvious connection is that