### Install GNparser for Development with Just

Source: https://github.com/gnames/gnparser/blob/main/README.md

Install gnparser for development purposes using the 'just' build tool. Ensure your PATH includes $HOME/go/bin.

```bash
git clone https://github.com/gnames/gnparser.git
cd gnparser
just tools
just install
```

--------------------------------

### Install GNparser with Go

Source: https://github.com/gnames/gnparser/blob/main/README.md

Install gnparser using the Go programming language's package management system.

```bash
go get -u github.com/gnames/gnparser/gnparser
```

--------------------------------

### Install gnparser with Nix Env

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Install gnparser using the traditional Nix environment manager.

```bash
nix-env -f default.nix -i
```

--------------------------------

### Install GNparser on Windows

Source: https://github.com/gnames/gnparser/blob/main/README.md

Install gnparser on Windows by creating a directory for executables, copying the binary, and adding the directory to your system's PATH environment variable.

```cmd
mkdir C:\bin
copy path_to\gnparser.exe C:\bin
```

--------------------------------

### Install gnparser with Nix Flakes

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Install gnparser globally using Nix Flakes. You can also specify a particular flake reference for installation.

```bash
nix profile install
```

```bash
nix profile install github:gnames/gnparser
```

--------------------------------

### Starting GNparser as a REST API

Source: https://github.com/gnames/gnparser/blob/main/README.md

Command to start the GNparser web server on a specified port, enabling access to its functionality via a REST API or a web-based graphical interface.

```bash
gnparser -p 9000
```

--------------------------------

### Install gnparser Tools

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

Run this command to install external tools and technologies required by gnparser, such as the PEG tool, Cobra CLI, and goimports.

```bash
just tools
```

--------------------------------

### Install GNparser with Homebrew

Source: https://github.com/gnames/gnparser/blob/main/README.md

Install gnparser using the Homebrew package manager on macOS, Linux, or Windows Subsystem for Linux.

```bash
brew update
brew tap gnames/gn
brew install gnparser
```

--------------------------------

### Start gnparser Web Server

Source: https://context7.com/gnames/gnparser/llms.txt

Start the gnparser web server with specified port and worker threads. Access the interactive UI via http://localhost:9000 and the API at http://localhost:9000/api/v1/.

```bash
# Start on port 9000 with 8 worker threads
gnparser -p 9000 -j 8

# Then open http://localhost:9000 for the interactive web UI
# API base: http://localhost:9000/api/v1/
```

--------------------------------

### Install GNparser on Linux/Mac OS X

Source: https://github.com/gnames/gnparser/blob/main/README.md

Manually install the gnparser executable on Linux or Mac OS X by moving the binary to a directory in your PATH.

```bash
tar xvf gnparser-xxx.tar.gz
sudo mv gnparser /usr/local/bin
```

--------------------------------

### Run gnparser without installing with Nix Flakes

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Execute the gnparser binary directly after building with Nix Flakes, without a formal installation.

```bash
nix run
```

--------------------------------

### Show GNparser Version

Source: https://context7.com/gnames/gnparser/llms.txt

Use the '-V' option to display the installed version of GNparser.

```bash
gnparser -V
```

--------------------------------

### Run Benchmarks

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

This command runs benchmarks for gnparser, installing `benchstat` if necessary, and then processing the benchmark output.

```bash
# this command will install benchstat
just tools

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

--------------------------------

### Add gnparser to NixOS Configuration

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Include gnparser in your NixOS system packages. This example shows how to call the package from a local path.

```nix
{ pkgs.callPackage /path/to/gnparser/default.nix {} };
```

--------------------------------

### Add gnparser to NixOS Configuration with Flakes

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Integrate gnparser into your NixOS configuration using flakes. This example defines an input for gnparser and includes it in the system packages.

```nix
{ inputs.gnparser.url = "github:gnames/gnparser"; outputs = { self, nixpkgs, gnparser }: { nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem { modules = [ { environment.systemPackages = [ gnparser.packages.x86_64-linux.default ]; } ]; }; }; }
```

--------------------------------

### Use gnparser CLI

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

Example of how to use the compiled gnparser executable from the command line to parse a scientific name.

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

--------------------------------

### Get parser version

Source: https://context7.com/gnames/gnparser/llms.txt

Retrieve the current version and build information of the gnparser service.

```APIDOC
## GET /api/v1/version — Get parser version

### Description
Retrieve the current version and build information of the gnparser service.

### Method
GET

### Endpoint
`/api/v1/version`

### Response
#### Success Response
- **version** (string) - The version of the gnparser.
- **build** (string) - The build timestamp of the gnparser.

### Response Example
```json
{"version":"v1.14.2","build":"2026-01-14_10:00:00UTC"}
```
```

--------------------------------

### GNparser API Response Example

Source: https://github.com/gnames/gnparser/wiki/GNparser-with-OpenRefine

This is an example of the JSON output received from the GNparser API after parsing a scientific name. It contains various fields including verbatim, normalized, canonical forms, and authorship.

```json
[{"parsed":true,"quality":2,"qualityWarnings":[{"quality":2,"warning":"Ex authors are not required (ICZN only)"}],"verbatim":"Bulimus canarius Philippi, in Pfeiffer, 1867","normalized":"Bulimus canarius Philippi ex Pfeiffer 1867","canonical":{"stemmed":"Bulimus canar","simple":"Bulimus canarius","full":"Bulimus canarius"},"cardinality":2,"authorship":{"verbatim":"Philippi, in Pfeiffer, 1867","normalized":"Philippi ex Pfeiffer 1867","year":"1867","authors":["Philippi","Pfeiffer"]},"id":"eb69fa41-52ca-5d6b-9d16-d76d97a6dddc","parserVersion":"v1.7.4"}]
```

--------------------------------

### GET Endpoint

Source: https://github.com/gnames/gnparser/blob/main/io/web/templates/doc_api.html

Use the GET method to parse names by appending a vertical line separated array of strings to the base URL. Ensure that '&' characters are escaped as '%26' and spaces as '+'.

```APIDOC
## GET /api/v1/{names}

### Description
Parses a list of names provided as a URL-encoded, vertical line-separated string.

### Method
GET

### Endpoint
`/api/v1/Aus+bus|Aus+bus+D.+%26+M.,+1870`

### Parameters
#### Path Parameters
- **names** (string) - Required - A vertical line-separated and URL-encoded string of names to parse. Spaces should be encoded as '+' and '&' as '%26'.
```

--------------------------------

### GNparser with Multiple Jobs

Source: https://github.com/gnames/gnparser/blob/main/README.md

Example of using the --jobs flag to increase parsing speed on multi-CPU computers by utilizing concurrent processes. Results are reassembled in the input order.

```bash
gnparser --jobs 200
```

--------------------------------

### Parse a single name with pretty format

Source: https://github.com/gnames/gnparser/blob/main/README.md

Use the `-f pretty` flag to output parsed names in a human-readable format. This example parses a specific scientific name.

```bash
gnparser -f pretty "Quadrella steyermarkii (Standl.) Iltis & Cornejo"
```

--------------------------------

### Making POST Requests to GNparser API in Ruby

Source: https://github.com/gnames/gnparser/blob/main/README.md

Example of sending a POST request with a JSON array of name-strings to the GNparser API endpoint using Ruby's Net::HTTP library.

```ruby
require 'json'
require 'net/http'

uri = URI('https://parser.globalnames.org/api/v1/')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json',
                                   'accept' => 'json')
request.body = ['Solanum mariae Särkinen & S.Knapp',
                'Ahmadiago Vánky 2004'].to_json
response = http.request(request)
```

--------------------------------

### Get Raw AST with GNparser Debug

Source: https://context7.com/gnames/gnparser/llms.txt

The `Debug` method returns the raw Abstract Syntax Tree (AST) from the PEG parser as bytes. This is helpful for diagnosing parsing issues or understanding the grammar's behavior with specific inputs.

```go
cfg := gnparser.NewConfig()
gnp := gnparser.New(cfg)

tree := gnp.Debug("Aus bus (K.) L.")
fmt.Println(string(tree)) // prints full PEG parse tree
```

--------------------------------

### Parse Array of Names to String using Ruby FFI

Source: https://context7.com/gnames/gnparser/llms.txt

This Ruby example uses the FFI gem to interact with the C shared library for parsing an array of names. It demonstrates how to prepare the array of pointers and call `ParseAryToString`. The output is a CSV string, and the memory for the result must be freed.

```ruby
require 'ffi'

module GNparser
  extend FFI::Library
  ffi_lib './libgnparser.so'

  attach_function :ParseAryToString,
    [:pointer, :int, :string, :string, :int, :int, :int, :int],
    :strptr
  attach_function :FreeMemory, [:pointer], :void
end

names = ["Pardosa moesta Banks, 1892", "Bubo bubo", "Homo sapiens L."]
ptrs = names.map { |n| FFI::MemoryPointer.from_string(n) }
arr = FFI::MemoryPointer.new(:pointer, ptrs.size)
ptrs.each_with_index { |p, i| arr[i].put_pointer(0, p) }

result_ptr, _ = GNparser.ParseAryToString(arr, names.size, "csv", "", 0, 0, 0, 0)
puts result_ptr
GNparser.FreeMemory(result_ptr)
```

--------------------------------

### Parse names via GET

Source: https://context7.com/gnames/gnparser/llms.txt

Parse one or more scientific names by providing them in the URL path, separated by pipes. Query parameters control output format and parsing options.

```APIDOC
## GET /api/v1/:names — Parse names via GET

### Description
Parse one or more scientific names by providing them in the URL path, separated by pipes. Query parameters control output format and parsing options.

### Method
GET

### Endpoint
`/api/v1/:names`

### Query Parameters
- **csv** (boolean) - Optional - If true, output will be in CSV format.
- **with_details** (boolean) - Optional - If true, include full detail tree in the output.
- **code** (string) - Optional - Nomenclatural code hint (e.g., `bot`, `zoo`, `bact`, `vir`, `cult`).
- **diaereses** (boolean) - Optional - If true, preserve diaereses in the output.
- **compact_authors** (boolean) - Optional - If true, compact author initials.
- **flatten** (boolean) - Optional - If true, flatten JSON output.

### Request Example
```bash
# Parse a single name (JSON output by default)
curl "http://localhost:9000/api/v1/Homo+sapiens+Linnaeus,+1758"

# Parse multiple names with pipe separator
curl "http://localhost:9000/api/v1/Homo+sapiens+Linnaeus|Bubo+bubo"

# Request CSV output with details
curl "http://localhost:9000/api/v1/Aus+bus+L.?csv=true&with_details=true"

# Botanical code hint, preserve diaereses, flatten JSON
curl "http://localhost:9000/api/v1/Leptochloöpsis+virgata?code=bot&diaereses=true&flatten=true"
```
```

--------------------------------

### Parse Spathiphyllum with Cultivar and Authorship

Source: https://github.com/gnames/gnparser/blob/main/testdata/test_data_cultivars.md

This example demonstrates parsing a scientific name that includes a cultivar and an authorship. The output clearly separates the uninomial, authorship, and cultivar components, with `cultivar` set to true.

```json
{"parsed":true,"nomenclaturalCodeSetting":"ICNCP","quality":1,"verbatim":"Spathiphyllum Schott “Mauna Loa”","normalized":"Spathiphyllum Schott ‘Mauna Loa’","canonical":{"stemmed":"Spathiphyllum ‘Mauna Loa’","simple":"Spathiphyllum ‘Mauna Loa’","full":"Spathiphyllum ‘Mauna Loa’"},"cardinality":2,"authorship":{"verbatim":"Schott","normalized":"Schott","authors":["Schott"],"originalAuth":{"authors":["Schott"]}},"cultivar":true,"details":{"uninomial":{"uninomial":"Spathiphyllum","cultivar":"Mauna Loa","authorship":{"verbatim":"Schott","normalized":"Schott","authors":["Schott"],"originalAuth":{"authors":["Schott"]}}}},"words":[{"verbatim":"Spathiphyllum","normalized":"Spathiphyllum","wordType":"UNINOMIAL","start":0,"end":13},{"verbatim":"Schott","normalized":"Schott","wordType":"AUTHOR_WORD","start":14,"end":20},{"verbatim":"Mauna","normalized":"Mauna","wordType":"CULTIVAR","start":22,"end":27},{"verbatim":"Loa","normalized":"Loa","wordType":"CULTIVAR","start":28,"end":31}],"id":"fb8afb5b-67b8-5bcc-8492-773cc40d3bb9","parserVersion":"test_version"}
```

--------------------------------

### Serialize Parsed Results to Different Formats

Source: https://context7.com/gnames/gnparser/llms.txt

Use the Output method to serialize a Parsed result to JSON (pretty or compact) or CSV. For CSV, use parsed.HeaderCSV to get the header row.

```go
cfg := gnparser.NewConfig(gnparser.OptFormat(gnfmt.PrettyJSON))
gnp := gnparser.New(cfg)
res := gnp.ParseName("Homo sapiens Linnaeus, 1758")

// Pretty JSON
fmt.Println(res.Output(gnfmt.PrettyJSON, false))

// Compact JSON with flat structure
fmt.Println(res.Output(gnfmt.CompactJSON, true))

// CSV row
header := parsed.HeaderCSV(gnfmt.CSV, false)
row := res.Output(gnfmt.CSV, false)
fmt.Println(header)
fmt.Println(row)
```

```text
Id,Verbatim,Cardinality,CanonicalStem,CanonicalSimple,CanonicalFull,Authorship,Year,Quality,NomCodeSetting
<uuid>,"Homo sapiens Linnaeus, 1758",2,Homo sapien,Homo sapiens,Homo sapiens,Linnaeus 1758,1758,1,
```

--------------------------------

### Parse Single Name to String using Python ctypes

Source: https://context7.com/gnames/gnparser/llms.txt

This Python example demonstrates parsing a single scientific name using the C shared library binding with ctypes. It shows how to call `ParseToString` and specifies parameters like details, diaereses, and author compaction. Remember to free the returned C string using `FreeMemory`.

```python
import ctypes

lib = ctypes.CDLL("./libgnparser.so")
lib.ParseToString.restype = ctypes.c_char_p
lib.FreeMemory.argtypes = [ctypes.c_char_p]

result_ptr = lib.ParseToString(
    b"Homo sapiens Linnaeus, 1758",  # name
    b"compact",                      # format: "csv" | "compact" | "pretty"
    b"",                             # nomenclatural code (empty = auto)
    1,                               # details: 0=no, 1=yes
    0,                               # diaereses: 0=no, 1=yes
    0,                               # compact authors: 0=no, 1=yes
    0,                               # flatten: 0=no, 1=yes
)
print(result_ptr.decode("utf-8"))
lib.FreeMemory(result_ptr)
```

--------------------------------

### Parse Names via REST API GET Request

Source: https://context7.com/gnames/gnparser/llms.txt

Parse names by providing a pipe-separated list in the URL path. Query parameters control output format and options like details, flattening, and nomenclatural code.

```bash
# Parse a single name (JSON output by default)
curl "http://localhost:9000/api/v1/Homo+sapiens+Linnaeus,+1758"

# Parse multiple names with pipe separator
curl "http://localhost:9000/api/v1/Homo+sapiens+Linnaeus|Bubo+bubo"

# Request CSV output with details
curl "http://localhost:9000/api/v1/Aus+bus+L.?csv=true&with_details=true"

# Botanical code hint, preserve diaereses, flatten JSON
curl "http://localhost:9000/api/v1/Leptochloöpsis+virgata?code=bot&diaereses=true&flatten=true"
```

--------------------------------

### Construct GNparser Instance and Inspect Configuration

Source: https://context7.com/gnames/gnparser/llms.txt

Create a `GNparser` instance using `gnparser.New` with a given `Config`. The returned interface allows access to parsing methods and configuration details like output format and version.

```go
cfg := gnparser.NewConfig(gnparser.OptFormat(gnfmt.PrettyJSON))
gnp := gnparser.New(cfg)

// Inspect configuration
fmt.Println(gnp.Format())       // gnfmt.PrettyJSON
fmt.Println(gnp.WithDetails())  // false
ver := gnp.GetVersion()
fmt.Println(ver.Version)        // e.g. "v1.14.2"
```

--------------------------------

### Using GNparser Library in Go

Source: https://github.com/gnames/gnparser/blob/main/README.md

Demonstrates how to use the GNparser Go library to parse a slice of name-strings and access parsed data. Includes configuration and output formatting.

```go
import (
  "fmt"

  "github.com/gnames/gnparser"
  "github.com/gnames/gnparser/ent/parsed"
)

func Example() {
  names := []string{"Pardosa moesta Banks, 1892", "Bubo bubo"}
  cfg := gnparser.NewConfig()
  gnp := gnparser.New(cfg)
  res := gnp.ParseNames(names)
  fmt.Println(res[0].Authorship.Normalized)
  fmt.Println(res[1].Canonical.Simple)
  fmt.Println(parsed.HeaderCSV(gnp.Format()))
  fmt.Println(res[0].Output(gnp.Format()))
  // Output:
  // Banks 1892
  // Bubo bubo
  // Id,Verbatim,Cardinality,CanonicalStem,CanonicalSimple,CanonicalFull,Authorship,Year,Quality
  // e2fdf10b-6a36-5cc7-b6ca-be4d3b34b21f,"Pardosa moesta Banks, 1892",2,Pardosa moest,Pardosa moesta,Pardosa moesta,Banks 1892,1892,1
}
```

--------------------------------

### Build gnparser Executable

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

Execute this command to create a gnparser executable and place it in your $GOPATH/bin directory.

```bash
just
```

--------------------------------

### Enable Experimental Nix Features

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Configure Nix to enable experimental features like 'nix-command' and 'flakes' by modifying the Nix configuration file.

```bash
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
```

--------------------------------

### Create GNparser Configuration with Options

Source: https://context7.com/gnames/gnparser/llms.txt

Use `gnparser.NewConfig` to create a configuration with default values and apply functional options to control parsing behavior. Options include output format, detail level, nomenclatural code hints, parallelism, and more.

```go
import (
    "github.com/gnames/gnfmt"
    "github.com/gnames/gnlib/ent/nomcode"
    "github.com/gnames/gnparser"
)

cfg := gnparser.NewConfig(
    gnparser.OptFormat(gnfmt.CompactJSON),   // "csv" | "tsv" | "compact" | "pretty"
    gnparser.OptWithDetails(true),           // include full detail tree
    gnparser.OptCode(nomcode.Zoological),    // hint for ambiguous names
    gnparser.OptJobsNum(8),                  // parallelism
    gnparser.OptBatchSize(10_000),
    gnparser.OptWithCapitaliation(true),     // capitalize first letter of input
    gnparser.OptWithPreserveDiaereses(true), // keep ï, ë, etc.
    gnparser.OptWithCompactAuthors(true),    // "A.B.Jones" instead of "A. B. Jones"
    gnparser.OptWithFlatOutput(true),        // flatten nested JSON output
    gnparser.OptWithSpeciesGroupCut(true),   // trim autonym/species-group stems
    gnparser.OptIgnoreHTMLTags(true),        // skip HTML tag stripping for speed
)
```

--------------------------------

### Build gnparser with Traditional Nix

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Build the project using traditional Nix commands. This also creates a 'result' symlink to the build output.

```bash
nix-build
```

--------------------------------

### GNparser Command Line Usage

Source: https://github.com/gnames/gnparser/blob/main/README.md

Demonstrates how to use GNparser from the command line for different output formats (CSV, TSV, JSON) and how to display help information. Ensure the binary is in your PATH.

```bash
tar xvf gnparser-v1.0.0-linux.tar.gz
sudo cp gnparser /usr/local/bin
```

```bash
# for CSV output
gnparser "Homo sapiens Linnaeus"
```

```bash
# for TSV output
gnparser -f tsv "Homo sapiens Linnaeus"
```

```bash
# for JSON output
gnparser -f compact "Homo sapiens Linnaeus"
```

```bash
gnparser -f compact "Homo sapiens Linnaeus" | jq
```

```bash
# or
gnparser -f pretty "Homo sapiens Linnaeus"
```

```bash
gnparser -h
```

--------------------------------

### Enter Development Shell with Nix Flakes

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Use this command to enter a development environment that includes Go and gopls when using Nix Flakes.

```bash
nix develop
```

--------------------------------

### Build with Experimental Nix Features Flag

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Alternatively, enable experimental features for a single command execution using a flag.

```bash
nix --experimental-features 'nix-command flakes' build
```

--------------------------------

### Docker Usage

Source: https://github.com/gnames/gnparser/blob/main/README.md

Instructions for running GNparser using a Docker image.

```bash
# run as a website and a RESTful service
docker run -p 0.0.0.0:80:8080 gnames/gognparser -p 8080

# just parse something
docker run gnames/gognparser "Amaurorhinus bewichianus (Wollaston,1860) (s.str.)"
```

--------------------------------

### Run Go Tests

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

Alternative command to run all tests for the gnparser project using Go's built-in testing utility.

```bash
go test ./...
```

--------------------------------

### Parse a single name with compact JSON output

Source: https://github.com/gnames/gnparser/blob/main/README.md

Use the `-f compact` flag to get a more concise JSON output for a single parsed scientific name.

```bash
# JSON compact format
gnparser "Parus major Linnaeus, 1788" -f compact
```

--------------------------------

### Run the built gnparser binary

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Execute the gnparser binary after it has been built and linked via a 'result' symlink.

```bash
./result/bin/gnparser
```

--------------------------------

### Enable Detailed Output with --details

Source: https://github.com/gnames/gnparser/wiki/Changes-in-v1.0.0

Use the `--details` flag with the `gnparser` CLI to include more comprehensive parsed data in the output. This flag is necessary when the detailed output is required beyond the default 'base' output.

```bash
gnparser -d
```

--------------------------------

### Get Parser Version via REST API

Source: https://context7.com/gnames/gnparser/llms.txt

Retrieve the current version of the gnparser service by calling the /api/v1/version endpoint. The response includes the version string and build timestamp.

```bash
curl "http://localhost:9000/api/v1/version"
```

--------------------------------

### Enter Development Shell without Nix Flakes

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Use this command to enter a development environment that includes Go and gopls when not using Nix Flakes.

```bash
nix-shell
```

--------------------------------

### REST API Interface

Source: https://github.com/gnames/gnparser/blob/main/README.md

The GNparser can be used as a REST API. The API and schema are described fully using OpenAPI specification. Make sure to CGI-escape name-strings for GET requests.

```APIDOC
## REST API

### Description
Provides a RESTful interface for parsing scientific names.

### Method
`GET`

### Endpoint
`/api?q={name-string}`

### Query Parameters
- **q** (string) - Required - The name-string to parse. Multiple names can be separated by '|'. CGI-escape special characters like '&' to '%26'.

### Method
`POST`

### Endpoint
`/api`

### Request Body
- **names** (array of strings) - Required - A JSON array of name-strings to parse.

### Request Example (POST)
```json
["Solanum mariae Särkinen & S.Knapp", "Ahmadiago Vánky 2004"]
```

### Response Example (Success)
```json
[{"id":"...","verbatim":"...", ...}]
```
```

--------------------------------

### Build gnparser with Nix Flakes

Source: https://github.com/gnames/gnparser/blob/main/NIX_BUILD.md

Use this command to build the project when using Nix Flakes. It creates a 'result' symlink pointing to the build output.

```bash
nix build
```

--------------------------------

### Parse Rhododendron with Cultivar

Source: https://github.com/gnames/gnparser/blob/main/testdata/test_data_cultivars.md

This example shows the JSON output for parsing a scientific name with a cultivar epithet. The `cultivar` field is set to true, and the `details.uninomial.cultivar` field specifies the cultivar name.

```json
{"parsed":true,"nomenclaturalCodeSetting":"ICNCP","quality":1,"verbatim":"Rhododendron cv Cilpinense","normalized":"Rhododendron ‘Cilpinense’","canonical":{"stemmed":"Rhododendron ‘Cilpinense’","simple":"Rhododendron ‘Cilpinense’","full":"Rhododendron ‘Cilpinense’"},"cardinality":2,"cultivar":true,"details":{"uninomial":{"uninomial":"Rhododendron","cultivar":"Cilpinense"}},"words":[{"verbatim":"Rhododendron","normalized":"Rhododendron","wordType":"UNINOMIAL","start":0,"end":12},{"verbatim":"Cilpinense","normalized":"Cilpinense","wordType":"CULTIVAR","start":16,"end":26}],"id":"abd299df-e4b2-533c-86eb-a4a5e273b934","parserVersion":"test_version"}
```

--------------------------------

### Compiling GNparser Shared C Library

Source: https://github.com/gnames/gnparser/blob/main/README.md

Instructions for compiling the GNparser shared C library using 'just' and 'GNU gcc compiler'. Includes copying the library to a project directory.

```bash
just clib
cd binding
cp libgnparser* /path/to/some/project
```

--------------------------------

### Create a Pool of GNparser Instances for Concurrent Use

Source: https://context7.com/gnames/gnparser/llms.txt

Use `gnparser.NewPool` to create a buffered channel of `GNparser` instances for safe concurrent access. Parsers are acquired from the pool, used, and then returned.

```go
cfg := gnparser.NewConfig()
pool := gnparser.NewPool(cfg, runtime.NumCPU())

// Acquire and release safely in goroutines
gnp := <-pool
result := gnp.ParseName("Abarema clypearia (Benth.) Kosterm.")
pool <- gnp // return to pool

fmt.Println(result.Canonical.Simple) // "Abarema clypearia"
```

--------------------------------

### gnparser.New

Source: https://context7.com/gnames/gnparser/llms.txt

Constructs a GNparser instance from a Config, returning the GNparser interface which provides all parsing methods.

```APIDOC
## gnparser.New(cfg Config) GNparser

### Description
Constructs a `GNparser` instance from a `Config`. Returns the `GNparser` interface, which provides all parsing methods.

### Parameters
- **cfg** (`Config`): The configuration object created by `gnparser.NewConfig`.

### Returns
- **GNparser**: An interface providing access to GNparser's parsing functionalities.

### Example
```go
cfg := gnparser.NewConfig(gnparser.OptFormat(gnfmt.PrettyJSON))
gnp := gnparser.New(cfg)

// Inspect configuration
fmt.Println(gnp.Format())       // gnfmt.PrettyJSON
fmt.Println(gnp.WithDetails())  // false
ver := gnp.GetVersion()
fmt.Println(ver.Version)        // e.g. "v1.14.2"
```
```

--------------------------------

### Basic GNparser Usage

Source: https://github.com/gnames/gnparser/blob/main/README.md

Demonstrates basic command-line usage for parsing scientific names, with and without the interactive flag.

```bash
gnparser "<i>Pomatomus</i>&nbsp;<i>saltator</i>"
```

```bash
gnparser -i "<i>Pomatomus</i>&nbsp;<i>saltator</i>"
```

```bash
gnparser -i "Pomatomus saltator"
```

--------------------------------

### Piping Input to GNparser in Ruby

Source: https://github.com/gnames/gnparser/blob/main/README.md

Shows how to use pipes to send input to GNparser and capture its output in Ruby. Requires the --stream -s flags.

```ruby
def self.start_gnparser
  io = {}

  ['compact', 'csv'].each do |format|
    stdin, stdout, stderr = Open3.popen3("./gnparser -s --format #{format}")
    io[format.to_sym] = { stdin: stdin, stdout: stdout, stderr: stderr }
  end
end
```

--------------------------------

### Run GNparser from Command Line

Source: https://github.com/gnames/gnparser/blob/main/README.md

Execute GNparser on a file with specified JSON output and thread count. Redirects output to /dev/null.

```bash
gnparser 1_000_000_names.txt -j 200 > /dev/null
```

--------------------------------

### Run gnparser Tests

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

Use this command to run all tests for the gnparser project.

```bash
just test
```

--------------------------------

### Running GNparser Docker Image

Source: https://github.com/gnames/gnparser/blob/main/README.md

Commands to run GNparser using Docker, either as a website/RESTful service or for direct parsing of a name-string.

```bash
# run as a website and a RESTful service
docker run -p 0.0.0.0:80:8080 gnames/gognparser -p 8080
```

```bash
# just parse something
docker run gnames/gognparser "Amaurorhinus bewichianus (Wollaston,1860) (s.str.)"
```

--------------------------------

### gnparser.NewConfig

Source: https://context7.com/gnames/gnparser/llms.txt

Creates a Config struct with default settings and applies functional options to customize parsing behavior. Options control aspects like output format, detail level, parallelism, and more.

```APIDOC
## gnparser.NewConfig(opts ...Option) Config

### Description
Creates a `Config` struct with defaults (`Format: CSV`, `JobsNum: runtime.NumCPU()`, `BatchSize: 50_000`, `Port: 8080`) and applies any functional options. All parsing behavior—nomenclatural code, output format, detail level, parallelism, and more—is controlled through this configuration.

### Parameters
#### Options
- **OptFormat(format gnfmt.Format)**: Sets the output format (e.g., `gnfmt.CompactJSON`, `gnfmt.CSV`).
- **OptWithDetails(details bool)**: If true, includes the full detail tree in the output.
- **OptCode(code nomcode.NomCode)**: Provides a hint for ambiguous names, specifying the nomenclatural code (e.g., `nomcode.Zoological`).
- **OptJobsNum(num int)**: Sets the number of parallel jobs for parsing.
- **OptBatchSize(size int)**: Configures the batch size for processing.
- **OptWithCapitalization(cap bool)**: If true, capitalizes the first letter of the input string.
- **OptWithPreserveDiaereses(preserve bool)**: If true, preserves diaereses (e.g., ï, ë).
- **OptWithCompactAuthors(compact bool)**: If true, formats authors compactly (e.g., "A.B.Jones").
- **OptWithFlatOutput(flat bool)**: If true, flattens the nested JSON output.
- **OptWithSpeciesGroupCut(cut bool)**: If true, trims autonym/species-group stems.
- **OptIgnoreHTMLTags(ignore bool)**: If true, skips HTML tag stripping for performance.

### Example
```go
import (
    "github.com/gnames/gnfmt"
    "github.com/gnames/gnlib/ent/nomcode"
    "github.com/gnames/gnparser"
)

cfg := gnparser.NewConfig(
    gnparser.OptFormat(gnfmt.CompactJSON),   // "csv" | "tsv" | "compact" | "pretty"
    gnparser.OptWithDetails(true),           // include full detail tree
    gnparser.OptCode(nomcode.Zoological),    // hint for ambiguous names
    gnparser.OptJobsNum(8),                  // parallelism
    gnparser.OptBatchSize(10_000),
    gnparser.OptWithCapitaliation(true),     // capitalize first letter of input
    gnparser.OptWithPreserveDiaereses(true), // keep ï, ë, etc.
    gnparser.OptWithCompactAuthors(true),    // "A.B.Jones" instead of "A. B. Jones"
    gnparser.OptWithFlatOutput(true),        // flatten nested JSON output
    gnparser.OptWithSpeciesGroupCut(true),   // trim autonym/species-group stems
    gnparser.OptIgnoreHTMLTags(true),        // skip HTML tag stripping for speed
)
```
```

--------------------------------

### Generate New Test Data

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

Navigate to the tools directory and run this command to generate new test data files (`test_data_new.md` and `test_data_cultivars_new.md`) if your changes affect existing test data.

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

--------------------------------

### Debug

Source: https://context7.com/gnames/gnparser/llms.txt

Returns the raw AST (abstract syntax tree) from the PEG parser engine as bytes. Useful for diagnosing parse failures or understanding grammar behavior.

```APIDOC
## Debug

### Description
Returns the raw AST (abstract syntax tree) from the PEG parser engine as bytes. Useful for diagnosing parse failures or understanding grammar behavior.

### Method Signature
`(GNparser).Debug(s string) []byte

### Parameters
* `s` (string) - The name string to generate the AST for.

### Returns
* `[]byte` - The raw AST as a byte slice.

### Request Example
```go
cfg := gnparser.NewConfig()
gnp := gnparser.New(cfg)

tree := gnp.Debug("Aus bus (L.) K.")
fmt.Println(string(tree)) // prints full PEG parse tree
```
```

--------------------------------

### gnparser.NewPool

Source: https://context7.com/gnames/gnparser/llms.txt

Creates a buffered channel of GNparser instances for safe concurrent use, allowing multiple goroutines to acquire, use, and return parsers.

```APIDOC
## gnparser.NewPool(cfg Config, size int) chan GNparser

### Description
Creates a buffered channel of `GNparser` instances for safe concurrent use. Callers acquire a parser from the pool, use it, then return it.

### Parameters
- **cfg** (`Config`): The configuration object for the GNparser instances.
- **size** (`int`): The size of the buffered channel (pool size).

### Returns
- **chan GNparser**: A channel from which `GNparser` instances can be acquired.

### Example
```go
cfg := gnparser.NewConfig()
pool := gnparser.NewPool(cfg, runtime.NumCPU())

// Acquire and release safely in goroutines
gnp := <-pool
result := gnp.ParseName("Abarema clypearia (Benth.) Kosterm.")
pool <- gnp // return to pool

fmt.Println(result.Canonical.Simple) // "Abarema clypearia"
```
```

--------------------------------

### ChangeConfig

Source: https://context7.com/gnames/gnparser/llms.txt

Returns a new `GNparser` with modified configuration. The original instance remains unchanged. Useful for per-request option overrides.

```APIDOC
## ChangeConfig

### Description
Returns a new `GNparser` with modified configuration. Original instance is unchanged. Useful for per-request option overrides in a server context.

### Method Signature
`(GNparser).ChangeConfig(opts ...Option) GNparser

### Parameters
* `opts` (...Option) - A variadic list of configuration options to apply.

### Returns
* `GNparser` - A new GNparser instance with the applied configuration.

### Request Example
```go
gnp := gnparser.New(gnparser.NewConfig())

// Create a variant configured for botanical names
gnpBot := gnp.ChangeConfig(
    gnparser.OptCode(nomcode.Botanical),
    gnparser.OptWithDetails(true),
    gnparser.OptFormat(gnfmt.PrettyJSON),
)

res := gnpBot.ParseName("Aus (Bus) L.")
fmt.Println(res.QualityWarnings) // warns about ICN author vs subgenus ambiguity
```
```

--------------------------------

### Parse a file with detailed output and compact JSON

Source: https://github.com/gnames/gnparser/blob/main/README.md

Parse a file of scientific names and output the results in a compact JSON format (`-f compact`) with additional details (`-d`).

```bash
# to parse file with more detailed output
gnparser names.txt -d -f compact > names_parsed.txt
```

--------------------------------

### Update Test Data Files

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

After generating new test data, move the new files to replace the old ones. It is crucial to review the differences before this step.

```bash
mv test_data_new.md test_data.md
mv test_data_cultivars_new.md test_data_cultivars.md
```

--------------------------------

### Modify GNparser Configuration with ChangeConfig

Source: https://context7.com/gnames/gnparser/llms.txt

Use `ChangeConfig` to create a new `GNparser` instance with updated options without altering the original. This is useful for per-request configuration changes, such as specifying botanical names or enabling detailed output.

```go
gnp := gnparser.New(gnparser.NewConfig())

// Create a variant configured for botanical names
gnpBot := gnp.ChangeConfig(
    gnparser.OptCode(nomcode.Botanical),
    gnparser.OptWithDetails(true),
    gnparser.OptFormat(gnfmt.PrettyJSON),
)

res := gnpBot.ParseName("Aus (Bus) L.")
fmt.Println(res.QualityWarnings) // warns about ICN author vs subgenus ambiguity
```

--------------------------------

### Accessing Raw Parsed AST Tree

Source: https://github.com/gnames/gnparser/blob/main/CONTRIBUTING.md

To view the raw AST generated by the PEG parser, modify the `debug` constant to `true` in `gnparser/gnparser/cmd/root.go` and run `just`. This allows examination of the raw node tree for a given string.

```bash
gnparser "Bubo bubo"
```