Ohm ยท
![Chat on Discord](https://camo.githubusercontent.com/d4af570d10f67290bc6d4c6601169cd13fef09f63df7749663e3c7c603b6c76c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636861742d6f6e253230646973636f72642d3732383964612e7376673f73616e6974697a653d74727565)
Ohm is a parsing toolkit consisting of a library and a domain-specific language. You can use it to parse custom file formats or quickly build parsers, interpreters, and compilers for programming languages.
The Ohm language is based on parsing expression grammars (PEGs), which are a formal way of describing syntax, similar to regular expressions and context-free grammars. The Ohm library provides a JavaScript interface for creating parsers, interpreters, and more from the grammars you write.
- Full support for left-recursive rules means that you can define left-associative operators in a natural way.
- Object-oriented grammar extension makes it easy to extend an existing language with new syntax.
- Modular semantic actions. Unlike many similar tools, Ohm completely separates grammars from semantic actions. This separation improves modularity and extensibility, and makes both grammars and semantic actions easier to read and understand.
- Online editor and visualizer. The Ohm Editor provides instant feedback and an interactive visualization that makes the entire execution of the parser visible and tangible. It'll make you feel like you have superpowers. ๐ช
Some awesome things people have built using Ohm:
- Seymour, a live programming environment for the classroom.
- Shadama, a particle simulation language designed for high-school science.
- turtle.audio, an audio environment where simple text commands generate lines that can play music.
- A browser-based tool that turns written Konnakkol (a South Indian vocal percussion art) into audio.
- Wildcard, a browser extension that empowers anyone to modify websites to meet their own specific needs, uses Ohm for its spreadsheet formulas.
The easiest way to get started with Ohm is to use the interactive editor. Alternatively, you can play with one of the following examples on JSFiddle:
- Tutorial: Ohm: Parsing Made Easy
- The math example is extensively commented and is a good way to dive deeper.
- Examples
- Documentation
- For community support and discussion, join us on Discord, GitHub Discussions, or the ohm-discuss mailing list.
- For updates, follow @_ohmjs on Twitter.
To use Ohm in the browser, just add a single <script>
tag to your page:
<!-- Development version of Ohm from unpkg.com -->
<script src="https://unpkg.com/ohm-js@16/dist/ohm.js"></script>
or
<!-- Minified version, for faster page loads -->
<script src="https://unpkg.com/ohm-js@16/dist/ohm.min.js"></script>
This creates a global variable named ohm
.
First, install the ohm-js
package with your package manager:
Then, you can use require
to use Ohm in a script:
const ohm = require('ohm-js');
As of v16.2.0, Ohm can also be imported as an ES module:
import ohm from 'ohm-js';
To use Ohm from Deno:
import ohm from 'https://unpkg.com/ohm-js@16/dist/ohm.esm.js';
To use Ohm, you need a grammar that is written in the Ohm language. The grammar provides a formal definition of the language or data format that you want to parse. There are a few different ways you can define an Ohm grammar:
-
The simplest option is to define the grammar directly in a JavaScript string and instantiate it using
ohm.grammar()
. In most cases, you should use a template literal with String.raw:const myGrammar = ohm.grammar(String.raw` MyGrammar { greeting = "Hello" | "Hola" } `);
-
In Node.js, you can define the grammar in a separate file, and read the file's contents and instantiate it using
ohm.grammar(contents)
:In
myGrammar.ohm
:MyGrammar { greeting = "Hello" | "Hola" }
In JavaScript:
const fs = require('fs'); const ohm = require('ohm-js'); const contents = fs.readFileSync('myGrammar.ohm', 'utf-8'); const myGrammar = ohm.grammar(contents);
For more information, see Instantiating Grammars in the API reference.
Once you've instantiated a grammar object, use the grammar's match()
method to recognize input:
const userInput = 'Hello';
const m = myGrammar.match(userInput);
if (m.succeeded()) {
console.log('Greetings, human.');
} else {
console.log("That's not a greeting!");
}
The result is a MatchResult object. You can use the succeeded()
and failed()
methods to see whether the input was recognized or not.
For more information, see the main documentation.
Ohm has two tools to help you debug grammars: a text trace, and a graphical visualizer.
You can try the visualizer online.
To see the text trace for a grammar g
, just use the g.trace()
method instead of g.match
. It takes the same arguments, but instead of returning a MatchResult
object, it returns a Trace object โ calling its toString
method returns a string describing
all of the decisions the parser made when trying to match the input. For example, here is the
result of g.trace('ab').toString()
for the grammar G { start = letter+ }
:
ab โ start โ "ab"
ab โ letter+ โ "ab"
ab โ letter โ "a"
ab โ lower โ "a"
ab โ Unicode [Ll] character โ "a"
b โ letter โ "b"
b โ lower โ "b"
b โ Unicode [Ll] character โ "b"
โ letter
โ lower
โ Unicode [Ll] character
โ upper
โ Unicode [Lu] character
โ unicodeLtmo
โ Unicode [Ltmo] character
โ end โ ""
If you've written an Ohm grammar that you'd like to share with others, see our suggestions for publishing grammars.
All you need to get started:
git clone https://github.com/harc/ohm.git
cd ohm
npm install
NOTE: We recommend using the latest Node.js stable release.
npm test
runs the unit tests.npm run test-watch
re-runs the unit tests every time a file changes.npm run build
builds dist/ohm.js and dist/ohm.min.js, which are stand-alone bundles that can be included in a webpage.- When editing Ohm's own grammar (in
src/ohm-grammar.ohm
), runnpm run bootstrap
to re-build Ohm and test your changes.
Before submitting a pull request, be sure to add tests, and ensure that npm run prepublish
runs
without errors.