Start adding documentation to the language
This commit is contained in:
parent
5991a75d32
commit
6f5bb51e3b
264
documentation/README.md
Normal file
264
documentation/README.md
Normal file
@ -0,0 +1,264 @@
|
|||||||
|
# Reid Language
|
||||||
|
|
||||||
|
This is where the documentation for this language will go, describing the
|
||||||
|
features, syntax and standard library of the language as best as I have time and
|
||||||
|
motivation to write.
|
||||||
|
|
||||||
|
Documentation is presented in a formal grammar and an example,
|
||||||
|
syntax-highlighted with Rust, because it's close enough.
|
||||||
|
|
||||||
|
## Syntax
|
||||||
|
|
||||||
|
Syntax for Reid is very much inspired by rust, and examples of the language can
|
||||||
|
be found in the [examples](../examples/)-folder.
|
||||||
|
|
||||||
|
In Reid **modules** (or files) on the top-level are comprised of imports, type
|
||||||
|
definitions, binop-definitions and functions.
|
||||||
|
|
||||||
|
In formal grammar
|
||||||
|
```bnf
|
||||||
|
<module> :: (<import> | <type-definition> | <binop-definition> | <function>)*
|
||||||
|
```
|
||||||
|
|
||||||
|
Table of Contents:
|
||||||
|
- [Common tokens](#common-tokens)
|
||||||
|
- [Imports](#imports)
|
||||||
|
- [Type definitions](#type-definitions)
|
||||||
|
- [Struct types](#struct-types)
|
||||||
|
- [Binary operation Definitions](#binary-operation-definitions)
|
||||||
|
- [Function definitions](#function-definition)
|
||||||
|
- [Statement](#statement)
|
||||||
|
- [Expression](#expression)
|
||||||
|
|
||||||
|
### Common tokens
|
||||||
|
|
||||||
|
Common token used throughout this document to express parts of grammar include:
|
||||||
|
```bnf
|
||||||
|
<ident> :: [a-Z]([_a-Z0-9])*
|
||||||
|
|
||||||
|
<literal> :: <integer> | <real> | <char> | <string> | <bool>
|
||||||
|
<integer> :: <decimal> | <hexadecimal> | <octal> | <binary>
|
||||||
|
<real> :: [0-9]+ "." [0-9]+
|
||||||
|
<char> :: "'" <any-character> "'"
|
||||||
|
<string> :: "\"" <any-character>* "\""
|
||||||
|
<bool> :: "true" | "false"
|
||||||
|
|
||||||
|
// Any character (except "), or any character escaped
|
||||||
|
<any-character> :: [.] | "\" [.]
|
||||||
|
|
||||||
|
<decimal> :: [0-9]+
|
||||||
|
<hexadecimal> :: "0x" [0-9a-f]+
|
||||||
|
<octal> :: "0o" [0-7]+
|
||||||
|
<binary> :: "0b" [01]+
|
||||||
|
|
||||||
|
|
||||||
|
<type> :: <primitive-type>
|
||||||
|
| "[" <type> ";" <integer>] "]"
|
||||||
|
| "*" <type>
|
||||||
|
| "&" [ "mut" ] <type>
|
||||||
|
|
||||||
|
<primitive-type> ::
|
||||||
|
"char" | "bool" |
|
||||||
|
"u8" | "u16" | "u32" | "u64" | "u128" |
|
||||||
|
"i8" | "i16" | "i32" | "i64" | "i128" |
|
||||||
|
"f16" | "f32" | "f32b" | "f64" | "f80" | "f128" | "f128ppc"
|
||||||
|
|
||||||
|
<binop> :: "+" | "-" | "*" | "/" | "%" | "&&" | <cmp>
|
||||||
|
<cmp> :: "<" | "<=" | "==" | "!=" | ">=" | >"
|
||||||
|
<unary> :: "+" | "-" | "!"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Imports
|
||||||
|
|
||||||
|
Imports are used to import functions and types from other modules. In formal
|
||||||
|
grammar the syntax for imports is
|
||||||
|
```bnf
|
||||||
|
<import> :: "import" <ident> "::" <ident> ";"
|
||||||
|
```
|
||||||
|
|
||||||
|
An example importing the `print`-function from `std` would be
|
||||||
|
``` rust
|
||||||
|
import std::print;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Type Definitions
|
||||||
|
|
||||||
|
Type definitions are used to define new types. Currently this only supports
|
||||||
|
struct-types. In formal grammar:
|
||||||
|
```bnf
|
||||||
|
<type-definition> :: <struct-definition>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Struct types
|
||||||
|
|
||||||
|
Struct (or Structure) types are aggregate types containing other types within
|
||||||
|
struct fields. In formal grammar:
|
||||||
|
```bnf
|
||||||
|
<struct-definition> :: "struct" <ident> "{" [ <field-def> ( "," <field-def> )* [ "," ] ] "}"
|
||||||
|
<field-def> :: <ident> ":" <type>
|
||||||
|
```
|
||||||
|
|
||||||
|
An example of a struct `Test` containing two fields `first` and `second` of
|
||||||
|
integer types.
|
||||||
|
```rust
|
||||||
|
struct Test {
|
||||||
|
first: u32,
|
||||||
|
second: u64,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Binary Operation Definitions
|
||||||
|
|
||||||
|
Reid has a feature where custom binary operations can be defined with a
|
||||||
|
specialized syntas. Only pre-defined operators are allowed however. In formal
|
||||||
|
grammar:
|
||||||
|
|
||||||
|
```bnf
|
||||||
|
<binop-definition>: "impl" "binop" <param> <binop> <param> "-> " <type> <block>
|
||||||
|
<param> :: "(" <ident> ":" <type> ")"
|
||||||
|
```
|
||||||
|
|
||||||
|
(Block-syntax is defined formally with functions)
|
||||||
|
|
||||||
|
An example of a custom binary operator `+` between type `u16` and `u32` could be:
|
||||||
|
```rust
|
||||||
|
impl binop (lhs: u16) + (rhs: u32) -> u32 {
|
||||||
|
return (lhs as u32) + rhs;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Function Definition
|
||||||
|
|
||||||
|
Rust syntax for defining functions is similar to rust. There are two types of functions:
|
||||||
|
1. `extern` functions which are defined in another module, used to define functions from outside modules such as `libc`.
|
||||||
|
2. `local` functions which are defined locally in the module in Reid. Their
|
||||||
|
definition is contained within a `block` which contains a list of
|
||||||
|
`statement`s.
|
||||||
|
|
||||||
|
In formal grammar:
|
||||||
|
```bnf
|
||||||
|
<function-definition> :: <extern-function> | <local-function>
|
||||||
|
<extern-function> :: "extern" "fn" <signature> ";"
|
||||||
|
<local-function> :: [ "pub" ] "fn" <signature> <block>
|
||||||
|
|
||||||
|
<signature> :: <ident> "(" [ <params> ] ")" [ "->" <type> ]
|
||||||
|
<params> <param> ( "," <param> )*
|
||||||
|
<param> :: <ident> ":" <type>
|
||||||
|
<block> :: "{" <statement>* "}"
|
||||||
|
```
|
||||||
|
|
||||||
|
An example of a simple `extern` and `local` function definition would be:
|
||||||
|
```rust
|
||||||
|
extern fn puts(message: *char) -> i32;
|
||||||
|
|
||||||
|
fn main() -> u8 {
|
||||||
|
return 7;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Statement
|
||||||
|
|
||||||
|
Statements in Reid is how you tell the program to do anything. Currently supported statements include:
|
||||||
|
- Let-statement to declare new variables
|
||||||
|
- Let-statements declare immutable variables by-default, but can declare
|
||||||
|
mutable variables with the `mut` keyword similar to Rust.
|
||||||
|
- Set-statement to re-set previously declared (mutable) variables to new values.
|
||||||
|
- Statements can also be simply expressions without intent to store the result.
|
||||||
|
- Return-statements to return values out of blocks or functions.
|
||||||
|
- For-loops to loop over a certain range of numbers
|
||||||
|
- While-loops to loop until a certain condition is no longer met.
|
||||||
|
|
||||||
|
In formal grammar:
|
||||||
|
```bnf
|
||||||
|
<statement> :: <let> | <set> | <return> | <for> | <while> | <expr-statement>
|
||||||
|
<let> :: "let" [ "mut" ] <ident> "=" <expression> ";"
|
||||||
|
<set> :: <ident> "=" <expression> ";"
|
||||||
|
<expr-statement> :: <expression> ";"
|
||||||
|
<for> :: "for" <ident> "in" <expression> ".." <expression> <block>
|
||||||
|
<while> :: "while" <expression> <block>
|
||||||
|
<return> :: ( "return" <expression> ";" ) | <expression>
|
||||||
|
```
|
||||||
|
|
||||||
|
An example of each statement type would be:
|
||||||
|
```rust
|
||||||
|
let mut value = 5;
|
||||||
|
value = 6;
|
||||||
|
for i in 0..5 { }
|
||||||
|
while value < 5 { }
|
||||||
|
|
||||||
|
// "hard" return
|
||||||
|
return value;
|
||||||
|
|
||||||
|
// "soft" return
|
||||||
|
value
|
||||||
|
```
|
||||||
|
|
||||||
|
### Expression
|
||||||
|
|
||||||
|
Expressions in Reid are anything that can return a value, such as function
|
||||||
|
calls, literals, or if-expressions. Types of supported expressions include:
|
||||||
|
- **Variable name reference**, to reference a value in a variable
|
||||||
|
- **Borrow**, which works similar to Rust but with a little less safety. In simple
|
||||||
|
terms it creates a safer pointer-type than a regular pointer.
|
||||||
|
- **Deref**, which extracts the value out of a borrow.
|
||||||
|
- **Literal**, which is just some direct value, such as a number.
|
||||||
|
- **Array-value**, to declare a new array with a static length
|
||||||
|
- **Struct-value**, to declare a new value for a struct that has been defined
|
||||||
|
earlier.
|
||||||
|
- Shorter way to declare arrays with a single initialized value.
|
||||||
|
- **Indexing** into an array-value
|
||||||
|
- **Accessing a field** in a struct-value
|
||||||
|
- **Binary operations** (such as add/sub/mult)
|
||||||
|
- **Unary operations** (such as !value or -value)
|
||||||
|
- **Function calls**, to invoke a predefined function with given parameters
|
||||||
|
- **Block-expressions**, which can return a value to the higher-level expression
|
||||||
|
if they have a statement with a soft-return. Otherwise they return void.
|
||||||
|
- **If-expressions**, which can execute one of two expressions depending on the
|
||||||
|
given condition.
|
||||||
|
- **Casts** to explicitly cast a value to another type.
|
||||||
|
|
||||||
|
Expressions can also always be surrounded by (paranthesis).
|
||||||
|
|
||||||
|
In formal grammar:
|
||||||
|
```bnf
|
||||||
|
<expression> ::
|
||||||
|
<variable> | <borrow> |
|
||||||
|
<deref> | <literal> |
|
||||||
|
<array> | <struct> |
|
||||||
|
<indexing> | <accessing> |
|
||||||
|
<binary-exp> | <unary-exp> |
|
||||||
|
<function-call> | <block> |
|
||||||
|
<if-expr> | <cast> |
|
||||||
|
( "(" <expression> ")" )
|
||||||
|
|
||||||
|
<variable> :: <ident>
|
||||||
|
<borrow> :: "&" [ "mut" ] <ident>
|
||||||
|
<deref> :: "*" <ident>
|
||||||
|
<array> :: "[" <expression>* "]"
|
||||||
|
<struct> :: <ident> "{" [ <field> ( "," <field> )* [ "," ] ]
|
||||||
|
<field> :: <ident> ":" <expression>
|
||||||
|
<indexing> :: <expression> "[" <integer> "]"
|
||||||
|
<accessing> :: <expression> "." <ident>
|
||||||
|
<binary-exp> :: <expression> <binop> <expression>
|
||||||
|
<unary-exp> :: <unary> <expression>
|
||||||
|
<function-call> :: <expression> "(" [ <expression> ( "," <expression> )* ] ")"
|
||||||
|
<if-expr> :: "if" <expression> <expression> [ "else" <expression> ]
|
||||||
|
<cast> :: <expression> "as" <type>
|
||||||
|
```
|
||||||
|
|
||||||
|
An example of each expression in-order is:
|
||||||
|
```rust
|
||||||
|
varname // Variable
|
||||||
|
&varname // Borrow
|
||||||
|
*borrowed_varname // Deref
|
||||||
|
[ varname, 5, 7 ] // Array
|
||||||
|
Test { first: 4, second: 15 } // Struct
|
||||||
|
array[0] // Indexing
|
||||||
|
test.first // Accessing
|
||||||
|
7 + value // Binop
|
||||||
|
!bool_value // Unary
|
||||||
|
func(value, 14) // Function call
|
||||||
|
if varname {} else {} // If-expression
|
||||||
|
value as u32 // cast
|
||||||
|
(value + 2) // Binop within parenthesis
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user