Parsihax

Parsihax is a small library for writing big parsers made up of lots of little parsers. The API is inspired by parsec, Promises/A+ and Parsimmon (originally, Parsihax was just supposed to be Parsimmon rewrite in Haxe).

Installation

Install the library via haxelib (library manager that comes with any Haxe distribution).

haxelib install parsihax 

API Documentation

Haxe-generated API documentation is available at documentation website, or see the annotated source of Parsihax.hx.

Examples

See the test directory for annotated examples of parsing JSON, simple Lisp-like structure and monad parser.

Basics

To use nice sugar syntax, simply add this to your Haxe file

import Parsihax.*;
using Parsihax;

A Parsihax.Parser parser is an abstract that represents an action on a stream of text, and the promise of either an object yielded by that action on success or a message in case of failure. For example, Parsihax.string('foo') yields the string 'foo' if the beginning of the stream is 'foo', and otherwise fails.

The method .map is used to transform the yielded value. For example,

'foo'.string()
  .map(function(x) return x + 'bar');

will yield 'foobar' if the stream starts with 'foo'. The parser

~/[0-9]+/.regexp()
  .map(function(x) return Std.parseInt(x) * 2);

will yield the number 24 when it encounters the string '12'.

Also, Parsihax supports nice monad sugar syntax (thanks to Monax). For example,

monad({
  a <= "a".string();
  b <= "b".string();
  c <= "c".string();
  ret([a,b,c]);
});

will yield [ 'a', 'b', 'c'] when it encounters the string 'abc'.

Getting parse from a Parsihax.Parser (or explicitly casting it to Parsihax.Function returns parsing function String -> ?Int -> Result<A> (or just Parsihax.Function), that parses the string and returns a Parsihax.Result with a boolean status flag, indicating whether the parse succeeded. If it succeeded, the value attribute will contain the yielded value. Otherwise, the index and expected attributes will contain the offset of the parse error, and a sorted, unique array of messages indicating what was expected.

The error object can be passed along with the original source to Parsihax.formatError to obtain a human-readable error string.

Changing Parsihax.Parser.parse value changes Parsihax.Parser behaviour, but still keeps it's reference, what is really usefull in recursive parsers.