API Reference

April 7, 2026 · View on GitHub

Parsing

`Jsonic(src, meta?, parent_ctx?)`

Parse a string using default settings. Jsonic is both a callable function and a namespace for the API below.

const { Jsonic } = require('jsonic')

Jsonic('a:1')  // {"a": 1}

The optional meta parameter passes arbitrary data through to plugins and rule actions.

`instance(src, meta?)`

A configured instance is also directly callable.

const j = Jsonic.make({ comment: { lex: false } })
j('a:1')  // {"a": 1}

Instance Management

`Jsonic.make(options?)`

Create a new parser instance with the given options. Unset options fall back to defaults. Returns a callable instance with the full API.

const strict = Jsonic.make({
  comment: { lex: false },
  text: { lex: false }
})

The options parameter can also be a string shortcut:

'json' -- strict JSON parser (only JSON-tagged grammar rules)
'jsonic' -- minimal jsonic parser

`Jsonic.empty(options?)`

Create an empty parser with no grammar or defaults. Used as a base for building custom parsers from scratch.

Configuration

`instance.options`

Direct access to the current options object.

`instance.options(changes?)`

When called as a function, deep-merges changes into the options and returns the result. Does not modify the instance in-place (use make() for that).

`instance.config()`

Returns a deep copy of the internal configuration. This is the resolved, compiled form of the options -- useful for debugging.

Grammar

`instance.rule(name?, definer?)`

Access or modify grammar rules.

rule() -- returns the full rule spec map
rule(name) -- returns the rule spec for name
rule(name, definer) -- calls definer(ruleSpec) to modify the rule

Each rule spec has open and close alternate lists, plus state actions (bo, bc, ao, ac) for before/after open/close phases.

jsonic.rule('val', (rs) => {
  rs.open.unshift({
    s: [[myToken]],
    a: (rule) => { rule.node = 'custom' }
  })
})

`instance.token(ref)`

Get or create a token type. ref is a string name (e.g., '#OB' for open brace). When called with a second argument mapping to a source character, it registers a new fixed token.

const T_TILDE = jsonic.token('#TL', '~')

jsonic.use(myPlugin, { key: 'value' })

Plugins are re-applied when deriving child instances.

Events

`instance.sub({ lex?, rule? })`

Subscribe to lex and/or rule events.

lex(token, rule, ctx) -- fires after each token is lexed
rule(rule, ctx) -- fires before each rule processing step

jsonic.sub({
  lex: (token, rule, ctx) => {
    console.log('token:', token)
  }
})

Utilities

`instance.util`

A collection of helper functions for plugin authors:

tokenize -- convert token names to Tin numbers
deep -- deep merge objects
clone -- deep clone
regexp -- safe regex construction
srcfmt -- format source strings for display
charset -- build character sets
errmsg, strinject -- error message helpers
prop, keys, values, entries, omap -- object utilities
trimstk, makelog, clean, str, mesc, escre -- misc helpers

Property	Description
`code`	Error code (`'unexpected'`, `'unterminated_string'`, etc.)
`detail`	Human-readable message
`pos`	0-based character position
`row`	1-based line number
`col`	1-based column number
`src`	Source fragment at the error

Exports

The main module exports:

Export	Description
`Jsonic`	Main parser (callable + API)
`JsonicError`	Error class
`Parser`	Parser class
`makeLex`, `makeParser`	Factory functions
`makeToken`, `makePoint`, `makeRule`, `makeRuleSpec`	Internal constructors
`makeFixedMatcher`, `makeSpaceMatcher`, `makeLineMatcher`	Lexer matchers
`makeStringMatcher`, `makeCommentMatcher`, `makeNumberMatcher`, `makeTextMatcher`	Lexer matchers
`OPEN`, `CLOSE`, `BEFORE`, `AFTER`, `EMPTY`	Step constants
`util`	Utility functions
`make`	Alias for `Jsonic.make`