gloo 6.2.1 → 6.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dee07bac4d22ecf1656cd257c1f3ce3ad12ae334377263faf5918d7f1433e20
-  data.tar.gz: 6310ec46fcf0f0da75b874b984f169566c5d7d52ce4d21c2646134c5036e2205
+  metadata.gz: 8b2250e28df1b29cef0afb4bb989a7631b421b61aff2a6a4ca7a4a99784ea6f5
+  data.tar.gz: d1aada2c93dee25e57a9a99770637ac1bf5c76c7e5064ebfd6de0a9779c041e2
 SHA512:
-  metadata.gz: 1bd139bbe32577a3811247d7d04b0b270796a447b1179c4b62a337526d0c57b5610e0636fa08e8a6aad920d8435e372d7763038d6e759637adae92d9c6b7a3af
-  data.tar.gz: e4edde70f119ab15b319910ea1b128b6a862f8be723b27f7d9e8d7acf4c6cf98f8f6a62d2114203aedcaa9e89625b530d88334be65bd8d6ecf3d1221bc775ad9
+  metadata.gz: 0d6b391cda5acf241e452eadee0533a0929622dde953eb44fd32cadfd1a1c8c469a0b820370af157eca3f5128636127d6171fc57a6002e532e03e24d03982656
+  data.tar.gz: 97806263c82dfb98af8105c19e017dde5b3d4a426c85384c2368d7b2df1b4e9f396bc9236844b7fff77e3fd264c0aa77ccb17e10fa96d5fa4a658f7e39ec2475

data/.mailmap

@@ -0,0 +1 @@
+Eric Crane <eric.crane@mac.com> <encrane@datacor.com>

data/docs/language_syntax.md

@@ -88,7 +88,10 @@ The following events are application and file-level events:
 - `on_quit` — event triggered when gloo is quitting
 - `on_save` — when an object is saved, this event is triggered
 - `on_reload` — event triggered when an object receives message to reload
-- `on_error` — event triggered when there is an error in the application
+- `on_error` — event triggered when gloo hits a checked error condition (a bad path, a missing object, a verb used wrongly)
+- `on_exception` — event triggered when gloo's safety net catches an unanticipated Ruby exception (rare in normal code; use the `throw` verb to exercise it)
+
+`on_error` and `on_exception` are independent channels — a checked gloo error fires `on_error` only, an unhandled Ruby exception fires `on_exception` only, and neither triggers the other. In both cases the line that failed is abandoned and execution continues with the next line; a handler is a place to log or react, not a way to retry. Each handler reads its details from a sibling data container (`error_data` / `exception_data`) that the engine populates before running the script; the handler script and its data container can sit at the root of a file or be nested together inside a container.
 
 Some objects also have events that are triggered as part of their lifecycle. Here are some examples:
 
@@ -143,9 +146,22 @@ on_error [script] :
 error_data [can] :
   message [string] :
   backtrace [string] :
+
+
+#
+# Global Exception Handler.
+# Same shape as on_error, with a sibling exception_data container.
+# 'throw' deliberately raises a Ruby exception to exercise this.
+#
+on_exception [script] :
+  tell audit_exception.write to run
+
+exception_data [can] :
+  message [string] :
+  backtrace [string] :
 ```
 
-See also: Load, Reload, Unload, Save, Quit.
+See also: Load, Reload, Unload, Save, Quit, and the `throw` verb reference.
 
 ## Function Calls
 

data/docs/objects.md

@@ -4,6 +4,8 @@ Everything in gloo is an object. Strings, numbers, containers, scripts, function
 
 Gloo ships with a large set of built-in object types, and core libraries and extensions can add more. This page doesn't try to cover them all — it walks through three common ones to get a feel for how objects work. For the complete list of object types, and every message each one supports, use the in-app help: enter `help` (or `?`), then `objects` to list them all, or `object {name}` for detail on one (see Application, Help).
 
+An object's **type declares which messages it can receive** — `up` and `trim` for a `string`, `inc` for an `integer`, `run` for a `script`. An object doesn't have to have a type: with none it is `untyped` (short `any`), declared with a bare colon (`slot :`), with `[any]`, or by `create` with no `as`. An untyped object still takes the messages every object understands (`blank?`, `contains?`, `responds_to?`, `reload`, `unload`) — just not the type-specific ones. Untyped is the right choice when you only need to hold, compare, or show a value: a generic result slot, a config value passed straight through, or a field whose kind of value changes over its life.
+
 **Contents**
 
 - String
@@ -27,6 +29,8 @@ s [can] :
 
 Sending `up` to the string converts it to uppercase, in place. Sending `size` puts the character count into `it`. There are messages for lowercasing, counting words and lines, checking prefixes/suffixes, encoding, and generating random strings (UUIDs, hex, alphanumeric) — see the in-app help for the full list.
 
+For yes/no messages that inspect state (`blank?`, `starts_with?`, `ends_with?`), the `check` verb reads better than `tell` — `check s.msg for starts_with? ("Hello")` — but it does the same thing (see Verbs, Tell).
+
 ## Container
 
 A container holds other objects — it's the closest thing gloo has to a folder, a hash, or a struct. Any object nested inside a container is reachable through a dotted pathname:

data/docs/plugins.md

@@ -9,10 +9,6 @@
 
 Core Libraries extend gloo functionality, primarily by adding object types and potentially verbs.
 
-Be sure to load a core library (or extension) prior to loading a gloo file that includes object types defined in the library.
-
-Use the Load Verb to use an extension.
-
 A core library ships as its own gem (`gloo-<name>`). `load lib <name>` requires the gem, installing it first via `gem install` if it isn't already present — so the explicit `gem install` step below is optional, but doing it yourself ahead of time is recommended so the install doesn't happen mid-script. Once loaded, a library's objects and verbs show up in the `help`/`?` shell exactly like built-ins:
 
 ```gloo
@@ -21,6 +17,18 @@ A core library ships as its own gem (`gloo-<name>`). `load lib <name>` requires
 help> object yaml
 ```
 
+A library's object types must be registered before any file that declares one is parsed. To use a library type in a script file, put the `load lib` at the **top of the file**, before the first object:
+
+```gloo
+load lib yaml
+
+settings [can] :
+  file [yaml] : ~/.myapp/settings.yml
+  ...
+```
+
+The loader runs these top-of-file `load lib` / `load ext` lines before it builds the object tree, so declarations below them can use the library's types. Only `load lib` and `load ext` are recognized this way, and only above the first object — a `load lib` in a script still runs when that script runs, as before.
+
 ### Available Core Libraries
 
 - **CLI** — Use the `gloo-cli` gem when building CLI applications.

data/docs/verbs.md

@@ -42,6 +42,14 @@ tell {path.to.object} to {message}
 > tell the.container to count
 ```
 
+`check` is the same verb under another name — it sends a message exactly the way `tell` does. The two spellings exist so code reads like natural communication: use `tell` to trigger an action (`up`, `run`, `unload`), and `check` to investigate state with a yes/no question (`blank?`, `contains?`, `starts_with?`). The answer to a `check` lands in `it`, so it pairs naturally with `if` / `unless`.
+
+```gloo
+> tell my.str to up
+> check my.str for starts_with? ("HELLO")
+> if it then show 'it does'
+```
+
 ## Put
 
 `put` evaluates an expression and stores the result in an object.

data/lib/VERSION

@@ -1 +1 @@
-6.2.1
+6.3.0

data/lib/VERSION_NOTES

@@ -1,3 +1,7 @@
+6.3.0 - 2026.08.31
+ - Adds option to load a library at the top of a script that includes types from that lib.
+
+
 6.2.1 - 2026.08.25
  - Fixes bug starting in app mode.
 

data/lib/gloo/objs/basic/untyped.rb

@@ -47,12 +47,24 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'An untyped object. If no type is specified ' \
-            'when an object is created it will be of this type.',
+          :description => 'An object with no type. A type declares ' \
+            'which messages an object can receive; an untyped object ' \
+            'receives only the base object messages (blank?, ' \
+            'contains?, responds_to?, reload, unload) but can hold a ' \
+            'value of any kind. If no type is specified when an object ' \
+            'is created, it is untyped. Prefer untyped when you only ' \
+            'need to hold, compare, or show a value and do not need ' \
+            'type-specific behaviour.',
           :examples => <<~EXAMPLES.strip
             > create x
             > put 1 into x
             > put 'string' into x
+
+            #
+            # Declared with a bare colon, or with [any]:
+            #
+            slot :
+            flag [any] :
           EXAMPLES
         }
       end

data/lib/gloo/persist/file_loader.rb

@@ -12,6 +12,14 @@ module Gloo
       END_BLOCK = 'END'.freeze
       SPACE_CNT = 2
 
+      # A 'load lib {name}' (or 'load ext {name}') statement at the top
+      # of a file, before the first object declaration. It makes a core
+      # library's object types available to the declarations that
+      # follow. Same syntax as the load verb, but the loader runs it
+      # before building the object tree instead of a script running it
+      # afterward.
+      LIB_DIRECTIVE = /\A(?:load|ld)\s+(?:lib|ext)\s+\S+\s*\z/i.freeze
+
       attr_reader :obj
 
       #
@@ -27,6 +35,7 @@ module Gloo
         @exiting_multiline = false
         @in_block = false
         @block_value = ''
+        @body_started = false
         @debug = false
       end
 
@@ -51,11 +60,28 @@ module Gloo
         f.each_line do |line|
           next if skip_line? line
 
+          if !@body_started && line =~ LIB_DIRECTIVE
+            run_lib_directive line
+            next
+          end
+          @body_started = true
+
           handle_one_line line
         end
       end
 
-      # 
+      #
+      # Run a top-of-file 'load lib {name}' directive. It goes through
+      # the same load verb a script would use, so libraries are loaded
+      # and their object types registered before the declarations that
+      # depend on them are parsed.
+      #
+      def run_lib_directive( line )
+        @engine.log.debug "Loading file directive: #{line.strip}"
+        @engine.parser.run line.strip
+      end
+
+      #
       # Join continuation lines.
       #
       def join_continuations( data )

data/lib/gloo/verbs/check.rb

@@ -60,9 +60,13 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'Send a message to an object to check for an ' \
-            'object condition. This is the same as the tell verb, but ' \
-            'gives better syntactical naming.',
+          :description => 'Send a message to an object to investigate ' \
+            'its state — typically a yes/no question such as blank?, ' \
+            'contains? or starts_with?. Mechanically identical to the ' \
+            'tell verb; by convention check is used to investigate ' \
+            'state while tell is used to trigger an action. Using the ' \
+            'verb that matches intent makes the code read like ' \
+            'natural communication.',
           :syntax => [ 'check {path.to.object} for {condition_message}' ],
           :parameters => [
             '{path.to.object} — The object that we want to send a condition_message to.',
@@ -74,7 +78,7 @@ module Gloo
             "#{UNKNOWN_MSG_ERR} — No message was specified, or the 'for' keyword is missing.",
             'Object was not found — The target of the message was not found.'
           ],
-          :examples => <<~EXAMPLES.strip
+          :examples => <<~EXAMPLES.strip,
             #
             # Base object checks.
             #
@@ -95,6 +99,14 @@ module Gloo
                 check obj.msg for blank?
                 show it
           EXAMPLES
+          :notes => <<~NOTES.strip
+            check and tell send the same message the same way — the two
+            spellings exist for readability. Use check for state questions
+            (blank?, contains?, responds_to?, starts_with?) and tell for
+            action messages (up, inc, run, unload). The answer to a check
+            lands in it, so it pairs naturally with if / unless:
+            'check my.str for blank?' then 'if it then ...'.
+          NOTES
         }
       end
 

data/lib/gloo/verbs/create.rb

@@ -88,10 +88,15 @@ module Gloo
             '{type} — The type of the new object. Optional; if not provided the object will be untyped.',
             "{value} — The initial value for the new object. Optional; if not provided the object will have the default value for the type."
           ],
-          :result => "The new object will be created and added to the " \
-            "object heap. It will be set to the new object's initial value.",
+          :result => "If nothing exists at the path, a new object is " \
+            "created with the given (or type-default) value and added " \
+            "to the object tree, and it is set to that value. If an " \
+            "object already exists at the path it is left unchanged — " \
+            "the type and value given here are ignored — and it is set " \
+            "to the existing object's current value.",
           :errors => [
-            "#{NO_NAME_ERR} — The name of the object was not specified and the object cannot be created."
+            "#{NO_NAME_ERR} — The name of the object was not specified and the object cannot be created.",
+            'Could not create object. Bad path: {name} — The parent container named in the path does not exist. The path is root-relative and every container above the new object must already exist.'
           ],
           :examples => <<~EXAMPLES.strip
             # Basic examples of creating an object from the gloo shell:

data/lib/gloo/verbs/eval.rb

@@ -49,19 +49,33 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'Evaluate an expression and put the result into it.',
+          :description => 'Evaluate an expression and put the result ' \
+            'into it, without any other action. Unlike put it does ' \
+            'not store the result in a named object, and unlike show ' \
+            'it does not print it. Primarily used in tests: assert ' \
+            'and refute check the value of it, so eval is the bridge ' \
+            'for expressions and comparisons that do not already ' \
+            'leave a boolean there.',
           :syntax => [ 'eval {expression}' ],
           :parameters => [
             '{expression} — The expression that will be evaluated. The expression is optional. If not provided, eval will result in true.'
           ],
           :result => 'The result of the expression evaluation is put ' \
             'into it. No other action is performed.',
-          :examples => <<~EXAMPLES.strip
+          :examples => <<~EXAMPLES.strip,
             > eval "me"
             > eval "hello " "world"
             > eval 132 * 23
             > eval path.to.num = 1
           EXAMPLES
+          :notes => <<~NOTES.strip
+            eval was added for the gloo-test framework. assert and refute
+            only look at it; the common pattern is to run a verb or
+            message, then 'eval it = {expected}' to compare the result to
+            an expected value, then assert or refute. Bare eval (or its
+            shortcut noop) sets it to true, which pairs with assert for
+            'this state should hold' checks.
+          NOTES
         }
       end
 

data/lib/gloo/verbs/tell.rb

@@ -61,8 +61,12 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'Send a message to an object. Ask the object ' \
-            'to perform an action.',
+          :description => 'Send a message to an object, asking it to ' \
+            'perform an action. Mechanically identical to the check ' \
+            'verb; by convention tell is used to trigger an action ' \
+            'or change state, while check is used to investigate ' \
+            'state. Using the verb that matches intent makes the ' \
+            'code read like natural communication.',
           :syntax => [ 'tell {path.to.object} to {message}' ],
           :parameters => [
             '{path.to.object} — The object that we want to send a message to.',
@@ -73,12 +77,20 @@ module Gloo
             "#{UNKNOWN_MSG_ERR} — No message was specified, or the `to` keyword is missing.",
             'Object was not found — The target of the message was not found.'
           ],
-          :examples => <<~EXAMPLES.strip
+          :examples => <<~EXAMPLES.strip,
             > tell an.obj to unload
             > tell the.script to run
             > tell my.str to up
             > tell the.container to count
           EXAMPLES
+          :notes => <<~NOTES.strip
+            tell and check send the same message the same way — the two
+            spellings exist for readability. Use tell for action messages
+            (up, inc, run, unload, randomize) and check for state questions
+            (blank?, contains?, starts_with?). Either verb will accept
+            either kind of message, but mixing them reads wrong:
+            'tell my.str for blank?' works but should be a check.
+          NOTES
         }
       end
 

data/lib/gloo/verbs/throw.rb

@@ -72,10 +72,38 @@ module Gloo
           :result => "Fires the app's on_exception handler, if one is " \
             'defined, with exception_data.message set to the thrown ' \
             'message. Does not fire on_error.',
-          :examples => <<~EXAMPLES.strip
+          :examples => <<~EXAMPLES.strip,
             > throw
             > throw "custom message"
+
+            #
+            # Execution continues with the line after the throw.
+            #
+            demo [container] :
+              on_exception [script] :
+                show 'caught: ' + ^.exception_data.message
+              exception_data [can] :
+                message [string] :
+                backtrace [string] :
+              on_load [script] :
+                throw "boom"
+                show 'still running'
           EXAMPLES
+          :notes => <<~NOTES.strip
+            on_error and on_exception are independent channels: a checked
+            gloo error (bad path, missing object) fires on_error only; a
+            Ruby exception (from throw, or a real bug caught by gloo's
+            safety net) fires on_exception only. Neither triggers the
+            other, and in both cases the failing line is abandoned and
+            execution continues with the next line.
+
+            gloo logs every caught exception, so a throw during a script
+            run also prints the message and a truncated backtrace to the
+            console — that is the logging working, not a crash.
+
+            See gloo_sample_code/lang/exceptions.gloo for a runnable
+            walk-through.
+          NOTES
         }
       end
 

data/test.gloo/lang/continuation.test.gloo

@@ -0,0 +1,39 @@
+#
+# Line continuation tests
+#
+# A trailing \ continues a statement on the next line.
+#
+
+tests [can] :
+  lang [can] :
+    continuation [can] :
+
+      one [string] : Hello
+      two [string] : World
+      joined [string] :
+      split [string] :
+      flag [bool] : false
+
+      split_statement_matches_single_line [test] :
+        description [string] : a statement broken with \ produces the same result as one line.
+        on_test [script] :
+          put ^^.one and ' ' and ^^.two into ^^.joined
+
+          put ^^.one and \
+            ' ' and \
+            ^^.two into ^^.split
+
+          eval ^^.split = ^^.joined
+          assert "expected the continued statement to match the single-line one"
+
+          eval ^^.split = 'Hello World'
+          assert "expected the joined value"
+
+      continuation_in_an_if [test] :
+        description [string] : \ works inside an if statement.
+        on_test [script] :
+          put false into ^^.flag
+          if ^^.one = 'Hello' \
+            then put true into ^^.flag
+          eval ^^.flag = true
+          assert "expected the continued if to run its then branch"

data/test.gloo/lang/convert.test.gloo

@@ -0,0 +1,70 @@
+#
+# Value conversion tests
+#
+# 'put' converts the value to the target object's type.
+#
+
+tests [can] :
+  lang [can] :
+    convert [can] :
+
+      i [integer] : 0
+      d [decimal] : 0
+      s [string] : x
+      b [boolean] : false
+
+      string_to_number [test] :
+        description [string] : a string is converted to the leading number for an int or decimal target.
+        on_test [script] :
+          put '3 third time' into ^^.i
+          eval ^^.i = 3
+          assert "expected the leading integer to be parsed"
+
+          put '3.12 more' into ^^.d
+          eval ^^.d = 3.12
+          assert "expected the leading decimal to be parsed"
+
+          put 'notanumber' into ^^.i
+          eval ^^.i = 0
+          assert "expected a non-numeric string to convert to 0"
+
+      number_to_number [test] :
+        description [string] : int and decimal convert to each other; decimal to int truncates.
+        on_test [script] :
+          put 5 into ^^.d
+          eval ^^.d = 5.0
+          assert "expected the integer to widen to a decimal"
+
+          put 9.99 into ^^.i
+          eval ^^.i = 9
+          assert "expected the decimal to truncate toward zero"
+
+      anything_to_string [test] :
+        description [string] : a number or boolean put into a string becomes its text form.
+        on_test [script] :
+          put 123 into ^^.s
+          eval ^^.s = '123'
+          assert "expected the number to become a string"
+
+          put true into ^^.s
+          eval ^^.s = 'true'
+          assert "expected the boolean to become a string"
+
+      to_boolean [test] :
+        description [string] : strings (case-insensitive) and numbers convert to a boolean.
+        on_test [script] :
+          put 'false' into ^^.b
+          eval ^^.b = false
+          assert "expected 'false' to convert to false"
+
+          put 'TRUE' into ^^.b
+          eval ^^.b = true
+          assert "expected 'TRUE' to convert to true, case-insensitively"
+
+          put 0 into ^^.b
+          eval ^^.b = false
+          assert "expected 0 to convert to false"
+
+          put 42 into ^^.b
+          eval ^^.b = true
+          assert "expected a non-zero number to convert to true"

data/test.gloo/lang/here.test.gloo

@@ -0,0 +1,41 @@
+#
+# Here / parent reference tests
+#
+# From inside a script, ^ is the script's containing object, ^^ its
+# parent, ^^^ its grandparent, and so on.
+#
+
+tests [can] :
+  lang [can] :
+    here [can] :
+
+      s [string] : level 0
+
+      r1 [string] :
+      r2 [string] :
+      r3 [string] :
+
+      a [can] :
+        s [string] : level 1
+        b [can] :
+          s [string] : level 2
+          c [can] :
+            s [string] : level 3
+            capture [script] :
+              put ^.s into tests.lang.here.r1
+              put ^^.s into tests.lang.here.r2
+              put ^^^.s into tests.lang.here.r3
+
+      caret_walks_up_the_tree [test] :
+        description [string] : ^, ^^, ^^^ resolve relative to the running script's location.
+        on_test [script] :
+          tell tests.lang.here.a.b.c.capture to run
+
+          eval ^^.r1 = 'level 3'
+          assert "expected ^ to be the script's own container"
+
+          eval ^^.r2 = 'level 2'
+          assert "expected ^^ to be the parent container"
+
+          eval ^^.r3 = 'level 1'
+          assert "expected ^^^ to be the grandparent container"

data/test.gloo/lang/it.test.gloo

@@ -0,0 +1,41 @@
+#
+# 'it' tests
+#
+# 'it' holds the result of the last statement that produced one.
+#
+
+tests [can] :
+  lang [can] :
+    it [can] :
+
+      n [int] : 5
+      r [string] :
+
+      set_by_the_previous_statement [test] :
+        description [string] : show, eval, tell and put all leave their result in it.
+        on_test [script] :
+          show 3 + 4
+          eval it = 7
+          assert "expected show to leave the evaluated value in it"
+
+          eval 10 * 2
+          eval it = 20
+          assert "expected eval to leave its result in it"
+
+          put 'hello' into ^^.r
+          eval it = 'hello'
+          assert "expected put to leave the stored value in it"
+
+          put 5 into ^^.n
+          tell ^^.n to inc
+          eval it = 6
+          assert "expected tell to leave the message result in it"
+
+      persists_across_statements_that_produce_nothing [test] :
+        description [string] : statements like a bare show or list leave it untouched.
+        on_test [script] :
+          eval 42
+          show
+          list ^^.n
+          eval it = 42
+          assert "expected it to survive statements that don't produce a result"

data/test.gloo/lang/literal.test.gloo

@@ -0,0 +1,61 @@
+#
+# Literal value tests
+#
+
+tests [can] :
+  lang [can] :
+    literal [can] :
+
+      s [string] :
+      i [integer] :
+      d [decimal] :
+      b [boolean] :
+
+      string_quote_styles [test] :
+        description [string] : single and double quotes both make a string; the other quote can appear inside.
+        on_test [script] :
+          put 'single quoted' into ^^.s
+          eval ^^.s = 'single quoted'
+          assert "expected single quotes to work"
+
+          put "double quoted" into ^^.s
+          eval ^^.s = 'double quoted'
+          assert "expected double quotes to work"
+
+          put "you're fine" into ^^.s
+          eval ^^.s = "you're fine"
+          assert "expected an apostrophe inside double quotes to be literal"
+
+      number_literals [test] :
+        description [string] : integer and decimal literals, including negatives.
+        on_test [script] :
+          put -5 into ^^.i
+          eval ^^.i = -5
+          assert "expected a negative integer literal"
+
+          put 3.14159 into ^^.d
+          eval ^^.d = 3.14159
+          assert "expected a decimal literal"
+
+          put -2.5 into ^^.d
+          eval ^^.d = -2.5
+          assert "expected a negative decimal literal"
+
+      boolean_literals_are_case_insensitive [test] :
+        description [string] : TRUE, true, False, FALSE all parse.
+        on_test [script] :
+          put TRUE into ^^.b
+          eval ^^.b = true
+          assert "expected TRUE to parse"
+
+          put true into ^^.b
+          eval ^^.b = true
+          assert "expected true to parse"
+
+          put False into ^^.b
+          eval ^^.b = false
+          assert "expected False to parse"
+
+          put FALSE into ^^.b
+          eval ^^.b = false
+          assert "expected FALSE to parse"