Module: Parslet

Included in:
Expression, Parser, Transform, Transform
Defined in:
lib/parslet.rb,
lib/parslet/cause.rb,
lib/parslet/source.rb,
lib/parslet/error_reporter/tree.rb,
lib/parslet/error_reporter/deepest.rb

Overview

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.

Further reading

All parslet atoms are subclasses of Atoms::Base. You might want to look at all of those: Atoms::Re, Atoms::Str, Atoms::Repetition, Atoms::Sequence, Atoms::Alternative.

When things go wrong

A parse that fails will raise 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. (Cause)

Defined Under Namespace

Modules: Atoms, ClassMethods, ErrorReporter Classes: Cause, DelayedMatchConstructor, Expression, ParseFailed, Parser, Pattern, Slice, Source, Transform, UnconsumedInput

Class Method Summary collapse

Class Method Details

.any ⇒ Parslet::Atoms::Re

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

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

Returns:



183
184
185
 
# File 'lib/parslet.rb', line 183

def any
  Atoms::Re.new('.')
end

.exp(str) ⇒ Parslet::Atoms::Base

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"?))

Parameters:

  • str (String) —

    a treetop expression

Returns:



197
198
199
 
# File 'lib/parslet.rb', line 197

def exp(str)
  Parslet::Expression.new(str).to_parslet
end

.included(base) ⇒ Object

Extends classes that include Parslet with the module ClassMethods.



52
53
54
 
# File 'lib/parslet.rb', line 52

def self.included(base)
  base.extend(ClassMethods)
end

.match(str) ⇒ Parslet::Atoms::Re

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]')

Returns a parslet atom.

Parameters:

  • str (String) —

    character class to match (regexp syntax)

Returns:



157
158
159
160
161
 
# File 'lib/parslet.rb', line 157

def match(str=nil)
  return DelayedMatchConstructor.new unless str
  
  return Atoms::Re.new(str)
end

.sequence(symbol) ⇒ Object

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 Transform



214
215
216
 
# File 'lib/parslet.rb', line 214

def sequence(symbol)
  Pattern::SequenceBind.new(symbol)
end

.simple(symbol) ⇒ Object

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 Transform



228
229
230
 
# File 'lib/parslet.rb', line 228

def simple(symbol)
  Pattern::SimpleBind.new(symbol)
end

.str(str) ⇒ Parslet::Atoms::Str

Returns an atom matching the str given:

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

Parameters:

  • str (String) —

    string to match verbatim

Returns:



171
172
173
 
# File 'lib/parslet.rb', line 171

def str(str)
  Atoms::Str.new(str)
end

.subtree(symbol) ⇒ Object

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

{ :expression => subtree(:exp) }



238
239
240
 
# File 'lib/parslet.rb', line 238

def subtree(symbol)
  Pattern::SubtreeBind.new(symbol)
end