diff --git a/doc/syntax/literals.rdoc b/doc/syntax/literals.rdoc index 0d581a5787..6d681419a2 100644 --- a/doc/syntax/literals.rdoc +++ b/doc/syntax/literals.rdoc @@ -138,19 +138,18 @@ Also \Rational numbers may be imaginary numbers. == Strings -=== \String Literals +=== Escape Sequences -The most common way of writing strings is using ": +Some characters can be represented as escape sequences in +double-quoted strings, +character literals, +here document literals (non-quoted, double-quoted, and with backticks), +double-quoted symbols, +double-quoted symbol keys in Hash literals, +Regexp literals, and +several percent literals (%, %Q, %W, %I, %r, %x). - "This is a string." - -The string may be many lines long. - -Any internal " must be escaped: - - "This string has a quote: \". As you can see, it is escaped" - -Double-quote strings allow escaped characters such as \n for +They allow escape sequences such as \n for newline, \t for tab, etc. The full list of supported escape sequences are as follows: @@ -174,11 +173,31 @@ sequences are as follows: \M-\cx same as above \c\M-x same as above \c? or \C-? delete, ASCII 7Fh (DEL) + \ continuation line (empty string) -Any other character following a backslash is interpreted as the +The last one, \, represents an empty string instead of a character. +It is used to fold a line in a string. + +=== Double-quoted \String Literals + +The most common way of writing strings is using ": + + "This is a string." + +The string may be many lines long. + +Any internal " must be escaped: + + "This string has a quote: \". As you can see, it is escaped" + +Double-quoted strings allow escape sequences described in +{Escape Sequences}[#label-Escape+Sequences]. + +In a double-quoted string, +any other character following a backslash is interpreted as the character itself. -Double-quote strings allow interpolation of other values using +Double-quoted strings allow interpolation of other values using #{...}: "One plus one is two: #{1 + 1}" @@ -190,8 +209,14 @@ You can also use #@foo, #@@foo and #$foo as a shorthand for, respectively, #{ @foo }, #{ @@foo } and #{ $foo }. +See also: + +* {% and %Q: Interpolable String Literals}[#label-25+and+-25Q-3A+Interpolable+String+Literals] + +=== Single-quoted \String Literals + Interpolation may be disabled by escaping the "#" character or using -single-quote strings: +single-quoted strings: '#{1 + 1}' #=> "\#{1 + 1}" @@ -199,6 +224,16 @@ In addition to disabling interpolation, single-quoted strings also disable all escape sequences except for the single-quote (\') and backslash (\\\\). +In a single-quoted string, +any other character following a backslash is interpreted as is: +a backslash and the character itself. + +See also: + +* {%q: Non-Interpolable String Literals}[#label-25q-3A+Non-Interpolable+String+Literals] + +=== Literal String Concatenation + Adjacent string literals are automatically concatenated by the interpreter: "con" "cat" "en" "at" "ion" #=> "concatenation" @@ -211,10 +246,12 @@ be concatenated as long as a percent-string is not last. %q{a} 'b' "c" #=> "abc" "a" 'b' %q{c} #=> NameError: uninitialized constant q +=== Character Literal + There is also a character literal notation to represent single character strings, which syntax is a question mark (?) -followed by a single character or escape sequence that corresponds to -a single codepoint in the script encoding: +followed by a single character or escape sequence (except continuation line) +that corresponds to a single codepoint in the script encoding: ?a #=> "a" ?abc #=> SyntaxError @@ -228,11 +265,6 @@ 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 @@ -283,9 +315,10 @@ its end is a multiple of eight. The amount to be removed is counted in terms of the number of spaces. If the boundary appears in the middle of a tab, that tab is not removed. -A heredoc allows interpolation and escaped characters. You may disable -interpolation and escaping by surrounding the opening identifier with single -quotes: +A heredoc allows interpolation and the escape sequences described in +{Escape Sequences}[#label-Escape+Sequences]. +You may disable interpolation and the escaping by surrounding the opening +identifier with single quotes: expected_result = <<-'EXPECTED' One plus one is #{1 + 1} @@ -326,12 +359,15 @@ details on what symbols are and when ruby creates them internally. You may reference a symbol using a colon: :my_symbol. -You may also create symbols by interpolation: +You may also create symbols by interpolation and escape sequences described in +{Escape Sequences}[#label-Escape+Sequences] with double-quotes: :"my_symbol1" :"my_symbol#{1 + 1}" + :"foo\sbar" -Like strings, a single-quote may be used to disable interpolation: +Like strings, a single-quote may be used to disable interpolation and +escape sequences: :'my_symbol#{1 + 1}' #=> :"my_symbol\#{1 + 1}" @@ -451,9 +487,12 @@ may use these paired delimiters: * ( and ). * { and }. * < and >. -* Any other character, as both beginning and ending delimiters. +* Non-alphanumeric ASCII character except above, as both beginning and ending delimiters. -The first four pairs (brackets, parenthesis, braces, and angle brackets) can be nested. +The delimiters can be escaped with a backslash. +However, the first four pairs (brackets, parenthesis, braces, and +angle brackets) are allowed without backslash as far as they are correctly +paired. These are demonstrated in the next section. @@ -462,18 +501,21 @@ These are demonstrated in the next section. 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[foo bar baz] # => "foo bar baz" # Using []. + %q(foo bar baz) # => "foo bar baz" # Using (). + %q{foo bar baz} # => "foo bar baz" # Using {}. + %q # => "foo bar baz" # Using <>. + %q|foo bar baz| # => "foo bar baz" # Using two |. + %q:foo bar baz: # => "foo bar baz" # Using two :. %q(1 + 1 is #{1 + 1}) # => "1 + 1 is \#{1 + 1}" # No interpolation. %q[foo[bar]baz] # => "foo[bar]baz" # brackets can be nested. %q(foo(bar)baz) # => "foo(bar)baz" # parenthesis can be nested. %q{foo{bar}baz} # => "foo{bar}baz" # braces can be nested. %qbaz> # => "foobaz" # angle brackets can be nested. +This is similar to single-quoted string but only backslashs and +the specified delimiters can be escaped with a backslash. + === % and %Q: Interpolable String Literals You can write an interpolable string with %Q @@ -482,15 +524,22 @@ or with its alias %: %[foo bar baz] # => "foo bar baz" %(1 + 1 is #{1 + 1}) # => "1 + 1 is 2" # Interpolation. +This is similar to double-quoted string. +It allow escape sequences described in +{Escape Sequences}[#label-Escape+Sequences]. +Other escaped characters (a backslash followed by a character) are +interpreted as the character. + === %w and %W: String-Array Literals -You can write an array of strings with %w (non-interpolable) -or %W (interpolable): +You can write an array of strings as whitespace-separated words +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[foo\ bar baz\ bat] # => ["foo bar", "baz bat"] %w(#{1 + 1}) # => ["\#{1", "+", "1}"] %W(#{1 + 1}) # => ["2"] @@ -498,18 +547,40 @@ or %W (interpolable): # (not nested array). %w[foo[bar baz]qux] # => ["foo[bar", "baz]qux"] +The following characters are considered as white spaces to separate words: + +* space, ASCII 20h (SPC) +* form feed, ASCII 0Ch (FF) +* newline (line feed), ASCII 0Ah (LF) +* carriage return, ASCII 0Dh (CR) +* horizontal tab, ASCII 09h (TAB) +* vertical tab, ASCII 0Bh (VT) + +The white space characters can be escaped with a backslash to make them +part of a word. + +%W allow escape sequences described in +{Escape Sequences}[#label-Escape+Sequences]. +However the continuation line \ is not usable because +it is interpreted as the escaped newline described above. + === %i and %I: Symbol-Array Literals -You can write an array of symbols with %i (non-interpolable) -or %I (interpolable): +You can write an array of symbols as whitespace-separated words +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[foo\ bar baz\ bat] # => [:"foo bar", :"baz bat"] %i(#{1 + 1}) # => [:"\#{1", :+, :"1}"] %I(#{1 + 1}) # => [:"2"] +The white space characters and its escapes are interpreted as the same as +string-array literals described in +{%w and %W: String-Array Literals}[#label-25w+and+-25W-3A+String-Array+Literals]. + === %s: Symbol Literals You can write a symbol with %s: @@ -517,6 +588,10 @@ You can write a symbol with %s: %s[foo] # => :foo %s[foo bar] # => :"foo bar" +This is non-interpolable. +No interpolation allowed. +Only backslashs and the specified delimiters can be escaped with a backslash. + === %r: Regexp Literals You can write a regular expression with %r; @@ -541,4 +616,10 @@ See {Regexp modes}[rdoc-ref:Regexp@Modes] for details. You can write and execute a shell command with %x: - %x(echo 1) # => "1\n" + %x(echo 1) # => "1\n" + %x[echo #{1 + 2}] # => "3\n" + %x[echo \u0030] # => "0\n" + +This is interpolable. +%x allow escape sequences described in +{Escape Sequences}[#label-Escape+Sequences].