: Citrus [Citrus API Documentation]

Citrus is a compact and powerful parsing library for Ruby that combines the elegance and expressiveness of the language with the simplicity and power of parsing expressions.

mjackson.github.io/citrus

Methods

public class

cache
eval
load
require
rule

Classes and Modules

Module Citrus::Grammar
Module Citrus::GrammarMethods
Module Citrus::Nonterminal
Module Citrus::Proxy
Module Citrus::Rule
Class Citrus::Alias
Class Citrus::AndPredicate
Class Citrus::ButPredicate
Class Citrus::Choice
Class Citrus::Error
Class Citrus::Input
Class Citrus::LoadError
Class Citrus::Match
Class Citrus::MemoizedInput
Class Citrus::NotPredicate
Class Citrus::ParseError
Class Citrus::Repeat
Class Citrus::Sequence
Class Citrus::StringTerminal
Class Citrus::Super
Class Citrus::SyntaxError
Class Citrus::Terminal

Constants

DOT	=	/./mu	A pattern to match any character, including newline.
Infinity	=	1.0 / 0
CLOSE	=	-1

Public class methods

cache ()

Returns a map of paths of files that have been loaded via load to the result of eval on the code in that file.

Note: These paths are not absolute unless you pass an absolute path to load. That means that if you change the working directory and try to require the same file with a different relative path, it will be loaded twice.

[show source]

    # File lib/citrus.rb, line 29
29:   def self.cache
30:     @cache ||= {}
31:   end

eval (code, options={})

Evaluates the given Citrus parsing expression grammar code and returns an array of any grammar modules that are created. Accepts the same options as GrammarMethods#parse.

Citrus.eval(<<CITRUS)
grammar MyGrammar
  rule abc
    "abc"
  end
end
CITRUS
# => [MyGrammar]

[show source]

    # File lib/citrus.rb, line 46
46:   def self.eval(code, options={})
47:     File.parse(code, options).value
48:   end

load (file, options={})

Loads the grammar(s) from the given file. Accepts the same options as eval, plus the following:

force: Normally this method will not reload a file that is already in the cache. However, if this option is true the file will be loaded, regardless of whether or not it is in the cache. Defaults to false.

Citrus.load('mygrammar')
# => [MyGrammar]

[show source]

    # File lib/citrus.rb, line 71
71:   def self.load(file, options={})
72:     file += '.citrus' unless /\.citrus$/ === file
73:     force = options.delete(:force)
74: 
75:     if force || !cache[file]
76:       begin
77:         cache[file] = eval(::File.read(file), options)
78:       rescue SyntaxError => e
79:         e.message.replace("#{::File.expand_path(file)}: #{e.message}")
80:         raise e
81:       end
82:     end
83: 
84:     cache[file]
85:   end

require (file, options={})

Searches the $LOAD_PATH for a file with the .citrus suffix and attempts to load it via load. Returns the path to the file that was loaded on success, nil on failure. Accepts the same options as load.

path = Citrus.require('mygrammar')
# => "/path/to/mygrammar.citrus"
Citrus.cache[path]
# => [MyGrammar]

[show source]

     # File lib/citrus.rb, line 96
 96:   def self.require(file, options={})
 97:     file += '.citrus' unless /\.citrus$/ === file
 98:     found = nil
 99: 
100:     paths = ['']
101:     paths += $LOAD_PATH unless Pathname.new(file).absolute?
102:     paths.each do |path|
103:       found = Dir[::File.join(path, file)].first
104:       break if found
105:     end
106: 
107:     if found
108:       Citrus.load(found, options)
109:     else
110:       raise LoadError, "Cannot find file #{file}"
111:     end
112: 
113:     found
114:   end

rule (expr, options={})

Evaluates the given expression and creates a new Rule object from it. Accepts the same options as eval.

Citrus.rule('"a" | "b"')
# => #<Citrus::Rule: ... >

[show source]

    # File lib/citrus.rb, line 56
56:   def self.rule(expr, options={})
57:     eval(expr, options.merge(:root => :expression))
58:   end