Module: Parslet

### Home Classes Methods

### In Files

- lib/parslet/cause.rb
- lib/parslet/error_reporter/deepest.rb
- lib/parslet/error_reporter/tree.rb
- lib/parslet/source.rb
- lib/parslet.rb

### Namespace

- MODULE Parslet::Atoms
- MODULE Parslet::ClassMethods
- MODULE Parslet::ErrorReporter
- CLASS Parslet::Cause
- CLASS Parslet::DelayedMatchConstructor
- CLASS Parslet::Expression
- CLASS Parslet::ParseFailed
- CLASS Parslet::Parser
- CLASS Parslet::Pattern
- CLASS Parslet::Slice
- CLASS Parslet::Source
- CLASS Parslet::Transform
- CLASS Parslet::UnconsumedInput

### Methods

- ::any
- ::exp
- ::included
- ::match
- ::sequence
- ::simple
- ::str
- ::subtree

### Files

- README

### Class/Module Index

Quicksearch

- Parslet
- Parslet::Atoms
- Parslet::Atoms::Alternative
- Parslet::Atoms::Base
- Parslet::Atoms::CanFlatten
- Parslet::Atoms::Context
- Parslet::Atoms::DSL
- Parslet::Atoms::Entity
- Parslet::Atoms::Lookahead
- Parslet::Atoms::Named
- Parslet::Atoms::Precedence
- Parslet::Atoms::Re
- Parslet::Atoms::Repetition
- Parslet::Atoms::Sequence
- Parslet::Atoms::Str
- Parslet::Cause
- Parslet::ClassMethods
- Parslet::DelayedMatchConstructor
- Parslet::ErrorReporter
- Parslet::ErrorReporter::Deepest
- Parslet::ErrorReporter::Tree
- Parslet::Expression
- Parslet::Expression::Treetop
- Parslet::Expression::Treetop::Parser
- Parslet::Expression::Treetop::Transform
- Parslet::ParseFailed
- Parslet::Parser
- Parslet::Parser::PrettyPrinter
- Parslet::Parser::Visitors
- Parslet::Parser::Visitors::Citrus
- Parslet::Parser::Visitors::Treetop
- Parslet::Pattern
- Parslet::Pattern::SequenceBind
- Parslet::Pattern::SimpleBind
- Parslet::Pattern::SubtreeBind
- Parslet::Slice
- Parslet::Source
- Parslet::Source::LineCache
- Parslet::Source::RangeSearch
- Parslet::Transform
- Parslet::Transform::Context
- Parslet::UnconsumedInput

No matching classes.

# 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.

## Further reading

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

## 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.