Crate avid

Expand description

Plug and play configuration language.

Provides a simple API to insert this configuration language into your project. The language is easy to learn and checks for many common errors, including unknown variables and malformed statements, at (Avid’s) compile time.

The available APIs and other settings can be tweaked or modified easily by using the different methods on the Builder struct.

Examples

use avid::{Builder, Stack};

let src = "1 2 + print \"Hello, World!\" print-to-log";
let mut log = String::new();

let avid = Builder::new(src)
    // Add a new function that pops one item from the top of the stack
    // and prints it to the log
    .register_fn("print-to-log", |stack: &mut Stack| {
        let [to_print] = stack.pop()?;
        log.push_str(&to_print.to_string());
        Ok(())
    })
    .build().unwrap();

// Prints `3` to standard output
avid.run(None).unwrap();

assert_eq!(&log, "Hello, World!");

You can use any function with the correct signature, including closures.

Avid Syntax

Avid’s syntax is heavily inspired by forth and uses reverse polish notation. This means that all functions operate on an implicit “stack,” pushing and popping elements as needed. Let’s take a look at an example:

/* stack is now empty */

/* Pushes `1` to the stack */
1

/* stack: 1 */
/* Pushes `2` to the stack */
2

/* stack: 1 2 */
/* Pops the top two elements from the stack, sums them up, and pushes the result onto the stack */
+

/* stack: 3 */
/* Pops an element from the top of the stack and prints it. */
print

/* stack is now empty */

Avid also allows strings:

/* Stack is now empty */
/* Pushes itself onto the stack */
"Hello, "

/* Stack: "Hello, " */
"World!"

/* Stack: "Hello, " "World!" */
/* Swaps the top two items on the stack */
swap

/* Stack: "World!" "Hello, " */
/* Prints "Hello, World!" */
print print 


/* This prints: */
/*
all of these escape codes are allowed!: "Quotes", preventing new lines, adding
 new lines, 'Single quotes,'
urns,age ret
         tabs, and \\ slashes! \\
*\
"all of these escape codes are allowed!: \"Quotes\", preventing \
new lines, adding \n new lines, \'Single quotes,\' 
carriage ret\rurns,
\t tabs, and \\ slashes! \\" print


/* Stack is now empty */

And lists:

/* Stack is now empty */
/* Pushes a new list to the stack */
list

/* Stack: [] */
/* Pushes several new items to the stack and appends each to the list */
1 append
2 append
3 append

/* Stack: [1, 2, 3] */
/* Copies the top item on the stack */
dup

/* Stack: [1, 2, 3] [1, 2, 3] */
/* Prints: [1, 2, 3] */

/* Stack: [1, 2, 3] */
/* The list can be used again */

Control Flow

Control flow is very simple in Avid: an if statement just pops from the top of the stack, sees if that value is truthy, and continues into the if statement if it is. while loops are similar: on each iteration of the loop, the code between the while and the do parts is executed, and if what is left on top of the stack is truthy, the code inside the block is executed and execution returns to the while for reevaluation.

Both of these types of blocks are terminated by end statements.

Now, some examples!

0
while
    1 +
    dup 11 != dup

    /* You can do if statements anywhere, even inside the conditions of while loops! */
    if
        "The value is not eleven! " print
    end
do
    "The value is: " print
    dup print
    "! " print
end

Functions

Currently, you cannot define your own functions in Avid, but you can in rust! Check out the rust documentation for more details, and the list of pre-defined functions too!

The Avid Standard Library

Avid’s standard library is relatively small and simple. So, without further ado, let’s get into it!

Basic functions

Function	Description
`+`	Pops the top two items off of the stack, sums them up, and pushes the result onto the stack. Throws an error if the types at the top are not `Num`, `Num`.
`-`	Pops the top two items off of the stack, finds their difference, and pushes the result onto the stack. Throws an error if the types at the top are not `Num`, `Num`.
`dup`	Makes a copy of the top element of the stack and pushes it onto the stack.
`swap`	Swaps the top two elements on the stack.
`drop`	Removes the top element on the stack.
`list`	Creates a new list and pushes it onto the stack.
`append`	Pops the value from the top of the stack and appends it to the second element on the stack. Throws an error if the second element on the stack is not a `List`.
`not`	Pops the top element on the stack, performs a logical not, and pushes the result onto the stack.
`==`	Pops the top two elements on the stack, checks their equality, and pushes the result onto the stack.
`!=`	Pops the top two elements on the stack, checks their inequality, and pushes the result onto the stack.
`get`	Pops the top two elements from the stack, then pushes onto the stack a copy of the nth item from the second element, where n is the first item. Throws an error if the first element is not a `num` and the second element is not a `List`.
`rot`	Pops the top three elements from the top of the stack (`arg3`, `arg2`, `arg1`), then pushes the first element, then the third, then the second onto the stack (`arg1`, `arg3`, `arg2`).