FootlessParser: updated documentation and readme

08 Jun 2015 ❘ FootlessParser

The FootlessParser project is finally becoming usable and now has brand-new documentation generated by jazzy. The readme has also received some attention and is now actually useful:

FootlessParser is a simple and pretty naive implementation of a parser combinator in Swift. It enables infinite lookahead, non-ambiguous parsing with error reporting.

Also check out a series of blog posts about the development and documentation from the source code.

Introduction

In short, FootlessParser lets you define parsers like this:

let parser = function1 <^> parser1 <*> parser2 <|> parser3

function1 and parser3 return the same type.

parser will pass the input to parser1 followed by parser2, pass their results to function1 and return its result. If that fails it will pass the original input to parser3 and return its result.

Example

CSV parser

let delimiter = "," as Character
let quote = """ as Character
let newline = "n" as Character

let cell = char(quote) *> zeroOrMore(not(quote)) <* char(quote)
    <|> zeroOrMore(noneOf([delimiter, newline]))

let row = extend <^> cell <*> zeroOrMore( char(delimiter) *> cell ) <* char(newline)
let csvparser = zeroOrMore(row)

Here a cell (or field) either:

begins with a “, then contains anything, including commas, tabs and newlines, and ends with a “ (both quotes are discarded)
or is unquoted and contains anything but a comma or a newline.

Each row then consists of one or more cells, separated by commas and ended by a newline. The extend function joins the cells together into an array. Finally the csvparser collects zero or more rows into an array.

To perform the actual parsing:

let result = parse(csvparser, csvtext)
if let output = result.value {
    // output is an array of all the rows, 
    // where each row is an array of all its cells.
} else if let error = result.error {
    println(error)
}

The parse function returns a Result which if successful contains the output from the parser, or in case of failure contains the error.

Installation

Using Carthage

 github "kareman/FootlessParser"

Then run carthage update.

Follow the current instructions in Carthage’s README for up to date installation instructions.