Sync strscan HEAD again.

https://github.com/ruby/strscan/pull/99 split document with multi-byte
chars.

.rdoc_options

@@ -5,3 +5,5 @@ encoding: UTF-8
 main_page: README.md
 title: Documentation for Ruby development version
 visibility: :private
+rdoc_include:
+- doc

doc/strscan/helper_methods.md

@@ -0,0 +1,128 @@
+## Helper Methods
+
+These helper methods display values returned by scanner's methods.
+
+### `put_situation(scanner)`
+
+Display scanner's situation:
+
+- Byte position (`#pos`).
+- Character position (`#charpos`)
+- Target string (`#rest`) and size (`#rest_size`).
+
+```
+scanner = StringScanner.new('foobarbaz')
+scanner.scan(/foo/)
+put_situation(scanner)
+# Situation:
+#   pos:       3
+#   charpos:   3
+#   rest:      "barbaz"
+#   rest_size: 6
+```
+
+### `put_match_values(scanner)`
+
+Display the scanner's match values:
+
+```
+scanner = StringScanner.new('Fri Dec 12 1975 14:39')
+pattern = /(?<wday>\w+) (?<month>\w+) (?<day>\d+) /
+scanner.match?(pattern)
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       true
+#   matched_size:   11
+#   pre_match:      ""
+#   matched  :      "Fri Dec 12 "
+#   post_match:     "1975 14:39"
+# Captured match values:
+#   size:           4
+#   captures:       ["Fri", "Dec", "12"]
+#   named_captures: {"wday"=>"Fri", "month"=>"Dec", "day"=>"12"}
+#   values_at:      ["Fri Dec 12 ", "Fri", "Dec", "12", nil]
+#   []:
+#     [0]:          "Fri Dec 12 "
+#     [1]:          "Fri"
+#     [2]:          "Dec"
+#     [3]:          "12"
+#     [4]:          nil
+```
+
+### `match_values_cleared?(scanner)`
+
+Returns whether the scanner's match values are all properly cleared:
+
+```
+scanner = StringScanner.new('foobarbaz')
+match_values_cleared?(scanner) # => true
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       false
+#   matched_size:   nil
+#   pre_match:      nil
+#   matched  :      nil
+#   post_match:     nil
+# Captured match values:
+#   size:           nil
+#   captures:       nil
+#   named_captures: {}
+#   values_at:      nil
+#   [0]:            nil
+scanner.scan(/foo/)
+match_values_cleared?(scanner) # => false
+```
+
+## The Code
+
+```
+def put_situation(scanner)
+  puts '# Situation:'
+  puts "#   pos:       #{scanner.pos}"
+  puts "#   charpos:   #{scanner.charpos}"
+  puts "#   rest:      #{scanner.rest.inspect}"
+  puts "#   rest_size: #{scanner.rest_size}"
+end
+```
+
+```
+def put_match_values(scanner)
+  puts '# Basic match values:'
+  puts "#   matched?:       #{scanner.matched?}"
+  value = scanner.matched_size || 'nil'
+  puts "#   matched_size:   #{value}"
+  puts "#   pre_match:      #{scanner.pre_match.inspect}"
+  puts "#   matched  :      #{scanner.matched.inspect}"
+  puts "#   post_match:     #{scanner.post_match.inspect}"
+  puts '# Captured match values:'
+  puts "#   size:           #{scanner.size}"
+  puts "#   captures:       #{scanner.captures}"
+  puts "#   named_captures: #{scanner.named_captures}"
+  if scanner.size.nil?
+    puts "#   values_at:      #{scanner.values_at(0)}"
+    puts "#   [0]:            #{scanner[0]}"
+  else
+    puts "#   values_at:      #{scanner.values_at(*(0..scanner.size))}"
+    puts "#   []:"
+    scanner.size.times do |i|
+      puts "#     [#{i}]:          #{scanner[i].inspect}"
+    end
+  end
+end
+```
+
+```
+def match_values_cleared?(scanner)
+  scanner.matched? == false &&
+    scanner.matched_size.nil? &&
+    scanner.matched.nil? &&
+    scanner.pre_match.nil? &&
+    scanner.post_match.nil? &&
+    scanner.size.nil? &&
+    scanner[0].nil? &&
+    scanner.captures.nil? &&
+    scanner.values_at(0..1).nil? &&
+    scanner.named_captures == {}
+end
+```
+

doc/strscan/link_refs.txt

@@ -0,0 +1,17 @@
+[1]: rdoc-ref:StringScanner@Stored+String
+[2]: rdoc-ref:StringScanner@Byte+Position+-28Position-29
+[3]: rdoc-ref:StringScanner@Target+Substring
+[4]: rdoc-ref:StringScanner@Setting+the+Target+Substring
+[5]: rdoc-ref:StringScanner@Traversing+the+Target+Substring
+[6]: https://docs.ruby-lang.org/en/master/Regexp.html
+[7]: rdoc-ref:StringScanner@Character+Position
+[8]: https://docs.ruby-lang.org/en/master/String.html#method-i-5B-5D
+[9]: rdoc-ref:StringScanner@Match+Values
+[10]: rdoc-ref:StringScanner@Fixed-Anchor+Property
+[11]: rdoc-ref:StringScanner@Positions
+[13]: rdoc-ref:StringScanner@Captured+Match+Values
+[14]: rdoc-ref:StringScanner@Querying+the+Target+Substring
+[15]: rdoc-ref:StringScanner@Searching+the+Target+Substring
+[16]: https://docs.ruby-lang.org/en/master/Regexp.html#class-Regexp-label-Groups+and+Captures
+[17]: rdoc-ref:StringScanner@Matching
+[18]: rdoc-ref:StringScanner@Basic+Match+Values

doc/strscan/methods/get_byte.md

@@ -0,0 +1,30 @@
+call-seq:
+  get_byte -> byte_as_character or nil
+
+Returns the next byte, if available:
+
+- If the [position][2]
+  is not at the end of the [stored string][1]:
+
+    - Returns the next byte.
+    - Increments the [byte position][2].
+    - Adjusts the [character position][7].
+
+    ```
+    scanner = StringScanner.new(HIRAGANA_TEXT)
+    # => #<StringScanner 0/15 @ "\xE3\x81\x93\xE3\x82...">
+    scanner.string                                   # => "こんにちは"
+    [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\xE3", 1, 1]
+    [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x81", 2, 2]
+    [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x93", 3, 1]
+    [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\xE3", 4, 2]
+    [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x82", 5, 3]
+    [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x93", 6, 2]
+    ```
+
+- Otherwise, returns `nil`, and does not change the positions.
+
+    ```
+    scanner.terminate
+    [scanner.get_byte, scanner.pos, scanner.charpos] # => [nil, 15, 5]
+    ```

doc/strscan/methods/get_charpos.md

@@ -0,0 +1,19 @@
+call-seq:
+  charpos -> character_position
+
+Returns the [character position][7] (initially zero),
+which may be different from the [byte position][2]
+given by method #pos:
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.getch  # => "こ" # 3-byte character.
+scanner.getch  # => "ん" # 3-byte character.
+put_situation(scanner)
+# Situation:
+#   pos:       6
+#   charpos:   2
+#   rest:      "にちは"
+#   rest_size: 9
+```

doc/strscan/methods/get_pos.md

@@ -0,0 +1,14 @@
+call-seq:
+  pos -> byte_position
+
+Returns the integer [byte position][2],
+which may be different from the [character position][7]:
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string  # => "こんにちは"
+scanner.pos     # => 0
+scanner.getch   # => "こ" # 3-byte character.
+scanner.charpos # => 1
+scanner.pos     # => 3
+```

doc/strscan/methods/getch.md

@@ -0,0 +1,43 @@
+call-seq:
+  getch -> character or nil
+
+Returns the next (possibly multibyte) character,
+if available:
+
+- If the [position][2]
+  is at the beginning of a character:
+
+    - Returns the character.
+    - Increments the [character position][7] by 1.
+    - Increments the [byte position][2]
+      by the size (in bytes) of the character.
+
+    ```
+    scanner = StringScanner.new(HIRAGANA_TEXT)
+    scanner.string                                # => "こんにちは"
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["こ", 3, 1]
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["ん", 6, 2]
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["に", 9, 3]
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["ち", 12, 4]
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["は", 15, 5]
+    [scanner.getch, scanner.pos, scanner.charpos] # => [nil, 15, 5]
+    ```
+
+- If the [position][2] is within a multi-byte character
+  (that is, not at its beginning),
+  behaves like #get_byte (returns a 1-byte character):
+
+    ```
+    scanner.pos = 1
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["\x81", 2, 2]
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["\x93", 3, 1]
+    [scanner.getch, scanner.pos, scanner.charpos] # => ["ん", 6, 2]
+    ```
+
+- If the [position][2] is at the end of the [stored string][1],
+  returns `nil` and does not modify the positions:
+
+    ```
+    scanner.terminate
+    [scanner.getch, scanner.pos, scanner.charpos] # => [nil, 15, 5]
+    ```

doc/strscan/methods/scan.md

@@ -0,0 +1,51 @@
+call-seq:
+  scan(pattern) -> substring or nil
+
+Attempts to [match][17] the given `pattern`
+at the beginning of the [target substring][3].
+
+If the match succeeds:
+
+- Returns the matched substring.
+- Increments the [byte position][2] by <tt>substring.bytesize</tt>,
+  and may increment the [character position][7].
+- Sets [match values][9].
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string     # => "こんにちは"
+scanner.pos = 6
+scanner.scan(/に/) # => "に"
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       true
+#   matched_size:   3
+#   pre_match:      "こん"
+#   matched  :      "に"
+#   post_match:     "ちは"
+# Captured match values:
+#   size:           1
+#   captures:       []
+#   named_captures: {}
+#   values_at:      ["に", nil]
+#   []:
+#     [0]:          "に"
+#     [1]:          nil
+put_situation(scanner)
+# Situation:
+#   pos:       9
+#   charpos:   3
+#   rest:      "ちは"
+#   rest_size: 6
+```
+
+If the match fails:
+
+- Returns `nil`.
+- Does not increment byte and character positions.
+- Clears match values.
+
+```
+scanner.scan(/nope/)           # => nil
+match_values_cleared?(scanner) # => true
+```

doc/strscan/methods/scan_until.md

@@ -0,0 +1,52 @@
+call-seq:
+  scan_until(pattern) -> substring or nil
+
+Attempts to [match][17] the given `pattern`
+anywhere (at any [position][2]) in the [target substring][3].
+
+If the match attempt succeeds:
+
+- Sets [match values][9].
+- Sets the [byte position][2] to the end of the matched substring;
+  may adjust the [character position][7].
+- Returns the matched substring.
+
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string           # => "こんにちは"
+scanner.pos = 6
+scanner.scan_until(/ち/) # => "にち"
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       true
+#   matched_size:   3
+#   pre_match:      "こんに"
+#   matched  :      "ち"
+#   post_match:     "は"
+# Captured match values:
+#   size:           1
+#   captures:       []
+#   named_captures: {}
+#   values_at:      ["ち", nil]
+#   []:
+#     [0]:          "ち"
+#     [1]:          nil
+put_situation(scanner)
+# Situation:
+#   pos:       12
+#   charpos:   4
+#   rest:      "は"
+#   rest_size: 3
+```
+
+If the match attempt fails:
+
+- Clears match data.
+- Returns `nil`.
+- Does not update positions.
+
+```
+scanner.scan_until(/nope/)     # => nil
+match_values_cleared?(scanner) # => true
+```

doc/strscan/methods/set_pos.md

@@ -0,0 +1,27 @@
+call-seq:
+  pos = n -> n
+  pointer = n -> n
+
+Sets the [byte position][2] and the [character position][11];
+returns `n`.
+
+Does not affect [match values][9].
+
+For non-negative `n`, sets the position to `n`:
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string  # => "こんにちは"
+scanner.pos = 3 # => 3
+scanner.rest    # => "んにちは"
+scanner.charpos # => 1
+```
+
+For negative `n`, counts from the end of the [stored string][1]:
+
+```
+scanner.pos = -9 # => -9
+scanner.pos      # => 6
+scanner.rest     # => "にちは"
+scanner.charpos  # => 2
+```

doc/strscan/methods/skip.md

@@ -0,0 +1,43 @@
+call-seq:
+  skip(pattern) match_size or nil
+
+Attempts to [match][17] the given `pattern`
+at the beginning of the [target substring][3];
+
+If the match succeeds:
+
+- Increments the [byte position][2] by substring.bytesize,
+  and may increment the [character position][7].
+- Sets [match values][9].
+- Returns the size (bytes) of the matched substring.
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string                  # => "こんにちは"
+scanner.pos = 6
+scanner.skip(/に/)              # => 3
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       true
+#   matched_size:   3
+#   pre_match:      "こん"
+#   matched  :      "に"
+#   post_match:     "ちは"
+# Captured match values:
+#   size:           1
+#   captures:       []
+#   named_captures: {}
+#   values_at:      ["に", nil]
+#   []:
+#     [0]:          "に"
+#     [1]:          nil
+put_situation(scanner)
+# Situation:
+#   pos:       9
+#   charpos:   3
+#   rest:      "ちは"
+#   rest_size: 6
+
+scanner.skip(/nope/)            # => nil
+match_values_cleared?(scanner)  # => true
+```

doc/strscan/methods/skip_until.md

@@ -0,0 +1,49 @@
+call-seq:
+  skip_until(pattern) -> matched_substring_size or nil
+
+Attempts to [match][17] the given `pattern`
+anywhere (at any [position][2]) in the [target substring][3];
+does not modify the positions.
+
+If the match attempt succeeds:
+
+- Sets [match values][9].
+- Returns the size of the matched substring.
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string           # => "こんにちは"
+scanner.pos = 6
+scanner.skip_until(/ち/) # => 6
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       true
+#   matched_size:   3
+#   pre_match:      "こんに"
+#   matched  :      "ち"
+#   post_match:     "は"
+# Captured match values:
+#   size:           1
+#   captures:       []
+#   named_captures: {}
+#   values_at:      ["ち", nil]
+#   []:
+#     [0]:          "ち"
+#     [1]:          nil
+put_situation(scanner)
+# Situation:
+#   pos:       12
+#   charpos:   4
+#   rest:      "は"
+#   rest_size: 3
+```
+
+If the match attempt fails:
+
+- Clears match values.
+- Returns `nil`.
+
+```
+scanner.skip_until(/nope/)     # => nil
+match_values_cleared?(scanner) # => true
+```

doc/strscan/methods/terminate.md

@@ -0,0 +1,30 @@
+call-seq:
+  terminate -> self
+
+Sets the scanner to end-of-string;
+returns +self+:
+
+- Sets both [positions][11] to end-of-stream.
+- Clears [match values][9].
+
+```
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string                 # => "こんにちは"
+scanner.scan_until(/に/)
+put_situation(scanner)
+# Situation:
+#   pos:       9
+#   charpos:   3
+#   rest:      "ちは"
+#   rest_size: 6
+match_values_cleared?(scanner) # => false
+
+scanner.terminate              # => #<StringScanner fin>
+put_situation(scanner)
+# Situation:
+#   pos:       15
+#   charpos:   5
+#   rest:      ""
+#   rest_size: 0
+match_values_cleared?(scanner) # => true
+```

doc/strscan/strscan.md

@@ -0,0 +1,543 @@
+\Class `StringScanner` supports processing a stored string as a stream;
+this code creates a new `StringScanner` object with string `'foobarbaz'`:
+
+```
+require 'strscan'
+scanner = StringScanner.new('foobarbaz')
+```
+
+## About the Examples
+
+All examples here assume that `StringScanner` has been required:
+
+```
+require 'strscan'
+```
+
+Some examples here assume that these constants are defined:
+
+```
+MULTILINE_TEXT = <<~EOT
+Go placidly amid the noise and haste,
+and remember what peace there may be in silence.
+EOT
+
+HIRAGANA_TEXT = 'こんにちは'
+
+ENGLISH_TEXT = 'Hello'
+```
+
+Some examples here assume that certain helper methods are defined:
+
+- `put_situation(scanner)`:
+  Displays the values of the scanner's
+  methods #pos, #charpos, #rest, and #rest_size.
+- `put_match_values(scanner)`:
+  Displays the scanner's [match values][9].
+- `match_values_cleared?(scanner)`:
+  Returns whether the scanner's [match values][9] are cleared.
+
+See examples [here][ext/strscan/helper_methods_md.html].
+
+## The `StringScanner` \Object
+
+This code creates a `StringScanner` object
+(we'll call it simply a _scanner_),
+and shows some of its basic properties:
+
+```
+scanner = StringScanner.new('foobarbaz')
+scanner.string # => "foobarbaz"
+put_situation(scanner)
+# Situation:
+#   pos:       0
+#   charpos:   0
+#   rest:      "foobarbaz"
+#   rest_size: 9
+```
+
+The scanner has:
+
+* A <i>stored string</i>, which is:
+
+    * Initially set by StringScanner.new(string) to the given `string`
+      (`'foobarbaz'` in the example above).
+    * Modifiable by methods #string=(new_string) and #concat(more_string).
+    * Returned by method #string.
+
+    More at [Stored String][1] below.
+
+* A _position_;
+  a zero-based index into the bytes of the stored string (_not_ into its characters):
+
+    * Initially set by StringScanner.new to `0`.
+    * Returned by method #pos.
+    * Modifiable explicitly by methods #reset, #terminate, and #pos=(new_pos).
+    * Modifiable implicitly (various traversing methods, among others).
+
+    More at [Byte Position][2] below.
+ 
+* A <i>target substring</i>,
+  which is a trailing substring of the stored string;
+  it extends from the current position to the end of the stored string:
+
+    * Initially set by StringScanner.new(string) to the given `string`
+      (`'foobarbaz'` in the example above).
+    * Returned by method #rest.
+    * Modified by any modification to either the stored string or the position.
+
+    <b>Most importantly</b>:
+    the searching and traversing methods operate on the target substring,
+    which may be (and often is) less than the entire stored string.
+
+    More at [Target Substring][3] below.
+
+## Stored \String
+
+The <i>stored string</i> is the string stored in the `StringScanner` object.
+
+Each of these methods sets, modifies, or returns the stored string:
+
+| Method               | Effect                                          |
+|----------------------|-------------------------------------------------|
+| ::new(string)        | Creates a new scanner for the given string.     |
+| #string=(new_string) | Replaces the existing stored string.            |
+| #concat(more_string) | Appends a string to the existing stored string. |
+| #string              | Returns the stored string.                      |
+
+## Positions
+
+A `StringScanner` object maintains a zero-based <i>byte position</i>
+and a zero-based <i>character position</i>.
+
+Each of these methods explicitly sets positions:
+
+| Method                   | Effect                                                   |
+|--------------------------|----------------------------------------------------------|
+| #reset                   | Sets both positions to zero (begining of stored string). |
+| #terminate               | Sets both positions to the end of the stored string.     |
+| #pos=(new_byte_position) | Sets byte position; adjusts character position.          |
+
+### Byte Position (Position)
+
+The byte position (or simply _position_)
+is a zero-based index into the bytes in the scanner's stored string;
+for a new `StringScanner` object, the byte position is zero.
+
+When the byte position is:
+
+* Zero (at the beginning), the target substring is the entire stored string.
+* Equal to the size of the stored string (at the end),
+  the target substring is the empty string `''`.
+
+To get or set the byte position:
+
+* \#pos: returns the byte position.
+* \#pos=(new_pos): sets the byte position.
+
+Many methods use the byte position as the basis for finding matches;
+many others set, increment, or decrement the byte position:
+
+```
+scanner = StringScanner.new('foobar')
+scanner.pos # => 0
+scanner.scan(/foo/) # => "foo" # Match found.
+scanner.pos         # => 3     # Byte position incremented.
+scanner.scan(/foo/) # => nil   # Match not found.
+scanner.pos # => 3             # Byte position not changed.
+```
+
+Some methods implicitly modify the byte position;
+see:
+
+* [Setting the Target Substring][4].
+* [Traversing the Target Substring][5].
+
+The values of these methods are derived directly from the values of #pos and #string:
+
+- \#charpos: the [character position][7].
+- \#rest: the [target substring][3].
+- \#rest_size: `rest.size`.
+
+### Character Position
+
+The character position is a zero-based index into the _characters_
+in the stored string;
+for a new `StringScanner` object, the character position is zero.
+
+\Method #charpos returns the character position;
+its value may not be reset explicitly.
+
+Some methods change (increment or reset) the character position;
+see:
+
+* [Setting the Target Substring][4].
+* [Traversing the Target Substring][5].
+
+Example (string includes multi-byte characters):
+
+```
+scanner = StringScanner.new(ENGLISH_TEXT) # Five 1-byte characters.
+scanner.concat(HIRAGANA_TEXT)             # Five 3-byte characters
+scanner.string # => "Helloこんにちは"       # Twenty bytes in all.
+put_situation(scanner)
+# Situation:
+#   pos:       0
+#   charpos:   0
+#   rest:      "Helloこんにちは"
+#   rest_size: 20
+scanner.scan(/Hello/) # => "Hello" # Five 1-byte characters.
+put_situation(scanner)
+# Situation:
+#   pos:       5
+#   charpos:   5
+#   rest:      "こんにちは"
+#   rest_size: 15
+scanner.getch         # => "こ"    # One 3-byte character.
+put_situation(scanner)
+# Situation:
+#   pos:       8
+#   charpos:   6
+#   rest:      "んにちは"
+#   rest_size: 12```
+
+## Target Substring
+
+The target substring is the the part of the [stored string][1]
+that extends from the current [byte position][2] to the end of the stored string;
+it is always either:
+ 
+- The entire stored string (byte position is zero).
+- A trailing substring of the stored string (byte position positive).
+
+The target substring is returned by method #rest,
+and its size is returned by method #rest_size.
+
+Examples:
+
+```
+scanner = StringScanner.new('foobarbaz')
+put_situation(scanner)
+# Situation:
+#   pos:       0
+#   charpos:   0
+#   rest:      "foobarbaz"
+#   rest_size: 9
+scanner.pos = 3
+put_situation(scanner)
+# Situation:
+#   pos:       3
+#   charpos:   3
+#   rest:      "barbaz"
+#   rest_size: 6
+scanner.pos = 9
+put_situation(scanner)
+# Situation:
+#   pos:       9
+#   charpos:   9
+#   rest:      ""
+#   rest_size: 0
+```
+
+### Setting the Target Substring
+
+The target substring is set whenever:
+
+* The [stored string][1] is set (position reset to zero; target substring set to stored string).
+* The [byte position][2] is set (target substring adjusted accordingly).
+
+### Querying the Target Substring
+
+This table summarizes (details and examples at the links):
+
+| Method     | Returns                           |
+|------------|-----------------------------------|
+| #rest      | Target substring.                 |
+| #rest_size | Size (bytes) of target substring. |
+
+### Searching the Target Substring
+
+A _search_ method examines the target substring,
+but does not advance the [positions][11]
+or (by implication) shorten the target substring.
+
+This table summarizes (details and examples at the links):
+
+| Method                | Returns                                       | Sets Match Values? |
+|-----------------------|-----------------------------------------------|--------------------|
+| #check(pattern)       | Matched leading substring or +nil+.           | Yes.               |
+| #check_until(pattern) | Matched substring (anywhere) or +nil+.        | Yes.               |
+| #exist?(pattern)      | Matched substring (anywhere) end index.       | Yes.               |
+| #match?(pattern)      | Size of matched leading substring or +nil+.   | Yes.               |
+| #peek(size)           | Leading substring of given length (bytes).    | No.                |
+| #peek_byte            | Integer leading byte or +nil+.                | No.                |
+| #rest                 | Target substring (from byte position to end). | No.                |
+
+### Traversing the Target Substring
+
+A _traversal_ method examines the target substring,
+and, if successful:
+
+- Advances the [positions][11].
+- Shortens the target substring.
+
+
+This table summarizes (details and examples at links):
+
+| Method               | Returns                                              | Sets Match Values? |
+|----------------------|------------------------------------------------------|--------------------|
+| #get_byte            | Leading byte or +nil+.                               | No.                |
+| #getch               | Leading character or +nil+.                          | No.                |
+| #scan(pattern)       | Matched leading substring or +nil+.                  | Yes.               |
+| #scan_byte           | Integer leading byte or +nil+.                       | No.                |
+| #scan_until(pattern) | Matched substring (anywhere) or +nil+.               | Yes.               |
+| #skip(pattern)       | Matched leading substring size or +nil+.             | Yes.               |
+| #skip_until(pattern) | Position delta to end-of-matched-substring or +nil+. | Yes.               |
+| #unscan              | +self+.                                              | No.                |
+
+## Querying the Scanner
+
+Each of these methods queries the scanner object
+without modifying it (details and examples at links)
+
+| Method              | Returns                          |
+|---------------------|----------------------------------|
+| #beginning_of_line? | +true+ or +false+.               |
+| #charpos            | Character position.              |
+| #eos?               | +true+ or +false+.               |
+| #fixed_anchor?      | +true+ or +false+.               |
+| #inspect            | String representation of +self+. |
+| #pos                | Byte position.                   |
+| #rest               | Target substring.                |
+| #rest_size          | Size of target substring.        |
+| #string             | Stored string.                   |
+
+## Matching
+
+`StringScanner` implements pattern matching via Ruby class [Regexp][6],
+and its matching behaviors are the same as Ruby's
+except for the [fixed-anchor property][10].
+
+### Matcher Methods
+
+Each <i>matcher method</i> takes a single argument `pattern`,
+and attempts to find a matching substring in the [target substring][3].
+
+| Method       | Pattern Type      | Matches Target Substring | Success Return     | May Update Positions? |
+|--------------|-------------------|--------------------------|--------------------|-----------------------|
+| #check       | Regexp or String. | At beginning.            | Matched substring. | No.                   |
+| #check_until | Regexp.           | Anywhere.                | Substring.         | No.                   |
+| #match?      | Regexp or String. | At beginning.            | Updated position.  | No.                   |
+| #exist?      | Regexp.           | Anywhere.                | Updated position.  | No.                   |
+| #scan        | Regexp or String. | At beginning.            | Matched substring. | Yes.                  |
+| #scan_until  | Regexp.           | Anywhere.                | Substring.         | Yes.                  |
+| #skip        | Regexp or String. | At beginning.            | Match size.        | Yes.                  |
+| #skip_until  | Regexp.           | Anywhere.                | Position delta.    | Yes.                  |
+
+<br>
+
+Which matcher you choose will depend on:
+
+- Where you want to find a match:
+
+    - Only at the beginning of the target substring:
+      #check, #match?, #scan, #skip.
+    - Anywhere in the target substring:
+      #check_until, #exist?, #scan_until, #skip_until.
+
+- Whether you want to:
+
+    - Traverse, by advancing the positions:
+      #scan, #scan_until, #skip, #skip_until.
+    - Keep the positions unchanged:
+      #check, #check_until, #exist?, #match?.
+
+- What you want for the return value:
+
+    - The matched substring: #check, #check_until, #scan, #scan_until.
+    - The updated position: #exist?, #match?.
+    - The position delta: #skip_until.
+    - The match size: #skip.
+
+### Match Values
+
+The <i>match values</i> in a `StringScanner` object
+generally contain the results of the most recent attempted match.
+
+Each match value may be thought of as:
+
+* _Clear_: Initially, or after an unsuccessful match attempt:
+  usually, `false`, `nil`, or `{}`.
+* _Set_: After a successful match attempt:
+  `true`, string, array, or hash.
+
+Each of these methods clears match values:
+
+- ::new(string).
+- \#reset.
+- \#terminate.
+
+Each of these methods attempts a match based on a pattern,
+and either sets match values (if successful) or clears them (if not);
+
+- \#check(pattern)
+- \#check_until(pattern)
+- \#exist?(pattern)
+- \#match?(pattern)
+- \#scan(pattern)
+- \#scan_until(pattern)
+- \#skip(pattern)
+- \#skip_until(pattern)
+
+#### Basic Match Values
+
+Basic match values are those not related to captures.
+
+Each of these methods returns a basic match value:
+
+| Method          | Return After Match                     | Return After No Match |
+|-----------------|----------------------------------------|-----------------------|
+| #matched?       | +true+.                                | +false+.              |
+| #matched_size   | Size of matched substring.             | +nil+.                |
+| #matched        | Matched substring.                     | +nil+.                |
+| #pre_match      | Substring preceding matched substring. | +nil+.                |
+| #post_match     | Substring following matched substring. | +nil+.                |
+
+<br>
+
+See examples below.
+
+#### Captured Match Values
+
+Captured match values are those related to [captures][16].
+
+Each of these methods returns a captured match value:
+
+| Method          | Return After Match                      | Return After No Match |
+|-----------------|-----------------------------------------|-----------------------|
+| #size           | Count of captured substrings.           | +nil+.                |
+| #[](n)          | <tt>n</tt>th captured substring.        | +nil+.                |
+| #captures       | Array of all captured substrings.       | +nil+.                |
+| #values_at(*n)  | Array of specified captured substrings. | +nil+.                |
+| #named_captures | Hash of named captures.                 | <tt>{}</tt>.          |
+
+<br>
+
+See examples below.
+
+#### Match Values Examples
+
+Successful basic match attempt (no captures):
+
+```
+scanner = StringScanner.new('foobarbaz')
+scanner.exist?(/bar/)
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       true
+#   matched_size:   3
+#   pre_match:      "foo"
+#   matched  :      "bar"
+#   post_match:     "baz"
+# Captured match values:
+#   size:           1
+#   captures:       []
+#   named_captures: {}
+#   values_at:      ["bar", nil]
+#   []:
+#     [0]:          "bar"
+#     [1]:          nil
+```
+
+Failed basic match attempt (no captures);
+
+```
+scanner = StringScanner.new('foobarbaz')
+scanner.exist?(/nope/)
+match_values_cleared?(scanner) # => true
+```
+
+Successful unnamed capture match attempt:
+
+```
+scanner = StringScanner.new('foobarbazbatbam')
+scanner.exist?(/(foo)bar(baz)bat(bam)/)
+put_match_values(scanner)
+# Basic match values:
+#   matched?:       true
+#   matched_size:   15
+#   pre_match:      ""
+#   matched  :      "foobarbazbatbam"
+#   post_match:     ""
+# Captured match values:
+#   size:           4
+#   captures:       ["foo", "baz", "bam"]
+#   named_captures: {}
+#   values_at:      ["foobarbazbatbam", "foo", "baz", "bam", nil]
+#   []:
+#     [0]:          "foobarbazbatbam"
+#     [1]:          "foo"
+#     [2]:          "baz"
+#     [3]:          "bam"
+#     [4]:          nil
+```
+
+Successful named capture match attempt;
+same as unnamed above, except for #named_captures:
+
+```
+scanner = StringScanner.new('foobarbazbatbam')
+scanner.exist?(/(?<x>foo)bar(?<y>baz)bat(?<z>bam)/)
+scanner.named_captures # => {"x"=>"foo", "y"=>"baz", "z"=>"bam"}
+```
+
+Failed unnamed capture match attempt:
+
+```
+scanner = StringScanner.new('somestring')
+scanner.exist?(/(foo)bar(baz)bat(bam)/)
+match_values_cleared?(scanner) # => true
+```
+
+Failed named capture match attempt;
+same as unnamed above, except for #named_captures:
+
+```
+scanner = StringScanner.new('somestring')
+scanner.exist?(/(?<x>foo)bar(?<y>baz)bat(?<z>bam)/)
+match_values_cleared?(scanner) # => false
+scanner.named_captures # => {"x"=>nil, "y"=>nil, "z"=>nil}
+```
+
+## Fixed-Anchor Property
+
+Pattern matching in `StringScanner` is the same as in Ruby's,
+except for its fixed-anchor property,
+which determines the meaning of `'\A'`:
+
+* `false` (the default): matches the current byte position.
+
+    ```
+    scanner = StringScanner.new('foobar')
+    scanner.scan(/\A./) # => "f"
+    scanner.scan(/\A./) # => "o"
+    scanner.scan(/\A./) # => "o"
+    scanner.scan(/\A./) # => "b"
+    ```
+
+* `true`: matches the beginning of the target substring;
+  never matches unless the byte position is zero:
+
+    ```
+    scanner = StringScanner.new('foobar', fixed_anchor: true)
+    scanner.scan(/\A./) # => "f"
+    scanner.scan(/\A./) # => nil
+    scanner.reset
+    scanner.scan(/\A./) # => "f"
+    ```
+
+The fixed-anchor property is set when the `StringScanner` object is created,
+and may not be modified
+(see StringScanner.new);
+method #fixed_anchor? returns the setting.
+

ext/strscan/strscan.gemspec

@@ -29,6 +29,11 @@ Gem::Specification.new do |s|
     s.require_paths = %w{lib}
     files << "ext/strscan/extconf.rb"
     files << "ext/strscan/strscan.c"
+    s.rdoc_options << "-idoc"
+    s.extra_rdoc_files = [
+      ".rdoc_options",
+      *Dir.glob("doc/strscan/**/*")
+    ]
     s.extensions = %w{ext/strscan/extconf.rb}
   end
   s.files = files

tool/sync_default_gems.rb

@@ -273,6 +273,7 @@ module SyncDefaultGems
       cp_r("#{upstream}/ext/strscan", "ext")
       cp_r("#{upstream}/test/strscan", "test")
       cp_r("#{upstream}/strscan.gemspec", "ext/strscan")
+      cp_r("#{upstream}/doc/strscan", "doc")
       rm_rf(%w["ext/strscan/regenc.h ext/strscan/regint.h"])
       `git checkout ext/strscan/depend`
     when "cgi"