gloo 7.0.3 → 7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8c6f18a171f22ad2efb9354555f867568cc64baa563a09cad5909d3074eb55c
-  data.tar.gz: 69d44646d15c1054ea6693ae2ad8cd9a10513ce258ca83703a5af0120da9ed97
+  metadata.gz: 211368f27a7bbea86aed449d545c28f05a62857e92e8a3942394261a336e597b
+  data.tar.gz: 98ea31342225ac55d1ae499727fe2e71bf1679a8c4f1523651e57ac50829a714
 SHA512:
-  metadata.gz: 0b8c7c819ae9660f35bf1e8f1a6c93be762d8c94d1aef8a05828d0d57fa40d6415e567d9e9ef0bbf630e14cda7c6546616ed8a0c99e5d6b9d0a05daf6d1ddf29
-  data.tar.gz: 59f620d96fe5c1cf35b3e461c5dcd690bffd069b94da9e742927b8e40d934bbcfc9dc4b23c9a1d7018d67b67f3c7212cb39244c80d95c618b4bb1f8037e9e9ef
+  metadata.gz: c2457159e21684fbdb72367753c52204de25393f74ee715622ad9879a6b228477f580440e516fee5c0d47ea6c198f8568bd109912abb2cbb01704e1e84d94d79
+  data.tar.gz: 0ba0bd0264f57f0334312c897a07b3023bd2019e835c8ec88e6e9bd827aa6af80c4a7610c1f1198958bb8948da8e2ed4981c56b725b371086df2e8950661ab07

data/README.md

@@ -47,7 +47,8 @@ Read in order for a guided tour of the language, top to bottom, or jump straight
 8. [Operators](docs/operators.md) — math and comparison operators
 9. [Iterators](docs/iterators.md) — each, repeat
 10. [Plugins](docs/plugins.md) — core libraries and user extensions
-11. [A Trivial Web App](docs/web_app.md) — a two-page "Hello World" built with the `gloo-web` core library
+11. [Testing](docs/testing.md) — writing and running gloo tests with `gloo-test`
+12. [A Trivial Web App](docs/web_app.md) — a two-page "Hello World" built with the `gloo-web` core library
 
 Working on gloo itself? See [Development](docs/development.md) — source layout, running the tests, and conventions.
 

data/docs/application.md

@@ -17,6 +17,7 @@ Gloo keeps its configuration, projects, and logs under a per-user home directory
 - `gloo.gloo_config` — the configuration directory (see Configuration, below)
 - `gloo.gloo_projects` — the projects directory (same as `gloo.app` when an app is running)
 - `gloo.gloo_log` — the logging directory (see Logging, below)
+- `gloo.gloo_tmp` — a folder for temporary files, such as scratch files a script or test writes and then deletes. It's `tmp` under the gloo home directory unless `tmp_path` in `gloo.yml` says otherwise (see Configuration, below), and it's created if it isn't there. Use it instead of `/tmp`, which doesn't exist on Windows.
 
 ```
 > show gloo.gloo_home
@@ -70,6 +71,11 @@ When specifying a file there are a couple ways to reference the gloo file to ope
              - Run the script in the file parameter and then quit.
              - If a file is provided as a parameter this option does not need to be specified.
 --test       - Run in Test mode
+             - Runs the *.test.gloo files in the folders and files given
+               (the current folder if none), using the gloo-test library.
+             - Exits with status 1 if any test failed, or errors or warnings
+               were logged that no test expected; 0 otherwise.
+             - See Testing.
 --version    - Show application version
 --help       - Show the help screen
 ```
@@ -90,6 +96,12 @@ gloo:
   #
   project_path: /Users/my_user/gloo/projects
 
+  #
+  # Folder for temporary files, such as scratch files written by
+  # tests. Scripts get it with $.gloo_tmp.
+  #
+  tmp_path: /Users/my_user/gloo/tmp
+
   #
   # Run this script when starting up gloo.
   # (Only if a script file is not specified.)
@@ -148,7 +160,7 @@ 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`.
+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 summary at the end of a test run says how many errors and warnings were logged, and by which tests, leaving out those a test expects (`expect_errors`). See Testing.
 
 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.
 
@@ -199,4 +211,4 @@ help> quit
 
 ### Narrative Docs in the Shell
 
-This page and its ten siblings (`docs/*.md` in the interpreter's source) are the same files shown by `help> doc {name}` — there's no separate doc server or web mode. A `gloo --doc` local web server was considered and put off in favor of this: one system, no separate build/serve step.
+This page and the others in `docs/` (in the interpreter's source) are the same files shown by `help> doc {name}` — there's no separate doc server or web mode. A `gloo --doc` local web server was considered and put off in favor of this: one system, no separate build/serve step.

data/docs/development.md

@@ -54,7 +54,7 @@ Integration tests written in gloo itself, using the `[test]` object from the `gl
 gem install gloo-test gloo-yaml gloo-md
 ```
 
-Each `*.test.gloo` file holds `[test]` objects whose `on_test` script uses `assert` and `refute`:
+Each `*.test.gloo` file holds `[test]` objects whose `on_test` script uses `assert` and `refute`. How to write them (assertions, shuffled order, `expect_errors`, `expect_fail`, scratch files and fixtures) is in Testing; this section covers only what's particular to the interpreter's own suite. A test looks like this:
 
 ```gloo
 tests [can] :

data/docs/language_objects.md

@@ -4,6 +4,8 @@
 
 - Object Naming
 - Nested Container Shorthand
+- Documenting an Object
+- Where an Object Came From
 - Keywords
 - Literals
 - Value Conversion
@@ -106,10 +108,45 @@ floating comment in the file instead. When a name is declared in more
 than one loaded file, the first non-empty doc wins (same rule as the
 first value).
 
+A doc belongs to its object: when the object is moved, extracted, or
+deleted, its doc comment goes with it (see Verbs, Load & Save).
+
 `list` can show every documented object in a listed tree: turn on the
 `list_docs` setting (off by default) — see `list` and `settings` in the
 in-app help.
 
+## Where an Object Came From
+
+Every object can say which file it was loaded from: `check {obj} for
+source_file` puts the file's full path in `it`, and `check {obj} for
+source_dir` puts that file's folder (with no trailing slash). This lets a
+script reach files stored next to it without a hard-coded path. For
+example, a test can load a fixture that sits beside its own file:
+
+```gloo
+tests.my_area [can] :
+  where [string] :
+  fixture [string] : /fixtures/sample.gloo
+
+  loads_its_fixture [test] :
+    on_test [script] :
+      check ^^ for source_dir
+      put it into ^^.where
+      load ( ^^.where ^^.fixture )
+```
+
+The answer comes from the nearest object, going up from the one asked,
+that a loaded file declares. So a nested object answers with its file,
+even when its root container (like `tests` above) is declared in many
+files. An object created at run time inside a loaded one answers with
+that one's file. When several files declare the same object (a namespace
+container), the first file loaded answers.
+
+An object that didn't come from a file (created at run time, or
+unloaded) answers blank (`''`); that isn't an error. On a `[file]`
+object, `source_file` is the `.gloo` file that declared it, not the path
+it holds.
+
 ## Keywords
 
 Gloo doesn't reserve words the way many languages do. A verb keyword like `put` or an object type name like `string` can also be used as an object name — there's no parser conflict, because verbs are only looked up as the first word of a statement, and object type names are only looked up where a type is expected (inside the `[ ]` on a declaration). Everywhere else, the word is just a pathname segment (see Object Naming, above).

data/docs/language_syntax.md

@@ -3,6 +3,7 @@
 **Contents**
 
 - Color
+- Computed Arguments
 - Errors
 - Events
 - Function Calls
@@ -43,6 +44,28 @@ colors [can] :
 
 See also: Show.
 
+## Computed Arguments
+
+Some verbs take literal text rather than an object or an expression: a file name, a path, a name. Each of these can instead be an expression in parentheses. Gloo works out the expression and uses its value as the text:
+
+```
+load ( $.gloo_tmp '/scratch.gloo' )
+load lib ( lib_name )
+save my_obj to ( $.gloo_tmp '/my_obj' )
+context ( 'app.' section )
+exists? object ( type_name )
+```
+
+This works for `load` (a file, `ext` or `lib`), `save … to`, `context` and `exists?`. Anything not in parentheses is still taken literally, so `load common/app/*` still loads those files. A computed file name goes through the same lookup as a literal one, so wildcards, the `.gloo` extension and project-relative names work the same way.
+
+The `+` is optional when joining text, so `( $.gloo_tmp '/scratch.gloo' )` and `( $.gloo_tmp + '/scratch.gloo' )` are the same. A `[file]` or `[string]` object holding a path works too: `load ( my.file_obj )`.
+
+If the expression can't be worked out (for example, an object it names doesn't exist), that's reported as an error and the verb doesn't run.
+
+For anything else, `run ~>` works out a whole command and runs it: `run ~> 'load ' $.gloo_tmp '/x.gloo'`. Prefer the parentheses where they're available; a command built this way breaks if a path has spaces in it.
+
+See also: Load, Save, Context, Exists.
+
 ## 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.
@@ -254,6 +277,7 @@ gloo.gloo_home        # Get the gloo home directory
 gloo.gloo_config      # Get the gloo configuration directory
 gloo.gloo_projects    # Get the gloo projects directory
 gloo.gloo_log         # Get the gloo logging directory
+gloo.gloo_tmp         # Get the gloo tmp directory, for temporary files
 
 SCREEN
 gloo.screen_lines     # Get the number of lines on screen.
@@ -308,6 +332,7 @@ See also: Pathname.
 
 - **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 message that puts its result into a destination you name** puts its status in `it`: `true` when it worked, `false` when it didn't. With no destination, the result itself goes in `it`. So `tell f to read ( text )` puts the file's contents in `text` and `true` in `it`, while `tell f to read` puts the contents in `it`. The same goes for json `parse ( dst )` and string `split_list ( delim dst )`.
 - **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.
 

data/docs/objects.md

@@ -4,7 +4,7 @@ Everything in gloo is an object. Strings, numbers, containers, scripts, function
 
 Gloo ships with a large set of built-in object types, and core libraries and extensions can add more. This page doesn't try to cover them all — it walks through three common ones to get a feel for how objects work. For the complete list of object types, and every message each one supports, use the in-app help: enter `help` (or `?`), then `objects` to list them all, or `object {name}` for detail on one (see Application, Help).
 
-An object's **type declares which messages it can receive** — `up` and `trim` for a `string`, `inc` for an `integer`, `run` for a `script`. An object doesn't have to have a type: with none it is `untyped` (short `any`), declared with a bare colon (`slot :`), with `[any]`, or by `create` with no `as`. An untyped object still takes the messages every object understands (`blank?`, `contains?`, `responds_to?`, `doc`, `reload`, `unload`) — just not the type-specific ones. Of those, `blank?` asks about the object's simple value only, and `contains?` asks whether it has children: a container with children but no value of its own is blank, and contains. Untyped is the right choice when you only need to hold, compare, or show a value: a generic result slot, a config value passed straight through, or a field whose kind of value changes over its life.
+An object's **type declares which messages it can receive** — `up` and `trim` for a `string`, `inc` for an `integer`, `run` for a `script`. An object doesn't have to have a type: with none it is `untyped` (short `any`), declared with a bare colon (`slot :`), with `[any]`, or by `create` with no `as`. An untyped object still takes the messages every object understands (`blank?`, `contains?`, `responds_to?`, `doc`, `source_dir`, `source_file`, `reload`, `unload`) — just not the type-specific ones. Of those, `blank?` asks about the object's simple value only, and `contains?` asks whether it has children: a container with children but no value of its own is blank, and contains. Untyped is the right choice when you only need to hold, compare, or show a value: a generic result slot, a config value passed straight through, or a field whose kind of value changes over its life.
 
 **Contents**
 

data/docs/plugins.md

@@ -29,6 +29,12 @@ settings [can] :
 
 The loader runs these top-of-file `load lib` / `load ext` lines before it builds the object tree, so declarations below them can use the library's types. Only `load lib` and `load ext` are recognized this way, and only above the first object — a `load lib` in a script still runs when that script runs, as before.
 
+When working on a core library, `load lib` loads the installed gem, not the copy you're editing, so its tests quietly test the installed version. To test the edited source, run from the library's folder with `RUBYLIB` pointing at its `lib/`:
+
+```
+RUBYLIB="$(pwd)/lib" gloo --test test/
+```
+
 ### Available Core Libraries
 
 - **CLI** — Use the `gloo-cli` gem when building CLI applications.
@@ -60,7 +66,7 @@ The loader runs these top-of-file `load lib` / `load ext` lines before it builds
     > load lib md
     help> object markdown
     ```
-- **Test** — Use the `gloo-test` gem to manually include. See Test Runner for notes about the gloo test runner.
+- **Test** — Use the `gloo-test` gem to write and run gloo tests. `gloo --test` loads it for you; see Testing for how to write and run tests.
     - Library Objects: Test
     - Library Verbs: Assert, Refute
     - See also: Eval, It
@@ -348,7 +354,7 @@ class Stats < Gloo::Core::Obj
 end
 ```
 
-`self.messages` should call `super` and append to it — the base `Gloo::Core::Obj` already contributes messages every object receives (`reload`, `unload`, `blank?`, `contains?`, `responds_to?`).
+`self.messages` should call `super` and append to it — the base `Gloo::Core::Obj` already contributes messages every object receives (`save`, `reload`, `unload`, `blank?`, `contains?`, `responds_to?`, `doc`, `source_dir`, `source_file`).
 
 Used from gloo, once loaded:
 
@@ -374,7 +380,7 @@ Add `self.doc_data` to every verb/object class (see the `beep` and `stats` examp
 
 ### Testing an extension
 
-Add a Ruby unit test per verb/object class under `test/` (the same conventions as the interpreter's own tests, see Development, Tests — inherit from the project's `GlooTest`/`BaseEngineTest` base), and add a `*.test.gloo` integration test that loads the extension and exercises it end to end, e.g. `extensions/beep/test/beep.test.gloo`:
+Add a Ruby unit test per verb/object class under `test/` (the same conventions as the interpreter's own tests, see Development, Tests — inherit from the project's `GlooTest`/`BaseEngineTest` base), and add a `*.test.gloo` integration test that loads the extension and exercises it end to end (see Testing for how to write and run gloo tests), e.g. `extensions/beep/test/beep.test.gloo`:
 
 ```gloo
 tests [can] :

data/docs/testing.md

@@ -0,0 +1,206 @@
+# Testing
+
+How to write and run tests for gloo code: an app, an extension or a core library. Tests are written in gloo itself, in `*.test.gloo` files, using the `[test]` object and the `assert` and `refute` verbs from the `gloo-test` core library. This page is about those gloo tests. Ruby unit tests for an extension's Ruby code are covered in Plugins, Testing an Extension; for the interpreter's own tests, see Development, Tests.
+
+**Contents**
+
+- Running Tests
+- Writing a Test
+- Assertions
+- Test Order and Setup
+- Errors and Warnings
+- Tests Meant to Fail
+- Files in Tests
+
+## Running Tests
+
+Install the `gloo-test` gem, then run gloo in test mode with the tests to run:
+
+```
+gem install gloo-test
+gloo --test path/to/tests/
+```
+
+`--test` loads the `gloo-test` library itself, so a test file doesn't need `load lib test`. Give any mix of folders and single files. In a folder, every `*.test.gloo` file is run, including those in subfolders. With no path, gloo looks in the current folder.
+
+While the tests run, gloo shows a `.` for each test that passes and an `x` for each one that fails. Then it lists the failures, each with the test's path, its description and the message of the assertion that failed, and ends with a summary:
+
+```
+x.....
+
+*** Failures (1) ***
+
+tests.math.wrong_on_purpose -> A failing test, to see the output.
+   expected 2 + 2 to be 5
+
+Tests: 6 • Passed: 5 •  Failed: 1
+  Assertions: 6 • Files: 2
+Tests finished in 0.01 seconds
+```
+
+In test mode, errors and warnings go to the log files, not the console, so the output is just the test results (see Application, Logging). The summary says when any were logged; see Errors and Warnings, below.
+
+When the run is over, gloo exits with status 0 if it passed, and 1 if any test failed or the summary reports errors or warnings that no test expected. A missing test file or folder counts too. So a script or CI job can tell a good run from a bad one:
+
+```
+gloo --test test/ && echo "all good"
+```
+
+## Writing a Test
+
+A test file holds one root container with `[test]` objects inside it. By convention, the root is `tests`, and each file adds its own area under it with nested container shorthand (see Language, Objects), so many test files can share the `tests` root:
+
+```gloo
+tests.math [can] :
+
+  total [int] : 0
+
+  adds_up [test] :
+    description [string] : Adding two numbers.
+    on_test [script] :
+      eval 2 + 2
+      put it into ^^.total
+      eval ^^.total = 4
+      assert "expected 2 + 2 to be 4"
+```
+
+A `[test]` has two children:
+
+- `description` — what the test checks. It's shown with the test's path when the test fails.
+- `on_test` — the script that does the work and makes the assertions.
+
+Inside `on_test`, `^` is the test and `^^` is the container that holds it, so `^^.total` is the `total` object beside the test. Objects a test works with usually sit in the container, next to the tests.
+
+## Assertions
+
+`assert` and `refute` look at `it`. `assert` passes if `it` is true; `refute` passes if `it` is false. Each takes an optional message, which is shown if it fails, so write it as what was expected:
+
+```gloo
+check ^^.name for blank?
+refute "expected the name to be set"
+
+eval ^^.count > 0
+assert "expected at least one item"
+```
+
+`expect` is another name for `assert`, and `expect_not` for `refute`.
+
+So a test usually puts the thing it's checking into `it` first: with `eval` for a comparison, `check` for a question (`blank?`, `contains?`, `exists?`), or a message or verb that sets `it` (see Language, Syntax, It). A test can have any number of assertions, and it fails if any one of them fails.
+
+## Test Order and Setup
+
+Tests run in a random order: the files are shuffled, and so are the tests within each file. A test mustn't depend on another test having run first. Each one sets up what it needs and cleans up after itself.
+
+Between files, the heap is emptied: objects a file loads are gone before the next file runs. Within a file, the tests share the file's objects, so a test that uses one should set it at the start rather than rely on its declared value. For example, `put false into ^^.err_fired` before the step that should set it.
+
+Setup that's the same for every test in a file, and that no test changes, can go in an `on_load` script in the file's container. It runs when the file loads, before any of its tests:
+
+```gloo
+tests.files [can] :
+
+  scratch [file] :
+
+  # Runs when this file loads, before any test.
+  on_load [script] :
+    put $.gloo_tmp '/my_scratch.gloo' into ^.scratch
+```
+
+## Errors and Warnings
+
+The run keeps track of the errors and warnings logged by each test. If any were logged, the summary gets an extra line naming the tests that logged them:
+
+```
+Tests: 4 • Passed: 4 •  Failed: 0
+  Assertions: 4 • Files: 1
+  1 error logged during the run; see ~/gloo/logs/error.log
+    tests.files.missing_file_is_an_error (1 error)
+Tests finished in 0.0 seconds
+```
+
+Problems logged while a test file loads, outside any test, are counted too, as `(outside tests: …)`. A clean run has no such line. Treat one as a problem even when every test passed: something went wrong that no assertion caught.
+
+A test that triggers an error or a warning on purpose (to check an `on_error` handler, or that bad input is reported) sets `expect_errors` to true. What it logs is then left out of the summary:
+
+```gloo
+tests.files [can] :
+
+  err_fired [bool] : false
+
+  on_error [script] :
+    put true into ^.err_fired
+
+  missing_file_is_an_error [test] :
+    description [string] : Loading a file that isn't there fires on_error.
+    expect_errors [bool] : true
+    on_test [script] :
+      put false into ^^.err_fired
+      load no_such_file_xyz
+      eval ^^.err_fired = true
+      assert "expected on_error to fire"
+```
+
+## Tests Meant to Fail
+
+A test that's meant to fail, such as one that shows an assertion really does fail when it should, sets `expect_fail` to true. It then passes if at least one of its assertions fails, and fails if none does:
+
+```gloo
+  false_fails_an_assert [test] :
+    description [string] : assert fails when it is false.
+    expect_fail [bool] : true
+    on_test [script] :
+      eval 1 = 2
+      assert "this one is meant to fail"
+```
+
+`expect_fail` can't tell which assertion failed, or why, so a test can fail for the wrong reason and still pass. Keep a test like this to the one thing it checks. That's good practice for every test, but it matters most here.
+
+## Files in Tests
+
+**Scratch files.** A test that needs a file it writes and then deletes should put it in the gloo tmp folder, `$.gloo_tmp`, rather than `/tmp`, which doesn't exist on Windows (see Application, The Gloo Home Directory). Set the path once in `on_load`, as in Test Order and Setup, above. To load the file, put the path in parentheses so it's worked out rather than taken literally (see Language, Syntax, Computed Arguments). Unload what was loaded and delete the file at the end of the test:
+
+```gloo
+      tell ^^.scratch to write ( ^^.source )
+      load ( ^^.scratch )
+      # ... assertions ...
+      tell demo to unload
+      tell ^^.scratch to delete
+```
+
+**Fixtures.** A file the tests read but never change can be kept next to the test file, for example in a `fixtures` folder. Name it something other than `*.test.gloo`, so it isn't run as a test. `check ^^ for source_dir` gives the folder of the test file (see Language, Objects, Where an Object Came From):
+
+```gloo
+tests.files [can] :
+
+  where [string] :
+  fixture [string] : /fixtures/sample.gloo
+
+  loads_its_fixture [test] :
+    description [string] : A fixture next to this file can be loaded.
+    on_test [script] :
+      check ^^ for source_dir
+      put it into ^^.where
+      load ( ^^.where ^^.fixture )
+      eval sample.name = 'from the fixture'
+      assert "expected the fixture to load"
+      tell sample to unload
+```
+
+**Broken source on purpose.** To test how gloo handles a mistake in a file, such as a missing `]` or a declaration with no name, don't put the mistake in the test file itself. It would be reported while the file loads, outside any test. Instead, keep the broken source in a `[text]` object, write it to a scratch file inside the test, and load it there. The problem then belongs to that test, which sets `expect_errors`:
+
+```gloo
+  broken_src [text] : BEGIN
+broken_demo [can] :
+  count [int : 3
+END
+
+  broken_source_still_loads [test] :
+    description [string] : A type missing its ] is still read as that type.
+    expect_errors [bool] : true
+    on_test [script] :
+      tell ^^.scratch to write ( ^^.broken_src )
+      load ( ^^.scratch )
+      eval broken_demo.count = 3
+      assert "expected the value 3"
+      tell broken_demo to unload
+      tell ^^.scratch to delete
+```

data/docs/verbs.md

@@ -58,6 +58,13 @@ tell {path.to.object} to {message}
 > show it
 ```
 
+`source_dir` and `source_file` are two more: they put the folder, or the full path, of the file the object was loaded from in `it` — blank if it didn't come from a file (see Language, Objects — Where an Object Came From).
+
+```gloo
+> check my.obj for source_dir
+> show it
+```
+
 ## Put
 
 `put` evaluates an expression and stores the result in an object.
@@ -99,6 +106,12 @@ If the name can't be resolved to a file, `load` reports `File '{name}' was not f
 
 A save is a **rewrite, not a regeneration**: comments, blank lines, and the original spacing are kept, and only the values you actually changed are re-written. A declaration you never touched comes back byte-for-byte.
 
+What counts as a change is narrow: an object is changed when its value is set, or when it is created, moved (`move`, or extracted with `save … to`), or deleted (for example with `unload`); everything else is untouched and comes back exactly as written, wherever it lives. Adding, moving, or removing an object's children doesn't change the object itself: its own declaration stays as it was, and only the children's lines appear, move, or disappear.
+
+An object's doc comment goes wherever the object goes: it moves with a moved or extracted object and disappears with a deleted one.
+
+A save never loses or alters data: loading the saved files again gives back the same objects, with the same values and docs, under the same parents. The interpreter decides how a changed or new declaration is laid out; only what it says has to come back the same.
+
 `save {obj} to {path}` doesn't just write a copy — `obj` stops being declared in its old file, wherever that was. Given `app.core.settings` declared inside `app.gloo`, `save app.core.settings to config/settings` leaves `app.gloo` without a `settings` subtree and writes `config/settings.gloo` with `app.core.settings [can] : ...` at the top level (the `app`/`core` prefix is implied via nested-container shorthand, not repeated as nested declarations) plus everything `settings` owns underneath, comments included. An object with no file of its own yet (brand new, or nested under an object that's never been saved) is simply written fresh — nothing to move.
 
 If `obj`'s own subtree already has declarations spread across more than one file (the namespace-merge pattern below, applied *inside* the subtree being extracted, not just above it), extraction refuses rather than guessing which file's slice is authoritative — save each contributing file on its own first.

data/lib/VERSION

@@ -1 +1 @@
-7.0.3
+7.1

data/lib/VERSION_NOTES

@@ -1,3 +1,17 @@
+7.1 - 2026.10.23
+ - Loading an empty gloo file is now allowed and only gives a warning.
+ - Adds configuration setting for tmp directory.
+ - load (file, lib, ext), save … to, context and exists? accept ( expression ) in place of a literal name or path. For example, load ( $.gloo_tmp '/x.gloo' ).
+ - save … to with a blank path reports the missing-path error.
+ - Updates for more consistent results in `it`.
+ - Get source file path and name for object.
+ - Adds doc for gloo tests.
+
+
+7.0.4 - 2026.10.19
+ - Documentation update.
+
+
 7.0.3 - 2026.10.15
  - Removes test dependency on gloo-beep.
 
@@ -165,7 +179,7 @@
 
 
 5.1.0 - 2026.02.15
- - Fixes issue with int * dec 
+ - Fixes issue with int * dec
  - Some code cleanup
 
 
@@ -392,4 +406,3 @@ adds tag helper for apple touch icon
 
 2.0 - 2023.05.22
  - Version 2 merges gloo-lang back into a single gloo gem.
-

data/lib/gloo/app/engine.rb

@@ -154,21 +154,31 @@ module Gloo
         @args.files.each { |f| @persist_man.load( f ) }
       end
 
-      # 
+      #
       # Run in gloo unit test mode.
+      # Then quit, with exit status 1 if the run failed (see run_tests),
+      # so a calling script or CI job can tell.
       #
       def run_test
         @log.debug 'Running in Test mode…'
-
-        begin
-          @lib_manager.load_lib TEST_LIB_NAME
-          TestRunner.new( self, @args.files ).run
-        rescue StandardError, ScriptError => ex
-          handle_exception ex
-        end
-
+        passed = run_tests
         @log.debug 'Tests complete.'
         quit
+        exit( 1 ) unless passed
+      end
+
+      #
+      # Load gloo-test and run the tests given on the command line.
+      # True unless the run reports that it failed, or something went
+      # wrong running it. An older gloo-test whose run doesn't report
+      # counts as passed, as it always has.
+      #
+      def run_tests
+        @lib_manager.load_lib TEST_LIB_NAME
+        return TestRunner.new( self, @args.files ).run != false
+      rescue StandardError, ScriptError => ex
+        handle_exception ex
+        return false
       end
 
       #

data/lib/gloo/app/settings.rb

@@ -5,6 +5,7 @@
 #
 
 require 'yaml'
+require 'fileutils'
 
 module Gloo
   module App
@@ -137,9 +138,6 @@ module Gloo
         @ext_path = File.join( @user_root, 'extensions' )
         Dir.mkdir( @ext_path ) unless File.exist?( @ext_path )
 
-        @tmp_path = File.join( @user_root, 'tmp' )
-        Dir.mkdir( @tmp_path ) unless File.exist?( @tmp_path )
-
         @debug_path = File.join( @user_root, 'debug' )
         Dir.mkdir( @debug_path ) unless File.exist?( @debug_path )
       end
@@ -156,6 +154,8 @@ module Gloo
           @project_path = File.join( @user_root, 'projects' )
         end
 
+        init_tmp_path( settings[ 'gloo' ][ 'tmp_path' ] )
+
         @start_with = settings[ 'gloo' ][ 'start_with' ]
         @list_indent = settings[ 'gloo' ][ 'list_indent' ]
         @list_levels = settings[ 'gloo' ][ 'list_levels' ]
@@ -167,6 +167,16 @@ module Gloo
         @theme = DEFAULT_THEME unless THEMES.include?( @theme )
       end
 
+      #
+      # Set the tmp folder: the tmp_path setting if there is one (a
+      # leading ~ is expanded), or tmp under the user root. Created
+      # if it isn't there yet.
+      #
+      def init_tmp_path( path )
+        @tmp_path = path.blank? ? File.join( @user_root, 'tmp' ) : File.expand_path( path.to_s )
+        FileUtils.mkdir_p( @tmp_path ) unless File.exist?( @tmp_path )
+      end
+
       #
       # Get the app's required directories.
       #
@@ -188,6 +198,7 @@ module Gloo
       #
       def get_default_settings
         projects = File.join( @user_root, 'projects' )
+        tmp = File.join( @user_root, 'tmp' )
         str = <<~TEXT
           #
           # Gloo configuration
@@ -200,6 +211,12 @@ module Gloo
             #
             project_path: #{projects}
 
+            #
+            # Folder for temporary files, such as scratch files written by
+            # tests. Scripts get it with $.gloo_tmp.
+            #
+            tmp_path: #{tmp}
+
             #
             # Run this script when starting up gloo.
             # (Only if a script file is not specified.)

data/lib/gloo/core/gloo_system.rb

@@ -179,6 +179,11 @@ module Gloo
         return @engine.settings.project_path
       end
 
+      # Get the Gloo tmp directory
+      def msg_gloo_tmp
+        return @engine.settings.tmp_path
+      end
+
       # The running app directory.
       def msg_app
         return @engine.settings.project_path
@@ -314,6 +319,8 @@ module Gloo
             'gloo_config — Get the gloo configuration directory.',
             'gloo_projects — Get the gloo projects directory.',
             'gloo_log — Get the gloo logging directory.',
+            'gloo_tmp — Get the gloo tmp directory, for temporary files ' \
+              '(the tmp_path setting in gloo.yml).',
             'screen_lines — Get the number of lines on screen.',
             'screen_cols — Get the number of columns on screen.',
             'platform_cpu — Get the platform CPU.',