Combine

A parser combinator library for Elixir projects.

MasterHex.pm Version

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

License

MIT