gloo 6.7.2 → 7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfd9613e0faf6957907641ff2f7a8eee6e70d8d99478c43a910e65259537eb30
-  data.tar.gz: 4b5a3f2f27da015cdaa4899feed21bdedce47c9f3988e346ec4ed7dad06aa666
+  metadata.gz: 44699b19dc942762560f80854fd4761359dd663d0a154680db6a5e58a6afc442
+  data.tar.gz: 3326a1a25aa22a42ea296ee929a2297acd9de944fd700299cb8a833d86df9e73
 SHA512:
-  metadata.gz: b6010976ec3a99afee69a02c076d1da1ae44b41f0869f908e7239019bf06c948e3e67fe45221a2a0225ca00bad1f6278a6e02a38ba221e40e545cd88c54ce8aa
-  data.tar.gz: ce1ff1aeff6849d3f7f3b89bfc783a4cb140d82b9f7f0f3e6c5792ba84b19b66b33c3bdb464f5bccca56add517f0ac10102fbf65e6389ef91cc9041f80aa04d7
+  metadata.gz: 5ccdd1461cdec1c6c6aa1f3a698ab0804c3f86e77cf108ce23c10fd83e5db7ca7107bb0c1823f42af7adbfe8eaa14c4ba7c672bfef8ab06994bbe96dbbe53f7b
+  data.tar.gz: f67ee6091000e498da19444ef39ab7b194b2e069dc830c41660bb3090183ce727c0cb43dba6d3cae3b6bcfef551010467634c1a40a4041d19bb9a17294f8be7e

data/CLAUDE.md

@@ -31,6 +31,7 @@ This project is the authoritative source for gloo language documentation — not
 
 - **Narrative reference** — `docs/*.md`, eleven flat files: `getting_started.md`, `application.md`, `language_objects.md`, `language_syntax.md`, `language_scripting.md`, `operators.md`, `iterators.md`, `objects.md`, `verbs.md`, `plugins.md`, `web_app.md`. Linked from the root `README.md`. Convention: no markdown link syntax between pages (plain-text pointers instead, e.g. "see Put" not `[Put](put.md)`) since these are read both on GitHub and in a terminal; `---` separates sections that came from different source material.
 - **Verb/object reference** — each verb (`lib/gloo/verbs/*.rb`) and object type (`lib/gloo/objs/**/*.rb`) class defines `self.doc_data` (name, shortcut, description, syntax, parameters, result, errors, examples, notes — see `lib/gloo/docs/doc_data.rb`), rendered by the in-app interactive help shell (`help`/`?`, see `lib/gloo/docs/help_shell.rb`). When adding or changing a verb or object type, add/update its `doc_data` too.
+- **Error handling** — report problems with `@engine.syntax_err` (couldn't be understood), `@engine.err` (understood, couldn't be done) or `@engine.warn` (done, but probably not what was meant); a question answered "no" is just a result. Never `@engine.log.error`/`log.warn` for these (scripts can't see them). "Not found" messages use `Gloo::Core::NotFound`. See `docs/language_syntax.md`, Errors and Warnings.
 - Core-lib gems (`gloo_core_libraries`) follow the same `doc_data` pattern for their own verbs/objects; a narrative `doc/` folder per gem is planned but not yet built.
 
 ## Test Suites

data/docs/application.md

@@ -30,7 +30,7 @@ gloo [global option] [file]
 
 Running gloo with a file specified will run that file. Once that file is done, gloo will quit. However, by specifying `--cli`, once the file has finished, gloo will remain open in CLI mode.
 
-If a file named on the command line can't be found (a typo, the wrong folder, a missing `.gloo` extension on a full path), gloo prints `File not found: {name}` to stderr and exits with a non-zero status. Any other load or run error also exits non-zero, so a shell script calling gloo can tell a failed run from a clean one.
+If a file named on the command line can't be found (a typo, the wrong folder, a missing `.gloo` extension on a full path), gloo prints `File '{name}' was not found.` to stderr and exits with a non-zero status. Any other load or run error also exits non-zero — including syntax errors in a file that otherwise loaded (gloo keeps loading past them, reporting each with its file and line) — so a shell script calling gloo can tell a failed run from a clean one.
 
 When specifying a file there are a couple ways to reference the gloo file to open:
 
@@ -148,6 +148,8 @@ Debug messages are written to the log only, but other messages are also written
 
 Only error and warning level messages are written to the error log.
 
+In test mode (`--test`), errors and warnings go to the log files only, not the console, so the test output is just the test results. An error a test expects (or one from a test file that deliberately contains a problem) is still in `error.log`.
+
 The application logs folder is in the gloo folder. When gloo is run, the log files will be created if they do not exist. To trim the logs, just delete those log files.
 
 Example tail command to watch the gloo log:

data/docs/iterators.md

@@ -103,9 +103,11 @@ Children:
 - `dir` (file — a directory)
     - The directory instance.
 - `in` (file — a directory)
-    - The folder (directory) we will look in for directories.
+    - The folder (directory) we will look in for directories. The trailing slash is optional, a leading `~` means your home folder, and the path may include wildcards (see Walking a Folder Tree, under Each File).
 - `do` (script)
     - The action we want to perform for each directory in the folder.
+- `recursive` (bool)
+    - Optional. Walk the subfolders too, listing every folder in the tree. Default false.
 
 Messages:
 
@@ -140,11 +142,15 @@ Children:
 - `file` (file)
     - The file instance.
 - `in` (file)
-    - The folder (directory) we will look in for files.
+    - The folder (directory) we will look in for files. The trailing slash is optional, a leading `~` means your home folder, and the path may include wildcards (see Walking a Folder Tree, below).
 - `do` (script)
     - The action we want to perform for each file in the folder.
 - `ext` (string)
-    - Optional file extension. Limit to files of this kind.
+    - Optional file extension. Limit to files of this kind. The match ignores case, so `md` also finds `Notes.MD`, and a leading dot is optional.
+- `recursive` (bool)
+    - Optional. Walk the subfolders too. Default false.
+- `include_dirs` (bool)
+    - Optional. List folders as well as files. Default false: `each file` gives only files. Works with or without `recursive`.
 
 Messages:
 
@@ -169,6 +175,36 @@ each_file [can] :
     tell each_file.for to run
 ```
 
+### Walking a Folder Tree
+
+To go through every file in a folder and all its subfolders, set `recursive`:
+
+```gloo
+notes [each] :
+  file [file] :
+  in [file] : /my/notes/
+  ext [string] : md
+  recursive [bool] : true
+  do [script] : show ^.file
+```
+
+`each dir` takes `recursive` too, and then lists every folder in the tree (but not the `in` folder itself).
+
+For more control, put wildcards in the `in` path instead. They are the same wildcards the shell uses:
+
+- `in: /my/notes/**/` — every folder in the tree; the same as `recursive: true`.
+- `in: /projects/*/docs/` — the `docs` folder of each project, one level down.
+- `in: /projects/*/` — each folder one level down, but not the top folder.
+
+Wildcards combine with `ext`, `recursive` and `include_dirs`. For example, `in: /projects/*/docs/` with `recursive: true` walks every project's docs tree.
+
+What the walk gives:
+
+- Full paths, sorted, with each folder listed before what is in it.
+- Hidden files and folders (names starting with `.`, such as `.git/`) are skipped.
+- A `**` or `recursive` walk does not go into symlinked folders, so a link loop can't trap it. A symlinked folder is still listed itself by `each dir`, or by `each file` with `include_dirs`, and a single-level `*` in the path does go through it.
+- A missing `in` folder is an error for `each dir`, unless the path includes wildcards (then it just finds nothing). `each file` finds nothing either way.
+
 See also: Object Base, Each, Each Line, Each Word, Each Child, Each Directory.
 
 ## Each Line

data/docs/language_syntax.md

@@ -43,7 +43,22 @@ colors [can] :
 
 See also: Show.
 
-## Errors
+## Errors and Warnings
+
+Gloo makes a best guess and keeps going when it can, but it never does so silently: every problem is reported, in one of these ways.
+
+- **Syntax error** — the command couldn't be understood: an unknown verb or object type, a required part missing (`put 3 into`), the wrong number of arguments, an unclosed quote or parenthesis, or an operator missing a value (`show 1 +`).
+- **Runtime error** — the command was understood but couldn't be done: an object that doesn't exist used as a value or a target (`show no.such.obj`), division by zero, a file that can't be read or written, a position out of range. This includes failures caused by the input or the outside world: JSON that doesn't parse, a URL that's malformed or can't be reached, a wrong encryption key, a template with a mistake in it, a date object whose value isn't a date. These read `Could not {what}: {why}.` — for example `Could not parse the JSON in j: expected object key, got 'bad' at line 1 column 2`. A command that would have set `it` sets it to `false` (see It).
+- **Warning** — the command was done, but probably not the way it was meant: a value that isn't really of its type, used as a best guess (`'x' is not an integer; using 0.`), or indentation that doesn't line up. A warning is only logged; it isn't an error.
+- **Just a result** — a question whose answer is "no" is not an error at all: `exists?`, `contains?`, `substring?`, and `index_of` (which gives -1) answer in `it`.
+
+Errors are logged with where they happened in front of the message: the file and line while a file is loading (`app.gloo:12: Unknown type 'strng'; using untyped.`), or the script and its line (`app.on_load, line 3: Object 'app.nme' was not found.`). "Not found" errors always read the same way: `Object 'x' was not found.`, `File 'x' was not found.`, `Folder 'x' was not found.`, `Verb 'x' was not found.`
+
+What happens after an error:
+
+- The line that failed is abandoned, and the script continues with the next line. A `put` whose value couldn't be worked out leaves its target unchanged (and `it` is `false`).
+- Loading a file keeps going after a syntax error, so every problem in the file is reported at once. An object with an unknown type is created untyped, so anything nested under it still loads where it should. A declaration with no name (`[int] : 3`) is created under a placeholder name, `unnamed_1`, `unnamed_2` and so on. A type missing its closing bracket (`count [int : 3`) is read as if it were closed after the type word.
+- The error runs any `on_error` handler (see Events below).
 
 Gloo has a special `error` variable that's not part of the normal object heap. The error will be empty most of the time, but if a command results in an error, this variable will hold the error message until the next command is executed. The error is a string and can be accessed by simply referring to the path-name `error`.
 
@@ -88,10 +103,17 @@ The following events are application and file-level events:
 - `on_quit` — event triggered when gloo is quitting
 - `on_save` — when an object is saved, this event is triggered
 - `on_reload` — event triggered when an object receives message to reload
-- `on_error` — event triggered when gloo hits a checked error condition (a bad path, a missing object, a verb used wrongly)
-- `on_exception` — event triggered when gloo's safety net catches an unanticipated Ruby exception (rare in normal code; use the `throw` verb to exercise it)
+- `on_error` — event triggered when gloo reports a syntax or runtime error (see Errors and Warnings). Warnings don't trigger it.
+- `on_exception` — event triggered when gloo's safety net catches an unanticipated Ruby exception — a bug in gloo itself, since anticipated failures such as division by zero or a missing file are runtime errors (use the `throw` verb to exercise it)
+
+`on_error` and `on_exception` are independent channels — a gloo error fires `on_error` only, an unhandled Ruby exception fires `on_exception` only, and neither triggers the other. In both cases the line that failed is abandoned and execution continues with the next line; a handler is a place to log or react, not a way to retry. After the handler runs, the error is still there for the rest of the command to see (`error`).
 
-`on_error` and `on_exception` are independent channels — a checked gloo error fires `on_error` only, an unhandled Ruby exception fires `on_exception` only, and neither triggers the other. In both cases the line that failed is abandoned and execution continues with the next line; a handler is a place to log or react, not a way to retry. Each handler reads its details from a sibling data container (`error_data` / `exception_data`) that the engine populates before running the script; the handler script and its data container can sit at the root of a file or be nested together inside a container.
+Each handler reads its details from a sibling data container (`error_data` / `exception_data`) that the engine populates before running the script; the handler script and its data container can sit at the root of a file or be nested together inside a container. Each child is optional — the engine fills in the ones that are there:
+
+- `message` — the error message
+- `backtrace` — the backtrace, when there is one
+- `kind` (`error_data` only) — `syntax` if the command couldn't be understood, `runtime` if it couldn't be done
+- `location` (`error_data` only) — where it happened: `file:line` while loading, or `script path, line N`
 
 Some objects also have events that are triggered as part of their lifecycle. Here are some examples:
 
@@ -146,6 +168,8 @@ on_error [script] :
 error_data [can] :
   message [string] :
   backtrace [string] :
+  kind [string] :
+  location [string] :
 
 
 #
@@ -280,7 +304,14 @@ See also: Pathname.
 
 ## It
 
-`it` is a special virtual object. `it` contains the value of the last expression or command run. Not all commands result in a change to the value of `it`.
+`it` is a special virtual object. `it` contains the value of the last expression or command run. Which commands change it follows a simple rule:
+
+- **A question** (`check x for exists?`, `contains?`, `starts_with?`, …) puts its answer in `it`.
+- **A command or message that works out a value** puts that value in `it` (`eval`, `put`, `show 3 + 4`) — even if it also stores it somewhere, in the object's own value (`trim`, `sub`, `format_for_html`) or in a child (`run` on an `erb`, `http_get` or `system` object also sets its `result`).
+- **A pure action** — `list`, a bare `show`, deleting, opening a file — leaves `it` alone, so a value in `it` survives it. Running a script or a loop doesn't set `it` either, though the commands inside it do.
+- **When something goes wrong** in a question or a command that would set `it`, the problem is reported and `it` is `false`. The same goes for a message that never gets to run — the object doesn't exist, or doesn't take that message — including `run` itself: `it` is `false`, so no stale value from an earlier line is left behind.
+
+Each object's messages say what `it` will have (see Objects, or `help` in the app).
 
 Get the value of an expression and store it somewhere for later use:
 
@@ -298,6 +329,23 @@ example [can] :
 
 Running this script will show `7` twice. The first time will be the result of the addition. The second time will be showing the result object.
 
+`it` is read-only. It is a result value, not an object: it has no type, and the next command that produces a result replaces it. You can read it anywhere a value is allowed (`eval it = 7`, `put it into x`, `if it then …`), but nothing can target it. Sending it a message (`check it for …`, `tell it to …`), putting a value into it, or using it with `run`, `move`, `list`, `create`, `save` or `redirect` is an error, and `it` keeps its value.
+
+To send a message to the value in `it`, put it into an object first. Putting it into an object of a given type also says what kind of value it is:
+
+```gloo
+example [can] :
+  path [string] :
+  list [can] :
+    a : one
+    b : two
+  on_load [script] :
+    tell ^.list to random_child_path
+    put it into ^.path
+    check ^.path for starts_with? ( 'example.list.' )
+    show it
+```
+
 See also: Pathname.
 
 ## Operators

data/docs/objects.md

@@ -27,7 +27,7 @@ s [can] :
     show it
 ```
 
-Sending `up` to the string converts it to uppercase, in place. Sending `size` puts the character count into `it`. There are messages for lowercasing, counting words and lines, checking prefixes/suffixes, encoding, and generating random strings (UUIDs, hex, alphanumeric) — see the in-app help for the full list.
+Sending `up` to the string converts it to uppercase, in place. Sending `size` puts the character count into `it`. There are messages for lowercasing, counting words and lines, checking prefixes/suffixes, finding where a substring occurs (`index_of`), encoding, and generating random strings (UUIDs, hex, alphanumeric) — see the in-app help for the full list.
 
 For yes/no messages that inspect state (`blank?`, `starts_with?`, `ends_with?`), the `check` verb reads better than `tell` — `check s.msg for starts_with? ("Hello")` — but it does the same thing (see Verbs, Tell).
 
@@ -48,6 +48,63 @@ can [can] :
 
 `can.data` is itself a container holding three children; `count` puts the number of children into `it`. Because containers can nest arbitrarily, this is how gloo builds up everything from simple config blocks to entire applications.
 
+### Getting children by position
+
+A container keeps its children in the order they were added, so you can also reach them by position. Positions are 0-based: after `split_list`, index 0 is the child named `1`.
+
+- `child_value_at (index)` — the value of the child at that position.
+- `child_path_at (index)` — the child's path from root. This works for any child, including a container.
+- `random_child_value` — the value of a randomly chosen child.
+- `random_child_path` — the path of a randomly chosen child.
+
+Each puts its result into `it`. The `_value` messages are for simple children; a container child has no value of its own, so asking for one is an error. Use the path instead, and put it into an alias to reach the child's fields:
+
+```gloo
+books [can] :
+  list [can] :
+    a [can] :
+      title [string] : Walden
+    b [can] :
+      title [string] : Emma
+  ptr [alias] :
+  on_load [script] :
+    tell books.list to random_child_path
+    put it into books.ptr*
+    show books.ptr.title
+```
+
+An index that is out of range (including a negative one) or isn't a number, or an empty container for the `random_` messages, is an error, and `it` is `false`.
+
+The `random_` messages pick with replacement, so two calls can give the same child. For distinct picks, pick a random index with an integer's `randomize` message, keep the indexes already used as children of another container, and check it with `child_exists` before using `child_path_at`.
+
+### Building a numbered list
+
+To add children one at a time — say, while walking a folder — create each one through an alias. Point the alias at the next numbered path, then create the object there, and put its value in:
+
+```gloo
+names [can] :
+  words [string] : red green blue
+  list [can] :
+  next [int] : 0
+  slot [alias] :
+
+  add_each [each] :
+    word [string] :
+    in [alias] : names.words
+    do [script] :
+      tell names.list to count
+      put it + 1 into names.next
+      put 'names.list.' + names.next into names.slot*
+      create names.slot* as string
+      put ^.word into names.slot
+
+  on_load [script] :
+    tell names.add_each to run
+    tell names.list to show_key_value_table
+```
+
+The children are named `1`, `2`, `3`, the same way `split_list` names them, so `child_value_at ( 0 )` is the child named `1`. The `*` after the alias refers to the alias itself rather than what it points to (see `alias` in the in-app help), so `put … into names.slot*` changes where it points and `create names.slot*` creates the object there.
+
 ## Integer
 
 An integer holds a numeric value and responds to a handful of convenience messages:

data/docs/operators.md

@@ -5,6 +5,7 @@ Gloo operators can be used to do basic math and to compare values.
 **Contents**
 
 - Math Operators
+- Joining Values
 - Comparison Operators
 - Example
 
@@ -19,6 +20,21 @@ These are the gloo math operators:
 /   division
 ```
 
+An expression is worked out strictly left to right. There's no precedence and no grouping with parentheses, so `2 + 3 * 4` is `20` (`2 + 3` first, then `* 4`), not `14`. To work out one part first, put it into an object on its own line, then use that object: `put 3 * 4 into x`, then `eval 2 + x`.
+
+## Joining Values
+
+`+` also joins strings: `"hello" + " world"` is `hello world`. When two values sit side by side with no operator between them, gloo joins them with `+` too.
+
+`and` is another way to write `+`. It reads better when building a string out of several pieces:
+
+```
+> put first_name and ' ' and last_name into full_name
+> put VPM_ROOT and 'Tasks/' and file_name into path
+```
+
+`and` always joins; it is not a logical (boolean) and. Because it's an operator, `and` is never looked up as an object, even if one by that name exists.
+
 ## Comparison Operators
 
 Strings, integers, and decimal numbers can be compared.

data/docs/plugins.md

@@ -150,7 +150,15 @@ end
 
 ### Adding a Verb
 
-A verb subclasses `Gloo::Core::Verb` and must implement `self.keyword`, `self.keyword_shortcut`, and `run`. Inside `run`, `@tokens` gives access to the parsed command line and `@engine` is the running engine (use `@engine.err` for user-facing errors, `@engine.heap.it` to set the implicit `it` result).
+A verb subclasses `Gloo::Core::Verb` and must implement `self.keyword`, `self.keyword_shortcut`, and `run`. Inside `run`, `@tokens` gives access to the parsed command line and `@engine` is the running engine (`@engine.heap.it` sets the implicit `it` result).
+
+Report problems the same way the interpreter does (see Language, Syntax > Errors and Warnings):
+
+- `@engine.syntax_err( msg )` — the command couldn't be understood (eg. a required expression is missing)
+- `@engine.err( msg )` — it was understood but couldn't be done (eg. an object or file wasn't found; use `Gloo::Core::NotFound.object( path )` and friends for the message)
+- `@engine.warn( msg )` — it was done, but probably not the way it was meant (eg. a value used as a best guess)
+
+Don't use `@engine.log.error` or `@engine.log.warn` for these: they only write to the log, so scripts and `on_error` never see them.
 
 The simplest possible verb — `beep`, which takes no parameters (`extensions/beep/src/beep.rb`):
 

data/docs/verbs.md

@@ -43,7 +43,7 @@ tell {path.to.object} to {message}
 > tell the.container to count
 ```
 
-`check` is the same verb under another name — it sends a message exactly the way `tell` does. The two spellings exist so code reads like natural communication: use `tell` to trigger an action (`up`, `run`, `unload`), and `check` to investigate state with a yes/no question (`blank?`, `contains?`, `starts_with?`). The answer to a `check` lands in `it`, so it pairs naturally with `if` / `unless`.
+`check` is the same verb under another name — it sends a message exactly the way `tell` does. The two spellings exist so code reads like natural communication: use `tell` to trigger an action (`up`, `run`, `unload`), and `check` to investigate state with a yes/no question (`blank?`, `contains?`, `starts_with?`). The answer to a `check` lands in `it`, so it pairs naturally with `if` / `unless`. `it` itself can't be sent a message (`check it for …` is an error); put it into an object first — see Language, Syntax > It.
 
 ```gloo
 > tell my.str to up
@@ -75,6 +75,8 @@ put {expression} into {dst.path}
 
 `it` also picks up the result of the evaluation, same as with other verbs — see It.
 
+If the destination doesn't exist, or the expression can't be worked out (eg. it uses an object that doesn't exist), `put` reports an error, leaves the destination unchanged, and sets `it` to `false`. A value that doesn't fit the destination's type is used as a best guess, with a warning: `put 'x' into x` (an integer) gives `0` and warns `'x' is not an integer; using 0.` (see Language, Syntax > Errors and Warnings).
+
 ## Load & Save
 
 `load` reads a `.gloo` file into the heap and runs its `on_load` script. Give a path relative to the project folder (no extension needed) or a full path (extension required); `*` in place of a file name loads every `.gloo` file in a folder.
@@ -85,7 +87,7 @@ put {expression} into {dst.path}
 > load ~/.my_app/settings.gloo
 ```
 
-If the name can't be resolved to a file, `load` reports `File not found: {name}` — it fires `on_error` and, when the file was named on the `gloo` command line, prints the message to stderr and exits non-zero. A bad or missing file never fails silently.
+If the name can't be resolved to a file, `load` reports `File '{name}' was not found.` — it fires `on_error` and, when the file was named on the `gloo` command line, prints the message to stderr and exits non-zero. A bad or missing file never fails silently.
 
 `save` writes loaded objects back to their files. With no argument it saves every open file; with an object it saves the file (or files) that object's tree came from; with `to {path}` it **extracts** — moves the object (and its descendants) out of whichever file currently owns them, into a new file, under their full dotted path.
 

data/lib/VERSION

@@ -1 +1 @@
-6.7.2
+7.0

data/lib/VERSION_NOTES

@@ -1,3 +1,23 @@
+7.0 - 2026.10.01
+ - Error handling (and warnings) revamp.
+ - String adds index_of message.
+ - Adds container messages to access children by index and random children.
+ - 'And' becomes an official operator, a variant of '+'.
+ - Adds protection against treating it as an object or message target.
+ - Adds warnings or errors when extra parameters are added to verbs.
+ - Some operations are now correctly setting it.
+ - Fixes duplicate space in format_for_html message.
+ - Better reporting for predictable failures.
+ - Fixes issue with exists? verb not including instances as part of any option.
+ - Create verb adds bad name check.
+ - Adds recursion for file and dir loops
+	 - `each file` and `each dir` can walk a folder tree with `recursive: true`;
+	   `in` takes a leading `~`, works with or without a trailing `/`, and may
+	   include wildcards (`**/`). `ext` now ignores case.
+	 - `each file` without `ext` no longer lists folders; add
+	   `include_dirs: true` to get them back.
+
+
 6.7.2 - 2026.09.16
  - Fixes issue with logging errors in the dictionary.
 

data/lib/gloo/app/engine.rb

@@ -65,6 +65,8 @@ module Gloo
         @log.debug 'starting the engine...'
         @log.debug Gloo::App::Info.display_title
         @mode = @args.detect_mode
+        # Test output is the test results; errors go to the log only.
+        @log.console_errors = false if @mode == Mode::TEST
         @running = true
 
         @dictionary = Gloo::Core::Dictionary.get( self )
@@ -161,7 +163,7 @@ module Gloo
         begin
           @lib_manager.load_lib TEST_LIB_NAME
           TestRunner.new( self, @args.files ).run
-        rescue => ex
+        rescue StandardError, ScriptError => ex
           handle_exception ex
         end
 
@@ -245,7 +247,7 @@ module Gloo
 
         begin
           @parser.run @last_cmd
-        rescue => e
+        rescue StandardError, ScriptError => e
           handle_exception e
         end
       end
@@ -331,20 +333,74 @@ module Gloo
       # runs the on_error script (if any) unless we're already inside
       # one, so a broken handler can't loop.
       #
-      def err( msg, backtrace=nil )
-        @log.error msg
-        @heap.error.set_to msg
+      # Before the engine has started (eg. while start is still
+      # validating the command line) there's no heap to hold the
+      # error and nothing to handle it, so it is only logged.
+      #
+      # The location (where the failing line is: a script and line, or
+      # a file and line while loading) is found automatically unless
+      # given, and is logged in front of the message.
+      #
+      def err( msg, backtrace=nil, kind: Gloo::Core::Error::RUNTIME, location: nil )
+        location ||= @exec_env&.current_location
+        @log.error( location ? "#{location}: #{msg}" : msg )
+        return unless @heap
+
+        @heap.error.set_to msg, kind, location
 
         return if @handling_error
 
+        # The handler's own lines run as commands, which reset and clear
+        # the error state; put it back afterward so the failed command
+        # is still seen as failed.
+        error = @heap.error
+        value, count = error.value, error.error_count
         @handling_error = true
         begin
-          @event_manager.on_error( msg, backtrace )
+          @event_manager.on_error( msg, backtrace, kind, location )
         ensure
           @handling_error = false
+          error.value = value
+          error.error_count = count
+          error.kind = kind
+          error.location = location
         end
       end
 
+      #
+      # Report a syntax error: the command couldn't be understood
+      # (eg. an unknown verb, or a required part of it is missing).
+      #
+      def syntax_err( msg, location: nil )
+        err( msg, kind: Gloo::Core::Error::SYNTAX, location: location )
+      end
+
+      #
+      # Report a warning: the command was done, but probably not the
+      # way it was meant (eg. a value that isn't really an integer,
+      # used as a best guess). Only logged, with the location in front
+      # of the message: it doesn't set the error or run on_error.
+      #
+      def warn( msg )
+        return if @warnings_off
+
+        location = @exec_env&.current_location
+        @log.warn( location ? "#{location}: #{msg}" : msg )
+      end
+
+      #
+      # Run the block without logging warnings, for internal work that
+      # repeats what was already warned about (eg. re-reading a value
+      # just to compare it).
+      #
+      def without_warnings
+        was_off = @warnings_off
+        @warnings_off = true
+        yield
+      ensure
+        @warnings_off = was_off
+      end
+
       #
       # Log an exception.
       # This function does not log the full backtrace, but
@@ -352,7 +408,7 @@ module Gloo
       #
       def log_exception ex
         backtrace = format_backtrace( ex )
-        @log.error backtrace
+        @log.backtrace backtrace
 
         err( ex.message, backtrace)
       end
@@ -366,7 +422,7 @@ module Gloo
       def handle_exception ex
         backtrace = format_backtrace( ex )
         @log.error ex.message
-        @log.error backtrace
+        @log.backtrace backtrace
 
         return if @handling_exception
 

data/lib/gloo/app/log.rb

@@ -23,6 +23,16 @@ module Gloo
       ERROR_FILE = 'error.log'.freeze
 
       attr_accessor :quiet
+
+      # When false, errors and warnings go to the log files only, not
+      # to the console (eg. while running tests, where the output is
+      # the test results).
+      attr_accessor :console_errors
+
+      # How many errors and warnings have been logged (since the log was
+      # created, or since reset_counts). A test runner uses these to
+      # summarize what was logged during the run.
+      attr_reader :error_count, :warning_count
       attr_reader :logger
 
       # ---------------------------------------------------------------------
@@ -37,6 +47,8 @@ module Gloo
       def initialize( engine, quiet = true )
         @engine = engine
         @quiet = quiet
+        @console_errors = true
+        reset_counts
         @debug = engine.settings.debug
         @theme = engine.theme
 
@@ -159,9 +171,10 @@ module Gloo
       # Also write to the console unless quiet.
       #
       def warn( msg )
+        @warning_count += 1
         @logger.warn msg
         @error.warn msg
-        puts @theme.warn( msg ) unless @quiet
+        puts @theme.warn( msg ) if errors_to_console?
       end
 
       #
@@ -170,20 +183,48 @@ module Gloo
       # Also write to the console (on stderr) unless quiet.
       #
       def error( msg, ex = nil, engine = nil )
+        @error_count += 1
         engine&.heap&.error&.set_to( msg ) if engine
         @logger.error msg
         @error.error msg
         if ex
           @error.error ex.message
           @error.error ex.backtrace
-          $stderr.puts @theme.error( msg ) unless @quiet
-          $stderr.puts @theme.error( ex.message ) unless @quiet
-          $stderr.puts ex.backtrace unless @quiet
-        else
-          $stderr.puts @theme.error( msg ) unless @quiet
+          if errors_to_console?
+            $stderr.puts @theme.error( msg )
+            $stderr.puts @theme.error( ex.message )
+            $stderr.puts ex.backtrace
+          end
+        elsif errors_to_console?
+          $stderr.puts @theme.error( msg )
         end
       end
 
+      #
+      # Write a backtrace for an error that was (or is about to be)
+      # logged. It's part of that error, so it isn't counted again.
+      #
+      def backtrace( text )
+        @logger.error text
+        @error.error text
+        $stderr.puts @theme.error( text ) if errors_to_console?
+      end
+
+      #
+      # Start counting errors and warnings from zero.
+      #
+      def reset_counts
+        @error_count = 0
+        @warning_count = 0
+      end
+
+      #
+      # Should errors and warnings also be written to the console?
+      #
+      def errors_to_console?
+        return !@quiet && @console_errors
+      end
+
     end
   end
 end