Merge pull request #271 from koto-lang/docs-tweaks

Documentation and help system improvements

crates/lexer/src/lexer.rs

@@ -692,7 +692,7 @@ fn is_octal_digit(c: char) -> bool {
 }
 
 fn is_hex_digit(c: char) -> bool {
-    matches!(c, '0'..='9' | 'a'..='f' | 'A'..='F')
+    c.is_ascii_hexdigit()
 }
 
 fn is_whitespace(c: char) -> bool {

crates/runtime/src/core_lib/iterator/adaptors.rs

@@ -860,10 +860,7 @@ impl Iterator for TakeWhile {
             return None;
         }
 
-        let Some(iter_output) = self.iter.next() else {
-            return None;
-        };
-
+        let iter_output = self.iter.next()?;
         let predicate = self.predicate.clone();
         let predicate_result = match &iter_output {
             Output::Value(value) => self

docs/language/basics.md

@@ -1,7 +1,5 @@
 # Language Basics
 
-## Koto Programs
-
 Koto programs contain a series of expressions that are evaluated by Koto's runtime.
 
 For example, this program asks for the user's name and then offers them a
@@ -14,7 +12,7 @@ print "Hi there, $name!"
 ```
 
 Try placing the above example in a file named `hello.koto`, and then running 
-`koto hello.koto`.
+`koto hello.koto`, or entering the expressions one at a time in the REPL.
 
 ## Comments
 

docs/language/conditional_expressions.md

@@ -1,5 +1,7 @@
 # Conditional Expressions
 
+Koto includes several ways of producing values that depend on _conditions_.
+
 ## if
 
 `if` expressions come in two flavours; single-line:

docs/language/functions_advanced.md

@@ -1,5 +1,27 @@
 # Advanced Functions
 
+Functions in Koto stored by the runtime as values and can hold internal captured state.
+
+If a value is accessed in a function that wasn't assigned locally, 
+then the value is copied into the function (or _captured_) when it's created. 
+
+```koto
+x = 1
+
+# x is assigned outside the function,
+# so it gets captured when it's created.
+f = |n| n + x 
+
+# Reassigning x here doesn't modify the value 
+# of x that was captured when f was created.
+x = 100
+
+print! f 2
+check! 3
+```
+
+It's worth noting that this behavior is different to many other scripting languages, where captures are often taken by _reference_ rather than by _value_.
+
 ## Optional Arguments
 
 When calling a function, any missing arguments will be replaced by `null`.
@@ -126,20 +148,3 @@ check! (('foo_a', 1), ('foo_b', 3))
 
 ## Captured Values
 
-If a value is accessed in a function that wasn't assigned locally, 
-then the value is copied into the function (or _captured_) when it's created. 
-
-```koto
-x = 1
-
-# x is assigned outside the function,
-# so it gets captured when it's created.
-f = |n| n + x 
-
-# Reassigning x here doesn't modify the value 
-# of x that was captured when f was created.
-x = 100
-
-print! f 2
-check! 3
-```

docs/language/loops.md

@@ -1,5 +1,7 @@
 # Loops
 
+Koto includes several ways of evaluating expressions repeatedly in a loop.
+
 ## for
 
 `for` loops can be used to iterate over any iterable value.

docs/language/modules.md

@@ -1,5 +1,7 @@
 # Modules
 
+Koto includes a module system that helps you to organize and re-use your code when your program grows too large for a single file.
+
 ## `import`
 
 Module items can be brought into the current scope using `import`.

docs/language/ranges.md

@@ -25,7 +25,25 @@ print! r.contains 200
 check! true
 ```
 
-Ranges are iterable, so can be used in for loops, and with the `iterator` module.
+If a value is missing from either side of the range operator then an _unbounded_
+range is created.
+
+```koto
+r = 10..
+print! r.start()
+check! 10
+print! r.end()
+check! null
+ 
+r = ..=100
+print! r.start()
+check! null
+print! r.end()
+check! 100
+```
+
+_Bounded_ ranges are iterable, so can be used in for loops, and with the 
+`iterator` module.
 
 ```koto
 for x in 1..=3
@@ -38,3 +56,28 @@ print! (0..5).to_list()
 check! [0, 1, 2, 3, 4]
 ```
 
+## Slices
+
+Ranges can be used to create a _slice_ of a container's data.
+
+```koto
+x = (10, 20, 30, 40, 50)
+print! x[1..=3] 
+check! (20, 30, 40)
+```
+
+For tuples and strings, slices share the original container's data, which
+avoids making copies of the elements in the slice. For lists (which contain 
+mutable data), copies of the slices elements are made.
+
+If a range doesn't have a defined start, then the slice starts from the
+beginning of the container's data. Similarly, if a range doesn't have a defined
+end, then the slice includes elements up to the end of the container's data.
+
+```koto
+z = 'Hëllø'
+print! z[..2]
+check! Hë
+print! z[2..]
+check! llø
+```

docs/language/strings.md

@@ -54,7 +54,7 @@ print! '2 plus 3 is ${2 + 3}.'
 check! 2 plus 3 is 5.
 ```
 
-## String Escape codes
+## String Escape Codes
 
 Strings can contain the following escape codes to define special characters,
 all of which start with a `\`. 
@@ -79,7 +79,7 @@ print! 'Hi \u{1F44B}'
 check! Hi 👋
 ```
 
-## Single or double quotes
+## Single or Double Quotes
 
 Whether you use `'` or `"` for your strings doesn't make a difference, except that you can use the other quote character freely in the string without having to escape it with `\`.
 

docs/language/testing.md

@@ -1,8 +1,11 @@
 # Testing
 
+Koto includes some features that help you to automatically check that your code is behaving as you expect.
+
 ## Assertions
 
-A collection of [assertion functions](../../core/test) are available. 
+A collection of assertion functions are available in the [`test` core library module](../../core/test),
+which are included by default in the [prelude](./prelude).
 
 ```koto
 try 
@@ -22,6 +25,9 @@ check! An assertion failed
 
 Tests can be organized in a Map by defining `@test` functions. 
 
+The runtime can be configured to automatically run tests when importing modules, 
+e.g. the CLI will run module tests when the `--import_tests` option is used.
+
 The tests can then be run with [`test.run_tests`](../../core/test#run-tests).
 
 ```koto

docs/language/tuples.md

@@ -33,6 +33,8 @@ print! b
 check! (1, 2, 3, 4, 5, 6)
 ```
 
+## Creating Empty or Single-Value Tuples
+
 To create an empty Tuple, or a Tuple with a single entry, use a trailing `,` inside the parentheses.
 
 ```koto
@@ -51,6 +53,8 @@ print! (1,)
 check! (1)
 ```
 
+## Tuple Mutability
+
 Although Tuples have a fixed structure, mutable values in a Tuple (e.g. Lists and Maps) can still be modified.
 
 ```koto