kjuulh/rhai
1
0
Fork 0
Code Issues 1 Pull Requests 1 Packages Projects Releases Wiki Activity

Revise docs.

Browse Source
This commit is contained in:
Stephen Chung 2020-06-25 11:07:56 +08:00
parent 58c198776f
commit aeb47efce8
11 changed files with 99 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
doc/src/appendix/keywords.md
View File

@ -3,28 +3,28 @@ Keywords List
{{#include ../links.md}}
| Keyword | Description |
| :--------: | ------------------------------------- |
| `true` | Boolean true literal |
| `false` | Boolean false literal |
| `let` | Variable declaration |
| `const` | Constant declaration |
| `if` | If statement |
| `else` | else block of if statement |
| `while` | While loop |
| `loop` | Infinite loop |
| `for` | For loop |
| `in` | Containment test, part of for loop |
| `continue` | Continue a loop at the next iteration |
| `break` | Loop breaking |
| `return` | Return value |
| `throw` | Throw exception |
| `private` | Mark function private |
| `import` | Import module |
| `export` | Export variable |
| `as` | Alias for variable export |
| `fn` | Function definition |
| `type_of` | Get type name of value |
| `print` | Print value |
| `debug` | Print value in debug format |
| `eval` | Evaluate script |
| Keyword | Description | Not available under |
| :--------: | ------------------------------------- | ------------------- |
| `true` | Boolean true literal | |
| `false` | Boolean false literal | |
| `let` | Variable declaration | |
| `const` | Constant declaration | |
| `if` | If statement | |
| `else` | else block of if statement | |
| `while` | While loop | |
| `loop` | Infinite loop | |
| `for` | For loop | |
| `in` | Containment test, part of for loop | |
| `continue` | Continue a loop at the next iteration | |
| `break` | Loop breaking | |
| `return` | Return value | |
| `throw` | Throw exception | |
| `private` | Mark function private | [`no_function`] |
| `import` | Import module | [`no_module`] |
| `export` | Export variable | [`no_module`] |
| `as` | Alias for variable export | [`no_module`] |
| `fn` | Function definition | [`no_function`] |
| `type_of` | Get type name of value | |
| `print` | Print value | |
| `debug` | Print value in debug format | |
| `eval` | Evaluate script | |

2
doc/src/language/constants.md
View File

@ -9,7 +9,9 @@ Constants follow the same naming rules as [variables].
```rust
const x = 42;
print(x * 2); // prints 84
x = 123; // <- syntax error: cannot assign to constant
```

4
doc/src/language/convert.md
View File

@ -11,10 +11,14 @@ That's it; for other conversions, register custom conversion functions.
```rust
let x = 42;
let y = x * 100.0; // <- error: cannot multiply i64 with f64
let y = x.to_float() * 100.0; // works
let z = y.to_int() + x; // works
let c = 'X'; // character
print("c is '" + c + "' and its code is " + c.to_int()); // prints "c is 'X' and its code is 88"
```

10
doc/src/language/for.md
View File

@ -14,7 +14,9 @@ let s = "hello, world!";
for ch in s {
if ch > 'z' { continue; } // skip to the next iteration
print(ch);
if x == '@' { break; } // break out of for loop
}
@ -23,21 +25,27 @@ let array = [1, 3, 5, 7, 9, 42];
for x in array {
if x > 10 { continue; } // skip to the next iteration
print(x);
if x == 42 { break; } // break out of for loop
}
// The 'range' function allows iterating from first to last-1
for x in range(0, 50) {
if x > 10 { continue; } // skip to the next iteration
print(x);
if x == 42 { break; } // break out of for loop
}
// The 'range' function also takes a step
for x in range(0, 50, 3) { // step by 3
if x > 10 { continue; } // skip to the next iteration
print(x);
if x == 42 { break; } // break out of for loop
}
@ -47,7 +55,9 @@ let map = #{a:1, b:3, c:5, d:7, e:9};
// Property names are returned in unsorted, random order
for x in keys(map) {
if x > 10 { continue; } // skip to the next iteration
print(x);
if x == 42 { break; } // break out of for loop
}

5
doc/src/language/keywords.md
View File

@ -13,8 +13,9 @@ The following are reserved keywords in Rhai:
| `while`, `loop`, `for`, `in`, `continue`, `break` | Looping | |
| `fn`, `private` | Functions | [`no_function`] |
| `return` | Return values | |
| `throw` | Return errors | |
| `throw` | throw exceptions | |
| `import`, `export`, `as` | Modules | [`no_module`] |
| `type_of`, `print`, `debug`, `eval` | Special functions | |
Keywords cannot be the name of a [function] or [variable], unless the relevant exclusive feature is enabled.
Keywords cannot be the name of a [function] or [variable], unless the relevant feature is enabled.
For example, `fn` is a valid variable name under [`no_function`].

36
doc/src/language/logic.md
View File

@ -13,8 +13,11 @@ set of types (see [built-in operators]).
```rust
42 == 42; // true
42 > 42; // false
"hello" > "foo"; // true
"42" == 42; // false
```
@ -23,13 +26,17 @@ except for '`!=`' (not equals) which results in `true`. This is in line with int
```rust
42 == 42.0; // false - i64 cannot be compared with f64
42 != 42.0; // true - i64 cannot be compared with f64
42 > "42"; // false - i64 cannot be compared with string
42 <= "42"; // false - i64 cannot be compared with string
let ts = new_ts(); // custom type
ts == 42; // false - types cannot be compared
ts != 42; // true - types cannot be compared
```
@ -51,9 +58,11 @@ Single boolean operators `&` and `|` always evaluate both operands.
```rust
this() || that(); // that() is not evaluated if this() is true
this() && that(); // that() is not evaluated if this() is false
this() | that(); // both this() and that() are evaluated
this() & that(); // both this() and that() are evaluated
```
@ -61,14 +70,29 @@ Compound Assignment Operators
----------------------------
```rust
let number = 5;
number += 4; // number = number + 4
number -= 3; // number = number - 3
number *= 2; // number = number * 2
number /= 1; // number = number / 1
number %= 3; // number = number % 3
let number = 9;
number += 8; // number = number + 8
number -= 7; // number = number - 7
number *= 6; // number = number * 6
number /= 5; // number = number / 5
number %= 4; // number = number % 4
number ~= 3; // number = number ~ 3
number <<= 2; // number = number << 2
number >>= 1; // number = number >> 1
number &= 0x00ff; // number = number & 0x00ff;
number |= 0x00ff; // number = number | 0x00ff;
number ^= 0x00ff; // number = number ^ 0x00ff;
```
The `+=` operator can also be used to build [strings]:

3
doc/src/language/loop.md
View File

@ -13,8 +13,11 @@ let x = 10;
loop {
x = x - 1;
if x > 5 { continue; } // skip to the next iteration
print(x);
if x == 0 { break; } // break out of loop
}
```

1
doc/src/language/modules.md
View File

@ -1 +0,0 @@
# Modules

7
doc/src/language/overload.md
View File

@ -10,13 +10,20 @@ New definitions _overwrite_ previous definitions of the same name and number of
```rust
fn foo(x,y,z) { print("Three!!! " + x + "," + y + "," + z) }
fn foo(x) { print("One! " + x) }
fn foo(x,y) { print("Two! " + x + "," + y) }
fn foo() { print("None.") }
fn foo(x) { print("HA! NEW ONE! " + x) } // overwrites previous definition
foo(1,2,3); // prints "Three!!! 1,2,3"
foo(42); // prints "HA! NEW ONE! 42"
foo(1,2); // prints "Two!! 1,2"
foo(); // prints "None."
```

3
doc/src/language/print-debug.md
View File

@ -7,8 +7,11 @@ The `print` and `debug` functions default to printing to `stdout`, with `debug`
```rust
print("hello"); // prints hello to stdout
print(1 + 2 + 3); // prints 6 to stdout
print("hello" + 42); // prints hello42 to stdout
debug("world!"); // prints "world!" to stdout using debug formatting
```

19
doc/src/language/variables.md
View File

@ -6,15 +6,20 @@ Variables
Valid Names
-----------
Variables in Rhai follow normal C naming rules (i.e. must contain only ASCII letters, digits and underscores '`_`').
Variables in Rhai follow normal C naming rules - must contain only ASCII letters, digits and underscores '`_`',
and cannot start with a digit.
Variable names must start with an ASCII letter or an underscore '`_`', must contain at least one ASCII letter,
and must start with an ASCII letter before a digit.
For example: '`_c3po`' and '`r2d2`' are valid variable names, but '`3abc`' is not.
Therefore, names like '`_`', '`_42`', '`3a`' etc. are not legal variable names, but '`_c3po`' and '`r2d2`' are.
Variable names are also case _sensitive_.
However, unlike Rust, a variable name must also contain at least one ASCII letter, and an ASCII letter must come before any digit.
In other words, the first character that is not an underscore '`_`' must be an ASCII letter and not a digit.
Variable names cannot be the same as a [keyword].
Therefore, some names acceptable to Rust, like '`_`', '`_42foo`', '`_1`' etc., are not valid in Rhai.
This restriction is to reduce confusion because, for instance, '`_1`' can easily be misread (or mis-typed) as `-1`.
Variable names are case _sensitive_.
Variable names also cannot be the same as a [keyword].
Declare a Variable
@ -23,7 +28,7 @@ Declare a Variable
Variables are declared using the `let` keyword.
Variables do not have to be given an initial value.
If none is provided, then it defaults to [`()`].
If none is provided, it defaults to [`()`].
A variable defined within a statement block is _local_ to that block.