More docs

Author: J-Cake

README.md

@@ -14,18 +14,36 @@ In order to evaluate expressions, three things must happen;
 ## Data Provider
 
 A data provider is an object which converts addresses into values. Addresses are arbitrary text tokens wrapped in
-braces. The provider determines their meaning. 
+braces. The provider determines their meaning. [See the `repl.rs`](examples/repl.rs) for a feature-complete REPL.
 
 ```rust
+#[derive(Copy, Clone)]
 struct Provider;
 
 impl expression::DataSource for Provider {
     fn query(&self, query: impl AsRef<str>) -> Option<expression::Object> {
         // Parse the query however you need to.
         // For example, the format `column:row`
-        
-        let (column, row) = query.as_ref().split_at(query.as_ref().rfind(':'));
-        
+
+        Some(Object::string("Hey!"))
     }
 }
+```
+
+## Context
+
+Next you'll need a context object which holds state and variables and acts as an API to the expression engine. You can
+define your own functions, globals and operators here.
+
+```rust
+fn main() {
+    let mut cx = expression::Context::new(Provider)
+        .with_global("twelve", expression::Object::Number(12))
+        .with_fn("print", |_cx, args| {
+            println!("{:?}", args);
+            Ok(expression::Object::Nothing)
+        });
+
+    assert_eq!(cx.evaluate("twelve"), expression::Object::Number(12));
+}
 ```

examples/repl.rs

@@ -1,17 +1,9 @@
-use expression::Context;
-use expression::DataSource;
-use expression::Object;
-use std::fmt::Debug;
-use std::io::BufRead;
-use std::io::BufReader;
-use std::io::BufWriter;
-use std::io::Write;
-
 /// A simple REPL to demonstrate the use of the expression crate.
 /// # Features:
-///  - Basic expression evaluation
-///  - Simple table for demonstrating addresses
-///  - Demonstrate complex usage of the API
+///  - Basic expression evaluation: [`repl.rs:169`](./#L169)
+///  - Simple table for demonstrating addresses: [`repl.rs:30`](./#L30)
+///  - A top-level `eval` function to demonstrate programmatic evaluation: [`repl.rs:137`](./#L137)
+///  - A `<<` operator to demonstrate operator registration: [`repl.rs:144`](./#L144)
 ///
 /// Type an expression into the REPL and press enter.
 /// The following commands are available:
@@ -23,6 +15,16 @@ use std::io::Write;
 /// # Addresses:
 /// Addresses are of the form `column:row` where `column` is the name of the column and `row` is the row number. Therefore, columns may contain `:`.
 
+use std::any::Any;
+use expression::Context;
+use expression::OperatorBuilder;
+use expression::DataSource;
+use expression::Object;
+use std::fmt::Debug;
+use std::io::BufRead;
+use std::io::BufReader;
+use std::io::Write;
+
 #[derive(Debug, Clone)]
 struct Table {
     columns: Vec<String>,
@@ -31,6 +33,10 @@ struct Table {
 
 impl DataSource for Table {
     fn query(&self, query: impl AsRef<str>) -> Option<Object> {
+
+        // Parse the address into a usable format.
+        // Since the address is of the form `column:row`, we can split the address at the last `:`.
+
         let (column, row) = query.as_ref().split_at(query.as_ref().rfind(':')?);
         let col = self.columns.iter().position(|c| c == column)?;
 
@@ -126,12 +132,34 @@ mod commands {
 }
 
 pub fn main() {
-    let mut cx = Context::new(Table::empty(["a", "b", "c"]));
+    let mut cx = Context::new(Table::empty(["a", "b", "c"]))
+        .with_fn("eval", |cx, args| {
+            if let Some(Object::String(s)) = args.get(0) {
+                cx.evaluate(s)
+            } else {
+                Ok(Object::Nothing)
+            }
+        })
+        .with_operator(OperatorBuilder::new()
+            .operands(2)
+            .symbol("<<")
+            .handler(|args| {
+                let (Some(Object::Number(base)), Some(Object::Number(shift))) = (args.get(0), args.get(1)) else {
+                    return Err(expression::Error::other("<< requires two numbers"))
+                };
+
+                let base = *base as i64;
+                let shift = *shift as i64;
+
+                Ok(Object::Number((base << shift) as f64))
+            })
+            .build());
 
     loop {
         let cmd = prompt("> ");
 
         match cmd.trim() {
+            "" => continue,
             "/exit" => break,
             "/dump" => println!("{:#?}", cx.provider()),
             cmd if cmd.starts_with("/set ") => commands::set(&mut cx, cmd[5..].trim()),

src/error.rs

@@ -70,9 +70,16 @@ multi_error! { global();
 
 pub type Result<T> = core::result::Result<T, Error>;
 
-use alloc::string::String;
+use alloc::borrow::ToOwned;
+use alloc::string::{String, ToString};
 pub use global::Error;
 
+impl global::Error {
+    pub fn other(message: impl AsRef<str>) -> Self {
+        Self::from(ManualError::OtherError(message.as_ref().to_owned()))
+    }
+}
+
 /// TODO: Document the error types used throughout the expression parser below.
 #[derive(Debug, Clone)]
 pub enum ManualError {
@@ -85,6 +92,8 @@ pub enum ManualError {
     ConversionFailed,
     ExpectedType(String),
     EmptyResultSet(String),
+
+    OtherError(String)
 }
 
 impl core::error::Error for ManualError {}