# Chupacabra Quick Reference Card

See also, <https://git.sr.ht/~eli_oat/chupacabra>

Chupacabra is a stack-based programming language/calculator implemented in lua. It works a lot like any other forth, save for 2 big differences: 

1. you cannot define new words
2. you can put entire arrays on to the stack

## Basic Usage
- **Numbers**: You can push numbers onto the stack. For example, `1` pushes the number 1 onto the stack.
- **Arrays**: You can push arrays onto the stack. For example, `[1 2 3 4]` pushes the array {1, 2, 3, 4} onto the stack.
- **`.`**: The `.` operator pops the top element from the stack and discards it.
- **`:`**: The `:` operator duplicates the top element of the stack.
- **`?`**: The `?` operator swaps the top two elements of the stack.
- **`=`**: The `=` operators checks the top two elements of the stack are equal. Arrays can never be equal, only their values can be.

## Array-first keywords
- **`@`**: The `@` keyword allows you to grab a specific value from an array by index, e.g. `[10 20 30] 2 @` would return the value `20`.
- **`@+`**: The `@+` keyword adds the top two elements on the stack. It supports addition between two numbers, a number and an array, or two arrays.
- **`@-`**: The `@-` keyword subtracts the second topmost element on the stack from the topmost element. It supports subtraction between two numbers, a number and an array, or two arrays.
- **`@*`**: The `@*` keyword multiplies the top two elements on the stack. It supports multiplication between two numbers, a number and an array, or two arrays.
- **`@/`**: The `@/` keyword divides the topmost element on the stack by the second topmost element. It supports division between two numbers, a number and an array, or two arrays.
- **`@=`**: The `@=` keyword compares two equal length arrays and returns an array (like a bit-mask). 

## Test cases
You can create test cases using the `tc` function from lua. The `tc` function takes an input string and an expected output, runs the input string through the Chupacabra interpreter, and checks if the output matches the expected output.

For example, `tc("[1 1 1] [2 3 4] @+", {3, 4, 5})` tests that adding the arrays `[1 1 1`] and `[2 3 4]` results in the array `[3 4 5]`.

~~There is also a totally shit repl. I'll make that better, soon...maybe.~~ I made the repl a little better!

## repl
There is a repl provided to use when exploring chupacabra. First run, `chmod +x repl` and then every other time you should be able to run `./repl` to start it up.

## Other stuff
- Nested arrays? lol, nope.
- User defined words? Also a nope.
- Lambdas? Maybe one day.