Struct Interpreter

Source

pub struct Interpreter<State> {
    pub state: State,
    /* private fields */
}

Expand description

The core interpreter object. Takes in a custom defined state that can be modified by built-ins.

Fields§

§state: State

Custom state for each application. Allows users to register built-ins that modify this state.

Implementations§

Source §

impl<State> Interpreter<State>

Source

pub fn reset_program(&mut self)

Resets the program counter and clears the program and program debug locations but preserves RAM and stack.

Source §

impl<State> Interpreter<State>

Source

pub fn format_code(code: &str, path: Option<PathBuf>) -> Result<String, Err>

Format a code file.

Examples found in repository ?

examples/format_code.rs (line 36)

3fn main() {
4    // This is just some ugly code to showcase the formatting.
5    // Typically '.' is used as a noop op and helps with formatting.
6    let code = r#"
7    var 
8    stuff 
9    .
10
11    1 stuff 
12    set .
13
14    stuff
15    get 
16    .
17
18
19    : debug "" "" "" print-stack drop ;
20    0 begin 1 + dup 2 == if 
21            "hello" .  stuff get drop .  break
22        end
23
24        dup
25        2 == if 
26            "hello"
27        else
28            "world"
29            drop
30        end
31    loop
32
33    "world"
34    
35    "#;
36    let code = Interpreter::<()>::format_code(code, None).unwrap();
37
38    println!("{}", code);
39}

Source

pub fn stringify_program(&self) -> String

Returns the program as a formatted string.

Source §

impl<State> Interpreter<State>

Source

pub fn new(state: State) -> Self

Create a new interpreter. Pass in the initial custom state for the interpreter.

Examples found in repository ?

examples/add.rs (line 5)

3fn main() {
4    let code = "1 1 +";
5    let mut interpreter = Interpreter::new(());
6    interpreter.evaluate(code, None).unwrap();
7
8    println!("1 1 + ={}", interpreter.pop_number().unwrap());
9}

More examples

Hide additional examples

examples/print_documentation.rs (line 8)

3fn main() {
4    println!("This is how you print documentation");
5    let code = r#"
6    documentation
7    "#;
8    let mut interpreter = Interpreter::new(());
9    interpreter.evaluate(code, None).unwrap();
10}

examples/execute_address.rs (line 7)

3fn main() {
4    let code = r#"
5    1 2 [ + ] @
6    "#;
7    let mut interpreter = Interpreter::new(());
8    interpreter.evaluate(code, None).unwrap();
9
10    println!(
11        "1 2 [ + ] @  should return {}",
12        interpreter.pop_number().unwrap()
13    );
14}

examples/custom_word.rs (line 15)

3fn main() {
4    let code = r#"
5    : squared
6        "n -- n^2"
7        "Squares the top of the stack"
8        "2 squared"
9        dup *
10    ;
11
12    2 squared
13    print-stack
14    "#;
15    let mut interpreter = Interpreter::new(());
16    interpreter.evaluate(code, None).unwrap();
17}

examples/repl.rs (line 6)

3fn main() {
4    // TODO: figure out way to start repl in interpreter
5    // let code = "repl \"example of repl\" print-stack";
6    let mut interpreter = Interpreter::new(());
7    // interpreter.evaluate(code, None).unwrap();
8
9    // Alternative way to start repl in host
10    interpreter.start_repl().unwrap();
11}

examples/loop.rs (line 21)

3fn main() {
4    let code = r#"
5
6    0
7    begin
8        print-stack
9    
10        dup 10 <=
11        if
12            drop
13            "loop finished"
14            print-stack
15            break
16        end
17        1 + 
18    loop
19    
20    "#;
21    let mut interpreter = Interpreter::new(());
22    interpreter.evaluate(code, None).unwrap();
23}

Additional examples can be found in:

Source

pub fn exit(&self) -> bool

Returns whether the interpreter should exit.

Source

pub fn evaluate(&mut self, code: &str, path: Option<PathBuf>) -> Result<(), Err>

Evaluate a program.

Examples found in repository ?

examples/add.rs (line 6)

3fn main() {
4    let code = "1 1 +";
5    let mut interpreter = Interpreter::new(());
6    interpreter.evaluate(code, None).unwrap();
7
8    println!("1 1 + ={}", interpreter.pop_number().unwrap());
9}

More examples

Hide additional examples

examples/print_documentation.rs (line 9)

3fn main() {
4    println!("This is how you print documentation");
5    let code = r#"
6    documentation
7    "#;
8    let mut interpreter = Interpreter::new(());
9    interpreter.evaluate(code, None).unwrap();
10}

examples/execute_address.rs (line 8)

3fn main() {
4    let code = r#"
5    1 2 [ + ] @
6    "#;
7    let mut interpreter = Interpreter::new(());
8    interpreter.evaluate(code, None).unwrap();
9
10    println!(
11        "1 2 [ + ] @  should return {}",
12        interpreter.pop_number().unwrap()
13    );
14}

examples/custom_word.rs (line 16)

3fn main() {
4    let code = r#"
5    : squared
6        "n -- n^2"
7        "Squares the top of the stack"
8        "2 squared"
9        dup *
10    ;
11
12    2 squared
13    print-stack
14    "#;
15    let mut interpreter = Interpreter::new(());
16    interpreter.evaluate(code, None).unwrap();
17}

examples/loop.rs (line 22)

3fn main() {
4    let code = r#"
5
6    0
7    begin
8        print-stack
9    
10        dup 10 <=
11        if
12            drop
13            "loop finished"
14            print-stack
15            break
16        end
17        1 + 
18    loop
19    
20    "#;
21    let mut interpreter = Interpreter::new(());
22    interpreter.evaluate(code, None).unwrap();
23}

examples/if.rs (line 30)

3fn main() {
4    let code = r#"
5    "Example of if"
6    print-stack
7    drop
8
9    1 if 
10        "evaluated when true!"
11        print-stack
12        drop
13    end
14
15    "Now we do an example of an else"
16    print-stack
17    drop
18
19    0 if 
20        "Not ran"
21        print-stack
22        drop
23    else
24        "else is ran"
25        print-stack
26        drop
27    end
28    "#;
29    let mut interpreter = Interpreter::new(());
30    interpreter.evaluate(code, None).unwrap();
31}

Additional examples can be found in:

Source

pub fn get_name(&self, address: Address) -> String

Get the name of an address if present.

Source

pub fn pop(&mut self) -> Result<StackValue, Err>

Pop a value from the stack.

Source

pub fn pop_bool(&mut self) -> Result<bool, Err>

Pop a boolean from the stack.

Source

pub fn pop_number(&mut self) -> Result<f32, Err>

Pop a number from the stack.

Examples found in repository ?

examples/add.rs (line 8)

3fn main() {
4    let code = "1 1 +";
5    let mut interpreter = Interpreter::new(());
6    interpreter.evaluate(code, None).unwrap();
7
8    println!("1 1 + ={}", interpreter.pop_number().unwrap());
9}

More examples

Hide additional examples

examples/execute_address.rs (line 12)

3fn main() {
4    let code = r#"
5    1 2 [ + ] @
6    "#;
7    let mut interpreter = Interpreter::new(());
8    interpreter.evaluate(code, None).unwrap();
9
10    println!(
11        "1 2 [ + ] @  should return {}",
12        interpreter.pop_number().unwrap()
13    );
14}

Source

pub fn push_number(&mut self, number: f32)

Push a number onto the stack.

Examples found in repository ?

examples/custom_builtin.rs (line 24)

3fn main() {
4    let state: u32 = 0;
5    let mut interpreter = Interpreter::new(state);
6
7    interpreter.register_builtin(
8        "increment-state",
9        "--",
10        "Increments the state.",
11        "increment-state",
12        |interpreter| {
13            interpreter.state += 1;
14            Ok(())
15        },
16    );
17
18    interpreter.register_builtin(
19        "get-state",
20        "-- n",
21        "Gets the state.",
22        "get-state",
23        |interpreter| {
24            interpreter.push_number(interpreter.state as f32);
25            Ok(())
26        },
27    );
28
29    let code = r#"
30    print-stack
31    increment-state
32    get-state
33    "The state has been modified!"
34    print-stack
35    "#;
36
37    println!("State before execution: {:?}", interpreter.state);
38    interpreter.evaluate(code, None).unwrap();
39    println!("State after execution: {:?}", interpreter.state);
40}

Source

pub fn push_address(&mut self, address: Address)

Push an address onto the stack.

Source

pub fn pop_address(&mut self) -> Result<Address, Err>

Pop an address from the stack.

Source

pub fn push_string(&mut self, string: String)

Push a string onto the stack.

Source

pub fn pop_string(&mut self) -> Result<String, Err>

Pop a string from the stack.

Source

pub fn start_repl(&mut self) -> Result<(), Err>

Start a REPL.

Examples found in repository ?

examples/repl.rs (line 10)

3fn main() {
4    // TODO: figure out way to start repl in interpreter
5    // let code = "repl \"example of repl\" print-stack";
6    let mut interpreter = Interpreter::new(());
7    // interpreter.evaluate(code, None).unwrap();
8
9    // Alternative way to start repl in host
10    interpreter.start_repl().unwrap();
11}

Source

pub fn register_builtin( &mut self, name: &str, stack_modification: &str, documentation: &str, example: &str, func: BuiltIn<State>, )

Register a built-in function to be used in the interpreter.

Examples found in repository ?

examples/custom_error.rs (lines 7-16)

3fn main() {
4    let state: u32 = 0;
5    let mut interpreter = Interpreter::new(state);
6
7    interpreter.register_builtin(
8        "example-error",
9        "-- n",
10        "returns an error",
11        "get-state",
12        |interpreter| {
13            //
14            Err(("This is an error".to_string(), interpreter.location()))
15        },
16    );
17
18    let code = r#"
19    example-error
20    "#;
21
22    let result = interpreter.evaluate(code, None);
23    println!("Result: {:?}", result);
24}

More examples

Hide additional examples

examples/custom_builtin.rs (lines 7-16)

3fn main() {
4    let state: u32 = 0;
5    let mut interpreter = Interpreter::new(state);
6
7    interpreter.register_builtin(
8        "increment-state",
9        "--",
10        "Increments the state.",
11        "increment-state",
12        |interpreter| {
13            interpreter.state += 1;
14            Ok(())
15        },
16    );
17
18    interpreter.register_builtin(
19        "get-state",
20        "-- n",
21        "Gets the state.",
22        "get-state",
23        |interpreter| {
24            interpreter.push_number(interpreter.state as f32);
25            Ok(())
26        },
27    );
28
29    let code = r#"
30    print-stack
31    increment-state
32    get-state
33    "The state has been modified!"
34    print-stack
35    "#;
36
37    println!("State before execution: {:?}", interpreter.state);
38    interpreter.evaluate(code, None).unwrap();
39    println!("State after execution: {:?}", interpreter.state);
40}

Source

pub fn print_documentation(&self)

Print the documentation for all words.

Source

pub fn location(&self) -> Location

Returns the location of the current instruction.

Examples found in repository ?

examples/custom_error.rs (line 14)

3fn main() {
4    let state: u32 = 0;
5    let mut interpreter = Interpreter::new(state);
6
7    interpreter.register_builtin(
8        "example-error",
9        "-- n",
10        "returns an error",
11        "get-state",
12        |interpreter| {
13            //
14            Err(("This is an error".to_string(), interpreter.location()))
15        },
16    );
17
18    let code = r#"
19    example-error
20    "#;
21
22    let result = interpreter.evaluate(code, None);
23    println!("Result: {:?}", result);
24}