From 0209beaca6880eba18eaf15591ff7f8d02b0d208 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 6 Dec 2021 16:26:28 -0600 Subject: Enhanced RDoc for literals.rdoc (#5213) Makes link targets among percent literals. Adds links to those targets. Adds examples to percent literals. Links from opening summary list to corresponding sections. --- doc/syntax/literals.rdoc | 154 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 118 insertions(+), 36 deletions(-) diff --git a/doc/syntax/literals.rdoc b/doc/syntax/literals.rdoc index 45d3d90c58..66e17fd503 100644 --- a/doc/syntax/literals.rdoc +++ b/doc/syntax/literals.rdoc @@ -2,15 +2,31 @@ Literals create objects you can use in your program. Literals include: -* Booleans and nil -* Numbers -* Strings -* Symbols -* Arrays -* Hashes -* Ranges -* Regexps -* Lambda Procs +* {Boolean and Nil Literals}[#label-Boolean+and+Nil+Literals] +* {Number Literals}[#label-Number+Literals] + + * {Integer Literals}[#label-Integer+Literals] + * {Float Literals}[#label-Float+Literals] + * {Rational Literals}[#label-Rational+Literals] + * {Complex Literals}[#label-Complex+Literals] + +* {String Literals}[#label-String+Literals] +* {Here Document Literals}[#label-Here+Document+Literals] +* {Symbol Literals}[#label-Symbol+Literals] +* {Array Literals}[#label-Array+Literals] +* {Hash Literals}[#label-Hash+Literals] +* {Range Literals}[#label-Range+Literals] +* {Regexp Literals}[#label-Regexp+Literals] +* {Lambda Proc Literals}[#label-Lambda+Proc+Literals] +* {Percent Literals}[#label-Percent+Literals] + + * {%q: Non-Interpolable String Literals}[#label-25q-3A+Non-Interpolable+String+Literals] + * {% and %Q: Interpolable String Literals}[#label-25+and+-25Q-3A+Interpolable+String+Literals] + * {%w and %W: String-Array Literals}[#label-25w+and+-25W-3A+String-Array+Literals] + * {%i and %I: Symbol-Array Literals}[#label-25i+and+-25I-3A+Symbol-Array+Literals] + * {%r: Regexp Literals}[#label-25r-3A+Regexp+Literals] + * {%s: Symbol Literals}[#label-25s-3A+Symbol+Literals] + * {%x: Backtick Literals}[#label-25x-3A+Backtick+Literals] == Boolean and Nil Literals @@ -20,7 +36,7 @@ Literals create objects you can use in your program. Literals include: +true+ is a true value. All objects except +nil+ and +false+ evaluate to a true value in conditional expressions. -== Numbers +== Number Literals === \Integer Literals @@ -162,15 +178,6 @@ In addition to disabling interpolation, single-quoted strings also disable all escape sequences except for the single-quote (\') and backslash (\\\\). -You may also create strings using %: - - %(1 + 1 is #{1 + 1}) #=> "1 + 1 is 2" - -There are two different types of % strings %q(...) behaves -like a single-quote string (no interpolation or character escaping), while -%Q behaves as a double-quote string. See Percent Strings below for -more discussion of the syntax of percent strings. - Adjacent string literals are automatically concatenated by the interpreter: "con" "cat" "en" "at" "ion" #=> "concatenation" @@ -200,6 +207,11 @@ a single codepoint in the script encoding: ?\C-\M-a #=> "\x81", same as above ?あ #=> "あ" +See also: + +* {%q: Non-Interpolable String Literals}[#label-25q-3A+Non-Interpolable+String+Literals] +* {% and %Q: Interpolable String Literals}[#label-25+and+-25Q-3A+Interpolable+String+Literals] + === Here Document Literals If you are writing a large block of text you may use a "here document" or @@ -299,6 +311,11 @@ Like strings, a single-quote may be used to disable interpolation: When creating a Hash, there is a special syntax for referencing a Symbol as well. +See also: + +* {%s: Symbol Literals}[#label-25s-3A+Symbol+Literals] + + == \Array Literals An array is created using the objects between [ and ]: @@ -310,6 +327,11 @@ You may place expressions inside the array: [1, 1 + 1, 1 + 2] [1, [1 + 1, [1 + 2]]] +See also: + +* {%w and %W: String-Array Literals}[#label-25w+and+-25W-3A+String-Array+Literals] +* {%i and %I: Symbol-Array Literals}[#label-25i+and+-25I-3A+Symbol-Array+Literals] + See Array for the methods you may use with an array. == \Hash Literals @@ -365,6 +387,10 @@ Interpolation may be used inside regular expressions along with escaped characters. Note that a regular expression may require additional escaped characters than a string. +See also: + +* {%r: Regexp Literals}[#label-25r-3A+Regexp+Literals] + See Regexp for a description of the syntax of regular expressions. == Lambda Proc Literals @@ -383,25 +409,81 @@ This proc will add one to its argument. == Percent Literals -Besides %(...) which creates a String, the % may create -other types of object. As with strings, an uppercase letter allows -interpolation and escaped characters while a lowercase letter disables them. +Each of the literals in described in this section +may use these paired delimiters: + +* [ and ]. +* ( and ). +* { and }. +* < and >. +* Any other character, as both beginning and ending delimiters. + +These are demonstrated in the next section. + +=== %q: Non-Interpolable String Literals + +You can write a non-interpolable string with %q. +The created string is the same as if you created it with single quotes: + + %[foo bar baz] # => "foo bar baz" # Using []. + %(foo bar baz) # => "foo bar baz" # Using (). + %{foo bar baz} # => "foo bar baz" # Using {}. + % # => "foo bar baz" # Using <>. + %|foo bar baz| # => "foo bar baz" # Using two |. + %:foo bar baz: # => "foo bar baz" # Using two :. + %q(1 + 1 is #{1 + 1}) # => "1 + 1 is \#{1 + 1}" # No interpolation. + +=== % and %Q: Interpolable String Literals + +You can write an interpolable string with %Q +or with its alias %: + + %[foo bar baz] # => "foo bar baz" + %(1 + 1 is #{1 + 1}) # => "1 + 1 is 2" # Interpolation. + +=== %w and %W: String-Array Literals + +You can write an array of strings with %w (non-interpolable) +or %W (interpolable): + + %w[foo bar baz] # => ["foo", "bar", "baz"] + %w[1 % *] # => ["1", "%", "*"] + # Use backslash to embed spaces in the strings. + %w[foo\ bar baz\ bat] # => ["foo bar", "baz bat"] + %w(#{1 + 1}) # => ["\#{1", "+", "1}"] + %W(#{1 + 1}) # => ["2"] + +=== %i and %I: Symbol-Array Literals + +You can write an array of symbols with %i (non-interpolable) +or %I (interpolable): + + %i[foo bar baz] # => [:foo, :bar, :baz] + %i[1 % *] # => [:"1", :%, :*] + # Use backslash to embed spaces in the symbols. + %i[foo\ bar baz\ bat] # => [:"foo bar", :"baz bat"] + %i(#{1 + 1}) # => [:"\#{1", :+, :"1}"] + %I(#{1 + 1}) # => [:"2"] + +=== %s: Symbol Literals + +You can write a symbol with %s: + + %s[foo] # => :foo + %s[foo bar] # => :"foo bar" + +=== %r: Regexp Literals + +You can write a regular expression with %r: -These are the types of percent literals: + r = %r[foo\sbar] # => /foo\sbar/ + 'foo bar'.match(r) # => # + r = %r[foo\sbar]i # => /foo\sbar/i + 'FOO BAR'.match(r) # => # -%i :: Array of Symbols -%q :: String -%r :: Regular Expression -%s :: Symbol -%w :: Array of Strings -%x :: Backtick (capture subshell result) -For the two array forms of percent string, if you wish to include a space in -one of the array entries you must escape it with a "\\" character: +=== %x: Backtick Literals - %w[one one-hundred\ one] - #=> ["one", "one-hundred one"] +You can write and execute a shell command with %x: -If you are using "(", "[", "{", "<" you must close it with ")", "]", "}", ">" -respectively. You may use most other non-alphanumeric characters for percent -string delimiters such as "%", "|", "^", etc. + %x(echo 1) # => "1\n" -- cgit v1.2.3