lazyhelper

Lazy parser is constructed when parsing starts. It is useful to reference a parser not defined yet
example:
parser = lazy{future}
future = 'jim'.r
assert_equal 'jim', parser.parse '12323'

one_of(str) helper

Parses one of chars in str
example:
multiplicative = one_of '*/%'
assert_equal '/', multiplicative.parse '/'
assert_equal Rsec::INVALID, actualmultiplicative.parse '+'

one_of_(str) helper

See also #one_of#, with leading and trailing optional breakable spaces
example:
additive = one_of_('+-')
assert_equal '+', additive.parse('  +')

prim(type, options={}) helper

Primitive parser, returns nil if overflow or underflow.
There can be an optional '+' or '-' at the beginning of string except unsinged_int32 | unsinged_int64.
type =
  :double |
  :hex_double |
  :int32 |
  :int64 |
  :unsigned_int32 |
  :unsigned_int64
options:
  :allowed_sign => '+' | '-' | '' | '+-' (default '+-')
  :allowed_signs => (same as :allowed_sign)
  :base => integer only (default 10)
example:
p = prim :double
assert_equal 1.23, p.parse('1.23')
p = prim :double, allowed_sign: '-'
assert_equal 1.23, p.parse('1.23')
assert_equal -1.23, p.parse('-1.23')
assert_equal Rsec::INVALID, p.parse('+1.23')
p = prim :int32, base: 36
assert_equal 49713, p.parse('12cx')

seq(*xs) helper

Sequence parser
example:
assert_equal ['a', 'b', 'c'], actualseq('a', 'b', 'c').parse('abc')

seq_(*xs) helper

Sequence parser with skippable pattern(or parser)
option
  :skip default= /\s*/
example:
assert_equal ['a', 'b', 'c'], actualseq_('a', 'b', 'c', skip: ',').parse('a,b,c')

symbol(pattern, skip=/\s*/) helper

A symbol is something wrapped with optional space

word(pattern) helper

A word is wrapped with word boundaries
example:
assert_equal ['yes', '3'], seq('yes', '3').parse('yes3')
assert_equal INVALID, seq(word('yes'), '3').parse('yes3')

map(lambda_p=nil)

Transform result
example:
parser = /\w+/.r.map{|word| word * 2}
assert_equal 'hellohello', parser.parse!('hello')

join(inter)

"p.join('+')" parses strings like "p+p+p+p+p".
Note that at least 1 of p appears in the string.
Sometimes it is useful to reverse the joining:
/\s*/.r.join('p').odd parses string like " p p  p "

|(y)

Branch parser, note that rsec is a PEG parser generator,
beware of the difference between PEG and CFG.

*(n)

Repeat n or in a range.
If range.end < 0, repeat at least range.begin
(Infinity and -Infinity are considered)

maybe

Appears 0 or 1 times, result is wrapped in an array
example:
parser = 'a'.r.maybe
assert_equal ['a'], parser.parse('a')
assert_equal [], parser.parse('')

star

Kleen star, 0 or more any times

&(other)

Lookahead predicate, note that other can be a very complex parser

^(other)

Negative lookahead predicate

fail(*tokens)

When parsing failed, show "expect tokens" error

>>(other)

Short for seq_(parser, other)[1]

<<(other)

Short for seq_(parser, other)[0]

eof

Should be end of input after parse

cached

Packrat parser combinator, returns a parser that caches parse result, may optimize performance

[](idx) seq, seq_

Returns the parse result at idx, shorter and faster than map{|array| array[idx]}
example:
assert_equal 'b', seq('a', 'b', 'c')[1].parse('abc')

unboxseq, seq_, join, join.even, join.odd

If parse result contains only 1 element, return the element instead of the array

inner

Think about "innerHTML"!
example:
parser = seq('<b>', /[\w\s]+/, '</b>').inner
parser.parse('<b>the inside</b>')

evenjoin

Only keep the even(left, token) parts

oddjoin

Only keep the odd(right, inter) parts

untilr

Scan until the pattern happens

_?

alias for maybe

expect

alias for fail