wander/
lib.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at http://mozilla.org/MPL/2.0/.
4
5//! This module is an implementation of the Wander language.
6
7#![deny(missing_docs)]
8
9use std::{
10    collections::{HashMap, HashSet},
11    fmt::{Debug, Display, Write},
12};
13
14use environment::Environment;
15use identifier::Identifier;
16use interpreter::{eval, Expression};
17use lexer::{tokenize, tokenize_and_filter, transform, Token};
18use parser::{parse, Element};
19use serde::{Deserialize, Serialize};
20use translation::translate;
21
22#[doc(hidden)]
23pub mod environment;
24#[doc(hidden)]
25pub mod interpreter;
26#[doc(hidden)]
27pub mod lexer;
28#[doc(hidden)]
29pub mod parser;
30#[doc(hidden)]
31pub mod preludes;
32#[doc(hidden)]
33pub mod translation;
34pub mod identifier;
35
36/// An error that occurs while running a Wander script.
37#[derive(Debug, PartialEq, Eq, Deserialize, Serialize, Clone)]
38pub struct WanderError(pub String);
39
40/// A combination of all the traits needed to implement a HostType.
41pub trait HostType: Debug + PartialEq + Eq + Serialize + Clone + Display + Serialize {}
42impl<T> HostType for T where T: Debug + PartialEq + Eq + Serialize + Clone + Display + Serialize {}
43
44/// A trait for the pluggable type checker used by Wander.
45pub trait TypeChecker<T: HostType> {
46    /// Called when a value is assigned to a TaggedNamed.
47    fn check(&self, value: WanderValue<T>, tag: WanderValue<T>) -> Result<bool, WanderError>;
48}
49
50/// A TypeChecker that does nothing, everything passes.
51pub struct EpsilonChecker {}
52
53impl<T: HostType> TypeChecker<T> for EpsilonChecker {
54    fn check(&self, _value: WanderValue<T>, _tag: WanderValue<T>) -> Result<bool, WanderError> {
55        Ok(true)
56    }
57}
58
59/// This is a dummy type you can use when you don't need a HostType.
60#[derive(Debug, PartialEq, Eq, Deserialize, Serialize, Clone)]
61pub struct NoHostType {}
62
63impl Display for NoHostType {
64    fn fmt(&self, _: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
65        panic!("NoHostType should never be displayed.")
66    }
67}
68
69/// struct describing a HostFunction.
70pub struct HostFunctionBinding {
71    /// Name used to bind this HostFunction including Namespaces.
72    pub name: String,
73    /// The type of the parameters this HostFunction takes.
74    pub parameters: Vec<(String, Option<String>)>,
75    /// The type of the result of this HostFunction.
76    pub result: Option<String>,
77    /// The documentation for this HostFunction.
78    /// Can be text or Markdown.
79    pub doc_string: String,
80}
81
82/// A trait representing a function exported from the hosting application that
83/// can be called from Wander.
84pub trait HostFunction<T: HostType> {
85    /// The function called when the HostFunction is called from Wander.
86    fn run(
87        &self,
88        arguments: &[WanderValue<T>],
89        bindings: &Environment<T>,
90    ) -> Result<WanderValue<T>, WanderError>;
91    /// Get the binding information for this HostFunction.
92    fn binding(&self) -> HostFunctionBinding;
93}
94
95/// Type alias used for TokenTransformers.
96pub type TokenTransformer = fn(&[Token]) -> Result<Vec<Token>, WanderError>;
97
98/// A value of a type provided by the host application that can be accessed via Wander.
99/// Note it cannot be accessed by Wander directly, only through HostFunctions.
100#[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize, Serialize)]
101pub struct HostValue<T> {
102    /// The value passed to Wander.
103    /// Note it cannot be accessed by Wander directly, only through HostFunctions.
104    pub value: T,
105}
106
107/// Values in Wander programs used for Wander's implementation and interfacing between
108/// Wander and the host application.
109#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
110pub enum WanderValue<T: Clone + PartialEq + Eq> {
111    /// A Bool value.
112    Bool(bool),
113    /// A 64-bit signed integer value.
114    Int(i64),
115    /// A String value.
116    String(String),
117    /// An Identifier.
118    Identifier(Identifier),
119    /// The nothing value.
120    Nothing,
121    /// A Lambda
122    Lambda(String, Option<String>, Option<String>, Box<Element>),
123    /// A List.
124    List(Vec<WanderValue<T>>),
125    /// A Tuple.
126    Tuple(Vec<WanderValue<T>>),
127    /// A Set.
128    Set(HashSet<WanderValue<T>>),
129    /// A Record.
130    Record(HashMap<String, WanderValue<T>>),
131    /// A HostValue.
132    HostValue(HostValue<T>),
133}
134
135impl<T: Clone + PartialEq + Eq> core::hash::Hash for WanderValue<T> {
136    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
137        core::mem::discriminant(self).hash(state);
138    }
139}
140
141/// A struct represting a partially applied function.
142/// The function can be a Lambda or a HostFunction.
143#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
144pub struct PartialApplication<T: Clone + PartialEq + Eq> {
145    arguments: Vec<WanderValue<T>>,
146    callee: WanderValue<T>,
147}
148
149/// Write integer.
150pub fn write_integer(integer: &i64) -> String {
151    format!("{}", integer)
152}
153
154/// Write float.
155pub fn write_float(float: &f64) -> String {
156    let res = format!("{}", float);
157    if res.contains('.') {
158        res
159    } else {
160        res + ".0"
161    }
162}
163
164// Encode a
165// pub fn write_bytes(bytes: &Bytes) -> String {
166//     format!("0x{}", encode(bytes))
167// }
168
169/// Escape a String value.
170pub fn write_string(string: &str) -> String {
171    //TODO this could be done better
172    let escaped_string = string
173        .replace('\\', "\\\\")
174        .replace('"', "\\\"")
175        //.replace("\f", "\\b") <-- TODO not sure how to handle this or if I really need to
176        //.replace("\b", "\\b") <-- TODO not sure how to handle this or if I really need to
177        .replace('\n', "\\n")
178        .replace('\r', "\\r")
179        .replace('\t', "\\t");
180    format!("\"{}\"", escaped_string)
181}
182
183fn write_list_or_tuple_wander_value<T: Clone + Display + PartialEq + Eq + Debug>(
184    open: &str,
185    close: char,
186    contents: &Vec<WanderValue<T>>,
187    f: &mut std::fmt::Formatter<'_>,
188) -> std::fmt::Result {
189    f.write_str(open).unwrap();
190    let mut i = 0;
191    for value in contents {
192        write!(f, "{value}").unwrap();
193        i += 1;
194        if i < contents.len() {
195            write!(f, " ").unwrap();
196        }
197    }
198    write!(f, "{close}")
199}
200
201fn write_set<T: Clone + Display + PartialEq + Eq + Debug>(
202    contents: &HashSet<WanderValue<T>>,
203    f: &mut std::fmt::Formatter<'_>,
204) -> std::fmt::Result {
205    f.write_str("#(").unwrap();
206    let mut i = 0;
207    for value in contents {
208        write!(f, "{value}").unwrap();
209        i += 1;
210        if i < contents.len() {
211            write!(f, " ").unwrap();
212        }
213    }
214    f.write_char(')')
215}
216
217fn write_host_value<T: Display + PartialEq + Eq>(
218    value: &HostValue<T>,
219    f: &mut std::fmt::Formatter<'_>,
220) -> std::fmt::Result {
221    write!(f, "{}", value.value)
222}
223
224fn write_record<T: Clone + Display + PartialEq + Eq + Debug>(
225    contents: &HashMap<String, WanderValue<T>>,
226    f: &mut std::fmt::Formatter<'_>,
227) -> std::fmt::Result {
228    write!(f, "{{").unwrap();
229    let mut i = 0;
230    for (name, value) in contents {
231        write!(f, "{name} = {value}").unwrap();
232        i += 1;
233        if i < contents.len() {
234            write!(f, " ").unwrap();
235        }
236    }
237    write!(f, "}}")
238}
239
240impl<T: Clone + Display + PartialEq + Eq + std::fmt::Debug> Display for WanderValue<T> {
241    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
242        match self {
243            WanderValue::Bool(value) => write!(f, "{}", value),
244            WanderValue::Int(value) => write!(f, "{}", value),
245            WanderValue::String(value) => f.write_str(&write_string(value)),
246            WanderValue::Identifier(value) => write!(f, "<{}>", value.id()),
247            WanderValue::Nothing => write!(f, "nothing"),
248            WanderValue::List(contents) => write_list_or_tuple_wander_value("[", ']', contents, f),
249            WanderValue::HostValue(value) => write_host_value(value, f),
250            WanderValue::Tuple(contents) => {
251                write_list_or_tuple_wander_value("'(", ')', contents, f)
252            }
253            WanderValue::Record(values) => write_record(values, f),
254            WanderValue::Lambda(p, i, o, b) => write!(
255                f,
256                "[lambda {:?}]",
257                WanderValue::Lambda::<T>(p.clone(), i.clone(), o.clone(), b.clone())
258            ),
259            WanderValue::Set(contents) => write_set(contents, f),
260        }
261    }
262}
263
264/// Run a Wander script with the given Bindings.
265pub fn run<T: HostType + Display>(
266    script: &str,
267    bindings: &mut Environment<T>,
268) -> Result<WanderValue<T>, WanderError> {
269    let tokens = tokenize_and_filter(script)?;
270    let tokens = transform(&tokens, bindings)?;
271    let elements = parse(tokens)?;
272    let expression = translate(elements)?;
273    eval(&expression, bindings)
274}
275
276#[derive(Debug, Serialize)]
277/// Structure used for debugging or inspecting code.
278pub struct Introspection {
279    /// A list of all Tokens including whitespace.
280    pub tokens_ws: Vec<Token>,
281    /// A list of all Tokens without whitespace.
282    pub tokens: Vec<Token>,
283    /// A list of all Tokens after macro transformations.
284    pub tokens_transformed: Vec<Token>,
285    /// Element representation.
286    pub element: Element,
287    /// Expression representation.
288    pub expression: Expression,
289}
290
291/// Run a Wander script with the given Bindings.
292pub fn introspect<T: HostType>(
293    script: &str,
294    bindings: &Environment<T>,
295) -> Result<Introspection, WanderError> {
296    let tokens_ws = tokenize(script).or(Ok(vec![]))?;
297    let tokens = tokenize_and_filter(script).or(Ok(vec![]))?;
298    let tokens_transformed = transform(&tokens.clone(), bindings).or(Ok(vec![]))?;
299    let element = parse(tokens_transformed.clone()).or(Ok(Element::String("Error".to_owned())))?; //TODO handle errors better
300    let expression = translate(element.clone()).or(Ok(Expression::String("Error".to_owned())))?; //TODO handle errors better
301    Ok(Introspection {
302        tokens_ws,
303        tokens,
304        tokens_transformed,
305        element,
306        expression,
307    })
308}
wander/lib.rs

wander/
lib.rs
