en ParseOptions - chiba233/yumeDSL GitHub Wiki

ParseOptions

Handler Helpers | Token Structure

The config object you pass to parseRichText, createParser, and parseStructural. Lots of options, but most have sensible defaults — handlers alone is enough to get started.

Options overview

                        ParseOptions
                            │
         ┌──────────────────┼──────────────────┐
         ▼                  ▼                  ▼
   ParserBaseOptions    ParseOptions only    StructuralParseOptions only
   (shared base)        (parseRichText)      (parseStructural)
         │                  │                  │
    ┌────┼────┐        ┌────┼────┐          just one:
    │    │    │        │    │    │          trackPositions
    ▼    ▼    ▼        ▼    ▼    ▼
handlers  syntax  ...  createId  blockTags  ...
depthLimit tagName     onError   mode(deprecated)
allowForms             trackPositions
implicitInlineShorthand
baseOffset
tracker

Everyday options

Option In a nutshell Default
handlers Tag name → handler map, the one you need {}
onError Callback on parse errors; omit to silently ignore silent
trackPositions Stamp every token with source coordinates false

Safety / limits

Option In a nutshell Default
allowForms Globally restrict which tag forms (inline/raw/block) are accepted all enabled
implicitInlineShorthand Control name(...) shorthand in inline args. Since 1.3 false
depthLimit Max nesting depth to prevent stack overflow 50

Custom syntax

Option In a nutshell Default
syntax Swap out $$, (, )$$, etc. default $$tag(...)$$ family
tagName Control which characters are allowed in tag names letters + underscore + hyphen

Substring parsing

Option In a nutshell Default
baseOffset Where the slice starts in the original document 0
tracker Line table built from the original doc, used with baseOffset none

parseRichText only

Option In a nutshell Default
createId Custom token ID generation sequential counter rt-0, rt-1, ...
blockTags Declare which tags get line-break normalization (usually auto-derived) derived from handlers

Detailed reference

handlers

handlers?: Record<string, TagHandler>

Tag name to handler map. Tags not in handlers don't cause errors — their syntax is output as plain text (graceful degradation).

Use Handler Helpers to register in bulk and skip the boilerplate.

allowForms

allowForms?: readonly ("inline" | "raw" | "block")[]

Globally restrict which tag forms the parser accepts. Unlisted forms degrade to literal text.

// UGC scenario: inline only, block/raw too dangerous
parseRichText(input, { handlers, allowForms: ["inline"] });

implicitInlineShorthand

Since 1.3

implicitInlineShorthand?: boolean | readonly string[]

Control implicit inline shorthand (name(...)) inside inline argument context. When enabled, the parser recognizes tagName( as an inline tag open inside an existing inline arg — no $$ prefix needed.

  • false (default): disabled — only full $$tag(...)$$ syntax recognized.
  • true: enabled for every registered tag that supports inline form.
  • string[]: enabled only for listed tag names.
// Enable for all inline-capable tags
parseRichText("$$bold(Hello italic(world))$$", {
    handlers, implicitInlineShorthand: true,
});

// Enable only for specific tags
parseRichText("$$bold(Hello italic(world))$$", {
    handlers, implicitInlineShorthand: ["italic"],
});

Parsing priority: full DSL structures ($$tag(...)$$, raw, block) always match first. Shorthand is only attempted when no full structure is found. Literal parentheses inside shorthand args must be escaped with \) / \(.

depthLimit

depthLimit?: number  // default 50

Max recursive nesting. Exceeding it triggers a DEPTH_LIMIT error and the tag degrades to literal text. Prevents malicious input from blowing the stack.

syntax

syntax?: Partial<SyntaxInput>

Override DSL syntax tokens. Only specify what you want to change; the rest keeps its defaults. See Custom Syntax.

interface SyntaxInput {
    tagPrefix: string;    // default: "$$"
    tagOpen: string;      // default: "("
    tagClose: string;     // default: ")$$"
    tagDivider: string;   // default: "|"
    endTag: string;       // default: "end$$"
    rawOpen: string;      // default: ")%"
    blockOpen: string;    // default: ")*"
    blockClose: string;   // default: "*end$$"
    rawClose: string;     // default: "%end$$"
    escapeChar: string;   // default: "\\"
}

tagName

tagName?: Partial<TagNameConfig>

Control tag name characters. See Custom Tag Name Characters.

interface TagNameConfig {
    isTagStartChar: (char: string) => boolean;  // what can start a tag name
    isTagChar: (char: string) => boolean;        // what can appear after the first char
}

baseOffset / tracker

Used when parsing substrings. baseOffset shifts offset; pair it with tracker for fully correct line/column. See Source Position Tracking.

createId

createId?: (token: TokenDraft) => string

Custom token ID generation. Default is a sequential counter rt-0, rt-1, .... For content-based stable IDs that survive surrounding edits, use createEasyStableId(). See Stable Token IDs.

blockTags

blockTags?: readonly BlockTagInput[]

Declare which tags get line-break normalization, preventing extra blank lines at render time.

  • raw / block: strips one boundary line break at each end of multiline tag content
  • inline: strips the trailing \n immediately after inline close $$ — for tags using inline syntax that render as block-level elements

Usually omit this — the parser auto-derives raw/block from handlers. When you do pass blockTags, overrides are per-tag: tags you list completely replace auto-derivation for that tag; tags you don't mention keep auto-derived behavior. Inline normalization is never auto-derived — it must be explicitly declared. Pass a string to normalize all three forms (raw + block + inline); pass { tag, forms } for fine-grained control.

See Handler Helpers declareMultilineTags for the full explanation.

onError

onError?: (error: ParseError) => void

Called on parse errors. Omit to silently discard — the parser still produces best-effort output.

interface ParseError {
    code: ErrorCode;
    message: string;
    line: number;
    column: number;
    snippet: string;
}

See Error Handling.

trackPositions

trackPositions?: boolean  // default false

When on, every token gets a position property. Performance overhead is near zero. See Source Position Tracking.

mode (deprecated)

mode?: "render"

Only value: "render". Backward compat only. Don't use in new code.

StructuralParseOptions

Used by parseStructural. Extends ParserBaseOptions with just trackPositions.

Does not include createId, blockTags, onError, or mode — the structural parser doesn't assign IDs, doesn't normalize line breaks, and doesn't need handler registration.