bitwalker / Combine

Combine

A parser combinator library for Elixir projects.

How to Use

First add it to your dependency list like so:

def deps do
  [{:combine, "~> x.x.x"}, ...]
end

Documentation is located here.

From there the API is fairly straightforward, the docs cover what parser combinators are available, but here's a quick taste of how you use it:

defmodule DateTimeParser do
  use Combine

  def parse(datetime), do: Combine.parse(datetime, parser)

  defp parser, do: date |> ignore(char("T")) |> time

  defp date do
    label(integer, "year")
    |> ignore(char("-"))
    |> label(integer, "month")
    |> ignore(char("-"))
    |> label(integer, "day")
  end

  defp time(previous) do
    previous
    |> label(integer, "hour")
    |> ignore(char(":"))
    |> label(integer, "minute")
    |> ignore(char(":"))
    |> label(float, "seconds")
    |> either(
      map(char("Z"), fn _ -> "UTC" end),
      pipe([either(char("-"), char("+")), word], &(Enum.join(&1)))
    )
  end
end

...> datetime = "2014-07-22T12:30:05.0002Z"
...> datetime_zoned = "2014-07-22T12:30:05.0002+0200"
...> DateTimeParser.parse(datetime)
[2014, 7, 22, 12, 30, 5.0002, "UTC"]
...> DateTimeParser.parse(datetime_zoned)
[2014, 7, 22, 12, 30, 5.0002, "+0200"]

Why Combine vs ExParsec?

Combine is a superset of ExParsec's API for the most part and it's performance is significantly better in the one benchmark I've run with a very simple parser. Benchfella was used to run the benchmarks, and the benchmarks used for comparison are present in both Combine and ExParsec's bench directories with the exception of the datetime parsing one, which is easily replicated in ExParsec if you wish to double check yourself. For reference, here's what I'm seeing on my machine:

# ExParsec

Settings:
  duration:      1.0 s

## Bench.ExParsec.Binary
[19:01:54] 1/2: many bits
## Bench.ExParsec.Text
[19:01:56] 2/2: many any_char

Finished in 5.67 seconds

## Bench.ExParsec.Binary
many bits            1000   1731.83 µs/op

## Bench.ExParsec.Text
many any_char                  5000   616.02 µs/op
parse ISO 8601 datetime        2000   964.48 µs/op

# Combine

Settings:
  duration:      1.0 s

## Combine.Bench
[15:21:21] 1/5: parse ISO 8601 datetime
[15:21:22] 2/5: many bits
[15:21:25] 3/5: many any_char
[15:21:27] 4/5: large set of choices (one_of/word)
[15:21:30] 5/5: large set of choices (choice/parsers)

Finished in 12.08 seconds

## Combine.Bench
large set of choices (one_of/word)         100000   25.60 µs/op
many any_char                               50000   32.98 µs/op
many bits                                   50000   43.90 µs/op
parse ISO 8601 datetime                     10000   139.45 µs/op
large set of choices (choice/parsers)       10000   265.04 µs/op

ExParsec also appears to be falling behind on maintenace, even with PRs being submitted, so rather than forking I decided to write my own from scratch that met my needs.

Parsers

You should look at the docs for usage on each parser combinator, but the following lists which ones are available in each module.

Combine.Parsers.Base

between         both
choice          either
eof             fail
fatal           ignore
label           many
map             none_of
one_of          option
pair_both       pair_left
pair_right      pipe
satisfy         sep_by
sep_by1         sequence
skip            skip_many
skip_many1      times
zero

Combine.Parsers.Text

alphanumeric      bin_digit
char              digit
float             fixed_integer
hex_digit         integer
letter            lower
newline           octal_digit
space             spaces
string            tab
upper             word
word_of

Combine.Parsers.Binary

bits       bytes
float      int
uint

Roadmap

• Streaming parsers

License

MIT