tessl/npm-ohm-js

An object-oriented language for parsing and pattern matching based on parsing expression grammars

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Grammar Management

Name: tessl/npm-ohm-js
Author: tessl

Core functionality for creating and managing Ohm grammars from source definitions.

Imports

import { grammar, grammars, _buildGrammar } from "ohm-js";

For TypeScript:

import { grammar, grammars, Grammar, Namespace, _buildGrammar } from "ohm-js";

Capabilities

Grammar Creation

Creates a single Grammar instance from source code containing exactly one grammar definition.

/**
 * Instantiate the Grammar defined by source. If specified, namespace is
 * the Namespace to use when resolving external references in the grammar.
 * @param source - String containing grammar definition
 * @param namespace - Optional namespace for resolving external references
 * @returns Grammar instance
 * @throws Error if source contains zero or more than one grammar definition
 */
function grammar(source: string, namespace?: Namespace): Grammar;

Usage Examples:

import { grammar } from "ohm-js";

// Create a simple grammar
const myGrammar = grammar(`
  MyGrammar {
    greeting = "hello" | "hi"
    name = letter+
    message = greeting " " name
  }
`);

// Use with namespace for grammar extension
const baseGrammar = grammar(`
  Base {
    number = digit+
  }
`);

const extendedGrammar = grammar(`
  Extended <: Base {
    decimal = number "." number
  }
`, { Base: baseGrammar });

Multiple Grammar Creation

Creates a Namespace containing Grammar instances for all grammars defined in the source.

/**
 * Create a new Namespace containing Grammar instances for all of the
 * grammars defined in source.
 * If namespace is specified, it will be the prototype of the new Namespace.
 * @param source - String containing one or more grammar definitions
 * @param namespace - Optional parent namespace
 * @returns Namespace containing all defined grammars
 */
function grammars(source: string, namespace?: Namespace): Namespace;

Usage Examples:

import { grammars } from "ohm-js";

// Create multiple grammars at once
const myGrammars = grammars(`
  Math {
    number = digit+
    expr = number ("+" number)*
  }
  
  String {
    word = letter+
    phrase = word (" " word)*
  }
`);

// Access individual grammars
const mathGrammar = myGrammars.Math;
const stringGrammar = myGrammars.String;

Namespace Interface

Container for multiple Grammar instances, indexed by grammar name.

/**
 * A Namespace is a dictionary of Grammars
 */
interface Namespace {
  [index: string]: Grammar;
}

Usage Examples:

// Iterate over grammars in a namespace
for (const grammarName in myGrammars) {
  const grammar = myGrammars[grammarName];
  console.log(`Grammar: ${grammar.name}`);
}

// Create hierarchical namespaces
const childNamespace = grammars(childSource, parentNamespace);

Internal Grammar Building

Internal function used by ohm-editor for incremental parsing support.

/**
 * Internal function for building grammars (used by ohm-editor)
 * @internal This is not part of the public API
 * @param matchResult - MatchResult from parsing grammar source
 * @param namespace - Namespace to build grammar into  
 * @returns The built namespace with grammars
 */
function _buildGrammar(matchResult: any, namespace?: Namespace): any;

Usage Examples:

import { _buildGrammar, ohmGrammar } from "ohm-js";

// This is advanced internal usage - not recommended for general use
const grammarSource = `
  MyGrammar {
    rule = "hello"
  }
`;

const match = ohmGrammar.match(grammarSource, 'Grammars');
if (match.succeeded()) {
  const namespace = {};
  _buildGrammar(match, namespace);
  // namespace now contains the built grammar
}

Note: This function is exported for ohm-editor compatibility but is not intended for general use. Most users should use grammar() or grammars() instead.

Error Handling

The grammar creation functions will throw errors in the following cases:

Syntax errors in grammar source: Throws error with detailed position information
Missing grammar definition: grammar() throws if source contains no grammar definitions
Multiple grammar definitions: grammar() throws if source contains more than one definition
Invalid source type: Throws TypeError if source is not a string (Node.js Buffer objects are automatically converted)

Error Example:

try {
  const invalidGrammar = grammar("invalid syntax here");
} catch (error) {
  console.error("Grammar compilation failed:", error.message);
  // Error message includes line and column information
}

Type Definitions

interface Dict {
  [index: string]: any;
}

Install with Tessl CLI

npx tessl i tessl/npm-ohm-js

docs

grammar-management.md

index.md

parsing-and-matching.md

parsing-expressions.md

semantic-actions.md

utilities-and-extras.md

tile.json

tessl/npm-ohm-js