Parslet

A simple parser generator library. Typical usage would look like this:

require 'parslet'

class MyParser < Parslet::Parser
  rule(:a) { str('a').repeat }
  root(:a)        
end

pp MyParser.new.parse('aaaa')   # => 'aaaa'@0
pp MyParser.new.parse('bbbb')   # => Parslet::Atoms::ParseFailed: 
                                #    Don't know what to do with bbbb at line 1 char 1.

The simple DSL allows you to define grammars in PEG-style. This kind of grammar construction does away with the ambiguities that usually comes with parsers; instead, it allows you to construct grammars that are easier to debug, since less magic is involved.

Parslet is typically used in stages:

Parsing the input string; this yields an intermediary tree, see Parslet.any, Parslet.match, Parslet.str, Parslet::ClassMethods#rule and Parslet::ClassMethods#root.
Transformation of the tree into something useful to you, see Parslet::Transform, Parslet.simple, Parslet.sequence and Parslet.subtree.

The first stage is traditionally intermingled with the second stage; output from the second stage is usually called the 'Abstract Syntax Tree' or AST.

The stages are completely decoupled; You can change your grammar around and use the second stage to isolate the rest of your code from the changes you've effected.

When things go wrong

A parse that fails will raise {Parslet::ParseFailed}. This exception contains all the details of what went wrong, including a detailed error trace that can be printed out as an ascii tree. ({Parslet::Cause})

Public Class Methods

any() click to toggle source

Returns an atom matching any character. It acts like the '.' (dot) character in regular expressions.

any.parse('a')    # => 'a'

@return [Parslet::Atoms::Re] a parslet atom

# File lib/parslet.rb, line 183
def any
  Atoms::Re.new('.')
end

exp(str) click to toggle source

A special kind of atom that allows embedding whole treetop expressions into parslet construction.

# the same as str('a') >> str('b').maybe
exp(%Q("a" "b"?))

@param str [String] a treetop expression @return [Parslet::Atoms::Base] the corresponding parslet parser

# File lib/parslet.rb, line 197
def exp(str)
  Parslet::Expression.new(str).to_parslet
end

included(base) click to toggle source

Extends classes that include Parslet with the module {Parslet::ClassMethods}.

# File lib/parslet.rb, line 52
def self.included(base)
  base.extend(ClassMethods)
end

match(str=nil) click to toggle source

Returns an atom matching a character class. All regular expressions can be used, as long as they match only a single character at a time.

match('[ab]')     # will match either 'a' or 'b'
match('[\n\s]')   # will match newlines and spaces

There is also another (convenience) form of this method:

match['a-z']      # synonymous to match('[a-z]')
match['\n']       # synonymous to match('[\n]')

@overload match(str)

@param str [String] character class to match (regexp syntax)
@return [Parslet::Atoms::Re] a parslet atom

# File lib/parslet.rb, line 157
def match(str=nil)
  return DelayedMatchConstructor.new unless str
  
  return Atoms::Re.new(str)
end

sequence(symbol) click to toggle source

Returns a placeholder for a tree transformation that will only match a sequence of elements. The symbol you specify will be the key for the matched sequence in the returned dictionary.

# This would match a body element that contains several declarations.
{ :body => sequence(:declarations) }

The above example would match :body => ['a', 'b'], but not :body => 'a'.

see {Parslet::Transform}

# File lib/parslet.rb, line 214
def sequence(symbol)
  Pattern::SequenceBind.new(symbol)
end

simple(symbol) click to toggle source

Returns a placeholder for a tree transformation that will only match simple elements. This matches everything that #sequence doesn't match.

# Matches a single header. 
{ :header => simple(:header) }

see {Parslet::Transform}

# File lib/parslet.rb, line 228
def simple(symbol)
  Pattern::SimpleBind.new(symbol)
end

str(str) click to toggle source

Returns an atom matching the str given:

str('class')      # will match 'class'

@param str [String] string to match verbatim @return [Parslet::Atoms::Str] a parslet atom

# File lib/parslet.rb, line 171
def str(str)
  Atoms::Str.new(str)
end

subtree(symbol) click to toggle source

Returns a placeholder for tree transformation patterns that will match any kind of subtree.

{ :expression => subtree(:exp) }

# File lib/parslet.rb, line 238
def subtree(symbol)
  Pattern::SubtreeBind.new(symbol)
end

Home Classes Methods

In Files

Namespace

Methods

Files

Class/Module Index

Parslet

Further reading

When things go wrong

Public Class Methods