A Parser is defined as a function that takes an input state, including an input text, and returns either an Error, or a value with the next state.

Contains the description of an error. This includes an error message, the position, and the context stack.

Parse an input text, and get either an Error or the parsed value as a result.

-- Consumes a single letter, then "bc" are still remaining.
parse "abc" letter --> Ok 'a'


-- We get an error message if the parser doesn't match.
import Parser.Error


letter
    |> parse "123"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '1'."

Starts a parsing pipeline to parse into a data type.

You should also specify a name for the context, this helps to give better error messages.

import Parser.Common exposing (number)


type alias Point =
    { x : Float
    , y : Float
    }


-- We can use `into` to have more context when an error happens.
point : Parser Point
point =
    into "Point"
        (succeed Point
            |> drop (char '(')
            |> take number
            |> drop (char ',')
            |> take number
            |> drop (char ')')
        )


parse "(12,34)" point --> Ok {x = 12, y = 34}


-- We can get the error context stack as well as where they started matching.
parse "(a,b)" point
    |> Result.mapError .context
--> Err [{ name = "Point", row = 1, col = 1 }]

Takes a parsed value and feeds it to the return value of the parser.

Ignores a parsed value, but it still must match to continue.

Matches any single character.

ℹ️ Equivalent regular expression: .

-- We can match any character.
parse "abc" anyChar --> Ok 'a'
parse "#hashtag" anyChar --> Ok '#'


-- This can only fail if we run out of inputs.
import Parser.Error


anyChar
    |> parse ""
    |> Result.mapError Parser.Error.message
--> Err "1:0: I was expecting a character.\nI reached the end of the input text."

Matches a specific single character. This is case sensitive.

-- Match a specific character, case sensitive.
parse "abc" (char 'a') --> Ok 'a'


-- It fails if it's not _exactly_ the same.
import Parser.Error


char 'a'
    |> parse "ABC"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting the character 'a'.\nI got stuck when I got the character 'A'."

Matches a specific single character. This is case insensitive.

-- Match a specific character, case insensitive.
parse "abc" (charNoCase 'a') --> Ok 'a'
parse "ABC" (charNoCase 'a') --> Ok 'A'


-- But anything else makes it fail.
import Parser.Error


charNoCase 'a'
    |> parse "123"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting the character 'a' (case insensitive).\nI got stuck when I got the character '1'."

Matches exactly one digit character.

ℹ️ Equivalent regular expression: [0-9] or \d

-- Match a digit.
parse "123" digit --> Ok '1'
parse "3.14" digit --> Ok '3'


-- But anything else makes it fail.
import Parser.Error


digit
    |> parse "abc"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a digit [0-9].\nI got stuck when I got the character 'a'."

Matches one or more digit.

ℹ️ Equivalent regular expression: [0-9]+ or \d+

-- Match many digits.
parse "123abc" digits --> Ok "123"


-- But anything else makes it fail.
import Parser.Error


digits
    |> parse "abc123"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting one or more digits [0-9]+.\nI got stuck when I got the character 'a'."

Matches exactly one letter character. This is case insensitive.

ℹ️ Equivalent regular expression: [a-zA-Z]

-- Match any letter, case insensitive.
parse "abc" letter --> Ok 'a'
parse "ABC" letter --> Ok 'A'


-- But anything else makes it fail.
import Parser.Error


letter
    |> parse "123"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '1'."

Matches one or more letter. This is case insensitive.

ℹ️ Equivalent regular expression: [a-zA-Z]+

-- Match many letters, case insensitive.
parse "abc123" letters --> Ok "abc"
parse "ABC123" letters --> Ok "ABC"


-- But anything else makes it fail.
import Parser.Error


letters
    |> parse "123abc"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting one or more letters [a-zA-Z]+.\nI got stuck when I got the character '1'."

Matches exactly one lowercase letter character. This is case sensitive.

ℹ️ Equivalent regular expression: [a-z]

-- Match a lowercase letter.
parse "abc" lowercase --> Ok 'a'


-- But anything else makes it fail.
import Parser.Error


lowercase
    |> parse "ABC"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a lowercase letter [a-z].\nI got stuck when I got the character 'A'."

Matches exactly one uppercase letter character. This is case sensitive.

ℹ️ Equivalent regular expression: [A-Z]

-- Match an uppercase letter.
parse "ABC" uppercase --> Ok 'A'


-- But anything else makes it fail.
import Parser.Error


uppercase
    |> parse "abc"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting an uppercase letter [A-Z].\nI got stuck when I got the character 'a'."

Matches exactly one letter or digit character. This is case insensitive.

ℹ️ Equivalent regular expression: [a-zA-Z0-9]

-- Match a letter or number.
parse "abc" alphaNum --> Ok 'a'
parse "ABC" alphaNum --> Ok 'A'
parse "123" alphaNum --> Ok '1'


-- But anything else makes it fail.
import Parser.Error


alphaNum
    |> parse "_abc"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a letter or a digit [a-zA-Z0-9].\nI got stuck when I got the character '_'."

Matches a blank space character. A blank space can be a regular space ' ', tab '\t', new line '\n', carriage return '\r', form feed '\f', or vertical tab '\v'.

ℹ️ Equivalent regular expression: [ \t\n\r\f\v] or \s

-- Match a blank space.
parse "    abc" space --> Ok ' '
parse "\t abc" space --> Ok '\t'


-- But anything else makes it fail.
import Parser.Error


space
    |> parse "abc"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a blank space.\nI got stuck when I got the character 'a'."

Matches zero or more spaces.

ℹ️ Equivalent regular expression: [ \t\n\r\f\v]* or \s*

-- Match many spaces.
parse "    abc" spaces --> Ok "    "


parse "\t abc" spaces --> Ok "\t "


-- Including zero spaces :)
parse "abc" spaces --> Ok ""

Matches a specific text string. This is case sensitive.

-- Match an exact text, case sensitive.
parse "abcdef" (text "abc") --> Ok "abc"


-- But anything else makes it fail.
import Parser.Error


text "abc"
    |> parse "abCDEF"
    |> Result.mapError Parser.Error.message
--> Err "1:3: I was expecting the text 'abc'.\nI got stuck when I got the character 'C'."

Matches a specific text string. This is case insensitive.

-- Match an exact text, case insensitive.
parse "abcdef" (textNoCase "abc") --> Ok "abc"
parse "ABCDEF" (textNoCase "abc") --> Ok "ABC"


-- But anything else makes it fail.
import Parser.Error


textNoCase "abc"
    |> parse "ab@"
    |> Result.mapError Parser.Error.message
--> Err "1:3: I was expecting the text 'abc' (case insensitive).\nI got stuck when I got the character '@'."

Gets a string from a list of characters.

-- Get a `String` out of a `List Char`, we could have also used `letters` :)
textOf (oneOrMore letter)
    |> parse "abc123" --> Ok "abc"

Gets a line from the input text, delimited by '\n'.

-- A line could be delimited by the newline character '\n'.
parse "abc\ndef" line --> Ok "abc"


-- Or this could also be the last line.
parse "abc" line --> Ok "abc"


-- An empty line still counts.
parse "" line --> Ok ""

Matches a sequence of parsers in order, and gets the result as a List.

-- Note that all the parsers must be of the same type, like `Parser Char`.
sequence [ char '_', letter, digit ]
    |> parse "_A5" --> Ok [ '_', 'A', '5' ]

Concatenates the parsed values from all the parsers into a single list with all the values.

-- We get all these parsers as a single sequence of values.
concat
    [ oneOrMore digit       -- [ '3' ]
    , zeroOrOne (char '.')  -- [ '.' ]
    , zeroOrMore digit      -- [ '1', '4' ]
    ]
    |> parse "3.14"
--> Ok [ '3', '.', '1', '4' ]

Returns the value of the first parser that matches. It tries to match the parsers in order.

If none of the parsers match, it keeps the error message from the last parser. To give a more descriptive error message, you can use expecting.

ℹ️ It's a good idea to use expecting alongside this function to improve the error messages.

ℹ️ Equivalent regular expression: |

-- Try the first parser.
oneOf [ char '_', letter ]
    |> parse "_abc"
--> Ok '_'


-- If it doesn't work, try the next.
oneOf [ char '_', letter ]
    |> parse "abc"
--> Ok 'a'


-- If none of them work, we get the error from the last parser.
import Parser.Error


oneOf [ char '_', letter ]
    |> parse "123"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '1'."

Parses an optional value and returns it as a Maybe.

ℹ️ Equivalent regular expression: ?

-- Maybe we get `Just` a letter.
parse "abc" (maybe letter) --> Ok (Just 'a')


-- Or maybe we get `Nothing`.
parse "_abc" (maybe letter) --> Ok Nothing

Parses an optional value and returns it as a List.

ℹ️ Equivalent regular expression: ?

-- We want one letter, optionally.
parse "abc" (zeroOrOne letter) --> Ok [ 'a' ]


-- If we don't get any, that's still okay.
parse "_abc" (zeroOrOne letter) --> Ok []

Parses zero or more values and returns them as a List.

ℹ️ Equivalent regular expression: *

-- We want as many letters as there are.
parse "abc" (zeroOrMore letter) --> Ok [ 'a', 'b', 'c' ]


-- Even zero letters is okay.
parse "_abc" (zeroOrMore letter) --> Ok []

Parses one or more values and returns them as a List.

ℹ️ Equivalent regular expression: +

-- We want as many letters as there are.
parse "abc" (oneOrMore letter) --> Ok [ 'a', 'b', 'c' ]


-- But we want at least one.
import Parser.Error


oneOrMore letter
    |> parse "_abc"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '_'."

Parses a value exactly a number of times and returns them as a List.

ℹ️ Equivalent regular expression: {n}

-- We want `exactly` three letters.
parse "abcdef" (exactly 3 letter) --> Ok [ 'a', 'b', 'c' ]


-- Not two or four, we want three.
import Parser.Error


exactly 3 letter
    |> parse "ab_def"
    |> Result.mapError Parser.Error.message
--> Err "1:3: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '_'."

Parses a value at least a number of times and returns them as a List.

ℹ️ Equivalent regular expression: {min,}

-- We want at least three letters, we are okay with more than three.
parse "abcdef" (atLeast 3 letter) --> Ok [ 'a', 'b', 'c', 'd', 'e', 'f' ]


-- But not two, that's sacrilegious.
import Parser.Error


atLeast 3 letter
    |> parse "ab_def"
    |> Result.mapError Parser.Error.message
--> Err "1:3: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '_'."

Parses a value at most a number of times and returns them as a List.

ℹ️ Equivalent regular expression: {0,max}

-- We want a maximum of three letters.
parse "abcdef" (atMost 3 letter) --> Ok [ 'a', 'b', 'c' ]


-- Less than that is also okay.
parse "ab_def" (atMost 3 letter) --> Ok [ 'a', 'b' ]


-- Even zero letters are fine.
parse "_bcdef" (atMost 3 letter) --> Ok []

Parses a value between a range of times and returns them as a List.

ℹ️ Equivalent regular expression: {min,max}

-- We want between two and four letters.
parse "abcdef" (between 2 4 letter) --> Ok [ 'a', 'b', 'c', 'd' ]
parse "abc_ef" (between 2 4 letter) --> Ok [ 'a', 'b', 'c' ]
parse "ab_def" (between 2 4 letter) --> Ok [ 'a', 'b' ]


-- But less than that is not cool.
import Parser.Error


between 2 3 letter
    |> parse "a_cdef"
    |> Result.mapError Parser.Error.message
--> Err "1:2: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '_'."

Parses a values repeatedly until a delimiter parser matches. The delimiter marks the end of the sequence, and it is not consumed.

-- Get all the letters until we find 'd'.
letter
    |> until (char 'd')
    |> parse "abcdef"
--> Ok [ 'a', 'b', 'c' ]


-- The delimiter is _not_ consumed.
succeed (\str -> str)
    |> drop (char '<')
    |> take (textOf (letter |> until (char '>')))
    |> drop (char '>')
    |> end
    |> parse "<abc>"
--> Ok "abc"


-- If the delimiter is not found, we get an error.
import Parser.Error


letter
    |> until (char 'd')
    |> parse "abc123"
    |> Result.mapError Parser.Error.message
--> Err "1:4: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '1'."

Parses a values repeatedly until a delimiter parser matches. The delimiter marks the end of the sequence, and it is consumed.

-- Gets all the letters until we find 'd'.
letter
    |> untilIncluding (char 'd')
    |> parse "abcdef"
--> Ok ([ 'a', 'b', 'c' ], 'd')


-- If we don't care about the delimiter, we can extract only the values.
letter
    |> untilIncluding (char 'd')
    |> map Tuple.first
    |> parse "abcdef"
--> Ok [ 'a', 'b', 'c' ]


-- The delimiter is consumed.
succeed (\str -> str)
    |> drop (char '<')
    |> take (textOf (letter |> untilIncluding (char '>') |> map Tuple.first))
    |> end
    |> parse "<abc>"
--> Ok "abc"


-- If the delimiter is not found, we get an error.
import Parser.Error


letter
    |> untilIncluding (char 'd')
    |> parse "abc123"
    |> Result.mapError Parser.Error.message
--> Err "1:4: I was expecting a letter [a-zA-Z].\nI got stuck when I got the character '1'."

Parses values while a condition is still True. Once the condition is False, the sequence stops and the current value is not consumed.

If the condition never gets to False, it parses until it stops matching or until the end of the input text.

The condition function takes two inputs: a list of all the previously matched values, and the current value matched.

ℹ️ This is a low level function, for most cases you can probably find a higher level function that is more readable and easier to use.

-- Get letters `while` the current letter is not 'd'.
-- In other words, stop until we find a 'd'.
letter
    |> while (\_ value -> value /= 'd')
    |> parse "abcdef"
--> Ok [ 'a', 'b', 'c' ]


-- Get letters `while` we've got less than 3 letters.
-- In other words, stop until we have three letters.
letter
    |> while (\values _ -> List.length values < 3)
    |> parse "abcdef"
--> Ok [ 'a', 'b', 'c' ]


-- If we stop matching, we still succeed with whatever we could get.
letter
    |> while (\_ value -> value /= 'd')
    |> parse "abc123"
--> Ok [ 'a', 'b', 'c' ]


-- Once the condition fails, that input is _not_ consumed.
succeed (\str -> str)
    |> drop (char '<')
    |> take (textOf (letter |> while (\_ value -> value /= '>')))
    |> drop (char '>')
    |> parse "<abc>"
--> Ok "abc"

A parser that always succeeds with the given value.

-- Always succeed with "abc" no matter the input text.
parse "" (succeed "abc") --> Ok "abc"


-- This is usually used to start parser pipelines.
import Parser.Common exposing (int)


type alias Pair =
    { x : Int
    , y : Int
    }


pair : Parser Pair
pair =
    succeed Pair
        |> take int
        |> drop (char ',')
        |> take int


parse "12,34" pair --> Ok { x = 12, y = 34 }

A parser that always fails with the given error message.

-- Always fails with an error message.
import Parser.Error


expected "nothing, this always fails"
    |> parse ""
    |> Result.mapError Parser.Error.message
--> Err "1:0: I was expecting nothing, this always fails.\nI reached the end of the input text."

Parse one value andThen do something with that value, which results in another parser.

This can be used to validate the last thing we parsed, or transform the last value, or to use the last value for the next parser like a backreference.

-- Get some characters `andThen` interpret them as an `Int`.
import Parser.Error


textOf (oneOrMore anyChar)
    |> andThen
        (\chars ->
            case String.toInt chars of
                Just n -> succeed n
                Nothing -> expected "an integer, better use Parser.Common.int"
        )
    |> parse "123"
--> Ok 123

Parse two values andThen2 do something with those values, which results in another parser.

This can be used to validate the last things we parsed, or transform the last values, or to ignore eiher of the values, or to use the last values for the next parser like a backreference.

-- Get something like "=123" `andThen` interpret it as an `Int`.
andThen2
    (\_ chars ->
        case String.toInt chars of
            Just n -> succeed n
            Nothing -> expected "an integer, better use Parser.Common.int"
    )
    (char '=')
    digits
    |> parse "=123"
--> Ok 123

Parse and consume the next parser, but ignore its value.

This is useful when you want to match and advance the parser, but keep the previous value.

-- Let's parse a simple email, but we're only interested in the username.
letters
    |> andThenIgnore (char '@')
    |> andThenIgnore letters
    |> andThenIgnore (text ".com")
    |> parse "[email protected]"
--> Ok "user"


-- To ignore previous values, you can use a regular andThen
letters
    |> andThen (\_ -> char '@')
    |> andThen (\_ -> letters)
    |> andThenIgnore (text ".com")
    |> parse "[email protected]"
--> Ok "example"

If the previous parser failed, try a fallback parser.

-- Try letters, `orElse` give me some digits.
letters
    |> orElse digits
    |> parse "abc"
--> Ok "abc"


-- We didn't get letters, but we still got digits.
letters
    |> orElse digits
    |> parse "123"
--> Ok "123"


-- But if we still fail, give the error message of the fallback parser.
import Parser.Error


letters
    |> orElse digits
    |> parse "_"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting one or more digits [0-9]+.\nI got stuck when I got the character '_'."

Succeeds either if the parser succeeds, or if there are no more input characters.

-- Get some letters.
letters
    |> orEnd
    |> parse "abc123"
--> Ok (Just "abc")


-- If we get to the end of inputs, that's still okay.
letters
    |> orEnd
    |> parse ""
--> Ok Nothing


-- But if we match something different, that's _not_ okay.
import Parser.Error


letters
    |> orEnd
    |> parse "123abc"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting one or more letters [a-zA-Z]+.\nI got stuck when I got the character '1'."

If there is an error, this replaces the error message. This helps create more descriptive error messages instead of the more generic ones.

If you want to use the value that failed some validation in the error message, consider using a more relaxed parser and using andThen to do the validation. It's a little longer, but that way you get access to the potentially invalid parsed value.

-- We can redefine an error message if something goes wrong.
import Parser.Error


letters
    |> expecting "a name consisting of letters"
    |> parse "123"
    |> Result.mapError Parser.Error.message
--> Err "1:1: I was expecting a name consisting of letters.\nI got stuck when I got the character '1'."

Succeeds only if there are no more remaining characters in the input text. This does not consume any inputs.

ℹ️ Equivalent regular expression: $

-- Get some letters, and there are better no input characters left.
letters
    |> end
    |> parse "abc"
--> Ok "abc"


-- Or fail otherwise.
import Parser.Error


letters
    |> end
    |> parse "abc123"
    |> Result.mapError Parser.Error.message
--> Err "1:4: I was expecting the end of the input text, but 3 characters are still remaining.\nI got stuck when I got the character '1'."

Succeeds only if the input text is followed by a lookahead parser. This does not consume any inputs.

ℹ️ Equivalent regular expression: (?=...) (positive lookahead)

-- Match letters only if it's `followedBy` a digit.
letters
    |> followedBy digit
    |> parse "abc123"
--> Ok "abc"


-- Even if we match the letters, fail if the next character is not a digit.
import Parser.Error


letters
    |> followedBy digit
    |> parse "abc@def"
    |> Result.mapError Parser.Error.message
--> Err "1:4: I was expecting a digit [0-9].\nI got stuck when I got the character '@'."

Succeeds only if the input text is not followed by a lookahead parser. This does not consume any inputs.

ℹ️ It's a good idea to use expecting alongside this function to improve the error messages.

ℹ️ Equivalent regular expression: (?!...) (negative lookahead)

-- Match letters only if it's `notFollowedBy` a digit.
letters
    |> notFollowedBy digit
    |> expecting "letters not followed by a number"
    |> parse "abc@def"
--> Ok "abc"


-- Even if we match the letters, fail if the next character is a digit.
import Parser.Error


-- This is the default error message, but you can use `expecting` to improve it.
letters
    |> notFollowedBy digit
    |> parse "abc123"
    |> Result.mapError Parser.Error.message
--> Err "1:4: I was expecting to not match a pattern, but I did.\nI got stuck when I got the character '1'."

Transform the result of a parser.

-- Get some letters, and make them lowercase.
letters
    |> map String.toLower
    |> parse "ABC"
--> Ok "abc"

Transform the result of two parsers.

import Parser.Common exposing (int)


-- Get an `Int` and apply an unary operator.
map2
    (\op x ->
        if op == '-' then
            -x
        else
            x
    )
    (oneOf [char '+', char '-'])
    int
    |> parse "-123"
--> Ok -123

Transform the result of three parsers.

import Parser.Common exposing (int)


-- Get an `Int` and apply a binary operator.
map3
    (\x op y ->
        if op == '+' then
            x + y
        else
            x - y
    )
    int
    (oneOf [char '+', char '-'])
    int
    |> parse "5+2"
--> Ok 7

Transform the result of four parsers.

Transform the result of five parsers.

Transform the result of a list of parsers. Note that all parsers must be of the same type, unlike map2..map5.

-- Match a list of parsers, and then `map` a function to the results.
mapList (String.join ",")
    [ text "ab"
    , text "cd"
    , letters
    ]
    |> parse "abcdefg"
--> Ok "ab,cd,efg"