BPLUS-PARSER

The bplus-parser library is a set of parsers and combinators inspired by the FParsec library. The goal was to create an easy to use, TypeScript friendly version of those libraries.

Note

This project is maintained over at GitLab: https://gitlab.com/adleatherwood/bplus-parser

Install

https://www.npmjs.com/package/bplus-parser

npm i bplus-parser

Example Usage

Here's a basic example setup to parse the name and parameters of some function. This is a basic example of the patterns that are used to build a parser.

/* typescript */

// some structures to hold our parsed data in
type FunctionInfo = {
    name: string
    params: ParamInfo[]
}

type ParamInfo = {
    name: string
    type: string
}

// a function for creating space insensitive parsers
let syntax = (value: string) =>                                                |
    Parser.combine(many(space))
        .take(exact(value))                 // 'take' discards previous and keeps the current value
        .skip(many(space))                  // 'skip' parses but ignores values
        .build()                            // 'build' returns a single unified parser

// a parser for finding an unknown name
let id =
    Parser.combine(many1(char("ID", /[a-z]/)))
        .map(a => a.join(""))               // 'map' restructures parsed values
        .build("id")                        // 'build' takes a "label" for the parser

// a parser that returns a ParamInfo
let param =
    Parser.combine(id)
        .skip(syntax(":"))
        .and(id)                            // 'and' keeps previous values
        .map(args => {
            return {
                name: args[0],
                type: args[1]
            } as ParamInfo
        })
        .build()

// a parser that returns a FunctionInfo
let parser =
    Parser.combine(many(space))             // 'many' is a zero to (n) parser
        .skip(syntax("function"))
        .take(id)
        .skip(syntax("("))
        .and(separated(syntax(","), param))// 'separated' parses delimited values
        .map(args => {
            return {
                name: args[0],
                params: args[1]
            } as FunctionInfo
        })
        .build()

// a "stream" of input to be parsed
let stream = StringStream.create(`
function create(name: string, value: int) {
    ...
}`)

// parsing the stream
let result = parser.parse(stream)

// debugging parsers is sometimes challenging, printing the result can help
console.log(result)

// deconstructing the result
let value = Result.match(result,
    success => success.value,
    failure => { throw failure.error })

expect(value.name).toBe("create")
expect(value.params[0].name).toBe("name")
expect(value.params[0].type).toBe("string")
expect(value.params[1].name).toBe("value")
expect(value.params[1].type).toBe("int")

It's basically all about combining small parsers together to build bigger parsers.

Parsers

In the following signatures, we'll assume that 'a', 'b', 'c', etc. are parsers.

Value Parser Constructors

| Name | Signature | Function | | --------- | ------------ | ----------------------------------------------------- | | exact | (a) => a | Returns the exact value if matched | | between | (a,o,c) => a | Returns the result of 'a' from in between 'o' and 'c' | | separated | (a, d) => | Returns an 'a' array that is delimited by 'd' |

Parser Modifiers

| Name | Signature | Function | | ------- | ----------- | ------------------------------------------------------------------------- | | maybe | (a) => a | If the parser succeeds it returns the value, otherwise undefined | | many | (a) => a[] | Returns 0 to (n) values depending on many times the parser succeeds | | many1 | (a) => a[] | Like 'many', but returns 1 to (n) values and fails if no values are found | | any | (...a) => a | Returns the result of the first successful parser of the array | | attempt | (a) => a | For ensuring you can walk back the stream index if the parser fails | | map | (a) => b | For transforming input to a different type | | labeled | (a) => a | Adds a label to the current parser |

Parser Helpers (Mapping)

| Name | Signature | Function | | ---------- | -------------------- | --------------------------------------------------------- | | flatten3-8 | ((a,b),c) => [a,b,c] | Takes nested tuples and flattens them into a single tuple |

String Specific Parser Constructors

| Name | Signature | Function | | ---- | --------- | ------------------------------------------------------------------- | | char | (ex) => c | Like 'exact', but takes a regular expression for a single character |

Predefined String Parsers

| Name | Function | | ------ | ------------------------------------------ | | space | Matches a single space | | letter | Matches any letter | | digit | Matches any digit | | number | Matches a number (e.g. "12", "1.2", "-12") |

The Parser Builder

The parser builder is intended to give you an intuitive way to combine smaller parsers into larger parsers. Here is a very simple example.

let testParser: Parser<string,string[]> =
    Parser.combine(exact("this"))
        .skip(space)
        .and(exact("is"))
        .skip(space)
        .and(exact("a"))
        .skip(space)
        .and(exact("test"))
        // the result before 'flattening' is [[["this","is"],"a"],"test"]
        .map(flatten4)
        // the result after 'flattening' is ["this","is","a","test"]
        .build()

Here's a more complex example for the parsing of a number with a line by line breakdown.

const numberParser: Parser<string,number> =
    // Parser.combine() starts the builder workflow.  It takes a single parser.
    // Our first parser might return a "+" or a "-" or nothing as "-"
    Parser.combine(maybe(any(exact("+"), exact("-"))))
        // 'and' takes the previous sign and also returns 1 to (n) digits as ["-", [1,2,3]]
        .and(many1(digit))
        // this parser will return a decimal or undefined as [["-", [1,2,3]], "."]
        .and(maybe(exact(".")))
        // this parser will return 0 to (n) digits as [[["-", [1,2,3]], "."], [4,5,6]]
        .and(many(digit))
        // this helper will flatten out our nested tuples to ["-", [1,2,3], ".", [4,5,6]]
        .map(flatten4)
        // now we can easily put those parts together and return an actual number
        .map((a) => {
            const text = (a[0] || "") + (a[1].join("")) + (a[2] || "") + (a[3].join(""))
            return Number.parseFloat(text)
        })
        // build returns you a single parser for the parsers above
        .build()

The available builder functions are as follows:

| Name | Signature | Function | | ---- | --------------- | --------------------------------------------------------------------- | | and | (a, b) => [a,b] | Takes two parsers and returns a tuple of their results | | take | (a, b) => b | Discards and previously accumulated values and takes the value of 'b' | | skip | (a, b) => a | Skips the value of 'b' and keeps the value of 'a' |

Skip and take seem backwards, but in the context of a '.'-chained builder it fairly intuitive.

Streams

Streams conform to a specific interface.

export interface Stream<T> {
    tryTake(value: T): Option<[T, Stream<T>]>
    eof(): boolean
}

Below are the existing stream already defined in the library.

String Stream

A general purpose stream for parsing strings.

let stream - StringStream.create('this is a test')

A case insensitive stream can be created with the following.

let stream - StringStream.create('this is a test', { caseInsensitive: true })

Icons made by freepik