`complexpr` is a programming language, for a sufficiently inclusive definition of the term. It can be used to accomplish many tasks that the average programmer would wish to accomplish, including:
- Printing "Hello, world!" (and over 3 other strings!)
- Computing factorials
- Finding prime numbers
- Simulating arbitrary Turing machines
- And ∞ more!
To install complexpr, simply clone this repository, `cd complexpr-bin`, and `cargo install --path .`. You can then use the `complexpr` command to start a REPL, or pass a filename as an argument to read from a file.
The core `complexpr` parser and interpreter library, the standard library `complexpr-stdlib`, and the command-line interpreter and REPL `complexpr-bin` are licensed under the [GNU LGPL 3.0](https://www.gnu.org/licenses/lgpl-3.0.html).
Complex numbers can be written as the sum of a real component and imaginary component, where the imaginary component is suffixed with an `i`. For example, `5i`, `-1.3+3i`, and `0.5-0.2i` are all valid complex numbers.
Rational numbers are defined using the rational division operator `//`, described below.
| `\x##` | Arbitrary character (one byte codepoint) |
| `\u{##…}` | Arbitrary character (any size codepoint) |
Strings can extend across multiple lines, and will include the newlines by default. To prevent the newlines from being included, escape them using a `\` at the end of the line.
## Arithmetic operators
Data is rather useless if there is no way to operate it. As such, `complexpr` also includes several operators, the most basic of these being arithmetic operators.
| `//` | Rational division (results in a rational type) | `5//3`, `-1//10` |
All of these operators (except `//`) follow the following rule when applied to numeric operands of differing types: the type of the result is the *more generic* of the two operand types. In order of increasing genericness, `Int`, `Rational`, `Float`, `Complex`. As an example, the type of `5.0 + 3//2` is `Float`, since floats are more generic than rationals
Unlike the other operators, `//` is only valid for integer and rational arguments, and always results in a rational value.
`+` can also be used for concatenating chars and strings to each other. The result of this is always a string. `+` can also be used to concatenate lists. `*` can be used for repeating a list or string a certain number of times, for example `[0,1,2] * 3` = `[0,1,2,0,1,2,0,1,2]`.
`^` has the highest precedence and is right-associative (so, `2^3^4` = `2^(3^4)`). `*`, `/`, `%`, and `//` have the next highest precedence, followed by `+` and `-`.
In addition to operating on data, it is also desirable to compare it to other data. `complexpr` has the standard set of comparison operators plus a fairly uncommon one.
| Operator | Description | Example usage (all true) |
Equality and inequality will always succeed, regardless of the types of the arguments. Numeric types which have equal values will compare as equal, even if the types are different.
Comparison operators can be applied to real numbers (not `Complex`), chars, strings, and lists. Characters are compared by their codepoints, and strings and lists are compared [lexicographically](https://en.wikipedia.org/wiki/Lexicographic_order).
The spaceship operator results in 0 if the arguments are equal, 1 if the left-hand side is greater, or -1 if the right-hand side is greater.
`&&` and `||` are the logical AND and OR operators. `&&` will evaluate to the left-hand argument if it is falsy, otherwise it will evaluate to the right-hand argument. `||` will evaluate to the left-hand argument if it is `truthy`, otherwise it will evaluate to the right-hand one.
`!` is the unary NOT operator.
## Comments
Line comments are preceded by a hash sign (or number sign, or pound sign, or octothorpe, etc.). Block comments are surrounded with `#{ … }#`.
Variables are declared using the keyword `let`. For example, `let number = 12;` declares a variable named `number` with the value of `12`. The variable does not need to be assigned to right away, in which case it defaults to `nil` (for example: `let number;`).
Use a single equals sign (`=`) to reassign a previously declared variable. As with many other programming languages, you can also use compound assignment operators to modify a variable's value. These include `+=`, `-=`, `*=`, `/=`, `%=`, `^=`, and `//=`, and do exactly what you would expect. These cannot be used in `let` statements, for obvious reasons.
`complexpr` uses lexical scoping, so a variable is only valid in the block it was declared in, as well as all inner blocks. When assigning to a variable, if multiple outer scopes contain a declaration for the variable, the innermost one is modified.
`complexpr` offers three procedural-style methods of control flow: if statements, while loops, and for-each loops. If statements use the keywords `if` for the first condition, `elif` for all subsequent conditions, and `else` for the else clause. Conditions do not need to be parenthesized. The bodies of an if statement should be enclosed in braces (currently this is not required if the body is one statement long, but this may change in the future).
While loops are syntactically very similar, using the keyword `while` and also not requiring parentheses for the condition.
For-each loops use the keyword `for`, followed by the loop variable, a colon, and then the collection to iterate over (see below for information regarding iterators).
Functions can be defined either with a name or anonymously. Defining a named function is equivalent to creating an anonymous one and immediately declaring a variable and assigning the function to it.
```
# define the function "add1"
fn add1(x, y) {
return x + y;
}
# create an anonymous function and assign it to the variable "add2"
let add2 = fn(x, y) {
return x + y;
};
```
Functions can then be called using the typical syntax:
```
println(add1(3, 4)); # prints 7
```
When a function is declared, it captures the environment it was declared in, including definitions that occur after the function in the source code. This is somewhat counterintuitive.
```
let x = 5;
fn test() {
println(x);
}
test(); # prints 5
x = 7;
test(); # prints 7
```
Functions are first-class, they can be passed around just like any other value.
### Braces vs parentheses
If a function body is one or multiple statements, it must be surrounded by braces `{ }`. If the body consists of a single expression, it can be surrounded with parentheses, and the result of the expression will be returned.
```
fn add3(x, y) (x + y)
println(add3(1, 7)); # prints 8
```
### Partial applications
If a function is called with fewer than its required number of arguments, it will return a *partial function*. Calling this partial function with the remaining arguments will return the value expected had the function been called with all of its arguments at once.
Some infix operators can be converted to functions by prefixing them with a backslash `\`. For example, `\+` is a function that computes the sum of its two arguments (the same as `fn(x, y) (x + y)`). This can be done for arithmetic, comparison, and bitwise operators only.
An iterator is simply a function with the following properties:
- it takes zero arguments,
- it returns `nil` once it runs out of elements, and
- once it returns `nil` once, it will continue to do so forever
The language only enforces the first point, the second and third must be enforced by the programmer. It is also often the case that an iterator will return a different value each time it is called, however this is not neccesary.
Iterators can be used in most places that lists and strings can be used, for example in a for loop:
```
# print the numbers from 0 to 100 (exclusive)
for x in 0..100 {
println(x);
}
```
### Range syntax
Ranges are a simple built-in type of iterator for producing a range of numbers or characters. Because of floating-point rounding issues, they can only be used with integers and rationals (not floats or complex numbers). The most basic range type is written as `a..b`, where `a` is the initial value and `b` is the limit (which is exclusive, ie. the iterator will stop before reaching this value).
Adding an equals sign before the limit value will make the range inclusive - it will stop only once it exceeds the limit. Replacing the final value with an asterisk `*` will make the range infinite (this is incompatible with the inclusive syntax).
After the limit term, an optional step amount can be specified by appending a colon followed by the step value. If no step value is specified the default is the integer `1`.
For a numeric range, the three terms can be integers or rational numbers in any combination. For character literals (which must be inclusive), the start and limit must be characters while the step, if specified, must be an integer.
```
println(list(0..6)); # [0, 1, 2, 3, 4, 5]
println(list(0..=6)); # [0, 1, 2, 3, 4, 5, 6]
# println(list(0..*)); # Constructing a list from an infinite range is a bad idea
println(list(0..6:2)); # [0, 2, 4]
println(list(0..=6:2)); # [0, 2, 4, 6]
# println(list(0..*:2)); # This is also a bad idea
```
### Pipeline syntax
One of the hallmark features of `complexpr` is its pipeline syntax. Pipelines provide a convenient way to work with data, especially iterators, by allowing the programmer to write functions in the order that they are applied. Pipeline operators all have the same precedence and are applied left-to-right.
The most basic pipeline operator is `|>`. `|>` will call the function on the right side using the value on the left side as an argument.
```
# println("Hello, world!");
"Hello, world!" |> println;
```
`|:` is similar to `map` in other languages; it constructs an iterator that takes each element from the iterator on the left and applies the function on the right to it.
```
# prints the list of squares from 0^2 to 9^2
0..10 |: fn(x) (x^2) |> list |> println;
```
(Note: the iterator must first be converted to a list before printing.)
`|?` filters the iterator on the left using the function to the right. If the function returns `false` the item is skipped; if it returns true, the item is passed through.
`|//` folds the iterator on the left over the function on the right. This is commonly used to get the sum, product, minimum, or maximum of an iterator. `|//` starts folding from the beginning of the iterator and goes to the end.
In some cases (particulary when the function is not commutative) it may be desirable to use an initial value instead of taking the first two values from the list. This can be accomplished with the operator `|/`. This operators are ternary, so the right-hand side must include the initial value and the function, separated by a comma.
