# The parser

The bitmark parser is the reference implementation of bitmark. It is offered
by Get More Brain for the community, as open source under the ISC licence.
These docs describe what it does; when the two disagree, the parser is right.

## One core, every platform

The parser is one Rust core compiled to WebAssembly. It runs in the browser,
in Node.js, as a command-line tool (ready-made for macOS, Linux and Windows)
and directly in Rust. Every one of them gives the same result.

## What it does

- Converts bitmark to JSON and JSONL, and back.
- Writes HTML and XML, and imports standards documents in NISO STS XML.
- Checks content against the language definitions and reports errors,
  warnings and notes, each with a stable code.
- Compares two documents as a semantic diff: tag order, spacing and omitted
  defaults are not differences.
- Records where each bit sits in the input and in the output (`--bit-spans`,
  `--bit-anchors`), so tools can cite and link back.
- Reports what a conversion could not carry over (`--mapping-report`) instead
  of losing it silently.

## Get it

- **npm**: `npm install @gmb/bitmark-parser` for Node.js and bundlers; the
  package also brings the `bitmark` command.
- **Without installing**: `npx @gmb/bitmark-parser convert file.bitmark`.
- **In a web page**: load it from a CDN such as jsDelivr
  (`https://cdn.jsdelivr.net/npm/@gmb/bitmark-parser@latest/dist/browser/bitmark-parser.min.js`);
  pin a version instead of `latest` in production.
- **VS Code**: the bitmark language extension adds highlighting, problems,
  completion, hover and live previews (not on the Marketplace yet).
- **Try it first**: the [bitmark playground](https://getmorebrain.github.io/bitmark-playground/).

## Quick start

```bash
npx @gmb/bitmark-parser convert first.bitmark --output-format jsonl
npx @gmb/bitmark-parser convert first.json --input-format json --output-format bitmark
npx @gmb/bitmark-parser diff old.bitmark new.bitmark
```

```js
import { convert } from "@gmb/bitmark-parser";

const json = convert("[.article]\nHello", { inputFormat: "bitmark", warnings: true });
const bitmark = convert(json, { inputFormat: "json", outputFormat: "bitmark" });
```

In the browser, call `await init()` once before the first `convert`.
[Getting started](https://docs.bitmark-association.org/concepts/getting-started.md) walks through a first bit.

## JSONL for APIs

JSONL, one bit per line, is the recommended format for delivering bitmark
through an API. Each line stands alone, so a reader can stream a large
document, stop early or fetch part of it. The parser reads JSONL back as
easily as it writes it:

```bash
npx @gmb/bitmark-parser convert book.bitmark --output-format jsonl -o book.jsonl
npx @gmb/bitmark-parser convert book.jsonl --output-format bitmark
```

## Versions

Two numbers matter. The parser has its own release number (for example
7.21.2); the language it implements is bitmark 3. Every JSON entry names both
in its `parser` field. These docs are built from a parser release, so they
always describe what that release does.

## Under the hood

A readable grammar describes the language and is checked against the parser
in every build, so the two cannot drift apart. Editors highlight bitmark
through the parser's own semantic tokens, so what is coloured is exactly what
the parser reads.