Contents

= koi-reference-parser

This is the reference parser implementation for the programming language {Koi}[http://github.com/aarongough/koi]. The parser is implemented using a {Parsing Expression Grammar (PEG)}[http://en.wikipedia.org/wiki/Parsing_expression_grammar] that is run by a PEG engine called {Treetop}[http://treetop.rubyforge.org/].

=== Example

The parser takes a text string containing a program like:

  test = 1 + 2
  
And turns it into an {Abstract Syntax Tree (AST)}[http://en.wikipedia.org/wiki/Abstract_syntax_tree] that unambiguously represents the program's structure and meaning. The AST is represented as a series of Ruby objects that subclass a generic SyntaxNode class. The code above transformed into AST would look like:

  <Block "test = 1 + 2">
    <Statement "test = 1 + 2">
      <Assignment "test = 1 + 2">
        <Identifier "test">
        <AssignmentOperator "=">
        <Expression "1 + 2">
          <AdditiveExpression "1 + 2">
            <IntegerLiteral "1">
            <AdditionOperator "+">
            <IntegerLiteral "2">
            
The AST is also available in a far more portable format based on nested hashes by calling the to_hash method on the root AST node.

=== Installation

This parser is normally installed as part of Koi's default toolchain. However if you would like to install it on it's own you can do so by installing the gem like so:

  gem install koi-reference-parser

=== Usage

  require 'rubygems'
  require 'koi-reference-parser'
  
  include KoiReferenceParser
  
  ast = Parser.parse( program_text )
  
  # Get the AST as a portable nested hash
  ast_hash = ast.to_hash

=== Author & Credits

Author:: {Aaron Gough}[mailto:[e-mail]]

Copyright (c) 2010 {Aaron Gough}[http://thingsaaronmade.com/] ({thingsaaronmade.com}[http://thingsaaronmade.com/]), released under the MIT license

Version data entries

1 entries across 1 versions & 1 rubygems

Version	Path
koi-reference-parser-0.0.3	README.rdoc