Open-source image
open-source
Hime logo

Table of content

Quickstart for Rust

This guide gets you started with Hime using C#. It is also available for C# and Java. The program here is to download the tooling, get a prepared grammar, compile it with himecc and use the generated parser.

Pre-requisites for this guide are:

Get the tooling

The parser generator for Hime can be found on the download page.
Step 1 Download himecc for your system.
You may want some editing support for Hime grammars. In this case, head to the editors line-up page. For an IDE experience, we recommend the Visual Studio Code extension.

Get the grammar

Step 2 Create and open a file named MathExp.gram.
Step 3 Then copy-paste in this file the following grammar:

grammar MathExp
{
  options
  {
    Axiom = "exp"; // the top variable for this grammar
    Separator = "SEPARATOR"; // the terminal that represent white space
  }
  terminals
  {
    WHITE_SPACE -> U+0020 | U+0009 | U+000B | U+000C ;
    SEPARATOR   -> WHITE_SPACE+;

    INTEGER     -> [1-9] [0-9]* | '0' ;
    REAL        -> INTEGER? '.' INTEGER  (('e' | 'E') ('+' | '-')? INTEGER)?
                |  INTEGER ('e' | 'E') ('+' | '-')? INTEGER ;
    NUMBER      -> INTEGER | REAL ;
  }
  rules
  {
    exp_atom   -> NUMBER
               | '(' exp ')' ;
    exp_factor -> exp_atom
               |  exp_factor '*' exp_atom
               |  exp_factor '/' exp_atom ;
    exp_term   -> exp_factor
               |  exp_term '+' exp_factor
               |  exp_term '-' exp_factor ;
    exp        -> exp_term ;
  }
}

Compile the grammar

Step 4 Compile the MathExp.gram:

  • On Windows: himecc.exe -t rust MathExp.gram
  • On Linux and MacOS: himecc -t rust MathExp.gram

The tool will generate 3 files:

    • MathExp.rs, the source file for the lexer and parser
    • MathExpLexer.bin, the binary representation of the lexer’s automaton
    • MathExpParser.bin, the binary representation of the parser’s automaton

Note here that the default target for himecc is the .Net platform; so that we have to specify Rust as the target with the -t rust option. For a complete guide to the options of himecc, head to the reference page.

Setup the test project

Step 5 Setup a test project as a standard Cargo project. Use the following project layout:

test/
+-> Cargo.toml
+-> src/
    +-> main.rs
    +-> MathExp.rs
    +-> MathExpLexer.bin
    +-> MathExpParser.bin

Step 6 Set the minimal Cargo.toml:

[package]
name = "test_hime"
version = "1.0.0"

[dependencies]
hime_redist = "4"

Step 7 Set the minimal main.rs:

#![forbid(unsafe_code)]
#![warn(clippy::pedantic)]

#[allow(dead_code)]
mod math_exp;

use hime_redist::ast::AstNode;

fn main() {
    let result = math_exp::parse_str("2 + 3");
    let ast = result.get_ast();
    let root = ast.get_root();
    print(root, &[]);
}

fn print(node: AstNode, crossings: &[bool]) {
    let mut i = 0;
    if !crossings.is_empty() {
        while i < crossings.len() - 1 {
            print!("{:}", if crossings[i] { "|   " } else { "    " });
            i += 1;
        }
        print!("+-> ");
    }
    println!("{node}");
    i = 0;
    let children = node.children();
    while i < children.len() {
        let mut child_crossings = crossings.to_owned();
        child_crossings.push(i < children.len() - 1);
        print(children.at(i), &child_crossings);
        i += 1;
    }
}

Build and execute the test project

Step 8/9 Build and run the test project:

cargo run

The output of the program should a text printout of the produced syntax tree be as follow:

exp
+-> exp_term
    +-> exp_term
    |   +-> exp_factor
    |       +-> exp_atom
    |           +-> NUMBER = 2
    +-> + = +
    +-> exp_factor
        +-> exp_atom
            +-> NUMBER = 3

This concludes this guide. For a more complete tutorial, head over to the the first Rust tutorial.