strscan 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 499afd5ba3e810119b88244dfd4f41078e201b5c1c994e827f42077cdfabb151
-  data.tar.gz: bdc3ef1dd90c53ec6a6c6807fa1b2634587e0d7294d5a747b3837ffd7fb41a01
+  metadata.gz: 45d46129cae1a1b9273f5500d6d15279e592946173312c034fb54387faef9d0d
+  data.tar.gz: fc2d15f94f2e597d57dc89c44dddce16aa0096f02a6d268c22e1595ab9c5a00f
 SHA512:
-  metadata.gz: 9d818fe222252c1e6c34b8252ab22eb206c96b320c920b647ae062a1561678bf1a235bddc9dbc3272357c5fa78e847f3790117c693a62b77a608edcf1c15eb2d
-  data.tar.gz: b4ea287ab0209eb24229d3699548d831caa9fd9fabcf4715fa815ffad218524414a1291dcc9123a5d1c40b02d312026c049657202219f1a4cd2f5450c2fc8662
+  metadata.gz: 295727ce636512083608565f16c7675509143708abce6896da39fb0b3bad4d8e69538b6574a0ed6c6d7e0f85c14569c79cdc5901b55c7c5320c3d5a7af0cc61d
+  data.tar.gz: 4bba01c59eb8e3062fb498d6e8468ed6def6fa36d7c5ef9a0bb24806f7d500def565e9598eb5b7958589b3145653b57991a270963d066486b4e1ba915cb3030f

data/.rdoc_options

@@ -0,0 +1,3 @@
+---
+rdoc_include:
+- doc

data/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
+```
+

data/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

data/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]
+    ```

data/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
+```

data/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
+```

data/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]
+    ```

data/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
+```

data/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
+```

data/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
+```

data/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
+```

data/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
+```

data/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
+```