File: parslet.rb [parslet-1.4.0 Documentation]

Last Modified
  2014-03-06 22:10:35 +0000
Requires
  - parslet/slice
  - parslet/cause
  - parslet/source
  - parslet/atoms
  - parslet/pattern
  - parslet/pattern/binding
  - parslet/transform
  - parslet/parser
  - parslet/error_reporter

## Description

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})