## Combine
A parser combinator library for Elixir projects.
[](https://travis-ci.org/bitwalker/combine)
[](https://hex.pm/packages/combine)
## How to Use
First add it to your dependency list like so:
```elixir
def deps do
[{:combine, "~> x.x.x"}, ...]
end
```
Documentation is [located here](http://hexdocs.pm/combine).
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:
```elixir
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
