Class

Class Methods

Returns a new StringScanner object whose [stored string][1] is the given string; sets the [fixed-anchor property][10]:

scanner = StringScanner.new('foobarbaz')
scanner.string
scanner.fixed_anchor?
put_situation(scanner)

Instance Methods

Returns a captured substring or nil; see [Captured Match Values][13].

When there are captures:

scanner = StringScanner.new('Fri Dec 12 1975 14:39')
scanner.scan(/(?<wday>\w+) (?<month>\w+) (?<day>\d+) /)

specifier zero: returns the entire matched substring:
```
scanner[0]
scanner.pre_match
scanner.post_match
```
specifier positive integer. returns the nth capture, or nil if out of range:
```
scanner[1]
scanner[2]
scanner[3]
scanner[4]
```
specifier negative integer. counts backward from the last subgroup:
```
scanner[-1]
scanner[-4]
scanner[-5]
```

specifier symbol or string. returns the named subgroup, or nil if no such:

scanner[:wday]
scanner['wday']
scanner[:month]
scanner[:day]
scanner[:nope]

When there are no captures, only [0] returns non-nil:

scanner = StringScanner.new('foobarbaz')
scanner.exist?(/bar/)
scanner[0]
scanner[1]

For a failed match, even [0] returns nil:

scanner.scan(/nope/)
scanner[0]
scanner[1]

Returns whether the [position][2] is at the beginning of a line; that is, at the beginning of the [stored string][1] or immediately after a newline:

scanner = StringScanner.new(MULTILINE_TEXT)
scanner.string
scanner.pos
scanner.beginning_of_line?
scanner.scan_until(/,/)
scanner.beginning_of_line?
scanner.scan(/\n/)
scanner.beginning_of_line?
scanner.terminate
scanner.beginning_of_line?
scanner.concat('x')
scanner.terminate
scanner.beginning_of_line?

StringScanner#bol? is an alias for StringScanner#beginning_of_line?.

Returns the array of [captured match values][13] at indexes (1..) if the most recent match attempt succeeded, or nil otherwise:

scanner = StringScanner.new('Fri Dec 12 1975 14:39')
scanner.captures
scanner.exist?(/(?<wday>\w+) (?<month>\w+) (?<day>\d+) /)
scanner.captures
scanner.values_at(*0..4)
scanner.exist?(/Fri/)
scanner.captures
scanner.scan(/nope/)
scanner.captures

No documentation available

Attempts to [match][17] the given pattern at the beginning of the [target substring][3]; does not modify the [positions][11].

If the match succeeds:

Returns the matched substring.
Sets all [match values][9].

scanner = StringScanner.new('foobarbaz')
scanner.pos = 3
scanner.check('bar')
put_match_values(scanner)
put_situation(scanner)

If the match fails:

Returns nil.
Clears all [match values][9].

scanner.check(/nope/)
match_values_cleared?(scanner)

Attempts to [match][17] the given pattern anywhere (at any [position][2]) in the [target substring][3]; does not modify the [positions][11].

If the match succeeds:

Sets all [match values][9].
Returns the matched substring, which extends from the current [position][2] to the end of the matched substring.

scanner = StringScanner.new('foobarbazbatbam')
scanner.pos = 6
scanner.check_until(/bat/)
put_match_values(scanner)
put_situation(scanner)

If the match fails:

Clears all [match values][9].
Returns nil.

scanner.check_until(/nope/)
match_values_cleared?(scanner)

Appends the given more_string to the [stored string][1].
Returns self.
Does not affect the [positions][11] or [match values][9].

scanner = StringScanner.new('foo')
scanner.string
scanner.terminate
scanner.concat('barbaz')
scanner.string
put_situation(scanner)

Returns whether the [position][2] is at the end of the [stored string][1]:

scanner = StringScanner.new('foobarbaz')
scanner.eos?
pos = 3
scanner.eos?
scanner.terminate
scanner.eos?

Attempts to [match][17] the given pattern anywhere (at any [position][2]) n the [target substring][3]; does not modify the [positions][11].

If the match succeeds:

Returns a byte offset: the distance in bytes between the current [position][2] and the end of the matched substring.
Sets all [match values][9].

scanner = StringScanner.new('foobarbazbatbam')
scanner.pos = 6
scanner.exist?(/bat/)
put_match_values(scanner)
put_situation(scanner)

If the match fails:

Returns nil.
Clears all [match values][9].

scanner.exist?(/nope/)
match_values_cleared?(scanner)

Returns whether the [fixed-anchor property][10] is set.

No documentation available

Returns a shallow copy of self; the [stored string][1] in the copy is the same string as in self.

Returns a string representation of self that may show:

The current [position][2].
The size (in bytes) of the [stored string][1].
The substring preceding the current position.
The substring following the current position (which is also the [target substring][3]).

scanner = StringScanner.new("Fri Dec 12 1975 14:39")
scanner.pos = 11
scanner.inspect

If at beginning-of-string, item 4 above (following substring) is omitted:

scanner.reset
scanner.inspect

If at end-of-string, all items above are omitted:

scanner.terminate
scanner.inspect

Attempts to [match][17] the given pattern at the beginning of the [target substring][3]; does not modify the [positions][11].

If the match succeeds:

Sets [match values][9].
Returns the size in bytes of the matched substring.

scanner = StringScanner.new('foobarbaz')
scanner.pos = 3
scanner.match?(/bar/) => 3
put_match_values(scanner)
put_situation(scanner)

If the match fails:

Clears match values.
Returns nil.
Does not increment positions.

scanner.match?(/nope/)
match_values_cleared?(scanner)

Returns the matched substring from the most recent [match][17] attempt if it was successful, or nil otherwise; see [Basic Matched Values][18]:

scanner = StringScanner.new('foobarbaz')
scanner.matched
scanner.pos = 3
scanner.match?(/bar/)
scanner.matched
scanner.match?(/nope/)
scanner.matched

Returns true of the most recent [match attempt][17] was successful, false otherwise; see [Basic Matched Values][18]:

scanner = StringScanner.new('foobarbaz')
scanner.matched?
scanner.pos = 3
scanner.exist?(/baz/)
scanner.matched?
scanner.exist?(/nope/)
scanner.matched?

Returns the size (in bytes) of the matched substring from the most recent match [match attempt][17] if it was successful, or nil otherwise; see [Basic Matched Values][18]:

scanner = StringScanner.new('foobarbaz')
scanner.matched_size
pos = 3
scanner.exist?(/baz/)
scanner.matched_size
scanner.exist?(/nope/)
scanner.matched_size

Returns the array of captured match values at indexes (1..) if the most recent match attempt succeeded, or nil otherwise; see [Captured Match Values][13]:

scanner = StringScanner.new('Fri Dec 12 1975 14:39')
scanner.named_captures
pattern = /(?<wday>\w+) (?<month>\w+) (?<day>\d+) /
scanner.match?(pattern)
scanner.named_captures
scanner.string = 'nope'
scanner.match?(pattern)
scanner.named_captures
scanner.match?(/nosuch/)
scanner.named_captures

Returns the substring string[pos, length]; does not update [match values][9] or [positions][11]:

scanner = StringScanner.new('foobarbaz')
scanner.pos = 3
scanner.peek(3)
scanner.terminate
scanner.peek(3)

Peeks at the current byte and returns it as an integer.

s = StringScanner.new('ab')
s.peek_byte

No documentation available

Returns the substring that follows the matched substring from the most recent match attempt if it was successful, or nil otherwise; see [Basic Match Values][18]:

scanner = StringScanner.new('foobarbaz')
scanner.post_match
scanner.pos = 3
scanner.match?(/bar/)
scanner.post_match
scanner.match?(/nope/)
scanner.post_match

Returns the substring that precedes the matched substring from the most recent match attempt if it was successful, or nil otherwise; see [Basic Match Values][18]:

scanner = StringScanner.new('foobarbaz')
scanner.pre_match
scanner.pos = 3
scanner.exist?(/baz/)
scanner.pre_match
scanner.exist?(/nope/)
scanner.pre_match

Sets both [byte position][2] and [character position][7] to zero, and clears [match values][9]; returns +self+:

scanner = StringScanner.new('foobarbaz')
scanner.exist?(/bar/)
scanner.reset
put_situation(scanner)
match_values_cleared?(scanner)

Returns the ‘rest’ of the [stored string][1] (all after the current [position][2]), which is the [target substring][3]:

scanner = StringScanner.new('foobarbaz')
scanner.rest
scanner.pos = 3
scanner.rest
scanner.terminate
scanner.rest

Returns the size (in bytes) of the rest of the [stored string][1]:

scanner = StringScanner.new('foobarbaz')
scanner.rest
scanner.rest_size
scanner.pos = 3
scanner.rest
scanner.rest_size
scanner.terminate
scanner.rest
scanner.rest_size

No documentation available

Scans one byte and returns it as an integer. This method is not multibyte character sensitive. See also: getch.

If base isn’t provided or is 10, then it is equivalent to calling scan with a ‘[+-]?\d+` pattern, and returns an Integer or nil.

If base is 16, then it is equivalent to calling scan with a ‘[+-]?(0x)?[0-9a-fA-F]+` pattern, and returns an Integer or nil.

The scanned string must be encoded with an ASCII compatible encoding, otherwise Encoding::CompatibilityError will be raised.

No documentation available

Returns the count of captures if the most recent match attempt succeeded, nil otherwise; see [Captures Match Values][13]:

scanner = StringScanner.new('Fri Dec 12 1975 14:39')
scanner.size
pattern = /(?<wday>\w+) (?<month>\w+) (?<day>\d+) /
scanner.match?(pattern)
scanner.values_at(*0..scanner.size)
scanner.size
scanner.match?(/nope/)
scanner.size

No documentation available

Returns the [stored string][1]:

scanner = StringScanner.new('foobar')
scanner.string
scanner.concat('baz')
scanner.string

Replaces the [stored string][1] with the given other_string:

Sets both [positions][11] to zero.
Clears [match values][9].
Returns other_string.

scanner = StringScanner.new('foobar')
scanner.scan(/foo/)
put_situation(scanner)
match_values_cleared?(scanner)
scanner.string = 'baz'
put_situation(scanner)
match_values_cleared?(scanner)

No documentation available

Sets the [position][2] to its value previous to the recent successful [match][17] attempt:

scanner = StringScanner.new('foobarbaz')
scanner.scan(/foo/)
put_situation(scanner)
scanner.unscan
put_situation(scanner)

Raises an exception if match values are clear:

scanner.scan(/nope/)
match_values_cleared?(scanner)
scanner.unscan

Returns an array of captured substrings, or nil of none.

For each specifier, the returned substring is [specifier]; see [].

scanner = StringScanner.new('Fri Dec 12 1975 14:39')
pattern = /(?<wday>\w+) (?<month>\w+) (?<day>\d+) /
scanner.match?(pattern)
scanner.values_at(*0..3)
scanner.values_at(*%i[wday month day])