0
# Ohm
1

2
Ohm is a parsing toolkit consisting of a library and domain-specific language for creating parsers, interpreters, and compilers. It's based on parsing expression grammars (PEGs) with full support for left-recursive rules, object-oriented grammar extension, and modular semantic actions that are completely separated from grammars.
3

4
## Package Information
5

6
- **Package Name**: ohm-js
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install ohm-js`
10

11
## Core Imports
12

13
```javascript
14
import { grammar, grammars, pexprs, ohmGrammar, version } from "ohm-js";
15
```
16

17
For TypeScript with full type support:
18

19
```typescript
20
import { 
21
  grammar, 
22
  grammars, 
23
  Grammar, 
24
  Semantics, 
25
  MatchResult, 
26
  Matcher,
27
  Interval,
28
  pexprs,
29
  ohmGrammar,
30
  ExperimentalIndentationSensitive,
31
  version
32
} from "ohm-js";
33
```
34

35
CommonJS:
36

37
```javascript
38
const { grammar, grammars, pexprs, ohmGrammar, version } = require("ohm-js");
39
```
40

41
Extras module (utilities):
42

43
```javascript
44
import { toAST, getLineAndColumnMessage, VisitorFamily, extractExamples } from "ohm-js/extras";
45
```
46

47
## Basic Usage
48

49
```javascript
50
import { grammar } from "ohm-js";
51

52
// Define a simple arithmetic grammar
53
const arithmeticGrammar = grammar(`
54
  Arithmetic {
55
    Exp = AddExp
56
    AddExp = MulExp ("+" MulExp | "-" MulExp)*
57
    MulExp = PriExp ("*" PriExp | "/" PriExp)*
58
    PriExp = "(" Exp ")" | number
59
    number = digit+
60
  }
61
`);
62

63
// Parse an expression
64
const match = arithmeticGrammar.match("2 + 3 * 4");
65
if (match.succeeded()) {
66
  console.log("Parse successful!");
67
} else {
68
  console.error("Parse failed:", match.message);
69
}
70

71
// Create semantic actions
72
const semantics = arithmeticGrammar.createSemantics().addOperation('eval', {
73
  Exp(e) { return e.eval(); },
74
  AddExp(expr) {
75
    return expr.children.length === 1
76
      ? expr.children[0].eval()
77
      : // Handle addition/subtraction operations
78
        this.sourceString; // Simplified
79
  },
80
  number(digits) {
81
    return parseInt(this.sourceString);
82
  }
83
});
84

85
// Evaluate the expression
86
const result = semantics(match).eval();
87
```
88

89
## Architecture
90

91
Ohm is built around several key components:
92

93
- **Grammar System**: Core grammar compilation and management (`Grammar`, `Namespace`)
94
- **Parsing Engine**: Match execution and incremental parsing (`MatchResult`, `Matcher`)
95
- **Semantic Actions**: Modular semantic processing (`Semantics`, `Node`)
96
- **Parsing Expressions**: Low-level parsing expression classes (`pexprs`)
97
- **Utility Functions**: Helper functions for error reporting and AST conversion
98

99
## Capabilities
100

101
### Grammar Creation and Management
102

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

105
```typescript { .api }
106
function grammar(source: string, namespace?: Namespace): Grammar;
107
function grammars(source: string, namespace?: Namespace): Namespace;
108

109
interface Namespace {
110
  [index: string]: Grammar;
111
}
112
```
113

114
[Grammar Management](./grammar-management.md)
115

116
### Parsing and Matching
117

118
Grammar parsing capabilities with support for incremental parsing and detailed error reporting.
119

120
```typescript { .api }
121
interface Grammar {
122
  name: string;
123
  superGrammar: Grammar;
124
  rules: {[ruleName: string]: RuleInfo};
125
  
126
  match(input: string, startRule?: string): MatchResult;
127
  matcher(): Matcher;
128
  trace(input: string, startRule?: string): Object;
129
  isBuiltIn(): boolean;
130
  createSemantics(): Semantics;
131
  extendSemantics(superSemantics: Semantics): Semantics;
132
}
133

134
interface MatchResult {
135
  succeeded(): boolean;
136
  failed(): boolean;
137
  message?: string;
138
  shortMessage?: string;
139
  getInterval(): Interval;
140
}
141
```
142

143
[Parsing and Matching](./parsing-and-matching.md)
144

145
### Semantic Actions
146

147
System for defining and executing semantic actions on parse results, completely separated from grammar definitions.
148

149
```typescript { .api }
150
interface Semantics {
151
  (match: MatchResult): Dict;
152
  
153
  addOperation<T>(name: string, actionDict: ActionDict<T>): Semantics;
154
  addAttribute<T>(name: string, actionDict: ActionDict<T>): Semantics;
155
  extendOperation<T>(name: string, actionDict: ActionDict<T>): Semantics;
156
  extendAttribute<T>(name: string, actionDict: ActionDict<T>): Semantics;
157
}
158

159
interface ActionDict<T> extends BaseActionDict<T> {
160
  [index: string]: Action<T> | undefined;
161
}
162

163
type Action<T> = (this: Node, ...args: Node[]) => T;
164
```
165

166
[Semantic Actions](./semantic-actions.md)
167

168
### Parsing Expressions
169

170
Low-level parsing expression classes that form the building blocks of Ohm grammars.
171

172
```typescript { .api }
173
const pexprs: {
174
  PExpr: typeof PExpr;
175
  Terminal: typeof Terminal;
176
  Range: typeof Range;
177
  Param: typeof Param;
178
  Alt: typeof Alt;
179
  Extend: typeof Extend;
180
  Splice: typeof Splice;
181
  Seq: typeof Seq;
182
  Iter: typeof Iter;
183
  Star: typeof Star;
184
  Plus: typeof Plus;
185
  Opt: typeof Opt;
186
  Not: typeof Not;
187
  Lookahead: typeof Lookahead;
188
  Lex: typeof Lex;
189
  Apply: typeof Apply;
190
  UnicodeChar: typeof UnicodeChar;
191
  CaseInsensitiveTerminal: typeof CaseInsensitiveTerminal;
192
  any: PExpr;
193
  end: PExpr;
194
};
195
```
196

197
[Parsing Expressions](./parsing-expressions.md)
198

199
### Utilities and Extras
200

201
Additional utilities for error reporting, AST conversion, and advanced tree traversal patterns.
202

203
```typescript { .api }
204
// Error reporting utilities
205
function getLineAndColumnMessage(str: string, offset: number, ...ranges: number[][]): string;
206
function getLineAndColumn(str: string, offset: number): LineAndColumnInfo;
207

208
// AST conversion
209
function toAST(matchResult: MatchResult, mapping?: {}): {};
210
function semanticsForToAST(g: Grammar): Semantics;
211

212
// Example extraction from grammar comments
213
function extractExamples(grammarsDef: string): Example[];
214

215
// Visitor pattern for tree traversal
216
class VisitorFamily {
217
  constructor(config: VisitorConfig);
218
  addOperation(signature: string, actions: {}): VisitorFamily;
219
  wrap(thing: any): any;
220
}
221
```
222

223
[Utilities and Extras](./utilities-and-extras.md)
224

225
## Built-in Resources
226

227
```typescript { .api }
228
const ohmGrammar: Grammar;
229
const ExperimentalIndentationSensitive: Grammar;
230
const version: string;
231
```
232

233
- **`ohmGrammar`**: The meta-grammar used to parse Ohm grammar definitions
234
- **`ExperimentalIndentationSensitive`**: Experimental grammar for indentation-sensitive languages
235
- **`version`**: Package version string