module Citrus::Rule

A Rule is an object that is used by a grammar to create matches on an Input during parsing.

Attributes

extension[R]

The module this rule uses to extend new matches.

grammar[RW]

The grammar this rule belongs to, if any.

label[R]

A label for this rule. If a rule has a label, all matches that it creates will be accessible as named captures from the scope of their parent match using that label.

name[R]

The name of this rule.

Public Class Methods

for(obj) click to toggle source

Returns a new Rule object depending on the type of object given.

# File lib/citrus.rb, line 588
def self.for(obj)
  case obj
  when Rule     then obj
  when Symbol   then Alias.new(obj)
  when String   then StringTerminal.new(obj)
  when Regexp   then Terminal.new(obj)
  when Array    then Sequence.new(obj)
  when Range    then Choice.new(obj.to_a)
  when Numeric  then StringTerminal.new(obj.to_s)
  else
    raise ArgumentError, "Invalid rule object: #{obj.inspect}"
  end
end

Public Instance Methods

==(other) click to toggle source
Calls superclass method
# File lib/citrus.rb, line 731
def ==(other)
  case other
  when Rule
    to_s == other.to_s
  else
    super
  end
end
Also aliased as: eql?
===(obj) click to toggle source

Tests the given obj for case equality with this rule.

# File lib/citrus.rb, line 684
def ===(obj)
  !test(obj).nil?
end
elide?() click to toggle source

Returns true if this rule should extend a match but should not appear in its event stream.

# File lib/citrus.rb, line 695
def elide?
  false
end
eql?(other)
Alias for: ==
extension=(mod) click to toggle source

Specifies a module that will be used to extend all Match objects that result from this rule. If mod is a Proc, it is used to create an anonymous module with a value method.

# File lib/citrus.rb, line 626
def extension=(mod)
  if Proc === mod
    mod = Module.new { define_method(:value, &mod) }
  end

  raise ArgumentError, "Extension must be a Module" unless Module === mod

  @extension = mod
end
label=(label) click to toggle source

Sets the label of this rule.

# File lib/citrus.rb, line 614
def label=(label)
  @label = label.to_sym
end
name=(name) click to toggle source

Sets the name of this rule.

# File lib/citrus.rb, line 606
def name=(name)
  @name = name.to_sym
end
parse(source, options={}) click to toggle source

Attempts to parse the given string and return a Match if any can be made. options may contain any of the following keys:

consume

If this is true a ParseError will be raised unless the entire input string is consumed. Defaults to true.

memoize

If this is true the matches generated during a parse are memoized. See MemoizedInput for more information. Defaults to false.

offset

The offset in string at which to start parsing. Defaults to 0.

# File lib/citrus.rb, line 657
def parse(source, options={})
  opts = default_options.merge(options)

  input = (opts[:memoize] ? MemoizedInput : Input).new(source)
  string = input.string
  input.pos = opts[:offset] if opts[:offset] > 0

  events = input.exec(self)
  length = events[-1]

  if !length || (opts[:consume] && length < (string.length - opts[:offset]))
    raise ParseError, input
  end

  Match.new(input, events, opts[:offset])
end
terminal?() click to toggle source

Returns true if this rule is a Terminal.

# File lib/citrus.rb, line 689
def terminal?
  false
end
test(string, options={}) click to toggle source

Tests whether or not this rule matches on the given string. Returns the length of the match if any can be made, nil otherwise. Accepts the same options as parse.

# File lib/citrus.rb, line 677
def test(string, options={})
  parse(string, options).length
rescue ParseError
  nil
end
to_s() click to toggle source

Returns the Citrus notation of this rule as a string.

# File lib/citrus.rb, line 706
def to_s
  if label
    "#{label}:" + (needs_paren? ? "(#{to_citrus})" : to_citrus)
  else
    to_citrus
  end
end
Also aliased as: to_str
to_str()

This alias allows strings to be compared to the string representation of Rule objects. It is most useful in assertions in unit tests, e.g.:

assert_equal('"a" | "b"', rule)
Alias for: to_s