README.md.template

# syntaks [![Crystal CI](https://github.com/Ragmaanir/syntaks/actions/workflows/crystal.yml/badge.svg)](https://github.com/Ragmaanir/syntaks/actions/workflows/crystal.yml)

### Version <%= Syntaks::VERSION %>

A parser combinator framework.

## Usage

```crystal
require "syntaks"
```

## Example

```crystal
<%= File.read("spec/examples/list/parser.cr") %>

<%= File.read("spec/examples/list/example.cr") %>
```

## Usage

Rules are specified in a format similar to EBNF:

```crystal
# literals/tokens
ignored(:space, /\s+/) # generates nil as AST-node
rule(:int, String, /[1-9][0-9]*/) { |m| m.content } # generates String as AST-node

# sequence
rule(:root, String, "var " >> id) { |m| m[1] } # use the second match (id) as AST-node

# sequence with backtracking disabled
rule(:root, String, "var " & id) { |m| m[1] }

# alternatives
rule(:root, String, a | b)

# repetition
rule(:root, Array(Int32), {"," >> int}) { |m| m.map(&.[1]) }
```

When backtracking is disabled an parsing fails, a syntax error is produced:

```crystal
<%= File.read("spec/examples/error/parser.cr") %>

<%= File.read("spec/examples/error/example.cr") %>
```

A parse log can be printed to inspect the parsing process:

```crystal
<%= File.read("spec/examples/log/example.cr") %>
```

## TODO

- simple token macro
- rules that do not generate ast nodes
- error-recovery productions / synchronization tokens
- optional whitespace skippers
- Simple lexer?
- Packrat parsing / memoization
- remember longest parsed prefix when parsing fails

## DONE

- Use ameba
- Generated `README.md` with examples
- LoggingContext with a ParseLog
- ProfilingContext
- EBNF DSL
- Selectively disable backtracking
- Detailed syntax errors: display production that failed and the location where exactly it failed


## Contributing

1. Fork it ( https://github.com/ragmaanir/syntaks/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

## Contributors

- [Ragmaanir](https://github.com/ragmaanir) - creator, maintainer