summaryrefslogtreecommitdiff
path: root/doc/strscan
diff options
context:
space:
mode:
Diffstat (limited to 'doc/strscan')
-rw-r--r--doc/strscan/.document1
-rw-r--r--doc/strscan/helper_methods.md12
-rw-r--r--doc/strscan/link_refs.txt2
-rw-r--r--doc/strscan/methods/get_byte.md7
-rw-r--r--doc/strscan/methods/get_charpos.md5
-rw-r--r--doc/strscan/methods/get_pos.md5
-rw-r--r--doc/strscan/methods/getch.md9
-rw-r--r--doc/strscan/methods/scan.md7
-rw-r--r--doc/strscan/methods/scan_until.md7
-rw-r--r--doc/strscan/methods/set_pos.md8
-rw-r--r--doc/strscan/methods/skip.md5
-rw-r--r--doc/strscan/methods/skip_until.md13
-rw-r--r--doc/strscan/methods/terminate.md5
-rw-r--r--doc/strscan/strscan.md46
14 files changed, 50 insertions, 82 deletions
diff --git a/doc/strscan/.document b/doc/strscan/.document
new file mode 100644
index 0000000000..b8085a8474
--- /dev/null
+++ b/doc/strscan/.document
@@ -0,0 +1 @@
+helper_methods.md
diff --git a/doc/strscan/helper_methods.md b/doc/strscan/helper_methods.md
index 6555a2ce66..9fb1d79bba 100644
--- a/doc/strscan/helper_methods.md
+++ b/doc/strscan/helper_methods.md
@@ -10,7 +10,7 @@ Display scanner's situation:
- Character position (`#charpos`)
- Target string (`#rest`) and size (`#rest_size`).
-```
+```rb
scanner = StringScanner.new('foobarbaz')
scanner.scan(/foo/)
put_situation(scanner)
@@ -25,7 +25,7 @@ put_situation(scanner)
Display the scanner's match values:
-```
+```rb
scanner = StringScanner.new('Fri Dec 12 1975 14:39')
pattern = /(?<wday>\w+) (?<month>\w+) (?<day>\d+) /
scanner.match?(pattern)
@@ -53,7 +53,7 @@ put_match_values(scanner)
Returns whether the scanner's match values are all properly cleared:
-```
+```rb
scanner = StringScanner.new('foobarbaz')
match_values_cleared?(scanner) # => true
put_match_values(scanner)
@@ -75,7 +75,7 @@ match_values_cleared?(scanner) # => false
## The Code
-```
+```rb
def put_situation(scanner)
puts '# Situation:'
puts "# pos: #{scanner.pos}"
@@ -83,9 +83,7 @@ def put_situation(scanner)
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?}"
@@ -109,9 +107,7 @@ def put_match_values(scanner)
end
end
end
-```
-```
def match_values_cleared?(scanner)
scanner.matched? == false &&
scanner.matched_size.nil? &&
diff --git a/doc/strscan/link_refs.txt b/doc/strscan/link_refs.txt
index 19f6f7ce5c..04c4419982 100644
--- a/doc/strscan/link_refs.txt
+++ b/doc/strscan/link_refs.txt
@@ -1,5 +1,5 @@
[1]: rdoc-ref:StringScanner@Stored+String
-[2]: rdoc-ref:StringScanner@Byte+Position+-28Position-29
+[2]: rdoc-ref:StringScanner@Byte+Position+Position
[3]: rdoc-ref:StringScanner@Target+Substring
[4]: rdoc-ref:StringScanner@Setting+the+Target+Substring
[5]: rdoc-ref:StringScanner@Traversing+the+Target+Substring
diff --git a/doc/strscan/methods/get_byte.md b/doc/strscan/methods/get_byte.md
index 2f23be1899..775226638e 100644
--- a/doc/strscan/methods/get_byte.md
+++ b/doc/strscan/methods/get_byte.md
@@ -1,6 +1,3 @@
-call-seq:
- get_byte -> byte_as_character or nil
-
Returns the next byte, if available:
- If the [position][2]
@@ -10,7 +7,7 @@ Returns the next byte, if available:
- Increments the [byte position][2].
- Adjusts the [character position][7].
- ```
+ ```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
# => #<StringScanner 0/15 @ "\xE3\x81\x93\xE3\x82...">
scanner.string # => "こんにちは"
@@ -24,7 +21,7 @@ Returns the next byte, if available:
- Otherwise, returns `nil`, and does not change the positions.
- ```
+ ```rb
scanner.terminate
[scanner.get_byte, scanner.pos, scanner.charpos] # => [nil, 15, 5]
```
diff --git a/doc/strscan/methods/get_charpos.md b/doc/strscan/methods/get_charpos.md
index f77563c860..4de07897dc 100644
--- a/doc/strscan/methods/get_charpos.md
+++ b/doc/strscan/methods/get_charpos.md
@@ -1,11 +1,8 @@
-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:
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.getch # => "こ" # 3-byte character.
diff --git a/doc/strscan/methods/get_pos.md b/doc/strscan/methods/get_pos.md
index 56bcef3274..56b1636812 100644
--- a/doc/strscan/methods/get_pos.md
+++ b/doc/strscan/methods/get_pos.md
@@ -1,10 +1,7 @@
-call-seq:
- pos -> byte_position
-
Returns the integer [byte position][2],
which may be different from the [character position][7]:
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.pos # => 0
diff --git a/doc/strscan/methods/getch.md b/doc/strscan/methods/getch.md
index b57732ad7c..ede1d2b071 100644
--- a/doc/strscan/methods/getch.md
+++ b/doc/strscan/methods/getch.md
@@ -1,6 +1,3 @@
-call-seq:
- getch -> character or nil
-
Returns the next (possibly multibyte) character,
if available:
@@ -12,7 +9,7 @@ if available:
- Increments the [byte position][2]
by the size (in bytes) of the character.
- ```
+ ```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
[scanner.getch, scanner.pos, scanner.charpos] # => ["こ", 3, 1]
@@ -27,7 +24,7 @@ if available:
(that is, not at its beginning),
behaves like #get_byte (returns a 1-byte character):
- ```
+ ```rb
scanner.pos = 1
[scanner.getch, scanner.pos, scanner.charpos] # => ["\x81", 2, 2]
[scanner.getch, scanner.pos, scanner.charpos] # => ["\x93", 3, 1]
@@ -37,7 +34,7 @@ if available:
- If the [position][2] is at the end of the [stored string][1],
returns `nil` and does not modify the positions:
- ```
+ ```rb
scanner.terminate
[scanner.getch, scanner.pos, scanner.charpos] # => [nil, 15, 5]
```
diff --git a/doc/strscan/methods/scan.md b/doc/strscan/methods/scan.md
index 714fa9910a..805c797913 100644
--- a/doc/strscan/methods/scan.md
+++ b/doc/strscan/methods/scan.md
@@ -1,6 +1,3 @@
-call-seq:
- scan(pattern) -> substring or nil
-
Attempts to [match][17] the given `pattern`
at the beginning of the [target substring][3].
@@ -11,7 +8,7 @@ If the match succeeds:
and may increment the [character position][7].
- Sets [match values][9].
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.pos = 6
@@ -45,7 +42,7 @@ If the match fails:
- Does not increment byte and character positions.
- Clears match values.
-```
+```rb
scanner.scan(/nope/) # => nil
match_values_cleared?(scanner) # => true
```
diff --git a/doc/strscan/methods/scan_until.md b/doc/strscan/methods/scan_until.md
index 3b7ff2c3a9..5fb2912a1b 100644
--- a/doc/strscan/methods/scan_until.md
+++ b/doc/strscan/methods/scan_until.md
@@ -1,6 +1,3 @@
-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].
@@ -12,7 +9,7 @@ If the match attempt succeeds:
- Returns the matched substring.
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.pos = 6
@@ -46,7 +43,7 @@ If the match attempt fails:
- Returns `nil`.
- Does not update positions.
-```
+```rb
scanner.scan_until(/nope/) # => nil
match_values_cleared?(scanner) # => true
```
diff --git a/doc/strscan/methods/set_pos.md b/doc/strscan/methods/set_pos.md
index 230177109c..6a43edeb41 100644
--- a/doc/strscan/methods/set_pos.md
+++ b/doc/strscan/methods/set_pos.md
@@ -1,7 +1,3 @@
-call-seq:
- pos = n -> n
- pointer = n -> n
-
Sets the [byte position][2] and the [character position][11];
returns `n`.
@@ -9,7 +5,7 @@ Does not affect [match values][9].
For non-negative `n`, sets the position to `n`:
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.pos = 3 # => 3
@@ -19,7 +15,7 @@ scanner.charpos # => 1
For negative `n`, counts from the end of the [stored string][1]:
-```
+```rb
scanner.pos = -9 # => -9
scanner.pos # => 6
scanner.rest # => "にちは"
diff --git a/doc/strscan/methods/skip.md b/doc/strscan/methods/skip.md
index 656f134c5a..7e924b624b 100644
--- a/doc/strscan/methods/skip.md
+++ b/doc/strscan/methods/skip.md
@@ -1,6 +1,3 @@
-call-seq:
- skip(pattern) match_size or nil
-
Attempts to [match][17] the given `pattern`
at the beginning of the [target substring][3];
@@ -11,7 +8,7 @@ If the match succeeds:
- Sets [match values][9].
- Returns the size (bytes) of the matched substring.
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.pos = 6
diff --git a/doc/strscan/methods/skip_until.md b/doc/strscan/methods/skip_until.md
index 5187a4826f..a0ffab0b84 100644
--- a/doc/strscan/methods/skip_until.md
+++ b/doc/strscan/methods/skip_until.md
@@ -1,16 +1,14 @@
-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.
+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 size of the matched substring.
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.pos = 6
@@ -42,8 +40,9 @@ If the match attempt fails:
- Clears match values.
- Returns `nil`.
+- Does not update positions.
-```
+```rb
scanner.skip_until(/nope/) # => nil
match_values_cleared?(scanner) # => true
```
diff --git a/doc/strscan/methods/terminate.md b/doc/strscan/methods/terminate.md
index fd55727099..27f7d41cb1 100644
--- a/doc/strscan/methods/terminate.md
+++ b/doc/strscan/methods/terminate.md
@@ -1,13 +1,10 @@
-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].
-```
+```rb
scanner = StringScanner.new(HIRAGANA_TEXT)
scanner.string # => "こんにちは"
scanner.scan_until(/に/)
diff --git a/doc/strscan/strscan.md b/doc/strscan/strscan.md
index 558568dc43..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.
@@ -204,7 +204,7 @@ put_situation(scanner)
## 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:
@@ -216,7 +216,7 @@ and its size is returned by method #rest_size.
Examples:
-```
+```rb
scanner = StringScanner.new('foobarbaz')
put_situation(scanner)
# Situation:
@@ -417,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>. |
@@ -430,7 +430,7 @@ See examples below.
Successful basic match attempt (no captures):
-```
+```rb
scanner = StringScanner.new('foobarbaz')
scanner.exist?(/bar/)
put_match_values(scanner)
@@ -452,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
@@ -460,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)
@@ -486,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"}
@@ -494,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
@@ -503,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
@@ -518,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"
@@ -529,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
generated by cgit v1.2.3 (git 2.25.1) at 2026-06-05 20:44:00 +0000