json-ast Reference

Module defined in lua/common/json-ast.lua. A JSON/jbeam AST (Abstract Syntax Tree) parser that preserves formatting, comments, and whitespace. Used by the in-game jbeam editor for lossless round-trip editing.

Exports

Functions

M.parse(str, addAstId)

Parses a JSON/jbeam string into an AST context object that preserves all formatting.

• Parameters:
  • str - string - JSON/jbeam source text
  • addAstId - boolean|nil - Whether to add __astNodeIdx fields to converted Lua data
• Returns: table - Parse context with AST

Return structure:

{
  ast = {
    nodes = { ... }  -- array of AST nodes
  },
  transient = {
    hierarchy = { ... },  -- parent→children index mapping
    root = number,        -- root node index
    luaDataRaw = table,   -- converted Lua data (without table schema)
    luaData = table,      -- converted Lua data (with table schema processing)
    linesIndexes = { ... },     -- line→first node index mapping
    nodeIdxToLineNum = { ... }, -- node index→line number mapping
  }
}

M.stringify(ast)

Converts an AST back to a string, preserving all formatting.

• Parameters:
  • ast - table - AST object with nodes array
• Returns: string - Reconstructed source text

M.stringifyNode(node)

Converts a single AST node to its string representation.

• Parameters:
  • node - table - AST node {type, ...}
• Returns: string - JSON string representation

M.stringifyNodes(nodes)

Converts an array of AST nodes to a string.

• Parameters:
  • nodes - table - Array of AST nodes
• Returns: string

M.testFile(filename, writeAST, addASTId)

Tests round-trip parsing of a file (parse → stringify → compare).

• Parameters:
  • filename - string - File to test
  • writeAST - boolean|nil - Whether to write the AST to disk
  • addASTId - boolean|nil - Add AST IDs to Lua data
• Returns: boolean - true on success

M.testFiles(writeAST, reportOK)

Tests round-trip parsing of all .jbeam files.

• Parameters:
  • writeAST - boolean|nil
  • reportOK - boolean|nil - Log successful files too

Internal Notes

• AST node types: object_begin, object_end, list_begin, list_end, array_delimiter, string, string_single, number, bool, comment, comment_multiline, space, tab, newline, newline_windows, key_delimiter, literal
• Numbers preserve precision digits and prefix plus signs
• Hierarchy is computed after parsing for parent-child relationships
• Uses jbeam/tableSchema for table schema processing (converting jbeam table sections to key-value pairs)
• Line buffers are created for editor integration (jump to line, node-to-line mapping)