0
# Grammar Management
1

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

4
## Imports
5

6
```javascript
7
import { grammar, grammars, _buildGrammar } from "ohm-js";
8
```
9

10
For TypeScript:
11

12
```typescript
13
import { grammar, grammars, Grammar, Namespace, _buildGrammar } from "ohm-js";
14
```
15

16
## Capabilities
17

18
### Grammar Creation
19

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

22
```typescript { .api }
23
/**
24
 * Instantiate the Grammar defined by source. If specified, namespace is
25
 * the Namespace to use when resolving external references in the grammar.
26
 * @param source - String containing grammar definition
27
 * @param namespace - Optional namespace for resolving external references
28
 * @returns Grammar instance
29
 * @throws Error if source contains zero or more than one grammar definition
30
 */
31
function grammar(source: string, namespace?: Namespace): Grammar;
32
```
33

34
**Usage Examples:**
35

36
```javascript
37
import { grammar } from "ohm-js";
38

39
// Create a simple grammar
40
const myGrammar = grammar(`
41
  MyGrammar {
42
    greeting = "hello" | "hi"
43
    name = letter+
44
    message = greeting " " name
45
  }
46
`);
47

48
// Use with namespace for grammar extension
49
const baseGrammar = grammar(`
50
  Base {
51
    number = digit+
52
  }
53
`);
54

55
const extendedGrammar = grammar(`
56
  Extended <: Base {
57
    decimal = number "." number
58
  }
59
`, { Base: baseGrammar });
60
```
61

62
### Multiple Grammar Creation
63

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

66
```typescript { .api }
67
/**
68
 * Create a new Namespace containing Grammar instances for all of the
69
 * grammars defined in source.
70
 * If namespace is specified, it will be the prototype of the new Namespace.
71
 * @param source - String containing one or more grammar definitions
72
 * @param namespace - Optional parent namespace
73
 * @returns Namespace containing all defined grammars
74
 */
75
function grammars(source: string, namespace?: Namespace): Namespace;
76
```
77

78
**Usage Examples:**
79

80
```javascript
81
import { grammars } from "ohm-js";
82

83
// Create multiple grammars at once
84
const myGrammars = grammars(`
85
  Math {
86
    number = digit+
87
    expr = number ("+" number)*
88
  }
89
  
90
  String {
91
    word = letter+
92
    phrase = word (" " word)*
93
  }
94
`);
95

96
// Access individual grammars
97
const mathGrammar = myGrammars.Math;
98
const stringGrammar = myGrammars.String;
99
```
100

101
### Namespace Interface
102

103
Container for multiple Grammar instances, indexed by grammar name.
104

105
```typescript { .api }
106
/**
107
 * A Namespace is a dictionary of Grammars
108
 */
109
interface Namespace {
110
  [index: string]: Grammar;
111
}
112
```
113

114
**Usage Examples:**
115

116
```javascript
117
// Iterate over grammars in a namespace
118
for (const grammarName in myGrammars) {
119
  const grammar = myGrammars[grammarName];
120
  console.log(`Grammar: ${grammar.name}`);
121
}
122

123
// Create hierarchical namespaces
124
const childNamespace = grammars(childSource, parentNamespace);
125
```
126

127
### Internal Grammar Building
128

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

131
```typescript { .api }
132
/**
133
 * Internal function for building grammars (used by ohm-editor)
134
 * @internal This is not part of the public API
135
 * @param matchResult - MatchResult from parsing grammar source
136
 * @param namespace - Namespace to build grammar into  
137
 * @returns The built namespace with grammars
138
 */
139
function _buildGrammar(matchResult: any, namespace?: Namespace): any;
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
import { _buildGrammar, ohmGrammar } from "ohm-js";
146

147
// This is advanced internal usage - not recommended for general use
148
const grammarSource = `
149
  MyGrammar {
150
    rule = "hello"
151
  }
152
`;
153

154
const match = ohmGrammar.match(grammarSource, 'Grammars');
155
if (match.succeeded()) {
156
  const namespace = {};
157
  _buildGrammar(match, namespace);
158
  // namespace now contains the built grammar
159
}
160
```
161

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

164
## Error Handling
165

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

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

173
**Error Example:**
174

175
```javascript
176
try {
177
  const invalidGrammar = grammar("invalid syntax here");
178
} catch (error) {
179
  console.error("Grammar compilation failed:", error.message);
180
  // Error message includes line and column information
181
}
182
```
183

184
## Type Definitions
185

186
```typescript { .api }
187
interface Dict {
188
  [index: string]: any;
189
}
190
```