Sync strscan HEAD again.
https://github.com/ruby/strscan/pull/99 split document with multi-byte chars.
This commit is contained in:
parent
c5ae432ec8
commit
3eda59e975
@ -5,3 +5,5 @@ encoding: UTF-8
|
|||||||
main_page: README.md
|
main_page: README.md
|
||||||
title: Documentation for Ruby development version
|
title: Documentation for Ruby development version
|
||||||
visibility: :private
|
visibility: :private
|
||||||
|
rdoc_include:
|
||||||
|
- doc
|
||||||
|
128
doc/strscan/helper_methods.md
Normal file
128
doc/strscan/helper_methods.md
Normal file
@ -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
|
||||||
|
```
|
||||||
|
|
17
doc/strscan/link_refs.txt
Normal file
17
doc/strscan/link_refs.txt
Normal file
@ -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
|
30
doc/strscan/methods/get_byte.md
Normal file
30
doc/strscan/methods/get_byte.md
Normal file
@ -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]
|
||||||
|
```
|
19
doc/strscan/methods/get_charpos.md
Normal file
19
doc/strscan/methods/get_charpos.md
Normal file
@ -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
|
||||||
|
```
|
14
doc/strscan/methods/get_pos.md
Normal file
14
doc/strscan/methods/get_pos.md
Normal file
@ -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
|
||||||
|
```
|
43
doc/strscan/methods/getch.md
Normal file
43
doc/strscan/methods/getch.md
Normal file
@ -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]
|
||||||
|
```
|
51
doc/strscan/methods/scan.md
Normal file
51
doc/strscan/methods/scan.md
Normal file
@ -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
|
||||||
|
```
|
52
doc/strscan/methods/scan_until.md
Normal file
52
doc/strscan/methods/scan_until.md
Normal file
@ -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
|
||||||
|
```
|
27
doc/strscan/methods/set_pos.md
Normal file
27
doc/strscan/methods/set_pos.md
Normal file
@ -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
|
||||||
|
```
|
43
doc/strscan/methods/skip.md
Normal file
43
doc/strscan/methods/skip.md
Normal file
@ -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
|
||||||
|
```
|
49
doc/strscan/methods/skip_until.md
Normal file
49
doc/strscan/methods/skip_until.md
Normal file
@ -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
|
||||||
|
```
|
30
doc/strscan/methods/terminate.md
Normal file
30
doc/strscan/methods/terminate.md
Normal file
@ -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
|
||||||
|
```
|
543
doc/strscan/strscan.md
Normal file
543
doc/strscan/strscan.md
Normal file
@ -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.
|
||||||
|
|
File diff suppressed because it is too large
Load Diff
@ -29,6 +29,11 @@ Gem::Specification.new do |s|
|
|||||||
s.require_paths = %w{lib}
|
s.require_paths = %w{lib}
|
||||||
files << "ext/strscan/extconf.rb"
|
files << "ext/strscan/extconf.rb"
|
||||||
files << "ext/strscan/strscan.c"
|
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}
|
s.extensions = %w{ext/strscan/extconf.rb}
|
||||||
end
|
end
|
||||||
s.files = files
|
s.files = files
|
||||||
|
@ -273,6 +273,7 @@ module SyncDefaultGems
|
|||||||
cp_r("#{upstream}/ext/strscan", "ext")
|
cp_r("#{upstream}/ext/strscan", "ext")
|
||||||
cp_r("#{upstream}/test/strscan", "test")
|
cp_r("#{upstream}/test/strscan", "test")
|
||||||
cp_r("#{upstream}/strscan.gemspec", "ext/strscan")
|
cp_r("#{upstream}/strscan.gemspec", "ext/strscan")
|
||||||
|
cp_r("#{upstream}/doc/strscan", "doc")
|
||||||
rm_rf(%w["ext/strscan/regenc.h ext/strscan/regint.h"])
|
rm_rf(%w["ext/strscan/regenc.h ext/strscan/regint.h"])
|
||||||
`git checkout ext/strscan/depend`
|
`git checkout ext/strscan/depend`
|
||||||
when "cgi"
|
when "cgi"
|
||||||
|
Loading…
x
Reference in New Issue
Block a user