/honeycomb

A dead simple, no-nonsense parser combinator library written in pure Nim.

Primary LanguageNimMozilla Public License 2.0MPL-2.0

🍯 Honeycomb

tests docs

Honeycomb is a parser combinator library written in pure Nim. It's designed to be simple, straightforward, and easy to expand, while relying on zero dependencies from outside of Nim's standard library.

Honeycomb was heavily inspired by the excellent Python library parsy, as well as the existing but unmaintained combparser.

let 
  parser  = ((s("Hello") | s("Greetings")) << c(',') << whitespace) & (regex(r"\w+") << c("!."))
  result1 = parser.parse("Hello, world!")
  result2 = parser.parse("Greetings, peasants.")

assert result1.kind  == success
assert result1.value == @["Hello", "world"]

assert result2.kind  == success
assert result2.value == @["Greetings", "peasants"]

Honeycomb supports the following key features:

  • Predefined parsers and parser constructors for numerous basic parsing needs
  • An extensive library of combinators with which to combine them
  • Support for manually defining custom parsers / combinators
  • Forward-declared parsers to support mutually recursive parser definitions

Installation

You can install Honeycomb via Nim's package manager, nimble.

nimble install honeycomb

Once you've installed Honeycomb, you can use it in your project by importing it.

import honeycomb

Usage

You can find extensive documentation on using Honeycomb here.

For a more in-depth conceptual look at parser combinators in general, you can try these resources:

Contributing

  1. Fork this repository.
  2. Clone the fork to your local machine.
git clone https://github.com/<your-github-username>/honeycomb.git
cd honeycomb
  1. Make your changes.
  2. Make sure to add or update documentation comments to reflect your changes.
  3. Make sure to add or update tests in tests/test.nim to verify your changes.
  4. Create a pull request with your changes.

Honeycomb has an extensive and expanding suite of unit tests, which can be found in tests/test.nim. You can run the tests with:

nimble test

To generate a local copy of the documentation from Honeycomb's code, you can use the following command. Note that the docs folder is intentionally .gitignored and should not be committed; when your changes are merged into the master branch, an automated process will regenerate the documentation on the docs branch.

nimble gendocs