diff options
Diffstat (limited to 'doc/strscan/strscan.md')
| -rw-r--r-- | doc/strscan/strscan.md | 69 |
1 files changed, 35 insertions, 34 deletions
diff --git a/doc/strscan/strscan.md b/doc/strscan/strscan.md index 465cebd4cb..bbdeccd75e 100644 --- a/doc/strscan/strscan.md +++ b/doc/strscan/strscan.md @@ -1,7 +1,7 @@ \Class `StringScanner` supports processing a stored string as a stream; this code creates a new `StringScanner` object with string `'foobarbaz'`: -``` +```rb require 'strscan' scanner = StringScanner.new('foobarbaz') ``` @@ -10,13 +10,13 @@ scanner = StringScanner.new('foobarbaz') All examples here assume that `StringScanner` has been required: -``` +```rb require 'strscan' ``` Some examples here assume that these constants are defined: -``` +```rb MULTILINE_TEXT = <<~EOT Go placidly amid the noise and haste, and remember what peace there may be in silence. @@ -37,7 +37,7 @@ Some examples here assume that certain helper methods are defined: - `match_values_cleared?(scanner)`: Returns whether the scanner's [match values][9] are cleared. -See examples [here][ext/strscan/helper_methods_md.html]. +See examples at [helper methods](doc/strscan/helper_methods.md). ## The `StringScanner` \Object @@ -45,7 +45,7 @@ This code creates a `StringScanner` object (we'll call it simply a _scanner_), and shows some of its basic properties: -``` +```rb scanner = StringScanner.new('foobarbaz') scanner.string # => "foobarbaz" put_situation(scanner) @@ -112,11 +112,11 @@ 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. | +| Method | Effect | +|--------------------------|-----------------------------------------------------------| +| #reset | Sets both positions to zero (beginning 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) @@ -138,7 +138,7 @@ To get or set the byte position: Many methods use the byte position as the basis for finding matches; many others set, increment, or decrement the byte position: -``` +```rb scanner = StringScanner.new('foobar') scanner.pos # => 0 scanner.scan(/foo/) # => "foo" # Match found. @@ -176,7 +176,7 @@ see: Example (string includes multi-byte characters): -``` +```rb scanner = StringScanner.new(ENGLISH_TEXT) # Five 1-byte characters. scanner.concat(HIRAGANA_TEXT) # Five 3-byte characters scanner.string # => "Helloこんにちは" # Twenty bytes in all. @@ -199,11 +199,12 @@ put_situation(scanner) # pos: 8 # charpos: 6 # rest: "んにちは" -# rest_size: 12``` +# rest_size: 12 +``` ## Target Substring -The target substring is the the part of the [stored string][1] +The target substring is 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: @@ -215,7 +216,7 @@ and its size is returned by method #rest_size. Examples: -``` +```rb scanner = StringScanner.new('foobarbaz') put_situation(scanner) # Situation: @@ -326,13 +327,13 @@ 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. | +| #check_until | Regexp or String. | Anywhere. | Substring. | No. | +| #match? | Regexp or String. | At beginning. | Match size. | No. | +| #exist? | Regexp or String. | Anywhere. | Substring size. | No. | | #scan | Regexp or String. | At beginning. | Matched substring. | Yes. | -| #scan_until | Regexp. | Anywhere. | Substring. | Yes. | +| #scan_until | Regexp or String. | Anywhere. | Substring. | Yes. | | #skip | Regexp or String. | At beginning. | Match size. | Yes. | -| #skip_until | Regexp. | Anywhere. | Position delta. | Yes. | +| #skip_until | Regexp or String. | Anywhere. | Substring size. | Yes. | <br> @@ -350,14 +351,14 @@ Which matcher you choose will depend on: - Traverse, by advancing the positions: #scan, #scan_until, #skip, #skip_until. - Keep the positions unchanged: - #check, #check_until, #exist?, #match?. + #check, #check_until, #match?, #exist?. - 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. + - The matched substring: #check, #scan. + - The substring: #check_until, #scan_until. + - The match size: #match?, #skip. + - The substring size: #exist?, #skip_until. ### Match Values @@ -416,7 +417,7 @@ 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+. | +| #\[\](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>. | @@ -429,7 +430,7 @@ See examples below. Successful basic match attempt (no captures): -``` +```rb scanner = StringScanner.new('foobarbaz') scanner.exist?(/bar/) put_match_values(scanner) @@ -451,7 +452,7 @@ put_match_values(scanner) Failed basic match attempt (no captures); -``` +```rb scanner = StringScanner.new('foobarbaz') scanner.exist?(/nope/) match_values_cleared?(scanner) # => true @@ -459,7 +460,7 @@ match_values_cleared?(scanner) # => true Successful unnamed capture match attempt: -``` +```rb scanner = StringScanner.new('foobarbazbatbam') scanner.exist?(/(foo)bar(baz)bat(bam)/) put_match_values(scanner) @@ -485,7 +486,7 @@ put_match_values(scanner) Successful named capture match attempt; same as unnamed above, except for #named_captures: -``` +```rb scanner = StringScanner.new('foobarbazbatbam') scanner.exist?(/(?<x>foo)bar(?<y>baz)bat(?<z>bam)/) scanner.named_captures # => {"x"=>"foo", "y"=>"baz", "z"=>"bam"} @@ -493,7 +494,7 @@ scanner.named_captures # => {"x"=>"foo", "y"=>"baz", "z"=>"bam"} Failed unnamed capture match attempt: -``` +```rb scanner = StringScanner.new('somestring') scanner.exist?(/(foo)bar(baz)bat(bam)/) match_values_cleared?(scanner) # => true @@ -502,7 +503,7 @@ match_values_cleared?(scanner) # => true Failed named capture match attempt; same as unnamed above, except for #named_captures: -``` +```rb scanner = StringScanner.new('somestring') scanner.exist?(/(?<x>foo)bar(?<y>baz)bat(?<z>bam)/) match_values_cleared?(scanner) # => false @@ -517,7 +518,7 @@ which determines the meaning of `'\A'`: * `false` (the default): matches the current byte position. - ``` + ```rb scanner = StringScanner.new('foobar') scanner.scan(/\A./) # => "f" scanner.scan(/\A./) # => "o" @@ -528,7 +529,7 @@ which determines the meaning of `'\A'`: * `true`: matches the beginning of the target substring; never matches unless the byte position is zero: - ``` + ```rb scanner = StringScanner.new('foobar', fixed_anchor: true) scanner.scan(/\A./) # => "f" scanner.scan(/\A./) # => nil |