How to contribute to `gnparser` project

January 7, 2026 · View on GitHub

Did you find a bug?

Ensure the bug was not already reported by searching on GitHub under Issues.
If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case via https:parser.globalnames.org demonstrating the expected behavior that is not occurring.
Make sure you do not put more than one bug report in the new issue.

Do you intend to add a new feature or change an existing one?

Suggest your change in the GlobalNames gitter group, or create an issue that describes your suggestion in detail.
Make sure you do not put more than one feature or change in the new issue.

Did you write a patch that fixes a bug?

Open a new GitHub pull request with the patch.
Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
Clearly state if your PR is a proof of concept and what needs to be done to finish it, or, if it is ready to merge patch with tests and documentation added.

Did you write a client for your favorite language to access `gnparser` functionality via REST api?

Let us know about your client on GlobalNames gitter group.

Do you have questions about the source code?

Ask any question on the GlobalNames gitter group

Would you like to contribute, but do not know how?

Read the next section about configuring environment for the project.

Setting up `gnparser` programming environment

Install Go

Download and install Go for your operating system. Make sure you configured GOPATH environment library.

You need Go v1.25 or higher.

Install `gnparser` code

gnparser uses several external tools and technologies:

Parsing Expression Grammar tool to generate parsing code.
Cobra CLI framework for creating command line application.
goimport tool for fixing imports in PEG autogenerated go code.

To install them run

just tools

To create a gnparser executable and place it to $GOPATH/bin

just

Now you should be able to use gnparser compiled from the code:

gnparser -f pretty "Pica pica (Linnaeus, 1758)"

To run tests

just test

go test ./...

To generate tests automatically

If your change generates a lot of changes in testdata/test_data.md and/or testdata/test_data_cultivars.md you can generate testdata/test_data_new.md and testdata/test_data_cultivars_new.md files using gentest.go tool.

cd tools
go run gentest.go
cd ../testdata
ls

You will have two new files in testdata. It is VERY important now to check difference between old and new test files before making the next step:

mv test_data_new.md test_data.md
mv test_data_cultivars_new.md test_data_cultivars.md

Benchmarks

Benchmarks are located in gnparser_test.go

To run benchmarks from the project's root:

# this command will install benchstat
just tools

go test -bench=. -benchmem -count=10 -run=XXX > bench.txt && benchstat bench.txt

After running you should get results similar to:

name                                     time/op
Parse/Parse_to_object_once-16            73.0µs ± 1%
Parse/Parse_to_object_once_with_Init-16  83.2µs ± 1%
Parse/Parse_to_object-16                 67.5ms ± 1%
Parse/Parse_to_JSON-16                   71.5ms ± 1%
Parse/Parse_to_JSON_(Details)-16         71.8ms ± 1%
Parse/Parse_to_CSV-16                    69.1ms ± 1%

name                                     alloc/op
Parse/Parse_to_object_once-16            10.9kB ± 0%
Parse/Parse_to_object_once_with_Init-16  23.8kB ± 0%
Parse/Parse_to_object-16                 15.5MB ± 0%
Parse/Parse_to_JSON-16                   17.2MB ± 0%
Parse/Parse_to_JSON_(Details)-16         17.2MB ± 0%
Parse/Parse_to_CSV-16                    16.2MB ± 0%

name                                     allocs/op
Parse/Parse_to_object_once-16               250 ± 0%
Parse/Parse_to_object_once_with_Init-16     409 ± 0%
Parse/Parse_to_object-16                   235k ± 0%
Parse/Parse_to_JSON-16                     242k ± 0%
Parse/Parse_to_JSON_(Details)-16           242k ± 0%
Parse/Parse_to_CSV-16                      240k ± 0%

Accessing a raw parsed AST tree

PEG parser generates it own abstract syntax tree (AST), that later gets conberted into a gnparser specific AST. Sometimes it is useful to see the raw tree of nodes. To do that, open gnparser/gnparser/cmd/root.go, change const debug to true and run just. After that you will be able to examing raw tree of a string, for example:

gnparser "Bubo bubo"