The Parser Computation Expression

While operators are powerful, the most readable way to sequence multiple parsing steps is often with a parser { ... } computation expression. It allows you to write parsers in a familiar, sequential style.

open XParsec.CharParsers

let pJsonString = between (pchar '"') (pchar '"') (manyChars (pitem '\\' >>. pid <|> noneOf ['"']))
let pJsonNumber = pfloat |>> string

let pKeyValuePair = parser {
    let! key = pJsonString
    do! pchar ':'
    let! value = pJsonString <|> pJsonNumber
    return (key, value)
}

This computation expression is the most efficient way to chain parsers. It takes advantage of the monadic form of computation expressions and uses inline and the InlineIfLambda attribute to compile down to highly efficient code with almost zero overhead.

Available Operations

The parser computation expression builder defines a number of methods that translate keywords within the block into specific parser operations.

let!

Sequences parsers by running one, binding its result, and then using that result to create the next parser in the sequence.

Example:

let nameAndAge = parser {
    let! name = manyChars letter
    do! pchar ':'
    let! age = pint32
    return (name, age)
}

// run nameAndAge "Alice:30"
// -> Ok ("Alice", 30)

do!

Used to execute a parser when its result is not needed (i.e., it returns unit). This is common in two main scenarios:

1. Consuming Input: For parsers that match and consume parts of the input stream that are not part of the final result, such as separators, keywords, or whitespace.
2. Managing State: For parsers that interact with the user state without consuming input, like setUserState or updateUserState.

Example: This parser parses a let binding and stores the variable in the parser's user state, which is a Map.

open XParsec.State

// Parses "let x=10" and updates the state map.
let pLetBinding = parser {
    // 1. Consume input without capturing a result
    do! pstring "let"
    do! skipMany1Satisfies System.Char.IsWhiteSpace

    let! varName = many1Chars letter
    do! pchar '='
    let! value = pint32

    // 2. Modify state without consuming input
    do! updateUserState (Map.add varName value)
}

// To run this parser:
// let initialState = Map.empty<string, int>
// let reader = Reader.ofString "let x=10" initialState
// match run pLetBinding reader with
// | Ok result ->
//     // result.Parsed is ()
//     // reader.State is Map [("x", 10)]
// | Error e -> ...

return

Takes a regular value and lifts it into a parser that successfully returns that value without consuming any input.

Example:

let pDefault = parser {
    // some complex logic...
    return "default value"
}

try...with

Catches exceptions that might be thrown during the parsing process.

Example:

let pWithExceptionHandling = parser {
    try
        // A parser that might throw an exception
        let! num = pstring "123" |>> (fun s -> int s / 0)
        return num
    with
    | :? System.DivideByZeroException -> return -1
}

while

Repeatedly executes a unit-returning parser as long as a condition holds.

Example:

let mutable count = 3
let pWhile = parser {
    while count > 0 do
        count <- count - 1
        do! pchar 'a'
}
// run pWhile "aaa"
// -> Ok () and count will be 0

for

Iterates over a sequence and executes a unit-returning parser for each element in the sequence. This is useful for parsing repeating structures where the pattern is driven by an external collection. The overall for loop returns unit.

Example:

let keywords = [ "begin"; "let"; "end" ]
let pWhitespace = skipMany1Satisfies System.Char.IsWhiteSpace

// A parser that consumes "begin let end" with whitespace between them
let pKeywordSequence = parser {
    let mutable first = true
    for keyword in keywords do
        if not first then
            // All keywords after the first must be preceded by whitespace
            do! pWhitespace
        do! pstring keyword
        first <- false
}

// run pKeywordSequence "begin let end"
// -> Ok ()

// run pKeywordSequence "begin   let   end"
// -> Ok ()