v0.1.2: trait update

Author: AWeirdDev

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "hrun"
-version = "0.1.1"
+version = "0.1.2"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

Cargo.toml

@@ -6,13 +6,15 @@
 ![Contributors](https://badgen.net/github/contributors/AWeirdDev/hrun)
 ![Release](https://badgen.net/github/release/AWeirdDev/hrun)
 
-**`H`** is a simple runtime designed to be fast and memory-safe.
+**`H`** is a simple runtime designed to be fast and memory-safe. Available on PyPI with the name [`hrun-rt`](https://pypi.org/project/hrun-rt) ("rt" - runtime).
 
 You may find it useful for:
 - Writing simple scripts
 - Learning AST
 - Running unsafe code (e.g., from AI models)
 
+> **New!** — Now with functions, thanks to the `HFunction` trait update.
+
 First, create a new H runtime.
 
 ```python
@@ -80,3 +82,81 @@ h.run(code)
 print(h.get("c"))
 # Console output: Yes!
 ```
+
+***
+
+# Documentation
+The following components are already **available** as docstrings in Python:
+
+- `Expr`
+- `Statement`
+- `H` (The runtime)
+
+## <kbd>type</kbd> `Value`
+```python
+type Value = str | int | float | bool | None | list
+```
+A value. (Discoverable as `PyValue` in `src/lib.rs`, `Value` in `crates/h/src/lib.rs`)
+
+It is recommended to cast a value to another if you're certain about a type at runtime.
+
+## <kbd>type</kbd> `Identifier`
+```python
+type Identifier = str | int
+```
+An identifier. Could be a string or an integer; both have advantages & disadvantages.
+
+## ✨ Declaring functions
+Functions are available since `v0.1.2`.
+
+First, create a Python function:
+
+```python
+# We need cast() from typing because we're *certain* 
+# what the type would be
+from typing import cast
+
+from hrun import Value
+
+def add(items: Value) -> Value:
+    # Since the H runtime side would be calling 
+    # this like add([A, B]), items: list[int]
+    items = cast(list[int], items)
+    a = items[0]
+    b = items[1]
+
+    return a + b
+```
+
+Then, define a simple code structure:
+
+```python
+from hrun import Statement, Expr
+
+code = [
+    Statement.fn("add", add),  # Name this function as "add"
+    Statement.let("a", Expr.literal(1)),
+    Statement.let("b", Expr.literal(2)),
+    Statement.let(
+        "result",
+        Expr.call(
+            "add",
+            Expr.vector([
+                Expr.ident("a"),
+                Expr.ident("b")
+            ])
+        )
+    )
+]
+```
+
+Finally, run it with the `H` runtime:
+
+```python
+from hrun import H
+
+h = H()
+h.run(code)
+
+print(h.get("result"))  # Output: 3
+```

README.md

@@ -1,16 +1,77 @@
-use std::sync::Arc;
+use std::{ fmt::Debug, sync::Arc };
 
 use dashmap::DashMap;
 
-#[derive(Debug, Clone, PartialEq)]
+pub trait HFunction: HFunctionClone + Debug + Send + Sync {
+    fn run(&self, args: Arc<Value>) -> Value;
+}
+
+pub trait HFunctionClone {
+    fn clone_box(&self) -> Box<dyn HFunction>;
+}
+
+impl<T> HFunctionClone for T where T: 'static + HFunction + Clone {
+    fn clone_box(&self) -> Box<dyn HFunction> {
+        Box::new(self.clone())
+    }
+}
+
+impl Clone for Box<dyn HFunction> {
+    fn clone(&self) -> Self {
+        self.clone_box()
+    }
+}
+
+pub type BoxedHFunction = Box<dyn HFunction + 'static>;
+
+#[derive(Debug, Clone)]
 pub enum Value {
     Null,
     Boolean(bool),
     String(String),
     Number(Number),
+    Vector(Vec<Arc<Value>>),
+    Function(BoxedHFunction),
+}
+
+impl PartialEq for Value {
+    fn eq(&self, other: &Self) -> bool {
+        match self {
+            Self::Function(_) => panic!("Cannot perform PartialEq for Value::Fn"),
+            Self::Boolean(b) =>
+                b.eq(
+                    other
+                        .as_bool()
+                        .unwrap_or_else(|| panic!("Expected other item to be Value::Boolean"))
+                ),
+            Self::Null => other.is_null(),
+            Self::Number(n) =>
+                n.eq(
+                    other
+                        .as_number()
+                        .unwrap_or_else(|| panic!("Expected other item to be Value::Number"))
+                ),
+            Self::String(s) =>
+                s.eq(
+                    other
+                        .as_string()
+                        .unwrap_or_else(|| panic!("Expected other item to be Value::String"))
+                ),
+            Self::Vector(v) =>
+                v.eq(
+                    other
+                        .as_vector()
+                        .unwrap_or_else(|| panic!("Expected other item to be Value::Vector"))
+                ),
+        }
+    }
 }
 
 impl Value {
+    pub fn is_null(&self) -> bool {
+        matches!(self, Self::Null)
+    }
+
     pub fn is_number(&self) -> bool {
         matches!(self, Self::Number(_))
     }
@@ -44,6 +105,28 @@ impl Value {
         }
     }
 
+    pub fn is_function(&self) -> bool {
+        matches!(self, Self::Function(_))
+    }
+
+    pub fn as_function(&self) -> Option<&BoxedHFunction> {
+        match self {
+            Self::Function(f) => Some(f),
+            _ => None,
+        }
+    }
+
+    pub fn is_vector(&self) -> bool {
+        matches!(self, Self::Vector(_))
+    }
+
+    pub fn as_vector(&self) -> Option<&Vec<Arc<Self>>> {
+        match self {
+            Self::Vector(v) => Some(v),
+            _ => None,
+        }
+    }
+
     pub const fn null() -> Self {
         Self::Null
     }
@@ -128,6 +211,8 @@ pub enum Expr {
     Not(Box<Expr>),
     GreaterThan(Box<Expr>, Box<Expr>),
     LessThan(Box<Expr>, Box<Expr>),
+    Call(Identifier, Box<Expr>),
+    Vector(Vec<Expr>),
 }
 
 impl Expr {
@@ -152,6 +237,7 @@ impl Expr {
     }
 
     /// Creates a not expr
+    #[allow(clippy::should_implement_trait)]
     pub fn not(item: Self) -> Self {
         Self::Not(Box::new(item))
     }
@@ -165,6 +251,16 @@ impl Expr {
     pub fn less_than(a: Self, b: Self) -> Self {
         Self::LessThan(Box::new(a), Box::new(b))
     }
+
+    /// Calls a function
+    pub fn call(ident: Identifier, args: Self) -> Self {
+        Self::Call(ident, Box::new(args))
+    }
+
+    /// Creates a vector (i.e. `[expr_1, expr_2, expr_3, ...]`)
+    pub fn vector(items: Vec<Self>) -> Self {
+        Self::Vector(items)
+    }
 }
 
 #[derive(Debug, Clone)]
@@ -212,13 +308,20 @@ pub enum Statement {
         then: Vec<Statement>,
         otherwise: Vec<Statement>, // are you expecting "else"?? nahhh
     },
+    Fn(Identifier, BoxedHFunction),
 }
 
 #[derive(Debug)]
 pub struct Machine {
     pub vars: DashMap<Identifier, Arc<Value>>,
 }
 
+impl Default for Machine {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl Machine {
     pub fn new() -> Self {
         Self {
@@ -231,7 +334,10 @@ impl Machine {
     }
 
     pub fn get(&self, ident: &Identifier) -> Arc<Value> {
-        self.vars.get(ident).expect(&format!("Value cannot be found: {:?}", ident)).clone()
+        self.vars
+            .get(ident)
+            .unwrap_or_else(|| panic!("Value cannot be found: {:?}", ident))
+            .clone()
     }
 }
 
@@ -252,6 +358,9 @@ pub fn deduce(machine: &Machine, statements: Vec<Statement>) {
                     deduce(machine, otherwise);
                 }
             }
+            Statement::Fn(ident, function) => {
+                machine.set(ident, Arc::new(Value::Function(function)));
+            }
         }
     }
 }
@@ -327,6 +436,21 @@ pub fn deduce_expr(machine: &Machine, expr: Expr) -> Arc<Value> {
                 _ => Arc::new(Value::boolean(false)),
             }
         }
+        Expr::Call(ident, args) => {
+            let va = deduce_expr(machine, *args);
+            let function = machine.get(&ident);
+            let function = function.as_function().unwrap();
+
+            let result = function.run(va);
+            Arc::new(result)
+        }
+        Expr::Vector(mut v) => {
+            let items = v
+                .drain(..)
+                .map(|item| deduce_expr(machine, item))
+                .collect::<Vec<_>>();
+            Arc::new(Value::Vector(items))
+        }
     }
 }
 

crates/h/src/lib.rs

@@ -1,4 +1,4 @@
-from typing import List, Literal
+from typing import Callable, List, Literal
 from .types import Identifier, Value
 
 
@@ -98,6 +98,26 @@ class Expr:
             b (Expr): An expression. Must be a number.
         """
 
+    @staticmethod
+    def call(ident: Identifier, args: Expr) -> "Expr":
+        """Creates an expression that calls a function.
+
+        Args:
+            ident (Identifier): The identifier.
+            args (Expr): Arguments (parameters).
+        """
+
+    @staticmethod
+    def vector(items: List[Expr]) -> "Expr":
+        """Creates a vector.
+
+        In other words, this is like a bracket which creates a list of expressions,
+        like so: `[expr_1, expr_2, expr_3, ...]`
+
+        Args:
+            items (list[Expr]): Expression items.
+        """
+
 
 class Statement:
     """Represents a statement."""
@@ -125,3 +145,6 @@ class Statement:
             then (list[Statement]): The `if [...] then...` branch.
             otheriwse (list[Statement]): The `...else` branch.
         """
+
+    @staticmethod
+    def fn(ident: Identifier, item: Callable[[Value], Value]): ...

python/hrun/core.py

@@ -1,4 +1,4 @@
 from typing import Union
 
 Identifier = Union[str, int]
-Value = Union[str, int, float, bool, None]
+Value = Union[str, int, float, bool, None, list]