Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refactor docs #17

Merged
merged 2 commits into from
Aug 18, 2023
Merged

Refactor docs #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
46b91fe
docs: Update installation instructions and split monkey syntax
Yag000 Aug 16, 2023
2d73885
docs: Add link to the monkey language docs in the README
Yag000 Aug 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
262 changes: 20 additions & 242 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,31 +16,31 @@ There are some issues that I want to fix before I can call this implementation c
To start the REPL, run the following command:

```bash
cargo run --release --bin monkey
monkey
```

### File interpreter

To run a Monkey file, run the following command:

```bash
cargo run --release --bin monkey -- <path-to-file>
monkey <path-to-file>
```

### Other modes

You can also test the compiler, parser and lexer in the same way, adding the following flag after the path to the file:

```bash
--mode <mode>
monkey --mode <mode>
```

Where `<mode>` can be `compiler`, `parser`, `lexer` or `interpreter`.

Example:

```bash
cargo run --release --bin monkey -- <path-to-file> --mode compiler
monkey <path-to-file> --mode compiler
```

### Formatter
Expand All @@ -49,7 +49,7 @@ A monkey formatter is also available, with the binary `monkeyfmt`. I will format
To use it you only need to run the following command:

```bash
cargo run --release --bin monkeyfmt -- <path-to-file>
monkeyfmt <path-to-file>
```

Adding the `-r` flag after the file name will replace the contents of the file with the
Expand All @@ -61,254 +61,32 @@ formatted code. If the flag is not activated, the formatted code will be printed
To see the help, run the following command:

```bash
cargo run --release --bin monkey -- --help
monkey --help
```

## Monkey syntax
## Installation

### Types
### Crates.io

The monkey language supports the following types:
`Chimpanzee` is available as a cargo crate, which means that you can install it
by simple using:

- Integers
- Booleans
- Strings
- Arrays
- Hashes
- Functions (yes, functions are a type in Monkey)

#### Integers

Integers are 64-bit signed integers. They are written as follows:

```monkey
let a = 1;
let b = 2;
```

##### Operators

Integers support the following operators:

- `+`: addition
- `-`: subtraction
- `*`: multiplication
- `/`: division (integer division)
- `==`: equality
- `!=`: inequality
- `<`: less than
- `>`: greater than
- `<=`: less than or equal to
- `>=`: greater than or equal to

#### Booleans

Booleans are either `true` or `false`. They are written as follows:

```monkey
let a = true;
let b = false;
```

##### Operators

Booleans support the following operators:

- `==`: equality
- `!=`: inequality
- `!`: negation
- `&&`: and
- `||`: or

#### Strings

Strings are sequences of characters. They are written as follows:

```monkey
let a = "Hello, world!";
```

##### String interpolation

Strings can be interpolated using the `+` operator. The following example shows how to interpolate a string:

```monkey
let a = "Hello " + "world!";
```

###### Built-in functions

Strings have the following built-in functions:

- `len()`: returns the length of the string

#### Arrays

Arrays are sequences of values. They are written as follows:

```monkey
let a = [1, "two", [1,2,3]];
```

They can contain any type of value, including other arrays and functions.

##### Indexing

Arrays can be indexed using the `[]` operator. The index must be an integer. The index starts at 0. The following example shows how to index an array:

```monkey
let a = [1,2,3];
let b = a[0]; // b = 1
```

##### Built-in functions

Arrays have the following built-in functions:

- `len(array)`: returns the length of the array
- `first(array)`: returns the first element of the array
- `last(array)`: returns the last element of the array
- `rest(array)`: returns a new array containing all elements except the first
- `push(array, value)`: returns a new array containing all elements of the original array and the new value (at the end)

#### Hashes

Hashes are key-value pairs. They are written as follows:

```monkey
let a = {"one": 1, "two": 2};
```

The keys can be: `Integer` , `Boolean` or `String`. The values can be any type of value, including other hashes and functions.

##### Indexing

Hashes can be indexed using the `[]` operator. The index must be a key. The following example shows how to index a hash:

```monkey
let a = {"one": 1, "two": 2};
let b = a["one"]; // b = 1
```

##### Built-in functions

For now hashes have no built-in functions. In the future the following built-in functions will be supported:

- `keys(hash)`: returns an array containing all keys of the hash
- `values(hash)`: returns an array containing all values of the hash
- `add(hash, key, value)`: returns a new hash containing all key-value pairs of the original hash and the new key-value pair

#### Functions

The function syntax is as follows:

```monkey
let add = fn(a, b) {
return a + b;
};
```

Functions are first-class citizens in Monkey. This means that they can be assigned to variables, passed as arguments to other functions, and returned from other functions.
One example is the map function:

```monkey
let map = fn(arr, f) {
let iter = fn(arr, accumulated) {
if (len(arr) == 0) {
accumulated
} else {
iter(rest(arr), push(accumulated, f(first(arr))));
}
};
iter(arr, []);
};
let a = [1, 2, 3, 4];
let double = fn(x) { x * 2 };
map(a, double);
```

#### Return

Functions can return a value using the `return` keyword. The following example shows how to return a value from a function:

```monkey
let add = fn(a, b) {
return a + b;
};
```

Note that the `return` keyword is optional, Monkey allows implicit returns. The following example shows how to use an implicit return:

```monkey
let add = fn(a, b) {
a + b;
};
```

### Variables

Variables are declared using the `let` keyword. The following example shows how to declare a variable:

```monkey
let a = 1;
```

Shadowing is supported. The following example shows how to shadow a variable:

```monkey
let a = 1;
let a = 2;
```

### Control flow

#### If-else

The if-else syntax is as follows:

```monkey

if (condition) {
// code
} else {
// code
}
```

The following example shows how to use if-else:

```monkey
let a = 1;
if (a == 1) {
return "a is 1";
} else {
return "a is not 1";
}
```bash
cargo install chimpanzee
```

#### Loops
### From source

While loops have been implemented, but for now keywords such as `break` and `continue` have not yet been implemented.
To install it from source you bust clone the repo. Once you have clone it you build the project

```monkey
let a = 1;
while (a < 4) {
puts(a);
let a = a + 1;
}
```bash
cargo build --release
```

### Comments

For now comments are not supported ( not a huge loss :) )
> This step can take some time, the expected time is less that 2 minutes, but it can be even longer.

### Built-in functions
In the directory `target/directory` the two executables will be now available: `monkey` and `monkeyfmt`.

Monkey has the following built-in functions:
## Monkey language

- `puts(value)`: prints the value to the console
- `len(value)`
- `first(array)`
- `last(array)`
- `rest(array)`
- `push(array, value)`
Information about the monkey language is available in the [MONKEY file](docs/MONKEY.md).
Loading