gloo 6.4.0 → 6.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 345f1e1145a1c3e32a2d94f39eda0246c0b36c8a6aa36857cb8a459042b97b0a
-  data.tar.gz: a8cc80d6cfe82bd0f938cf9993e3948c7ae0ca1434fc430bb79a357239f8ac70
+  metadata.gz: 19bd707a24eb9bbd3e2759cdb2ae244d2dafc28f40c0f4046c856152e343261c
+  data.tar.gz: fd3fd34b664abb32a464d3745de0ede24e136f2b2a7f375809170312bbec51a1
 SHA512:
-  metadata.gz: 1c6f947e4282de5e585543771f30d42ec3ab85197237e805d1c560c06fc286ecd5053b5627b86f7f017368dcf3ae957c1784f74b498e885feacc247a43b17ea1
-  data.tar.gz: cd6e0ad73493fd5dd7e56dff790ed22dafa31a32d2f2347fb263cb4d6177aef4e83aaab7127ad28899d30802ffdddd6b83415f57ae27f2fc8dc2001494cd86cf
+  metadata.gz: f21efa7866b7eeb455fb4e7a8c64465bcd41a498d6129f04220c69eb814178f92775aeb96ef0e2a972f6df481d4603acf6e3de7c728e6508262347012cfb20cc
+  data.tar.gz: 956306465a135039e185104bb81cf504af379265814b5a02ba4637c3a6412463ce655aa48bae66e1f3315fd8c90925899c2ca0afda9fbf6a795c66b35e339967

data/docs/application.md

@@ -30,6 +30,8 @@ gloo [global option] [file]
 
 Running gloo with a file specified will run that file. Once that file is done, gloo will quit. However, by specifying `--cli`, once the file has finished, gloo will remain open in CLI mode.
 
+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 not found: {name}` to stderr and exits with a non-zero status. Any other load or run error also exits non-zero, so a shell script calling gloo can tell a failed run from a clean one.
+
 When specifying a file there are a couple ways to reference the gloo file to open:
 
 - By Path
@@ -101,6 +103,13 @@ gloo:
   #
   list_levels: 3
 
+  #
+  # When listing the object tree, also show each object's doc (the
+  # comment declared immediately above it in its source file), if it
+  # has one.
+  #
+  list_docs: false
+
   #
   # Show debug statements in the log?
   #

data/docs/language_objects.md

@@ -70,6 +70,46 @@ page.core.users.list [container] :
 - Indented lines below a shorthand declaration are children of the last
   segment (`list` above), not of any prefix container.
 
+## Documenting an Object
+
+A contiguous run of whole-line comments immediately above a declaration,
+at the same indent and with no blank line in between, is that object's
+**doc** — read it back at run time with `tell {obj} to doc` or
+`check {obj} for doc` (the cleaned text lands in `it`, like any other
+value-returning message):
+
+```gloo
+#
+# The user's display name. Empty until they set it in preferences.
+#
+name [string] :
+```
+
+```gloo
+> check name for doc
+> show it
+
+The user's display name. Empty until they set it in preferences.
+
+```
+
+Each line's own leading whitespace and `#` marker (plus one space after
+it, if there is one) are stripped, and the result is dedented to its
+shallowest line — but otherwise the full block is kept exactly as
+written, blank `#` lines above and below the text included. An object
+with no leading comment — including anything created at run time rather
+than loaded from a file — has a blank doc (`''`).
+
+A comment separated from the declaration by a blank line, or at a
+different indent, is not associated with it — it's kept as its own
+floating comment in the file instead. When a name is declared in more
+than one loaded file, the first non-empty doc wins (same rule as the
+first value).
+
+`list` can show every documented object in a listed tree: turn on the
+`list_docs` setting (off by default) — see `list` and `settings` in the
+in-app help.
+
 ## Keywords
 
 Gloo doesn't reserve words the way many languages do. A verb keyword like `put` or an object type name like `string` can also be used as an object name — there's no parser conflict, because verbs are only looked up as the first word of a statement, and object type names are only looked up where a type is expected (inside the `[ ]` on a declaration). Everywhere else, the word is just a pathname segment (see Object Naming, above).

data/docs/objects.md

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

data/docs/verbs.md

@@ -51,6 +51,13 @@ tell {path.to.object} to {message}
 > if it then show 'it does'
 ```
 
+`doc` is one such message every object responds to: it returns the comment block declared immediately above it in its source file, cleaned up (see Language, Objects — Documenting an Object).
+
+```gloo
+> tell my.obj to doc
+> show it
+```
+
 ## Put
 
 `put` evaluates an expression and stores the result in an object.
@@ -78,6 +85,8 @@ put {expression} into {dst.path}
 > load ~/.my_app/settings.gloo
 ```
 
+If the name can't be resolved to a file, `load` reports `File not found: {name}` — it fires `on_error` and, when the file was named on the `gloo` command line, prints the message to stderr and exits non-zero. A bad or missing file never fails silently.
+
 `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 saves to a new file and remembers the mapping.
 
 ```gloo

data/lib/VERSION

@@ -1 +1 @@
-6.4.0
+6.5.1

data/lib/VERSION_NOTES

@@ -1,3 +1,14 @@
+6.5.1 - 2026.09.11
+ - Adds doc to the load verb for recent changes.
+
+
+6.5.0 - 2026.09.11
+  - Adds option to show comments from the list verb.
+	  - Adds message to get doc for an object.
+  - Report error if the file to load can't be found.
+  - Fixes issue with multisegment root level object.
+
+
 6.4.0 - 2026.09.06
  - Persistance refresh with updates for loading and saving
  - Nested container shortcut syntax

data/lib/gloo/app/engine.rb

@@ -134,11 +134,15 @@ module Gloo
 
       #
       # Run files specified on the CLI.
-      # Then quit.
+      # Then quit, with a non-zero exit code if any file failed to
+      # load (missing, unresolvable, or errored on load) so that a
+      # calling shell script can tell a bad run from a good one.
       #
       def run_files
         load_files
+        failed = error?
         quit
+        exit( 1 ) if failed
       end
 
       # 

data/lib/gloo/app/log.rb

@@ -167,7 +167,7 @@ module Gloo
       #
       # Write an error message to the log and set the error
       # in the engine's data heap.
-      # Also write to the console unless quiet.
+      # Also write to the console (on stderr) unless quiet.
       #
       def error( msg, ex = nil, engine = nil )
         engine&.heap&.error&.set_to( msg ) if engine
@@ -176,11 +176,11 @@ module Gloo
         if ex
           @error.error ex.message
           @error.error ex.backtrace
-          puts @theme.error( msg ) unless @quiet
-          puts @theme.error( ex.message ) unless @quiet
-          puts ex.backtrace unless @quiet
+          $stderr.puts @theme.error( msg ) unless @quiet
+          $stderr.puts @theme.error( ex.message ) unless @quiet
+          $stderr.puts ex.backtrace unless @quiet
         else
-          puts @theme.error( msg ) unless @quiet
+          $stderr.puts @theme.error( msg ) unless @quiet
         end
       end
 

data/lib/gloo/app/settings.rb

@@ -15,7 +15,7 @@ module Gloo
 
       attr_reader :user_root, :log_path,
         :config_path, :project_path, :ext_path,
-        :start_with, :list_indent, :list_levels, :tmp_path,
+        :start_with, :list_indent, :list_levels, :list_docs, :tmp_path,
         :debug_path, :debug, :theme
 
       #
@@ -41,6 +41,7 @@ module Gloo
         puts theme.accent( '   Startup with:  ' ) + theme.emphasis( @start_with.to_s )
         puts theme.accent( '   Indent in Listing:  ' ) + theme.emphasis( @list_indent.to_s )
         puts theme.accent( '   List Levels:  ' ) + theme.emphasis( @list_levels.to_s )
+        puts theme.accent( '   List Docs:  ' ) + theme.emphasis( @list_docs.to_s )
         puts theme.accent( '   Debug?  ' ) + theme.emphasis( @debug.to_s )
         puts theme.accent( '   Theme:  ' ) + theme.emphasis( @theme )
         puts theme.accent( '   Screen Lines:  ' ) + theme.emphasis( Gloo::App::Settings.lines( @engine ).to_s )
@@ -158,6 +159,7 @@ module Gloo
         @start_with = settings[ 'gloo' ][ 'start_with' ]
         @list_indent = settings[ 'gloo' ][ 'list_indent' ]
         @list_levels = settings[ 'gloo' ][ 'list_levels' ]
+        @list_docs = settings[ 'gloo' ][ 'list_docs' ] == true
 
         @debug = settings[ 'gloo' ][ 'debug' ]
 
@@ -192,6 +194,7 @@ module Gloo
             start_with:
             list_indent: 2
             list_levels: 3
+            list_docs: false
             debug: false
             theme: #{DEFAULT_THEME}
         TEXT

data/lib/gloo/core/obj.rb

@@ -12,12 +12,21 @@ module Gloo
       attr_accessor :value
       attr_reader :children, :parent
 
+      # The object's documentation: the cleaned comment block declared
+      # immediately above it in its source file (Source::ObjNode#doc),
+      # copied on at load time by FileLoader. '' for an object with no
+      # such comment, or one created at run time. Loader-set only --
+      # there's no verb/message path to change it, so it can't drift
+      # from what the file actually says.
+      attr_accessor :doc
+
       #
       # Set up the object.
       #
       def initialize( engine )
         @engine = engine
         @value = ''
+        @doc = ''
         @children = []
         @parent = nil
       end
@@ -329,7 +338,7 @@ module Gloo
       # Get a list of message names that this object receives.
       #
       def self.messages
-        return %w[save reload unload blank? contains? responds_to?]
+        return %w[save reload unload blank? contains? responds_to? doc]
       end
 
       #
@@ -445,6 +454,17 @@ module Gloo
         end
       end
 
+      #
+      # Get this object's documentation -- the comment block declared
+      # immediately above it in its source file, cleaned up. Puts the
+      # result into 'it' rather than printing, same as other
+      # value-returning messages (count, down, blank?, ...).
+      #
+      def msg_doc
+        @engine.heap.it.set_to self.doc
+        return self.doc
+      end
+
 
       # ---------------------------------------------------------------------
       #    Render

data/lib/gloo/persist/file_loader.rb

@@ -226,6 +226,13 @@ module Gloo
 
         node = build_obj_node( leading_ws( line ), name, type, value, style )
         node.leading_doc = @comments.take_leading_doc( line_tabs, @indent_stack.node.children )
+        # First non-empty doc wins, same as "first value wins" for a
+        # name re-declared across files -- @last is the same object
+        # across re-declarations (the factory returns the existing
+        # one), so a later, comment-less re-declaration doesn't blank
+        # out an earlier file's doc. @last can be nil for an unknown
+        # type (factory.create logs a warning and returns nil).
+        @last.doc = node.doc if @last && @last.doc.to_s.strip.empty?
         @indent_stack.node.children << node
         @last_node = node
         @obj ||= @ledger.roots.last || @last

data/lib/gloo/persist/persist_man.rb

@@ -15,6 +15,7 @@ module Gloo
       OBJ_NOT_FOUND_ERR = 'Could not resolve object to save: '.freeze
       PATH_EXISTS_ERR = 'Will not overwrite a file not already saved there: '.freeze
       RELOAD_DIRTY_WARNING = 'Reloading will discard unsaved changes in: '.freeze
+      FILE_NOT_FOUND_ERR = 'File not found: '.freeze
 
       #
       # Constructor for the persistence manager.
@@ -75,12 +76,20 @@ module Gloo
       end
 
       #
-      # Load the object from the file.
+      # Load the object(s) from the file (or files, for a wildcard).
+      # Returns true if at least one object was loaded, false if the
+      # name couldn't be resolved to any file or nothing loaded --
+      # a missing/unresolvable file is reported via engine.err rather
+      # than failing silently.
       #
       def load( name )
         pns = get_full_path_names name
-        return unless pns
+        if pns.nil? || pns.empty?
+          @engine.err( "#{FILE_NOT_FOUND_ERR}#{name}" ) unless name.to_s.strip.empty?
+          return false
+        end
 
+        loaded = false
         pns.each do |pn|
           @engine.log.debug "Load file(s) at: #{pn}"
           begin
@@ -90,10 +99,12 @@ module Gloo
 
             @maps << fs
             @engine.event_manager.on_load fs.obj
+            loaded = true
           rescue => ex
             @engine.handle_exception( ex )
           end
         end
+        return loaded
       end
 
       # 
@@ -273,11 +284,32 @@ module Gloo
         nodes.each do |node|
           next unless node.is_a?( Gloo::Persist::Source::ObjNode )
 
-          owned[ node.obj ] = true if node.obj
+          if node.obj
+            owned[ node.obj ] = true
+            mark_shorthand_ancestors( node, owned )
+          end
           collect_owned( node.children, owned )
         end
       end
 
+      #
+      # A nested-container shorthand declaration (a.b.c [type] :) only
+      # records a source node for the leaf; the intermediate containers
+      # (a, a.b) are real heap objects with no node of their own. Mark
+      # them owned too, walking up from the leaf, so another file's save
+      # doesn't see an intermediate as an orphan and adopt its whole
+      # subtree.
+      #
+      def mark_shorthand_ancestors( node, owned )
+        return unless node.name.include?( '.' )
+
+        o = node.obj.parent
+        while o && !o.root?
+          owned[ o ] = true
+          o = o.parent
+        end
+      end
+
       #
       # Save to a path that's already mapped to some file. If that
       # mapping is for a different root, it's a real collision -- the

data/lib/gloo/persist/source/obj_node.rb

@@ -44,6 +44,47 @@ module Gloo
           @children = []
         end
 
+        #
+        # The cleaned-up leading_doc: each line's leading whitespace and
+        # its '#' marker (plus one following space, if any) stripped,
+        # then the result dedented to its shallowest line. The full
+        # block is kept as written, blank '#' lines at the top/bottom
+        # included -- it's a faithful reproduction of the comment, not
+        # a trimmed summary. '' when there's no leading_doc at all.
+        #
+        def doc
+          return '' unless @leading_doc
+
+          lines = @leading_doc.split( "\n" ).map { |l| strip_marker( l ) }
+          return dedent( lines ).join( "\n" )
+        end
+
+        private
+
+        #
+        # One raw comment line -> its text past the '#': leading
+        # whitespace dropped, then the '#' and at most one space after
+        # it, then trailing whitespace dropped.
+        #
+        def strip_marker( raw )
+          return raw.lstrip.sub( /\A#\x20?/, '' ).rstrip
+        end
+
+        #
+        # Remove the common leading whitespace shared by every non-blank
+        # line, so a comment block indented for readability (eg. a
+        # bullet list within it) keeps its relative indentation.
+        #
+        def dedent( lines )
+          non_blank = lines.reject( &:empty? )
+          return lines if non_blank.empty?
+
+          n = non_blank.map { |l| l[ /\A */ ].length }.min
+          return lines if n.zero?
+
+          return lines.map { |l| l.empty? ? l : l[ n.. ] }
+        end
+
       end
     end
   end

data/lib/gloo/verbs/list.rb

@@ -74,6 +74,7 @@ module Gloo
       #
       def show_obj( obj, indent = '  ' )
         theme = @engine.theme
+        show_doc( obj, indent ) if @engine.settings.list_docs
         if obj.multiline_value? && obj.value_is_array?
           str = theme.emphasis( "#{indent}#{obj.name}" )
           str << theme.accent( " [#{obj.type_display}] : " )
@@ -89,6 +90,23 @@ module Gloo
         end
       end
 
+      #
+      # Show the object's doc (its leading comment, cleaned up) above
+      # its listing line, one '#'-prefixed line per line of doc.
+      # Silent when the object has none.
+      #
+      def show_doc( obj, indent )
+        return if obj.doc.to_s.strip.empty?
+
+        theme = @engine.theme
+        # split( -1 ), not each_line -- a doc ending in a blank '#' line
+        # ends with "\n", and each_line silently drops that trailing
+        # empty line rather than yielding it.
+        obj.doc.split( "\n", -1 ).each do |line|
+          @engine.log.show theme.muted( "#{indent}# #{line}".rstrip )
+        end
+      end
+
       #
       # Determine how many levels to show.
       #
@@ -130,12 +148,16 @@ module Gloo
             'current context. When a path is provided, it will be ' \
             'listed instead of the current context. When using context, ' \
             'the current context will be shown, but when context has ' \
-            'not been set, the root will be shown.',
+            'not been set, the root will be shown. When the list_docs ' \
+            'setting is on, any listed object that has a doc (the ' \
+            'comment block declared immediately above it in its source ' \
+            'file) shows it too.',
           :syntax => [ 'list {path.to.object}' ],
           :parameters => [
             '{path.to.object} — Optional path to object that will be listed. When no path is provided, the current context is used.'
           ],
-          :result => 'Object and children are listed out in the CLI.',
+          :result => 'Object and children are listed out in the CLI. ' \
+            'Doc lines are included when the list_docs setting is on.',
           :errors => [
             "#{TARGET_MISSING_ERR}{path.to.object} — The object specified that is to be listed could not be found."
           ],

data/lib/gloo/verbs/load.rb

@@ -122,13 +122,24 @@ module Gloo
           :errors => [
             "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb.",
             "#{UNKNOWN_OPT_ERR} — The reference type given isn't file, ext, or lib.",
-            "#{WRONG_NUM_ARGS_ERR} — load expects 2 or 3 arguments (the verb, an optional reference type, and the file/ext/lib name)."
+            "#{WRONG_NUM_ARGS_ERR} — load expects 2 or 3 arguments (the verb, an optional reference type, and the file/ext/lib name).",
+            'File not found: {name} — The file name given could not be ' \
+              'resolved to a gloo file (checked as a full path, and ' \
+              'relative to the project and gloo root folders).'
           ],
           :notes => 'Several files can contribute to one container: ' \
             'declare it in each file and add different children, and ' \
             'they merge in the heap. If two loaded files declare the ' \
             'same object with different values, the first one loaded ' \
-            'wins and a warning is logged.',
+            "wins and a warning is logged.\n\n" \
+            'A contiguous run of whole-line comments declared ' \
+            'immediately above an object (same indent, no blank line ' \
+            "in between) becomes that object's doc, captured as the " \
+            'file loads. Read it back with tell {obj} to doc or ' \
+            'check {obj} for doc, or see it inline in the object tree ' \
+            'with list when the list_docs setting is on. When a name ' \
+            'is declared in more than one loaded file, the first ' \
+            'non-empty doc wins, same as the first value.',
           :examples => <<~EXAMPLES.strip
             > load my/project/file
             > load my/app/*

data/test.gloo/ctrl/each.test.gloo

@@ -2,38 +2,36 @@
 # Each and repeat control object tests
 #
 
-tests [can] :
-  ctrl [can] :
-    each [can] :
+tests.ctrl.each [can] :
 
-      count [int] : 0
+  count [int] : 0
 
-      wrd [each] :
-        word [string] :
-        IN [string] : one two three
-        do [script] :
-          eval ^^.count + 1
-          put it into ^^.count
+  wrd [each] :
+    word [string] :
+    IN [string] : one two three
+    do [script] :
+      eval ^^.count + 1
+      put it into ^^.count
 
-      rpt [repeat] :
-        times [int] : 3
-        index [int] : 0
-        do [script] :
-          eval ^^.count + 1
-          put it into ^^.count
+  rpt [repeat] :
+    times [int] : 3
+    index [int] : 0
+    do [script] :
+      eval ^^.count + 1
+      put it into ^^.count
 
-      each_word [test] :
-        description [string] : Count words with each word
-        on_test [script] :
-          put 0 into ^^.count
-          tell ^^.wrd to run
-          eval ^^.count = 3
-          assert "expected 3 words counted"
+  each_word [test] :
+    description [string] : Count words with each word
+    on_test [script] :
+      put 0 into ^^.count
+      tell ^^.wrd to run
+      eval ^^.count = 3
+      assert "expected 3 words counted"
 
-      repeat_n_times [test] :
-        description [string] : Repeat a script n times
-        on_test [script] :
-          put 0 into ^^.count
-          tell ^^.rpt to run
-          eval ^^.count = 3
-          assert "expected repeat to run 3 times"
+  repeat_n_times [test] :
+    description [string] : Repeat a script n times
+    on_test [script] :
+      put 0 into ^^.count
+      tell ^^.rpt to run
+      eval ^^.count = 3
+      assert "expected repeat to run 3 times"