gloo 7.2 → 7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. checksums.yaml +4 -4
  2. data/docs/application.md +19 -3
  3. data/docs/iterators.md +66 -1
  4. data/docs/language_objects.md +14 -7
  5. data/docs/language_scripting.md +17 -0
  6. data/docs/language_syntax.md +86 -3
  7. data/docs/objects.md +6 -6
  8. data/docs/operators.md +36 -2
  9. data/docs/plugins.md +26 -0
  10. data/docs/testing.md +31 -2
  11. data/docs/verbs.md +8 -0
  12. data/lib/VERSION +1 -1
  13. data/lib/VERSION_NOTES +15 -0
  14. data/lib/gloo/app/engine.rb +133 -17
  15. data/lib/gloo/app/prompt.rb +8 -0
  16. data/lib/gloo/convert/string_to_decimal.rb +3 -6
  17. data/lib/gloo/convert/string_to_integer.rb +3 -2
  18. data/lib/gloo/core/dictionary.rb +23 -12
  19. data/lib/gloo/core/obj.rb +77 -0
  20. data/lib/gloo/core/op.rb +99 -0
  21. data/lib/gloo/core/parser.rb +15 -0
  22. data/lib/gloo/core/tokens.rb +18 -0
  23. data/lib/gloo/core/verb.rb +130 -1
  24. data/lib/gloo/exec/dispatch.rb +7 -3
  25. data/lib/gloo/exec/runaway_recursion.rb +34 -0
  26. data/lib/gloo/exec/runner.rb +46 -0
  27. data/lib/gloo/exec/script.rb +16 -2
  28. data/lib/gloo/expr/expression.rb +77 -6
  29. data/lib/gloo/expr/l_decimal.rb +18 -2
  30. data/lib/gloo/expr/l_integer.rb +5 -2
  31. data/lib/gloo/expr/op_div.rb +4 -0
  32. data/lib/gloo/expr/op_eq.rb +4 -0
  33. data/lib/gloo/expr/op_gt.rb +4 -0
  34. data/lib/gloo/expr/op_gteq.rb +4 -0
  35. data/lib/gloo/expr/op_ineq.rb +4 -0
  36. data/lib/gloo/expr/op_lt.rb +4 -0
  37. data/lib/gloo/expr/op_lteq.rb +4 -0
  38. data/lib/gloo/expr/op_minus.rb +4 -0
  39. data/lib/gloo/expr/op_mult.rb +3 -7
  40. data/lib/gloo/expr/op_plus.rb +8 -1
  41. data/lib/gloo/objs/basic/alias.rb +6 -1
  42. data/lib/gloo/objs/basic/boolean.rb +15 -6
  43. data/lib/gloo/objs/basic/decimal.rb +25 -3
  44. data/lib/gloo/objs/basic/script.rb +3 -1
  45. data/lib/gloo/objs/basic/string_msgs.rb +50 -68
  46. data/lib/gloo/objs/ctrl/until.rb +219 -0
  47. data/lib/gloo/plugin/callback.rb +54 -10
  48. data/lib/gloo/plugin/ext_manager.rb +44 -0
  49. data/lib/gloo/plugin/lib_manager.rb +65 -1
  50. data/lib/gloo/shell/runner.rb +36 -9
  51. data/lib/gloo/verbs/break.rb +6 -4
  52. data/lib/gloo/verbs/check.rb +8 -2
  53. data/lib/gloo/verbs/create.rb +13 -4
  54. data/lib/gloo/verbs/if.rb +33 -10
  55. data/lib/gloo/verbs/invoke.rb +6 -1
  56. data/lib/gloo/verbs/list.rb +9 -2
  57. data/lib/gloo/verbs/load.rb +4 -1
  58. data/lib/gloo/verbs/move.rb +8 -2
  59. data/lib/gloo/verbs/put.rb +9 -2
  60. data/lib/gloo/verbs/reload.rb +2 -1
  61. data/lib/gloo/verbs/run.rb +8 -1
  62. data/lib/gloo/verbs/save.rb +4 -0
  63. data/lib/gloo/verbs/tell.rb +9 -2
  64. data/lib/gloo/verbs/unless.rb +34 -10
  65. data/lib/gloo/verbs/unload.rb +81 -16
  66. data/test.gloo/ctrl/until.test.gloo +100 -0
  67. data/test.gloo/lang/computed_paths.test.gloo +98 -0
  68. data/test.gloo/lang/literal.test.gloo +43 -0
  69. data/test.gloo/lang/ops.test.gloo +193 -0
  70. data/test.gloo/lang/runaway_recursion.test.gloo +44 -0
  71. data/test.gloo/objs/decimal.test.gloo +23 -0
  72. data/test.gloo/objs/string.test.gloo +30 -0
  73. data/test.gloo/verbs/create.test.gloo +6 -21
  74. data/test.gloo/verbs/if.test.gloo +41 -0
  75. data/test.gloo/verbs/load.test.gloo +4 -3
  76. data/test.gloo/verbs/unless.test.gloo +40 -0
  77. data/test.gloo/verbs/unload.test.gloo +61 -3
  78. metadata +6 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b5cc04330edd79c2663408d7afbedc9195dbd994c31ce0a7cd6a591ce9276c56
4
- data.tar.gz: d4f004bccdc1dbae382b2d3106154557b90e6b236447b04c8c5b5fcf05ebeffc
3
+ metadata.gz: 0fc8d097c99cd0b45404f5248f8618a62e52b052a14d971a9bfb9ef62b84cb54
4
+ data.tar.gz: 749ba266d911f205b1049a4d99e6132362cc0d5ccca6b3ce306f3eacc626dc4f
5
5
  SHA512:
6
- metadata.gz: 8a0ecc8a6e085ce93a55ec93de2a629c3fa023cfd4982fd0cc1005cc954c737ae81c4dd2d2299924623692546360df79a15b856d138201671a5c1181cccfb7c0
7
- data.tar.gz: 603536ee8defb9805546bd785b51afcea41809e67a76118a0d750ea8862e5929c5aca2e68cadd22c4488c12f52618864f1727bc2feb2e6f8e504e95035c63b19
6
+ metadata.gz: ac22bbda45bc8417c1b4228880f7f995e9f5d62759c9d4299aaccdd6eef4f8a003d9d1c258a2721ad16563e61c9aca88e4047d88369dfa4e35c2413fc8e86a3e
7
+ data.tar.gz: 2e9a802711e8e30b076bf70cd554e3097b817fd0153fc520004961cbfa942143ec276a5d3798db968f9b19471b6662c1b08f33e8b66df588f2f74c3a3d19dc7a
data/docs/application.md CHANGED
@@ -6,6 +6,7 @@
6
6
  - Running Gloo
7
7
  - Modes
8
8
  - Script Mode and App Mode
9
+ - Stopping with Ctrl-C
9
10
  - Configuration
10
11
  - Logging
11
12
  - Help
@@ -36,7 +37,7 @@ Gloo can also be started from another Ruby program; see Development, Running Glo
36
37
 
37
38
  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.
38
39
 
39
- The exit status covers the whole run, not just its last line: gloo exits with status 1 if any error, or any Ruby exception, happened at any point while the files were loading or running, and 0 otherwise. An error still counts when an `on_error` or `on_exception` handler ran for it, because a handler reports the problem, it doesn't undo it. Warnings don't count. This applies when gloo runs files (Script mode); App and CLI modes don't set an exit status, and Test mode has its own (see the `--test` option below).
40
+ The exit status covers the whole run, not just its last line: gloo exits with status 1 if any error, or any Ruby exception, happened at any point while the files were loading or running, and 0 otherwise. An error still counts when an `on_error` or `on_exception` handler ran for it, because a handler reports the problem, it doesn't undo it. Warnings don't count. This applies when gloo runs files (Script mode); App and CLI modes don't set an exit status, and Test mode has its own (see the `--test` option below). In any mode, a run that Ctrl-C stopped exits with 130 (see Stopping with Ctrl-C).
40
41
 
41
42
  When specifying a file there are a couple ways to reference the gloo file to open:
42
43
 
@@ -80,6 +81,8 @@ When specifying a file there are a couple ways to reference the gloo file to ope
80
81
  (the current folder if none), using the gloo-test library.
81
82
  - Exits with status 1 if any test failed, or errors or warnings
82
83
  were logged that no test expected; 0 otherwise.
84
+ - Each test file runs with only the libraries and extensions it
85
+ loads itself.
83
86
  - See Testing.
84
87
  --embed - Run in Embedded mode
85
88
  - Start the engine and return, for a Ruby program that drives
@@ -132,6 +135,19 @@ Files named on the command line are found differently: as given (from the workin
132
135
 
133
136
  A new file saved with a relative name (`save notes to lists/notes`, or `save notes` for a top-level object that has no file yet) goes in the first place a load would look: the app folder in App mode, otherwise next to the saving script's file, or the working folder for a command typed at the prompt. A script that didn't come from a file saves into the projects folder. So a script that saves `lists/notes` can load it back with `load lists/notes`.
134
137
 
138
+ ## Stopping with Ctrl-C
139
+
140
+ Ctrl-C stops whatever is running and gives you a clean prompt. It isn't a way to leave gloo — `quit` is.
141
+
142
+ - **A script** (`gloo file.gloo`, at a terminal): Ctrl-C stops the run and leaves you at the gloo prompt, with everything that was loaded and done so far still there to look at. `quit` then leaves.
143
+ - **At a prompt** — gloo's own, a web app's (the same prompt), a gloo-cli shell's or a menu's: Ctrl-C during a command stops it and gives you that same prompt back. At an empty prompt it says how to leave, for example `Use 'quit' to stop running gloo.`; with something typed, the line is dropped.
144
+ - **With no one at a terminal** (gloo run by cron or launchd, or with its input piped in) and in Test mode: Ctrl-C stops the run, runs `on_quit`, and exits.
145
+ - **While gloo is quitting** (`on_quit`, or a web app's `on_stop`): Ctrl-C stops the rest of the quitting, and gloo exits at once, with a warning, `Quit cut short by Ctrl-C: {where}.`
146
+
147
+ Ctrl-C isn't an error: it doesn't run `on_error`, and `it` keeps whatever the last finished line put there. But it's never silent: when it stops something, gloo says where, `Stopped by Ctrl-C: app.sync.do, line 2.`, and logs it as a warning, since the work it stopped may be half done. What already ran stays done.
148
+
149
+ After Ctrl-C has stopped something, gloo exits with status 130 when it ends (the usual status for a program stopped by Ctrl-C), so a shell script that ran it can tell.
150
+
135
151
  ## Configuration
136
152
 
137
153
  When gloo runs, it looks for a configuration file which it expects to find in `~/gloo/config/`. If there is no `gloo.yml` file in that directory, one will be created and default values added.
@@ -237,8 +253,8 @@ help
237
253
 
238
254
  From the `help>` prompt, look up verbs, object types, settings, the color theme, extensions, libraries, and narrative doc pages, or get detailed help for a specific verb, object, doc page, loaded library, or loaded extension:
239
255
 
240
- - `verbs` — list all verbs
241
- - `objects` — list all object types
256
+ - `verbs` — list all verbs, including those of the libraries and extensions loaded now
257
+ - `objects` — list all object types, including those of the libraries and extensions loaded now
242
258
  - `settings` — show application settings
243
259
  - `theme` — show the current color theme, how to change it, and a preview of both palettes
244
260
  - `extensions` — list loaded extensions (only loaded extensions are shown; use `load ext {name}` first)
data/docs/iterators.md CHANGED
@@ -9,6 +9,7 @@
9
9
  - Each Line
10
10
  - Each Word
11
11
  - Repeat
12
+ - Until
12
13
  - Skipping an Item or Ending a Loop
13
14
 
14
15
  ## Each
@@ -330,9 +331,73 @@ repeat [can] :
330
331
 
331
332
  See also: Object Base.
332
333
 
334
+ ## Until
335
+
336
+ Run a script again and again until a condition is true. Use `repeat` when you know how many times; use `until` when you know when to stop.
337
+
338
+ Each pass runs `do`, then `done`. The loop ends when `done`'s result — whatever is in `it` when it finishes — is true. `done` is checked after each pass, so `do` always runs at least once.
339
+
340
+ Children:
341
+
342
+ - `do` (script)
343
+ - The action to perform on each pass.
344
+ - `done` (script)
345
+ - Required. Run after each pass; the loop ends when its result is true. True and false follow the same rule as `if` (see Language Syntax, What Counts as True).
346
+ - `index` (integer)
347
+ - Optional. The current pass, counting from `0`.
348
+ - `max` (integer)
349
+ - Optional. The most passes to run. Without it (or with `0`) there is no limit.
350
+
351
+ Messages:
352
+
353
+ - `run` — Run the loop until `done` is true.
354
+
355
+ `done` is usually one line — a question or an `eval`, whose answer lands in `it`:
356
+
357
+ ```gloo
358
+ count [can] :
359
+ x [int] : 0
360
+ up [until] :
361
+ do [script] : tell count.x to inc
362
+ done [script] : eval count.x > 100
363
+ on_load [script] :
364
+ tell count.up to run
365
+ show count.x
366
+ ```
367
+
368
+ This shows `101`.
369
+
370
+ With no `max`, a loop whose `done` never comes true runs until it's stopped — an `until` doesn't call itself, so it can't run out of room the way a script that runs itself can. Give it a `max` when you know a sensible limit: reaching it is an error (`Could not finish until loop count.up: done wasn't true after 1000 passes.`), and `it` is `false`.
371
+
372
+ ```gloo
373
+ pick [can] :
374
+ tries [int] : 0
375
+ found [bool] : false
376
+ try [until] :
377
+ max [int] : 5
378
+ index [int] :
379
+ do [script] :
380
+ tell pick.tries to inc
381
+ if pick.tries = 3 then put true into pick.found
382
+ done [script] : eval pick.found
383
+ on_load [script] :
384
+ tell pick.try to run
385
+ show 'found on pass ' pick.try.index
386
+ ```
387
+
388
+ This shows `found on pass 2`.
389
+
390
+ Errors:
391
+
392
+ - No `done` script, or a blank one: `Could not run until loop {path}: it has no done script.` Nothing runs.
393
+ - An error in `done` ends the loop: whether it's done can't be known, so it stops rather than repeat the error. `it` is `false`.
394
+ - An error in `do` doesn't end the loop; the next pass may work.
395
+
396
+ See also: Object Base, Repeat, If.
397
+
333
398
  ## Skipping an Item or Ending a Loop
334
399
 
335
- `break` ends the script it's written in. In a loop's `do` script, that skips the rest of this pass, and the loop goes on with the next item. This works for `repeat` and every kind of `each`:
400
+ `break` ends the script it's written in. In a loop's `do` script, that skips the rest of this pass, and the loop goes on with the next item. This works for `repeat`, `until` and every kind of `each`:
336
401
 
337
402
  ```gloo
338
403
  skip [can] :
@@ -161,7 +161,7 @@ That said, gloo's own vocabulary — words that already mean something built-in
161
161
  - Verb keywords, and their shortcuts (see Verbs) — `put`, `show`, `run`, `tell`, and the rest.
162
162
  - Object type names, and their shortcuts (see Objects) — `string`, `container`, `integer`, and the rest.
163
163
 
164
- Both lists grow as core libraries and extensions load — `load lib {name}` and `load ext {name}` can add new verbs and object types at runtime, so the full set isn't fixed. Use the in-app help (see Application, Help) for the live list of whatever's currently loaded: enter `help` (or `?`), then `verbs` or `objects`.
164
+ Both lists change as core libraries and extensions load and unload — `load lib {name}` and `load ext {name}` can add new verbs and object types at runtime, and `unload lib {name}` and `unload ext {name}` take them away again (see Plugins, Loading and Unloading), so the full set isn't fixed. Use the in-app help (see Application, Help) for the live list of whatever's currently loaded: enter `help` (or `?`), then `verbs` or `objects`.
165
165
 
166
166
  See also: Verbs, Objects.
167
167
 
@@ -180,7 +180,11 @@ The following rules apply to literal values:
180
180
  `"say \"hi\""` is the string `say "hi"`.
181
181
  - Numbers
182
182
  - Integer and decimal numbers need no delimiters.
183
+ - An integer is digits with an optional sign: `42`, `-7`, `+5`. Leading zeros are fine — `007` is `7`, never octal.
184
+ - A decimal has a fraction or an exponent: `3.12`, `2.50`, `.5`, `-.5`, `1.0e3`, `2e-5`, `0.0000001`.
183
185
  - To refer to a decimal with no fractional value, include `.0` to indicate a decimal value.
186
+ - Not numbers: `5.` (it reads as the start of a path, like `'list.'`), `1,000`, `1_000`, `0x1A`. A bare word that isn't a number is an object's name.
187
+ - A typed value follows the same rule: `put '2.50' into d` or `d [decimal] : 2.50` is `2.5`; text that isn't written as a number is a best guess, with a warning (see Value Conversion).
184
188
  - Booleans
185
189
  - Can be `TRUE` or `FALSE`
186
190
  - Note that the text is case insensitive.
@@ -228,22 +232,25 @@ See also: Put, Show, String, Boolean, Integer, Decimal, Value Conversion.
228
232
 
229
233
  ## Value Conversion
230
234
 
231
- When putting an object or literal value into another object, gloo will attempt to convert the value to the target type.
235
+ When putting an object or literal value into another object, gloo will attempt to convert the value to the target type. (How text and numbers mix inside an expression, such as `5 + '5'` or `'5' < 10`, is up to the operator; see Operators.)
232
236
 
233
237
  Here are some of the value conversions that gloo will attempt:
234
238
 
235
239
  - string to integer
236
- - additional text is discarded
237
- - `put '1 one' into x` => 1
240
+ - text that isn't a whole number is a best guess, with a warning: the number it starts with, or 0
241
+ - `put '1 one' into x` => 1, with the warning `'1 one' is not an integer; using 1.`
242
+ - `put 'abc' into x` => 0, with the warning `'abc' is not an integer; using 0.`
243
+ - blank text is 0, without a warning
238
244
  - integer to string
239
245
  - simple to-string conversion
240
246
  - string to decimal
241
- - additional text is discarded
242
- - `put '3.25 and more…' into x` => 3.25
247
+ - text that isn't a number is a best guess, with a warning: the number it starts with, or 0.0
248
+ - `put '3.25 and more…' into x` => 3.25, with the warning `'3.25 and more…' is not a decimal number; using 3.25.`
249
+ - blank text is 0.0, without a warning
243
250
  - decimal to string
244
251
  - simple to-string conversion
245
252
  - decimal to integer
246
- - drops everything after the decimal point
253
+ - drops everything after the decimal point (no warning: this is the conversion, not a guess)
247
254
  - `put 1.23 into x` => 1
248
255
  - integer to decimal
249
256
  - decimal with integer value
@@ -31,6 +31,23 @@ hello [can] :
31
31
  on_load [script] : show 'hello world'
32
32
  ```
33
33
 
34
+ ### One-Line Scripts
35
+
36
+ A script with a single command can be written on one line, after the `:`, like the `on_load` above. Its lines go on the lines below when there are more than one:
37
+
38
+ ```gloo
39
+ total [can] :
40
+ x [int] : 150
41
+ big [bool] :
42
+ over_100 [script] : eval ^.x > 100
43
+ on_load [script] :
44
+ run ^.over_100
45
+ put it into ^.big
46
+ show ^.big
47
+ ```
48
+
49
+ This shows `true`. Running a script doesn't set `it` itself, but its commands do, so a script whose last command works out a value leaves that value in `it` — the one-line `over_100` is a question you can run. This is how an `until` loop's `done` script gives its answer (see Iterators, Until).
50
+
34
51
  ## Comments
35
52
 
36
53
  A line whose first non-blank character is `#` is a comment. Whole-line comments
@@ -12,6 +12,7 @@
12
12
  - It
13
13
  - Operators
14
14
  - Pathname
15
+ - What Counts as True
15
16
 
16
17
  ## Color
17
18
 
@@ -56,12 +57,58 @@ context ( 'app.' section )
56
57
  exists? object ( type_name )
57
58
  ```
58
59
 
59
- 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.
60
+ This works for `load` (a file, `ext` or `lib`), `unload` (`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.
60
61
 
61
62
  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 )`.
62
63
 
63
64
  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.
64
65
 
66
+ ### Computed Object Paths
67
+
68
+ Where a verb expects an object path, a parenthesized expression works the same way: gloo works it out, and its value is used as the path, exactly as if it had been typed there.
69
+
70
+ ```gloo
71
+ create ( 'quotes.' ^.i ) as string
72
+ put ^.file into ( 'quotes.' ^.i )
73
+ tell ( target ) to run
74
+ move ( src ) to ( dst )
75
+ ```
76
+
77
+ This works for `tell` and `check` (the object), `put … into`, `create` (the name), `move` (both the object and the new parent), `list`, `run`, `invoke` (the function) and `save` (the object).
78
+
79
+ Without parentheses you get the object; with them, the path its value holds. If `target` is a string holding `app.jobs.nightly`, `tell target to run` sends `run` to the string itself, while `tell ( target ) to run` runs `app.jobs.nightly`. Think of `( target )` as an inline alias: for one line, it does what an alias holding `target`'s value would, and nothing is stored.
80
+
81
+ - The fixed part of a path is text, so quote it: `( 'quotes.' ^.i )`. Without the quotes, `( quotes. ^.i )` would read `quotes.` as an object.
82
+ - A built path can be relative, and it's resolved the same way as when typed: `( '^.quotes.' ^.i )` starts from the running script's parent, `( '@.' name )` from the context.
83
+ - A value that isn't text is turned into text first, so `( i )` with `i` = 3 means the object named `3`.
84
+ - A computed path that names nothing is handled exactly as the same typed path would be: `create` creates it, `put` and `tell` report it isn't there, and the message names the worked-out path (`Object 'quotes.3' was not found.`), not the expression.
85
+ - A path that works out to blank is an error, `Object path '( p )' is blank.`, and the verb doesn't run.
86
+
87
+ Where a verb expects a value rather than a path, a group in parentheses is worked out first, as in `show 2 * ( 3 + 4 )` (see Operators, Grouping); one line can use both: `put 2 * ( 3 + 4 ) into ( 'list.' n )`. Parentheses anywhere else keep their meaning. In `tell ( s ) to starts_with? ( 'he' )` the first group is the object and the second is the message's parameters. A group after `create`'s `:` is the value, not the name. `invoke( f )` with no space is an inline function call (see Function Calls); `invoke ( f )`, with a space, is a computed path. `redirect` doesn't take a computed path: a group after it is its `(hard)` option.
88
+
89
+ #### Computed Paths and Aliases
90
+
91
+ An alias is a pointer you keep: declared once, saved with the file, used from many places. A computed path is a one-off, built and used on one line. Before computed paths, building a path at runtime meant pointing an alias at it first:
92
+
93
+ ```gloo
94
+ put 'quotes.' ^.i into ^.slot*
95
+ create ^.slot* as string
96
+ put ^.file into ^.slot
97
+ ```
98
+
99
+ That still works; `create ( 'quotes.' ^.i ) as string` and `put ^.file into ( 'quotes.' ^.i )` do the same without the alias.
100
+
101
+ Putting an alias inside the parentheses is new, and it adds a step. Working out an alias follows it to its target and gives the target's value, and that value is then used as the path. With `ln` pointing at `a.s`, and `a.s` holding the text `other.place`:
102
+
103
+ | Written | Goes into |
104
+ |---|---|
105
+ | `put x into ln` | `a.s` — the alias forwards to its target |
106
+ | `put x into ( ln )` | `other.place` — the target's value, used as a path: a second hop |
107
+ | `put x into ( ln* )` | `a.s` — the alias's own value, the path it holds; the same as `put x into ln` |
108
+ | `put x into ln*` | the alias itself, which now points somewhere else |
109
+
110
+ So `( ln )` is only what you want when the alias's target holds a path. To mean "where the alias points", leave the parentheses off, or use `( ln* )`.
111
+
65
112
  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.
66
113
 
67
114
  See also: Load, Save, Context, Exists.
@@ -70,16 +117,19 @@ See also: Load, Save, Context, Exists.
70
117
 
71
118
  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.
72
119
 
73
- - **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 +`).
120
+ - **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, empty parentheses, or an operator missing a value (`show 1 +`).
74
121
  - **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).
75
122
  - **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.
76
123
  - **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`.
77
124
 
125
+ Stopping a run with Ctrl-C isn't an error either: nothing went wrong, someone chose to stop. It's logged as a warning that says where it stopped, and it doesn't run `on_error` (see Application, Stopping with Ctrl-C).
126
+
78
127
  Errors and warnings 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.`), even when a script started the load; otherwise the script and its line (`app.on_load, line 3: Object 'app.nme' was not found.`). On the console both go to stderr, apart from a script's own output. "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.`
79
128
 
80
129
  What happens after an error:
81
130
 
82
131
  - 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`).
132
+ - One error is different: runaway recursion. A script that runs itself with no end — directly, through other scripts, or a function that invokes itself — runs scripts inside each other until there's no room left. Gloo stops it with `Could not run app.again: scripts ran 730 deep, one inside another (runaway recursion?).`, located at the deepest script. Rather than abandon only the deepest line (and let every level above carry on), it unwinds the run back to the line that started the recursion — the line that ran the first script that went on to run again — and reports it once. No line after an inner `run` runs, at any level on the way back up. The starting line is abandoned like any failed line, and its script carries on with its next line.
83
133
  - 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.
84
134
  - The error runs any `on_error` handler (see Events below).
85
135
 
@@ -371,7 +421,7 @@ example [can] :
371
421
  show it
372
422
  ```
373
423
 
374
- See also: Pathname.
424
+ See also: Pathname, What Counts as True.
375
425
 
376
426
  ## Operators
377
427
 
@@ -421,3 +471,36 @@ on_load [script] : show a.b.c
421
471
  ```
422
472
 
423
473
  See also: Context, Object Naming.
474
+
475
+ ## What Counts as True
476
+
477
+ A condition — the value after `if` or `unless`, or the result of an `until` loop's `done` script — is true or false by one rule, the same one a `[bool]` uses when a value is put into it:
478
+
479
+ | Value | Counts as |
480
+ |---|---|
481
+ | `true` | true |
482
+ | `false` | false |
483
+ | a number other than `0` (`5`, `-1`, `2.5`) | true |
484
+ | `0` | false |
485
+ | the text `true` or `t` (any case) | true |
486
+ | the text `false` or `f` (any case) | false |
487
+ | blank, or no value | false |
488
+ | any other text | false, with a warning |
489
+
490
+ Any other text is almost always a mistake — a value used as if it were a question — so it's false, and gloo warns: `'abc' is not true or false; using false.` To ask whether something has a value, ask it: `check name for blank?`, then `unless it then …`.
491
+
492
+ `unless` is the exact opposite of `if`: `unless x do …` runs exactly when `if x then …` wouldn't. A condition that can't be worked out (it names an object that doesn't exist, say) is an error, and the line is abandoned: neither the command nor `else` runs.
493
+
494
+ ```gloo
495
+ truth [can] :
496
+ name [string] :
497
+ on_load [script] :
498
+ if ^.name then show 'has a name' else show 'no name'
499
+ put 'Ann' into ^.name
500
+ check ^.name for blank?
501
+ unless it then show 'has a name now'
502
+ ```
503
+
504
+ This shows `no name`, then `has a name now`.
505
+
506
+ See also: It, If, Unless, Until, Boolean.
data/docs/objects.md CHANGED
@@ -79,14 +79,13 @@ The `random_` messages pick with replacement, so two calls can give the same chi
79
79
 
80
80
  ### Building a numbered list
81
81
 
82
- 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:
82
+ To add children one at a time — say, while walking a folder — work out the next numbered path, create the object there, and put its value in:
83
83
 
84
84
  ```gloo
85
85
  names [can] :
86
86
  words [string] : red green blue
87
87
  list [can] :
88
88
  next [int] : 0
89
- slot [alias] :
90
89
 
91
90
  add_each [each] :
92
91
  word [string] :
@@ -94,16 +93,17 @@ names [can] :
94
93
  do [script] :
95
94
  tell names.list to count
96
95
  put it + 1 into names.next
97
- put 'names.list.' + names.next into names.slot*
98
- create names.slot* as string
99
- put ^.word into names.slot
96
+ create ( 'names.list.' names.next ) as string
97
+ put ^.word into ( 'names.list.' names.next )
100
98
 
101
99
  on_load [script] :
102
100
  tell names.add_each to run
103
101
  tell names.list to show_key_value_table
104
102
  ```
105
103
 
106
- 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.
104
+ The children are named `1`, `2`, `3`, the same way `split_list` names them, so `child_value_at ( 0 )` is the child named `1`. `( 'names.list.' names.next )` is a computed path: gloo works out the expression and uses its value as the path (see Language, Syntax, Computed Arguments). The fixed part is quoted because it's text.
105
+
106
+ Older code does the same through an alias: `put 'names.list.' + names.next into names.slot*` points the alias at the path (the `*` refers to the alias itself rather than what it points to), then `create names.slot* as string` and `put ^.word into names.slot`. That still works.
107
107
 
108
108
  ## Integer
109
109
 
data/docs/operators.md CHANGED
@@ -5,6 +5,7 @@ Gloo operators can be used to do basic math and to compare values.
5
5
  **Contents**
6
6
 
7
7
  - Math Operators
8
+ - Grouping
8
9
  - Joining Values
9
10
  - Comparison Operators
10
11
  - Example
@@ -20,12 +21,41 @@ These are the gloo math operators:
20
21
  / division
21
22
  ```
22
23
 
23
- 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`.
24
+ How to write numbers (`5`, `-5`, `2.50`, `.5`, `1.0e3`) is in Language, Objects, Literals.
25
+
26
+ Integers and decimal numbers mix as numbers. An integer with an integer gives an integer; a decimal on either side gives a decimal, so `1 + 2.5` is `3.5` and `3 * 1.5` is `4.5`.
27
+
28
+ Dividing an integer by an integer gives an integer, rounded down: `7 / 2` is `3`, and `-7 / 2` is `-4`. For the fraction, make either side a decimal: `7.0 / 2` is `3.5`. Dividing by zero is an error.
29
+
30
+ Integers can be as large as needed: `123456789012345678901234567890 * 10` is exact. Decimals are binary floating point, so a result can be a tiny bit off (`0.1 + 0.2` shows `0.30000000000000004`); use `round` or `format` on a decimal to show it to a fixed number of places. Very large and very small decimals show in exponent form (`2.0e+20`, `1.0e-07`), a whole-number decimal keeps its `.0` (`1.5 * 2` is `3.0`), and a negative zero shows as `-0.0`.
31
+
32
+ `-`, `*` and `/` use text as a number: `10 - '4'` is `6` and `'7.0' / 2` is `3.5`. Text that isn't a number is used as 0, with a warning (`'a' is not a number; using 0.`); blank text is 0 without one. `+` is different: with text it joins (see Joining Values).
33
+
34
+ An expression is worked out strictly left to right. There's no precedence, so `2 + 3 * 4` is `20` (`2 + 3` first, then `* 4`), not `14`. To work out one part first, put it in parentheses (see Grouping).
35
+
36
+ ## Grouping
37
+
38
+ A group in parentheses is worked out first, and its value is used in its place: `2 + ( 3 * 4 )` is `14`, and `( 1 + 2 ) * 3` is `9`. Groups nest to any depth, `2 * ( 3 * ( 1 + 1 ) )` is `12`, and the parentheses can touch what's inside them: `((1 + 2) * (3 + 4))` is `21`. Outside a group, everything is still worked out left to right.
39
+
40
+ ```
41
+ > show 2 * ( 3 + 4 )
42
+ > put ( price + tax ) * qty into total
43
+ > if ( a = b ) then show 'same'
44
+ > tell d to round ( 1 + 1 )
45
+ ```
46
+
47
+ A group works anywhere gloo expects a value: `eval`, `show`, `put`, the condition and commands of `if` and `unless`, and a message's parameters: a group is one parameter, so `tell s to sub ( ( 'a' + 'b' ) 'x' )` replaces `ab` with `x`. Where a verb expects an object path instead, parentheses build the path (see Language, Syntax, Computed Object Paths): `put 2 * ( 3 + 4 ) into ( 'list.' n )` uses both.
48
+
49
+ At the end of a line, a group that comes after a value is the verb's extra part, such as a message's parameters or `show`'s colour, as it always has been: `show 'done' (green)`. So `show a ( b + c )` shows `a` in the colour `b + c` works out to. To join a group onto a value, write the operator: `show a + ( b + c )`.
50
+
51
+ Parentheses inside quotes are text: `show 'a (b)'` shows `a (b)`. A parenthesis without its partner, or an empty `( )`, is a syntax error.
24
52
 
25
53
  ## Joining Values
26
54
 
27
55
  `+` 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.
28
56
 
57
+ `+` joins whenever there's text on either side, so a number and text join as text: if `count` is 3, `show count ' items'` shows `3 items`, and `5 + '5'` is `55`. To add text that holds a number, put it into an integer or decimal first.
58
+
29
59
  `and` is another way to write `+`. It reads better when building a string out of several pieces:
30
60
 
31
61
  ```
@@ -37,7 +67,11 @@ An expression is worked out strictly left to right. There's no precedence and no
37
67
 
38
68
  ## Comparison Operators
39
69
 
40
- Strings, integers, and decimal numbers can be compared.
70
+ Strings, integers, and decimal numbers can be compared. An integer and a decimal are compared as numbers, so `1 = 1.9` is false and `1 < 1.5` is true.
71
+
72
+ A number and text that holds a number are compared as numbers: `'5' < 10` and `3 = '3'` are both true. A number and other text are compared as text, so `3 = 'abc'` is false.
73
+
74
+ `<`, `>`, `<=` and `>=` put strings in dictionary order. Case is ignored first, and only when two strings have the same letters does a capital come first: `'apple' < 'Banana'` and `'Banana' < 'banana'` are both true. `=` and `!=` still tell capitals apart (`'x' = 'X'` is false), so for any two strings exactly one of `<`, `=` and `>` is true.
41
75
 
42
76
  These are the gloo comparison operators:
43
77
 
data/docs/plugins.md CHANGED
@@ -4,6 +4,7 @@
4
4
 
5
5
  - Core Libraries
6
6
  - User Extensions
7
+ - Loading and Unloading
7
8
 
8
9
  ## Core Libraries
9
10
 
@@ -396,3 +397,28 @@ tests [can] :
396
397
  assert "beep verb should exist"
397
398
  beep
398
399
  ```
400
+
401
+ ## Loading and Unloading
402
+
403
+ A core library or extension stays loaded until it's unloaded, or until gloo stops. Loading one that's already loaded does nothing (it's noted in the log at info level only), so it's safe for several files to `load lib` the same library.
404
+
405
+ `unload lib {name}` and `unload ext {name}` take a library's or extension's verbs and object types away again, and `load` brings them back:
406
+
407
+ ```gloo
408
+ > load lib md
409
+ > unload lib md
410
+ > exists? object markdown # false
411
+ > load lib md # markdown is back
412
+ ```
413
+
414
+ Unloading means gloo forgets the verbs and object types: they're gone from `help`, `exists?` says they aren't there, and a line using one of the verbs is an unknown verb. The library's Ruby code stays loaded, though (Ruby can't unload code it has required), so any settings or caches the library keeps of its own aren't reset by unloading and loading it again.
415
+
416
+ - While objects of the library's types are on the heap, it can't be unloaded: `unload` is an error naming them, and nothing is unloaded. Unload those objects first (for example `tell m to unload`).
417
+ - Unloading a library or extension that isn't loaded does nothing.
418
+ - The name can be worked out in parentheses, as with `load`: `unload lib ( name )`.
419
+ - gloo-test, which gloo loads itself to run tests, can't be unloaded while the tests run.
420
+
421
+ What the other resets keep:
422
+
423
+ - Plain `unload` (every file) and `reload` keep libraries and extensions loaded: in a script or at the prompt, loading a library is part of setting up the session, not part of a file.
424
+ - Between test files, every library and extension is unloaded, except gloo-test, so each test file runs with only what it loads itself (see Testing, Test Order and Setup).
data/docs/testing.md CHANGED
@@ -10,6 +10,7 @@ How to write and run tests for gloo code: an app, an extension or a core library
10
10
  - Test Order and Setup
11
11
  - Errors and Warnings
12
12
  - Tests Meant to Fail
13
+ - Skipping a Test
13
14
  - Files in Tests
14
15
 
15
16
  ## Running Tests
@@ -23,7 +24,7 @@ gloo --test path/to/tests/
23
24
 
24
25
  `--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.
25
26
 
26
- 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:
27
+ While the tests run, gloo shows a `.` for each test that passes and an `x` for each one that fails (and an `s` for each one that's skipped; see Skipping a Test). 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:
27
28
 
28
29
  ```
29
30
  x.....
@@ -91,7 +92,7 @@ So a test usually puts the thing it's checking into `it` first: with `eval` for
91
92
 
92
93
  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.
93
94
 
94
- 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.
95
+ Between files, the heap is emptied: objects a file loads are gone before the next file runs. So are the core libraries and extensions it loaded (all but gloo-test itself): each file starts with only what it loads, whatever order the files run in, so every test file has to `load lib` (or `load ext`) what it uses, at the top of the file. A file that only worked because another file happened to load a library first fails. Within a run the same library can be loaded by many files; it's loaded again for each one (see Plugins, Loading and Unloading). 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.
95
96
 
96
97
  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:
97
98
 
@@ -154,6 +155,34 @@ A test that's meant to fail, such as one that shows an assertion really does fai
154
155
 
155
156
  `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.
156
157
 
158
+ ## Skipping a Test
159
+
160
+ To set a test aside without deleting it or commenting it out, set `skip` to true. Its `on_test` isn't run. Say why in a comment on the line above:
161
+
162
+ ```gloo
163
+ # Flaky until unload lib exists.
164
+ load_lib_registers_type [test] :
165
+ description [string] : load lib registers that library's object types.
166
+ skip [bool] : true
167
+ on_test [script] :
168
+ ...
169
+ ```
170
+
171
+ A skipped test shows as `s` while the tests run, and counts as neither passed nor failed, so a run with skipped tests and no failures still passes. So that a skipped test isn't forgotten, every run lists it, with its path and description, and the summary counts it:
172
+
173
+ ```
174
+ s.....
175
+
176
+ *** Skipped (1) ***
177
+
178
+ tests.verbs.load.load_lib_registers_type -> load lib registers that library's object types.
179
+
180
+ Tests: 6 • Passed: 5 • Failed: 0 • Skipped: 1
181
+ Assertions: 5 • Files: 2
182
+ ```
183
+
184
+ Put the reason on its own line, not after the `true`. Everything after the `:` is the value, so `skip [bool] : true # flaky` isn't true: the test runs, and gloo warns that `'true # flaky'` is not true or false. To run the test again, delete the line, or set it to `false`.
185
+
157
186
  ## Files in Tests
158
187
 
159
188
  **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:
data/docs/verbs.md CHANGED
@@ -141,6 +141,14 @@ Several files can contribute to one container — declare `app [container] :` in
141
141
 
142
142
  An object can also save itself: `tell config to save`.
143
143
 
144
+ `load lib {name}` and `load ext {name}` load a core library or extension, adding its verbs and object types (see Plugins). `unload lib {name}` and `unload ext {name}` take them out again, until the next `load`; they can't while objects of the library's types are on the heap, and gloo-test can't be unloaded while it runs the tests. The name can be worked out in parentheses, as with `load`: `unload lib ( name )`.
145
+
146
+ ```gloo
147
+ > unload lib md
148
+ > exists? object markdown # false
149
+ > load lib md # back again
150
+ ```
151
+
144
152
  ---
145
153
 
146
154
  `run`, `tell`, `put`, and `load` / `save` cover a lot of ground, but there are more than two dozen other verbs — `show`, `if`, `create`, `each`, `check`, `reload`, `unload`, and so on — all documented in-app. Enter `help` (or `?`), then `verbs` to browse them. (This page itself is also viewable in-app: `help> doc verbs`.)
data/lib/VERSION CHANGED
@@ -1 +1 @@
1
- 7.2
1
+ 7.3
data/lib/VERSION_NOTES CHANGED
@@ -1,3 +1,18 @@
1
+ 7.3 - 2026.11.16
2
+ - Where a verb expects an object path, an expression in parentheses is worked out and its value used as the path.
3
+ - Adds the new `until` looping object.
4
+ - Adds error handling for runaway recursion.
5
+ - Ctrl-C stops whatever is running and gives you a clean prompt
6
+ - Expression Semantics
7
+ - Bug fix for decimal literals.
8
+ - An integer on the left no longer truncates a decimal.
9
+ - <, >, <= and >= compare text in dictionary order (before, they were always false).
10
+ - Text and numbers mix by a single rule: a number compares numerically with text that holds a number.
11
+ - Parentheses group part of an expression
12
+ - A message parameter can be a group
13
+ - Reset state for full test isolation (unload libraries and extensions)
14
+
15
+
1
16
  7.2 - 2026.11.04
2
17
  - Update for lossless load and save: fixes a number of bugs.
3
18
  - Allow spaces inside type brackets.