17 releases
new 0.0.18-alpha | Oct 19, 2024 |
---|---|
0.0.17-alpha | Aug 12, 2024 |
0.0.8-alpha | Mar 10, 2024 |
0.0.3-alpha | Feb 26, 2024 |
#190 in Data structures
236 downloads per month
Used in 5 crates
(4 directly)
195KB
4.5K
SLoC
Garnish Core
Core libraries needed to embed the garnish language. These are what you will need to add Garnish scripting to an application.
If your interested in learning about the Garnish Language, please visit the Demo Site.
Libraries
This repository contains the following library crates. Version numbers for each are kept in sync with one another even if it means no changes were made to that library.
Traits
Contains base traits, structs, enums, etc. for use by rest of the core libraries.
Simple Data
An implementation of GarnishData
using standard Rust types and data structures.
Runtime
An implementation of GarnishRuntime
which executes instructions upon given data object.
Compiler
Contains functions to lex and parse and input string and building that instruction set into a data object.
Garnish Lang
Convenience single dependency for above four libraries.
Usage
These examples use the Garnish Lang crate. If you plan to import the four individually, simply adjust the use
statements accordingly.
Basic Compile and Execute
With just the core libraries this is a three-step process and a GarnishData
object will need to be created for the third.
use garnish_lang::compiler::lex::{lex, LexerToken};
use garnish_lang::compiler::parse::{parse, ParseResult};
use garnish_lang::compiler::build::build_with_data;
use garnish_lang::simple::SimpleGarnishData;
const INPUT: &str = "5 + 5";
fn main() -> Result<(), String> {
let tokens: Vec<LexerToken> = lex(input).or_else(|e| Err(e.get_message().clone()))?;
let parse_result: ParseResult = parse(&tokens).or_else(|e| Err(e.get_message().clone()))?;
let mut data = SimpleGarnishData::new();
build_with_data(parse_result.get_root(), parse_result.get_nodes().clone(), &mut data)
.or_else(|e| Err(e.get_message().clone()))?;
let mut runtime = SimpleGarnishRuntime::new(data);
// SimpleGarnishRuntime only provides method to execute instructions 1 at a time,
// so we loop until finished
loop {
// this None argument is where a GarnishContext would be passed
match runtime.execute_current_instruction(None) {
Err(e) => {
return Err(e.get_message().clone());
}
Ok(data) => match data.get_state() {
SimpleRuntimeState::Running => (),
SimpleRuntimeState::End => break,
},
}
}
// Result of an execution is a data objects current value
runtime.get_data().get_current_value().and_then(|v| {
// get_raw_data is not a trait member of GarnishData,
// but a convenience function of SimpleGarnishData
println!("Result: {:?}", runtime.get_data().get_raw_data(v))
});
Ok(())
}
Using Context
Providing a GarnishContext
object during execution is a way to extend the functionality of a script.
This can be providing environment variables, methods for accessing a database, or customizing operations.
The following example provides two items to a script. A constant value for PI and a way to execute the trigonometric function sine.
use std::collections::HashMap;
use garnish_lang::{GarnishContext, GarnishData, RuntimeError};
use garnish_lang::simple::{
DataError,
SimpleData,
SimpleGarnishData,
SimpleNumber,
symbol_value
};
const MATH_FUNCTION_SINE: usize = 1;
pub struct MathContext {
symbol_to_data: HashMap<u64, SimpleData>
}
impl MathContext {
pub fn new() -> Self {
let mut symbol_to_data = HashMap::new();
symbol_to_data.insert(
symbol_value("Math::PI"),
SimpleData::Number(SimpleNumber::Float(std::f64::consts::PI))
);
symbol_to_data.insert(
symbol_value("sin"),
SimpleData::External(MATH_FUNCTION_SINE)
);
BrowserContext {
symbol_to_expression: HashMap::new(),
symbol_to_data
}
}
}
impl GarnishContext<SimpleGarnishData> for MathContext {
// This method is called when ever a script has an unresolved identifier during runtime
fn resolve(&mut self, symbol: u64, data: &mut SimpleGarnishData)
-> Result<bool, RuntimeError<DataError>> {
// lookup given symbol to see if we have a value for it
// returning true tells runtime that the symbol was resolved
// and not to do any more checks
// returning false will let the runtime check additional resolve methods,
// resulting in a Unit value if nothing resolves it
match self.symbol_to_data.get(&symbol) {
Some(v) => match v {
SimpleData::External(n) => {
// using GarnishData trait methods, add_* for each GarnishDataType
data.add_external(*n).and_then(|addr| data.push_register(addr))?;
Ok(true)
},
SimpleData::Number(n) => {
data.add_number(*n).and_then(|addr| data.push_register(addr))?;
Ok(true)
},
_ => Ok(false)
}
None => Ok(false)
}
}
// This method is called when ever an External type value
// is used with Garnish's 'apply' type operations
fn apply(
&mut self,
external_value: usize,
input_addr: usize,
data: &mut SimpleGarnishData,
) -> Result<bool, RuntimeError<DataError>> {
// check that the external value given is actually supported
if external_value == MATH_FUNCTION_SINE {
// using some non trait methods, whether to use trait methods or
// implementation specific methods will depend on your use case
let new_data = data.get_raw_data(input_addr).and_then(|d| Some(match d {
SimpleData::Number(num) => SimpleData::Number(SimpleNumber::Float(match num {
SimpleNumber::Integer(n) => f64::sin(n as f64),
SimpleNumber::Float(f) => f64::sin(f),
})),
// sin function only supports numbers, all other values result in Unit
_ => SimpleData::Unit
})).ok_or(
DataError::from("Failed to retrieve data during external apply 'sin'"
.to_string())
)?;
// need to add new data
// then push its address to registers for next operation to use
// failure to not push expected values and still returning true,
// could cause script to fail due to empty registers
let addr = data.get_data().len();
data.get_data_mut().push(new_data);
data.push_register(addr)?;
Ok(true)
} else {
// return value signifies same as resolve method's return value
Ok(false)
}
}
}
Now we've implemented a GarnishContext
we can pass it into the execute_current_instruction
method instead of None.
// ...
let mut runtime = SimpleGarnishRuntime::new(data);
let mut context = MathContext::new();
loop {
// add new context object
match runtime.execute_current_instruction(Some(&mut context)) {
Err(e) => {
return Err(e.get_message().clone());
}
Ok(data) => match data.get_state() {
SimpleRuntimeState::Running => (),
SimpleRuntimeState::End => break,
},
}
}
// ...
Further Reading
The Browser Garnish project is the WebAssembly library used by the Demo Site. Going through the demo and viewing the source will illustrate how it all links together.
API Documentation - For full descriptions and more examples. (Currently still working in progress)
Dependencies
~165KB