gloo 7.1.3 → 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 (109) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +23 -0
  3. data/docs/application.md +65 -4
  4. data/docs/development.md +10 -0
  5. data/docs/iterators.md +66 -1
  6. data/docs/language_objects.md +34 -22
  7. data/docs/language_scripting.md +23 -2
  8. data/docs/language_syntax.md +86 -3
  9. data/docs/objects.md +6 -6
  10. data/docs/operators.md +36 -2
  11. data/docs/plugins.md +26 -0
  12. data/docs/testing.md +35 -9
  13. data/docs/verbs.md +31 -3
  14. data/lib/VERSION +1 -1
  15. data/lib/VERSION_NOTES +23 -0
  16. data/lib/dependencies.rb +4 -1
  17. data/lib/gloo/app/engine.rb +151 -23
  18. data/lib/gloo/app/prompt.rb +8 -0
  19. data/lib/gloo/convert/string_to_decimal.rb +3 -6
  20. data/lib/gloo/convert/string_to_integer.rb +3 -2
  21. data/lib/gloo/core/dictionary.rb +23 -12
  22. data/lib/gloo/core/obj.rb +77 -23
  23. data/lib/gloo/core/op.rb +99 -0
  24. data/lib/gloo/core/parser.rb +15 -0
  25. data/lib/gloo/core/tokens.rb +18 -0
  26. data/lib/gloo/core/verb.rb +130 -1
  27. data/lib/gloo/exec/dispatch.rb +7 -3
  28. data/lib/gloo/exec/runaway_recursion.rb +34 -0
  29. data/lib/gloo/exec/runner.rb +46 -0
  30. data/lib/gloo/exec/script.rb +16 -2
  31. data/lib/gloo/expr/expression.rb +77 -6
  32. data/lib/gloo/expr/l_decimal.rb +18 -2
  33. data/lib/gloo/expr/l_integer.rb +5 -2
  34. data/lib/gloo/expr/op_div.rb +4 -0
  35. data/lib/gloo/expr/op_eq.rb +4 -0
  36. data/lib/gloo/expr/op_gt.rb +4 -0
  37. data/lib/gloo/expr/op_gteq.rb +4 -0
  38. data/lib/gloo/expr/op_ineq.rb +4 -0
  39. data/lib/gloo/expr/op_lt.rb +4 -0
  40. data/lib/gloo/expr/op_lteq.rb +4 -0
  41. data/lib/gloo/expr/op_minus.rb +4 -0
  42. data/lib/gloo/expr/op_mult.rb +3 -7
  43. data/lib/gloo/expr/op_plus.rb +8 -1
  44. data/lib/gloo/objs/basic/alias.rb +6 -1
  45. data/lib/gloo/objs/basic/boolean.rb +15 -6
  46. data/lib/gloo/objs/basic/decimal.rb +25 -3
  47. data/lib/gloo/objs/basic/script.rb +3 -24
  48. data/lib/gloo/objs/basic/string_msgs.rb +50 -68
  49. data/lib/gloo/objs/ctrl/until.rb +219 -0
  50. data/lib/gloo/persist/declaration_ledger.rb +9 -9
  51. data/lib/gloo/persist/declaration_writer.rb +208 -0
  52. data/lib/gloo/persist/disc_mech.rb +70 -39
  53. data/lib/gloo/persist/file_loader.rb +125 -66
  54. data/lib/gloo/persist/file_saver.rb +130 -198
  55. data/lib/gloo/persist/file_storage.rb +15 -4
  56. data/lib/gloo/persist/file_style.rb +89 -0
  57. data/lib/gloo/persist/line_splitter.rb +16 -1
  58. data/lib/gloo/persist/persist_man.rb +112 -30
  59. data/lib/gloo/persist/save_index.rb +211 -0
  60. data/lib/gloo/persist/script_body_collector.rb +16 -21
  61. data/lib/gloo/persist/source/blank_node.rb +10 -3
  62. data/lib/gloo/persist/source/comment_node.rb +10 -2
  63. data/lib/gloo/persist/source/directive_node.rb +10 -2
  64. data/lib/gloo/persist/source/obj_node.rb +174 -9
  65. data/lib/gloo/persist/source/source_doc.rb +54 -0
  66. data/lib/gloo/persist/subtree_extractor.rb +9 -37
  67. data/lib/gloo/persist/trivia_buffer.rb +7 -7
  68. data/lib/gloo/plugin/callback.rb +54 -10
  69. data/lib/gloo/plugin/ext_manager.rb +44 -0
  70. data/lib/gloo/plugin/lib_manager.rb +65 -1
  71. data/lib/gloo/shell/runner.rb +36 -9
  72. data/lib/gloo/verbs/break.rb +6 -4
  73. data/lib/gloo/verbs/check.rb +8 -2
  74. data/lib/gloo/verbs/create.rb +13 -4
  75. data/lib/gloo/verbs/if.rb +33 -10
  76. data/lib/gloo/verbs/invoke.rb +6 -1
  77. data/lib/gloo/verbs/list.rb +9 -2
  78. data/lib/gloo/verbs/load.rb +31 -22
  79. data/lib/gloo/verbs/move.rb +50 -5
  80. data/lib/gloo/verbs/put.rb +9 -2
  81. data/lib/gloo/verbs/reload.rb +2 -1
  82. data/lib/gloo/verbs/run.rb +8 -1
  83. data/lib/gloo/verbs/save.rb +30 -4
  84. data/lib/gloo/verbs/tell.rb +9 -2
  85. data/lib/gloo/verbs/unless.rb +34 -10
  86. data/lib/gloo/verbs/unload.rb +81 -16
  87. data/test.gloo/app/exit_status.test.gloo +34 -0
  88. data/test.gloo/app/fixtures/exit_after_error.gloo +9 -0
  89. data/test.gloo/ctrl/until.test.gloo +100 -0
  90. data/test.gloo/lang/computed_paths.test.gloo +98 -0
  91. data/test.gloo/lang/declaration.test.gloo +36 -0
  92. data/test.gloo/lang/fixtures/mixed_indent.gloo +5 -0
  93. data/test.gloo/lang/literal.test.gloo +43 -0
  94. data/test.gloo/lang/naming.test.gloo +44 -6
  95. data/test.gloo/lang/ops.test.gloo +193 -0
  96. data/test.gloo/lang/runaway_recursion.test.gloo +44 -0
  97. data/test.gloo/objs/decimal.test.gloo +23 -0
  98. data/test.gloo/objs/string.test.gloo +30 -0
  99. data/test.gloo/verbs/create.test.gloo +6 -21
  100. data/test.gloo/verbs/fixtures/load_beside.gloo +6 -0
  101. data/test.gloo/verbs/fixtures/lossless_text.gloo +7 -0
  102. data/test.gloo/verbs/fixtures/lossless_text_saved.gloo +9 -0
  103. data/test.gloo/verbs/if.test.gloo +41 -0
  104. data/test.gloo/verbs/load.test.gloo +22 -3
  105. data/test.gloo/verbs/move.test.gloo +39 -0
  106. data/test.gloo/verbs/save.test.gloo +239 -0
  107. data/test.gloo/verbs/unless.test.gloo +40 -0
  108. data/test.gloo/verbs/unload.test.gloo +61 -3
  109. metadata +15 -1
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:
@@ -166,25 +195,22 @@ A test that's meant to fail, such as one that shows an assertion really does fai
166
195
  tell ^^.scratch to delete
167
196
  ```
168
197
 
169
- **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):
198
+ **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. A relative `load` looks next to the test file first (see Application, Script Mode and App Mode), so the fixture loads by its plain name:
170
199
 
171
200
  ```gloo
172
201
  tests.files [can] :
173
202
 
174
- where [string] :
175
- fixture [string] : /fixtures/sample.gloo
176
-
177
203
  loads_its_fixture [test] :
178
204
  description [string] : A fixture next to this file can be loaded.
179
205
  on_test [script] :
180
- check ^^ for source_dir
181
- put it into ^^.where
182
- load ( ^^.where ^^.fixture )
206
+ load fixtures/sample
183
207
  eval sample.name = 'from the fixture'
184
208
  assert "expected the fixture to load"
185
209
  tell sample to unload
186
210
  ```
187
211
 
212
+ For anything else that needs the test file's folder, such as the path of a data file to read or a program to run, `check ^^ for source_dir` gives it (see Language, Objects, Where an Object Came From).
213
+
188
214
  **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`:
189
215
 
190
216
  ```gloo
data/docs/verbs.md CHANGED
@@ -86,10 +86,10 @@ If the destination doesn't exist, or the expression can't be worked out (eg. it
86
86
 
87
87
  ## Load & Save
88
88
 
89
- `load` reads a `.gloo` file into the heap and runs its `on_load` script. Give a path relative to the project folder, a full path, or one starting with `~` for your home folder; the `.gloo` extension is optional. `*` in place of a file name loads every `.gloo` file in a folder, wherever the folder is. Anything before the `*` is the start of the file names, so `my/app/a*` loads just the files whose names start with `a`.
89
+ `load` reads a `.gloo` file into the heap and runs its `on_load` script. Give a relative name, a full path, or one starting with `~` for your home folder; the `.gloo` extension is optional. A relative name is looked for next to the file the loading script came from, in the projects folder, and in the gloo home; in App mode the app folder comes first (see Application, Script Mode and App Mode, for the order in each mode). `*` in place of a file name loads every `.gloo` file in a folder, found the same way. Anything before the `*` is the start of the file names, so `my/app/a*` loads just the files whose names start with `a`.
90
90
 
91
91
  ```gloo
92
- > load my/project/config
92
+ > load parts/config
93
93
  > load my/app/*
94
94
  > load ~/.my_app/settings.gloo
95
95
  > load ~/.my_app/plugins/*
@@ -99,6 +99,8 @@ If the name can't be resolved to a file, `load` reports `File '{name}' was not f
99
99
 
100
100
  `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.
101
101
 
102
+ A new file — `save {obj} to {path}`, or `save {obj}` for a top-level object with no file yet (named after the object) — goes where a relative `load` would look first: in App mode the app folder; otherwise next to the file the saving script came from, or the working folder for a command typed at the prompt (see Application, Script Mode and App Mode). A script that didn't come from a file saves into the projects folder. A full path, or one starting with `~`, is used as given. An object that's already loaded always saves back to its own file.
103
+
102
104
  ```gloo
103
105
  > save # every open file
104
106
  > save config # just config's file
@@ -113,14 +115,40 @@ An object's doc comment goes wherever the object goes: it moves with a moved or
113
115
 
114
116
  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.
115
117
 
118
+ How a change is written:
119
+
120
+ - A changed declaration keeps its name, type and spacing as written (an untyped `plain : old` stays untyped); only its value is written again.
121
+ - A new object goes after the last child of its parent's first declaration, indented like its neighbours, with its type spelled the way the file spells it (`[int]` in a file of `[int]`s), so it looks like the rest of the file. A new child of a container that only exists through a dotted name (`page.core.users [can] :` makes `page` and `core`) is written as a dotted line too: `page.core.x [string] : v`.
122
+ - A moved object takes its first declaration and its doc comment with it, at its new depth. Moving it into another file's container saves that file too.
123
+ - An object deleted and then created again is a new object: it's written where new objects go, without the old doc comment.
124
+ - A new top-level object isn't added to an existing file, so a bare `save` leaves it out and warns, naming it (`Not saved (no file yet): notes. Use save notes.`). `save {obj}` writes it to a file of its own, which later saves include.
125
+ - A file that doesn't end with a line break still doesn't after a save.
126
+
127
+ An object can be declared on more than one line — the same name twice in one container, or in more than one file (see Language, Objects, Object Naming). It's one object: its first declaration holds its value, so a change rewrites only that line, and the later lines stay exactly as written. Deleting or moving the object takes all of its lines with it, in every file, so a reload doesn't bring it back.
128
+
129
+ A few things can't be written back exactly; save writes the closest thing and, for a value, warns `Could not save '{path}' exactly: {why}.`:
130
+
131
+ - A multi-line value is written as a `BEGIN` … `END` block, its lines exactly as they are (a block's lines are its value, so they're not indented to match). A block value always ends with a line break, so a value without one gains it; a line that is just `END` would end the block early; and bytes that aren't UTF-8 are written as they are.
132
+ - A value ending in `\` or `BEGIN` is written as a block, since on the line it would be read as a continuation or a block start.
133
+ - A changed script body is written from its commands, at its original indentation; the comments and blank lines inside it are lost. (An untouched one is kept exactly.)
134
+ - A declaration gloo had to guess at when loading — no name (`[int] : 3` loads as `unnamed_1`) or a missing `]` (`b [int : 3`) — is written as gloo understood it.
135
+
116
136
  `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.
117
137
 
118
138
  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.
119
139
 
120
- Several files can contribute to one container — declare `app [container] :` in each and add different children. They merge in the heap, and each file's save only rewrites its own declarations. If two files declare the *same* object with different values, the first one loaded wins and `load` logs a warning.
140
+ Several files can contribute to one container — declare `app [container] :` in each and add different children. They merge in the heap, and each file's save only rewrites its own declarations; a new child of `app` goes into the file with `app`'s first declaration (the first loaded). If two files declare the *same* object with different values, the first one loaded wins and `load` logs a warning — the same as two declarations in one file.
121
141
 
122
142
  An object can also save itself: `tell config to save`.
123
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
+
124
152
  ---
125
153
 
126
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.1.3
1
+ 7.3
data/lib/VERSION_NOTES CHANGED
@@ -1,3 +1,26 @@
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
+
16
+ 7.2 - 2026.11.04
17
+ - Update for lossless load and save: fixes a number of bugs.
18
+ - Allow spaces inside type brackets.
19
+ - Improves gloo startup time.
20
+ - A script run now exits 1 if an error or Ruby exception happened anywhere in the run.
21
+ - Improves how load and save verbs use relatives paths.
22
+
23
+
1
24
  7.1.3 - 2026.10.29
2
25
  - break in a loop's do skips to the next item again, as it did before 7.1.1.
3
26
  - New: break loop ends the whole loop. It's only valid directly in a loop's do script.
data/lib/dependencies.rb CHANGED
@@ -23,7 +23,10 @@ end
23
23
  #
24
24
  # Now that we have the first with some key dependencies
25
25
  # at the top, we'll require them.
26
+ # require_relative skips RubyGems' require hook, which
27
+ # would otherwise search the installed gems for each file
28
+ # (about 0.4 s of startup).
26
29
  #
27
30
  files.each do |ruby_file|
28
- require ruby_file
31
+ require_relative ruby_file
29
32
  end
@@ -17,7 +17,14 @@ module Gloo
17
17
  #
18
18
  TEST_LIB_NAME = 'test'
19
19
 
20
- attr_reader :settings, :log, :running_app
20
+ # Ctrl-C: what's shown, and the exit status after it (the shell
21
+ # convention for a run stopped by SIGINT).
22
+ INTERRUPTED_MSG = 'Stopped by Ctrl-C'.freeze
23
+ QUIT_CUT_SHORT_MSG = 'Quit cut short by Ctrl-C'.freeze
24
+ QUIT_HINT = "Use 'quit' to stop running gloo.".freeze
25
+ INTERRUPTED_EXIT = 130
26
+
27
+ attr_reader :settings, :log, :running_app, :run_error_count
21
28
  attr_reader :args, :mode, :running, :platform,
22
29
  :dictionary, :parser, :heap, :factory,
23
30
  :ext_manager, :lib_manager
@@ -43,6 +50,9 @@ module Gloo
43
50
 
44
51
  @handling_exception = false
45
52
  @handling_error = false
53
+ @run_error_count = 0
54
+ @interrupted = false
55
+ @interrupt_location = nil
46
56
  @log.debug 'engine intialized...'
47
57
  end
48
58
 
@@ -97,7 +107,21 @@ module Gloo
97
107
  @persist_man = Gloo::Persist::PersistMan.new( self )
98
108
  end
99
109
 
100
- #
110
+ #
111
+ # Reset the session as if in a new process: what reset_state does
112
+ # (stop the app, a new empty heap), and then unload every library
113
+ # and extension, except the pinned ones gloo loaded itself. The
114
+ # test runner uses it between test files. The heap is emptied
115
+ # first, so no object of a library's types is left to stop it.
116
+ # (Plain unload and restart use reset_state, keeping libraries.)
117
+ #
118
+ def reset_session
119
+ reset_state
120
+ @lib_manager.unload_unpinned
121
+ @ext_manager.unload_all
122
+ end
123
+
124
+ #
101
125
  # Restart the engine with the same settings
102
126
  # and the same mode (with files, etc).
103
127
  #
@@ -136,15 +160,17 @@ module Gloo
136
160
 
137
161
  #
138
162
  # Run files specified on the CLI.
139
- # Then quit, with a non-zero exit code if any file failed to
140
- # load (missing, unresolvable, or errored on load) so that a
141
- # calling shell script can tell a bad run from a good one.
163
+ # Then quit, with exit status 1 if anything went wrong at any
164
+ # point in the run (see run_failed?), so that a calling shell
165
+ # script can tell a bad run from a good one.
142
166
  #
143
167
  def run_files
144
- load_files
145
- failed = error?
168
+ # Ctrl-C stops the run; at a terminal, stay at the gloo prompt
169
+ # to look at what ran.
170
+ self.loop if !run_interruptible { load_files } && interactive?
146
171
  quit
147
- exit( 1 ) if failed
172
+ exit( INTERRUPTED_EXIT ) if interrupted?
173
+ exit( 1 ) if run_failed?
148
174
  end
149
175
 
150
176
  #
@@ -161,9 +187,11 @@ module Gloo
161
187
  #
162
188
  def run_test
163
189
  @log.debug 'Running in Test mode…'
164
- passed = run_tests
190
+ passed = false
191
+ run_interruptible { passed = run_tests }
165
192
  @log.debug 'Tests complete.'
166
193
  quit
194
+ exit( INTERRUPTED_EXIT ) if interrupted?
167
195
  exit( 1 ) unless passed
168
196
  end
169
197
 
@@ -174,7 +202,9 @@ module Gloo
174
202
  # counts as passed, as it always has.
175
203
  #
176
204
  def run_tests
177
- @lib_manager.load_lib TEST_LIB_NAME
205
+ # Pinned: the runner needs it for the whole run, so a test can't
206
+ # unload it, and a session reset between test files keeps it.
207
+ @lib_manager.load_lib TEST_LIB_NAME, pinned: true
178
208
  return TestRunner.new( self, @args.files ).run != false
179
209
  rescue StandardError, ScriptError => ex
180
210
  handle_exception ex
@@ -185,17 +215,21 @@ module Gloo
185
215
  # Run in interactive mode.
186
216
  #
187
217
  def run
188
- # Open default file(s)
189
- self.open_start_file
218
+ started = run_interruptible do
219
+ # Open default file(s)
220
+ self.open_start_file
190
221
 
191
- # Open any files specifed in args
192
- load_files
222
+ # Open any files specifed in args
223
+ load_files
224
+ end
193
225
 
194
226
  unless @mode == Mode::SCRIPT || @args.quiet? || @args.single_command?
195
- self.loop
227
+ # Stopped by Ctrl-C with no one at a terminal: don't wait for input.
228
+ self.loop if started || interactive?
196
229
  end
197
230
 
198
231
  quit
232
+ exit( INTERRUPTED_EXIT ) if interrupted?
199
233
  end
200
234
 
201
235
  #
@@ -239,8 +273,14 @@ module Gloo
239
273
  #
240
274
  def loop
241
275
  while @running
242
- @last_cmd = @platform.prompt.ask
243
- process_cmd
276
+ begin
277
+ @last_cmd = @platform.prompt.ask
278
+ rescue Interrupt
279
+ # Ctrl-C at the prompt: the line is dropped.
280
+ interrupted_at_prompt( @platform.prompt.line_typed )
281
+ next
282
+ end
283
+ run_interruptible { process_cmd }
244
284
  end
245
285
  end
246
286
 
@@ -273,18 +313,84 @@ module Gloo
273
313
  # Do any clean up and quit.
274
314
  #
275
315
  def quit
276
- if app_running?
277
- @log.debug 'stopping running app...'
278
- stop_running_app
316
+ begin
317
+ if app_running?
318
+ @log.debug 'stopping running app...'
319
+ stop_running_app
320
+ end
321
+
322
+ @log.debug 'triggering on_quit events...'
323
+ @event_manager.on_quit
324
+ rescue Interrupt
325
+ # Ctrl-C while quitting: stop quitting and leave now.
326
+ @log.warn interrupt_msg( QUIT_CUT_SHORT_MSG )
327
+ exit( INTERRUPTED_EXIT )
279
328
  end
280
329
 
281
- @log.debug 'triggering on_quit events...'
282
- @event_manager.on_quit
283
-
284
330
  @log.info 'Gloo engine is quitting...'
285
331
  end
286
332
 
287
333
 
334
+ # ---------------------------------------------------------------------
335
+ # Ctrl-C
336
+ # ---------------------------------------------------------------------
337
+
338
+ #
339
+ # Run the block; if Ctrl-C stops it, say so and carry on. Returns
340
+ # false if it was stopped.
341
+ #
342
+ def run_interruptible
343
+ yield
344
+ return true
345
+ rescue Interrupt
346
+ interrupted
347
+ return false
348
+ end
349
+
350
+ #
351
+ # Ctrl-C stopped something that was running. It isn't an error (no
352
+ # on_error, not a failed run), but it's never silent: a warning,
353
+ # with where it stopped. A later quit exits with 130.
354
+ #
355
+ def interrupted
356
+ @interrupted = true
357
+ @log.warn interrupt_msg( INTERRUPTED_MSG )
358
+ end
359
+
360
+ #
361
+ # Ctrl-C at a prompt with nothing running: the line is dropped. If
362
+ # nothing had been typed, say how to leave (the hint; nil for
363
+ # none). A core library's own prompt (a shell, a menu) passes its
364
+ # own hint.
365
+ #
366
+ def interrupted_at_prompt( line_typed, hint = QUIT_HINT )
367
+ @interrupt_location = nil
368
+ @log.show hint if hint && line_typed.to_s.empty?
369
+ end
370
+
371
+ #
372
+ # Note where Ctrl-C stopped the run, the first (deepest) time it's
373
+ # seen on its way up (see Runner).
374
+ #
375
+ def note_interrupt_location
376
+ @interrupt_location ||= @exec_env&.current_location
377
+ end
378
+
379
+ #
380
+ # Did Ctrl-C stop something during this run?
381
+ #
382
+ def interrupted?
383
+ return @interrupted
384
+ end
385
+
386
+ #
387
+ # Is someone at a terminal to type at a prompt?
388
+ #
389
+ def interactive?
390
+ return $stdin.tty?
391
+ end
392
+
393
+
288
394
  # ---------------------------------------------------------------------
289
395
  # Running app within gloo
290
396
  # ---------------------------------------------------------------------
@@ -337,6 +443,16 @@ module Gloo
337
443
  return !@heap.error.value.nil?
338
444
  end
339
445
 
446
+ #
447
+ # Did anything go wrong since the engine started: an error or
448
+ # a Ruby exception, whether or not on_error or on_exception
449
+ # handled it? A handler reports, it doesn't undo the failure.
450
+ # Warnings don't count.
451
+ #
452
+ def run_failed?
453
+ return @run_error_count.positive?
454
+ end
455
+
340
456
  #
341
457
  # Report an error.
342
458
  # Write it to the log and set the heap error value. Always logged;
@@ -356,6 +472,7 @@ module Gloo
356
472
  @log.error( location ? "#{location}: #{msg}" : msg )
357
473
  return unless @heap
358
474
 
475
+ @run_error_count += 1
359
476
  @heap.error.set_to msg, kind, location
360
477
 
361
478
  return if @handling_error
@@ -433,6 +550,7 @@ module Gloo
433
550
  backtrace = format_backtrace( ex )
434
551
  @log.error ex.message
435
552
  @log.backtrace backtrace
553
+ @run_error_count += 1
436
554
 
437
555
  return if @handling_exception
438
556
 
@@ -450,6 +568,16 @@ module Gloo
450
568
 
451
569
  private
452
570
 
571
+ #
572
+ # The Ctrl-C message, with where it stopped if known; the location
573
+ # is used once.
574
+ #
575
+ def interrupt_msg( msg )
576
+ location = @interrupt_location
577
+ @interrupt_location = nil
578
+ return location ? "#{msg}: #{location}." : "#{msg}."
579
+ end
580
+
453
581
  #
454
582
  # Resolve the start_with setting to a loadable name/path.
455
583
  # A bare filename (no directory separator) is resolved against
@@ -44,6 +44,14 @@ module Gloo
44
44
  return response
45
45
  end
46
46
 
47
+ #
48
+ # What had been typed at the prompt when it was last left: after
49
+ # Ctrl-C, empty if nothing had been typed.
50
+ #
51
+ def line_typed
52
+ return Reline.line_buffer.to_s
53
+ end
54
+
47
55
  #
48
56
  # Prompt for multiline input.
49
57
  #
@@ -16,16 +16,13 @@ module Gloo
16
16
  end
17
17
 
18
18
  #
19
- # Is the value really a decimal number? A blank value is no
20
- # value (0.0).
19
+ # Is the value really a decimal number, written the way a decimal
20
+ # literal is (see LDecimal)? A blank value is no value (0.0).
21
21
  #
22
22
  def valid?( value, _result )
23
23
  return true if value.blank?
24
24
 
25
- Float( value.strip )
26
- return true
27
- rescue ArgumentError
28
- return false
25
+ return Gloo::Expr::LDecimal.number?( value )
29
26
  end
30
27
 
31
28
  end
@@ -18,10 +18,11 @@ module Gloo
18
18
  end
19
19
 
20
20
  #
21
- # Is the value really an integer? A blank value is no value (0).
21
+ # Is the value really an integer, written the way an integer
22
+ # literal is (see LInteger)? A blank value is no value (0).
22
23
  #
23
24
  def valid?( value, _result )
24
- return value.blank? || value.match?( /\A\s*[-+]?\d+\s*\z/ )
25
+ return value.blank? || Gloo::Expr::LInteger.integer?( value )
25
26
  end
26
27
 
27
28
  end