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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 153d674b150e06c999a0756c90c41f872a410205f516eaa8b560335f93ec0e2b
4
- data.tar.gz: 1b11115e161f139b44dc6750713e0e883f638ae58048c8b3007441cbf681f319
3
+ metadata.gz: 0fc8d097c99cd0b45404f5248f8618a62e52b052a14d971a9bfb9ef62b84cb54
4
+ data.tar.gz: 749ba266d911f205b1049a4d99e6132362cc0d5ccca6b3ce306f3eacc626dc4f
5
5
  SHA512:
6
- metadata.gz: 3e92b508048653b4e1e4e283a7e90de32605b4a239f56b7b24123c600e5b38a6af582a50a6d2a7130da8ed73d8ded9f0e6aab2a75798a9709939749cf72119dd
7
- data.tar.gz: 19cd40e0d35cfed856aa7eb6ffe4fe648adde3c706656d81211d01f0c940a4c38dd63b0bffe2a4b50b3b57d9e76afba997050c7fca99066f2fe6529825d05591
6
+ metadata.gz: ac22bbda45bc8417c1b4228880f7f995e9f5d62759c9d4299aaccdd6eef4f8a003d9d1c258a2721ad16563e61c9aca88e4047d88369dfa4e35c2413fc8e86a3e
7
+ data.tar.gz: 2e9a802711e8e30b076bf70cd554e3097b817fd0153fc520004961cbfa942143ec276a5d3798db968f9b19471b6662c1b08f33e8b66df588f2f74c3a3d19dc7a
data/Rakefile CHANGED
@@ -9,3 +9,26 @@ Rake::TestTask.new(:test) do |t|
9
9
  end
10
10
 
11
11
  task :default => :test
12
+
13
+ #
14
+ # Load and save a copy of every .gloo file under the given folders, and
15
+ # list the files that come back different. The originals are never
16
+ # written. For example:
17
+ # rake "round_trip[~/gloo/app,~/dev/gloo_apps]"
18
+ #
19
+ desc 'Round-trip copies of .gloo files and list the ones that change'
20
+ task :round_trip do |_task, args|
21
+ $LOAD_PATH.unshift File.expand_path( 'lib', __dir__ ), File.expand_path( 'test', __dir__ )
22
+ require 'gloo'
23
+ require 'round_trip_check'
24
+
25
+ check = RoundTripCheck.new do
26
+ engine = Gloo::App::Engine.new( Gloo::App::EngineContext.new( [ '--quiet' ] ) )
27
+ engine.log.quiet = true
28
+ engine.start
29
+ engine
30
+ end
31
+ changed, count = check.check_folders( args.extras )
32
+ changed.each { |path, diff| puts "#{path}\n #{diff}" }
33
+ puts "#{changed.size} of #{count} files changed."
34
+ end
data/docs/application.md CHANGED
@@ -5,6 +5,8 @@
5
5
  - The Gloo Home Directory
6
6
  - Running Gloo
7
7
  - Modes
8
+ - Script Mode and App Mode
9
+ - Stopping with Ctrl-C
8
10
  - Configuration
9
11
  - Logging
10
12
  - Help
@@ -35,6 +37,8 @@ Gloo can also be started from another Ruby program; see Development, Running Glo
35
37
 
36
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.
37
39
 
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).
41
+
38
42
  When specifying a file there are a couple ways to reference the gloo file to open:
39
43
 
40
44
  - By Path
@@ -46,11 +50,11 @@ When specifying a file there are a couple ways to reference the gloo file to ope
46
50
  ```
47
51
  - By Project
48
52
  - Use the path within the project folder.
49
- - Do not include the `.gloo` or other file extension.
53
+ - The `.gloo` extension can be left off.
50
54
  - The location of the project folder is part of the configuration.
51
55
  - For example:
52
56
  ```
53
- gloo my_project/file.gloo
57
+ gloo my_project/file
54
58
  ```
55
59
 
56
60
  ## Modes
@@ -77,6 +81,8 @@ When specifying a file there are a couple ways to reference the gloo file to ope
77
81
  (the current folder if none), using the gloo-test library.
78
82
  - Exits with status 1 if any test failed, or errors or warnings
79
83
  were logged that no test expected; 0 otherwise.
84
+ - Each test file runs with only the libraries and extensions it
85
+ loads itself.
80
86
  - See Testing.
81
87
  --embed - Run in Embedded mode
82
88
  - Start the engine and return, for a Ruby program that drives
@@ -87,6 +93,61 @@ When specifying a file there are a couple ways to reference the gloo file to ope
87
93
  --help - Show the help screen
88
94
  ```
89
95
 
96
+ ## Script Mode and App Mode
97
+
98
+ Gloo runs a file in one of two ways, and they're meant for different things.
99
+
100
+ **Script mode** (`gloo path/to/file.gloo`) is a transaction: gloo loads the file, runs its `on_load`, and quits. Use it for a job that does something and finishes.
101
+
102
+ **App mode** (`gloo --app path/to/folder`) is a process: gloo loads the folder's `start.gloo`, and the app stays up — a shell taking commands, a web server, a connection — until it's told to stop. The folder is the app's root: `gloo.app` is that folder, and words after it on the command line are a command for the app, not files to load.
103
+
104
+ An app only runs in App mode. If an app's `start.gloo` is run as a script by mistake, starting a shell (gloo-cli) or a web server (gloo-web) is an error that says how to run it, for example `Could not start the shell: an app runs in App mode. Run it with 'gloo --app ~/gloo/app/notes'.`, and gloo exits with status 1.
105
+
106
+ The two also differ in what the **project folder** is. In App mode it's the app's folder. Otherwise it's where you keep your projects: the `project_path` setting (see Configuration), `~/gloo/projects` unless you change it, and `gloo.gloo_projects`.
107
+
108
+ ### Where a Relative Load Looks
109
+
110
+ A `load` with a full path, or one starting with `~`, loads that file. A relative name is looked for in a few places, in order, and the first place that has it wins:
111
+
112
+ | Mode | Looks in, in order |
113
+ |---|---|
114
+ | App mode | the app folder → next to the loading file → the gloo home |
115
+ | Script and Test modes | next to the loading file → the projects folder → the gloo home |
116
+ | A command typed at the prompt | the working folder → the projects folder → the gloo home (in App mode: the app folder → the working folder → the gloo home) |
117
+
118
+ "Next to the loading file" is the folder of the file the running script was declared in — the folder `check {obj} for source_dir` gives for it. A script declared in one file and run from another still looks next to its own file. A script that didn't come from a file (one created while gloo runs) skips this step. A command typed at the prompt has no file, so the working folder stands in for it; a load inside a file never depends on where gloo was started.
119
+
120
+ A folder load (`load parts/*`) is looked for the same way, and the first place with matching `.gloo` files is used. The gloo home comes last in every mode, so files kept there (such as a `common` folder shared by several apps) can be loaded from anywhere.
121
+
122
+ For example, a small project:
123
+
124
+ ```
125
+ report/
126
+ start.gloo # on_load: load parts/*
127
+ parts/
128
+ totals.gloo
129
+ format.gloo
130
+ ```
131
+
132
+ Run as a script (`gloo report/start.gloo`), `load parts/*` finds `report/parts` next to `start.gloo`, whatever folder gloo was started from. Run as an app (`gloo --app report`), it finds the same folder as part of the app. Inside an app, a name means the same thing in every file: `load parts/format` gets `report/parts/format.gloo` whichever of the app's files says it.
133
+
134
+ Files named on the command line are found differently: as given (from the working folder), then in the projects folder, then in the gloo home (see Running Gloo, above).
135
+
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`.
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
+
90
151
  ## Configuration
91
152
 
92
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.
@@ -192,8 +253,8 @@ help
192
253
 
193
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:
194
255
 
195
- - `verbs` — list all verbs
196
- - `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
197
258
  - `settings` — show application settings
198
259
  - `theme` — show the current color theme, how to change it, and a preview of both palettes
199
260
  - `extensions` — list loaded extensions (only loaded extensions are shown; use `load ext {name}` first)
data/docs/development.md CHANGED
@@ -78,6 +78,16 @@ Use plain `ruby`, not `bundle exec`. The Gemfile doesn't include `gloo-test` or
78
78
 
79
79
  The same command runs the gloo tests of core libraries and extensions; add their `test/` folders to the list of paths.
80
80
 
81
+ ### Round-trip check
82
+
83
+ Saving a file that was loaded and not changed must give back the same bytes. `test/persist/round_trip_test.rb` checks that for every `.gloo` file in `test.gloo/` and `test/gloo/projects/` (add a fixture to `test/gloo/projects/round_trip/` for a new construct). To check other folders, such as apps:
84
+
85
+ ```
86
+ rake "round_trip[~/gloo/app,~/dev/gloo_apps]"
87
+ ```
88
+
89
+ It copies each file to a scratch folder, loads it without running any scripts or `load lib` lines, saves it, and lists the files that came back different with their first changed line. The originals are never written.
90
+
81
91
  ## Documentation
82
92
 
83
93
  The narrative documentation is the set of flat pages in `docs/`, linked from the README. Two conventions keep them readable both on GitHub and in a terminal:
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] :
@@ -15,18 +15,19 @@
15
15
  Object names are single words (no spaces) and conform to the following:
16
16
 
17
17
  - Spaces in names are not allowed.
18
- - Names should be unique within their context.
19
- - Note that there is no technical restriction. Multiple objects with the same name in the same context can exist, but there's no way to reference objects past the first one with the given name.
18
+ - A name is unique within its container.
19
+ - Declaring a name again, in the same file or another one, names the same object: its children are added to the first one's, and its value is ignored (with a warning when it's different). `create` with a name that's already there leaves the object as it is, and `move` won't move an object into a container that already has its name.
20
20
  - Names can be capitalized or lower case.
21
- - But names with different cases are not treated as unique.
21
+ - But names with different cases are not different names: `a` and `A` are the same object.
22
22
  - Names can contain numbers and special characters.
23
23
 
24
24
  ```gloo
25
25
  #
26
26
  # Example of object naming.
27
27
  #
28
- # NOTE that the second 'a' and the 'A' objects are not reachable.
29
- # 'naming.a' will always reach the 'First A' string.
28
+ # NOTE that the second 'a' and the 'A' lines name the same object as
29
+ # the first: 'naming.a' is 'First A', and loading warns that the other
30
+ # two values are ignored.
30
31
  #
31
32
  naming [container] :
32
33
  on_load [script] :
@@ -35,8 +36,8 @@ naming [container] :
35
36
  show naming.1
36
37
  msg!$% [string] : Naming stuff
37
38
  a [string] : First A
38
- a [string] : Second A is not reachable
39
- A [string] : Capital A is not reachable
39
+ a [string] : Second A
40
+ A [string] : Capital A
40
41
  1 [string] : One
41
42
  ```
42
43
 
@@ -121,20 +122,24 @@ Every object can say which file it was loaded from: `check {obj} for
121
122
  source_file` puts the file's full path in `it`, and `check {obj} for
122
123
  source_dir` puts that file's folder (with no trailing slash). This lets a
123
124
  script reach files stored next to it without a hard-coded path. For
124
- example, a test can load a fixture that sits beside its own file:
125
+ example, a script can read a data file that sits beside its own file:
125
126
 
126
127
  ```gloo
127
- tests.my_area [can] :
128
+ report [can] :
128
129
  where [string] :
129
- fixture [string] : /fixtures/sample.gloo
130
+ data [file] :
131
+ rows [string] :
130
132
 
131
- loads_its_fixture [test] :
132
- on_test [script] :
133
- check ^^ for source_dir
134
- put it into ^^.where
135
- load ( ^^.where ^^.fixture )
133
+ on_load [script] :
134
+ check ^ for source_dir
135
+ put it into ^.where
136
+ put ^.where '/data/rows.txt' into ^.data
137
+ tell ^.data to read ( ^.rows )
136
138
  ```
137
139
 
140
+ (A `load` doesn't need this: a relative name already looks next to the
141
+ loading file first. See Application, Script Mode and App Mode.)
142
+
138
143
  The answer comes from the nearest object, going up from the one asked,
139
144
  that a loaded file declares. So a nested object answers with its file,
140
145
  even when its root container (like `tests` above) is declared in many
@@ -156,7 +161,7 @@ That said, gloo's own vocabulary — words that already mean something built-in
156
161
  - Verb keywords, and their shortcuts (see Verbs) — `put`, `show`, `run`, `tell`, and the rest.
157
162
  - Object type names, and their shortcuts (see Objects) — `string`, `container`, `integer`, and the rest.
158
163
 
159
- 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`.
160
165
 
161
166
  See also: Verbs, Objects.
162
167
 
@@ -175,7 +180,11 @@ The following rules apply to literal values:
175
180
  `"say \"hi\""` is the string `say "hi"`.
176
181
  - Numbers
177
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`.
178
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).
179
188
  - Booleans
180
189
  - Can be `TRUE` or `FALSE`
181
190
  - Note that the text is case insensitive.
@@ -223,22 +232,25 @@ See also: Put, Show, String, Boolean, Integer, Decimal, Value Conversion.
223
232
 
224
233
  ## Value Conversion
225
234
 
226
- 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.)
227
236
 
228
237
  Here are some of the value conversions that gloo will attempt:
229
238
 
230
239
  - string to integer
231
- - additional text is discarded
232
- - `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
233
244
  - integer to string
234
245
  - simple to-string conversion
235
246
  - string to decimal
236
- - additional text is discarded
237
- - `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
238
250
  - decimal to string
239
251
  - simple to-string conversion
240
252
  - decimal to integer
241
- - drops everything after the decimal point
253
+ - drops everything after the decimal point (no warning: this is the conversion, not a guess)
242
254
  - `put 1.23 into x` => 1
243
255
  - integer to decimal
244
256
  - decimal with integer value
@@ -9,7 +9,11 @@
9
9
 
10
10
  ## Gloo Script Files
11
11
 
12
- Gloo scripts are stored in regular text files with the `.gloo` extension.
12
+ Gloo scripts are stored in regular text files with the `.gloo` extension. A file is UTF-8, whatever the locale gloo runs in (cron and launchd, for example, give a process a plain ASCII locale). A line with bytes that aren't UTF-8 still loads, with a warning: those bytes read as `�` (U+FFFD), and the file keeps them, so saving it doesn't change them.
13
+
14
+ Indentation is what puts an object under another: one level deeper is a tab or two spaces. They can be mixed, from line to line or on one line (a tab and two spaces is two levels).
15
+
16
+ An object is declared as `name [type] : value`. Spaces just inside the brackets don't matter: `[ int ]` and `[int ]` are `[int]`.
13
17
 
14
18
  Conventions:
15
19
 
@@ -27,6 +31,23 @@ hello [can] :
27
31
  on_load [script] : show 'hello world'
28
32
  ```
29
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
+
30
51
  ## Comments
31
52
 
32
53
  A line whose first non-blank character is `#` is a comment. Whole-line comments
@@ -85,7 +106,7 @@ constants [can] :
85
106
 
86
107
  ## Line Continuation
87
108
 
88
- In gloo scripting, a line continuation is done by ending a line with a backslash (`\`). Logical lines can be split across multiple physical lines of text in scripts. A line break is otherwise an indication of a new statement.
109
+ In gloo scripting, a line continuation is done by ending a line with a backslash (`\`). Logical lines can be split across multiple physical lines of text in scripts. A line break is otherwise an indication of a new statement. Inside a `BEGIN` … `END` block a backslash is just a character: the block's lines are its value, exactly as written.
89
110
 
90
111
  ```gloo
91
112
  #
@@ -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