gloo 6.5.1 → 6.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19bd707a24eb9bbd3e2759cdb2ae244d2dafc28f40c0f4046c856152e343261c
-  data.tar.gz: fd3fd34b664abb32a464d3745de0ede24e136f2b2a7f375809170312bbec51a1
+  metadata.gz: 7bec0a2a7c9eb15015734a7610359cc6b7c18abbc9abbb239131f9fad9927fcf
+  data.tar.gz: a9d8810c5581416608f4913d1cd7f1b24e385fb4b1d47b74eb5e1dcd8aaafd47
 SHA512:
-  metadata.gz: f21efa7866b7eeb455fb4e7a8c64465bcd41a498d6129f04220c69eb814178f92775aeb96ef0e2a972f6df481d4603acf6e3de7c728e6508262347012cfb20cc
-  data.tar.gz: 956306465a135039e185104bb81cf504af379265814b5a02ba4637c3a6412463ce655aa48bae66e1f3315fd8c90925899c2ca0afda9fbf6a795c66b35e339967
+  metadata.gz: 17694e6f6a9019c0071248eb4c59ab80ffba8c352b7aa5341eeca150d0503e5176eabc0e00a0214d8a99c24e98fa045138dfb7783bb55c1c30198f0704235cec
+  data.tar.gz: 6cff2396f6bdc2debed6ab6f03a43e5932a1fa4c5a54a07c40b0e5d18f3686721ca9ae90e05d60ea26fc416c93f66e1acb05de9141e9777afec78406c17181a6

data/docs/application.md

@@ -88,6 +88,8 @@ gloo:
   #
   # Run this script when starting up gloo.
   # (Only if a script file is not specified.)
+  # A bare filename (no path) is looked up in the config directory
+  # above. Either way, the .gloo extension is assumed if left off.
   #
   start_with:
 

data/docs/verbs.md

@@ -87,16 +87,20 @@ put {expression} into {dst.path}
 
 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.
+`save` writes loaded objects back to their files. With no argument it saves every open file; with an object it saves the file (or files) that object's tree came from; with `to {path}` it **extracts** — moves the object (and its descendants) out of whichever file currently owns them, into a new file, under their full dotted path.
 
 ```gloo
 > save                        # every open file
 > save config                 # just config's file
-> save config to backups/config
+> save app.core.settings to config/settings
 ```
 
 A save is a **rewrite, not a regeneration**: comments, blank lines, and the original spacing are kept, and only the values you actually changed are re-written. A declaration you never touched comes back byte-for-byte.
 
+`save {obj} to {path}` doesn't just write a copy — `obj` stops being declared in its old file, wherever that was. Given `app.core.settings` declared inside `app.gloo`, `save app.core.settings to config/settings` leaves `app.gloo` without a `settings` subtree and writes `config/settings.gloo` with `app.core.settings [can] : ...` at the top level (the `app`/`core` prefix is implied via nested-container shorthand, not repeated as nested declarations) plus everything `settings` owns underneath, comments included. An object with no file of its own yet (brand new, or nested under an object that's never been saved) is simply written fresh — nothing to move.
+
+If `obj`'s own subtree already has declarations spread across more than one file (the namespace-merge pattern below, applied *inside* the subtree being extracted, not just above it), extraction refuses rather than guessing which file's slice is authoritative — save each contributing file on its own first.
+
 Several files can contribute to one container — declare `app [container] :` in each and add different children. They merge in the heap, and each file's save only rewrites its own declarations. If two files declare the *same* object with different values, the first one loaded wins and `load` logs a warning.
 
 An object can also save itself: `tell config to save`.

data/lib/VERSION

@@ -1 +1 @@
-6.5.1
+6.7.0

data/lib/VERSION_NOTES

@@ -1,3 +1,15 @@
+6.7.0 - 2026.09.13
+ - Adds alternative secondary keywords for conditional verbs.
+ - Adds option to save an object subtree into its own file.
+ - Fixes issue with load and save comments and blank lines.
+
+
+6.6.0 - 2026.09.12
+ - Allow shortcut reference for start file in configuration directory.
+ - Adds word wrap message for strings and text.
+ - Adds line wrapping for object comments and help documentation.
+
+
 6.5.1 - 2026.09.11
  - Adds doc to the load verb for recent changes.
 

data/lib/gloo/app/engine.rb

@@ -207,7 +207,9 @@ module Gloo
         end
 
         name = @settings.start_with
-        @persist_man.load( name ) if name
+        return if name.blank?
+
+        @persist_man.load( resolve_start_with( name ) )
       end
 
       #
@@ -382,6 +384,20 @@ module Gloo
 
       private
 
+      #
+      # Resolve the start_with setting to a loadable name/path.
+      # A bare filename (no directory separator) is resolved against
+      # the config directory rather than the project path, and the
+      # .gloo extension is assumed when not given.
+      #
+      def resolve_start_with( name )
+        ext = @persist_man.file_ext
+        name = "#{name}#{ext}" unless name.end_with?( ext )
+        return name if name.include?( File::SEPARATOR )
+
+        return File.join( @settings.config_path, name )
+      end
+
       #
       # Get the stack trace as a string, truncating the middle if it's long.
       #

data/lib/gloo/app/settings.rb

@@ -189,13 +189,53 @@ module Gloo
       def get_default_settings
         projects = File.join( @user_root, 'projects' )
         str = <<~TEXT
+          #
+          # Gloo configuration
+          #
           gloo:
+
+            #
+            # Root directory for projects.
+            # Update this with the directory with your gloo projects.
+            #
             project_path: #{projects}
+
+            #
+            # Run this script when starting up gloo.
+            # (Only if a script file is not specified.)
+            # A bare filename (no path) is looked up in the config directory
+            # above. Either way, the .gloo extension is assumed if left off.
+            #
             start_with:
+
+            #
+            # Indentation (spaces) when showing an object outline.
+            #
             list_indent: 2
+
+            #
+            # Show listing the object tree,
+            # how many levels of children will be shown?
+            # Children at deeper levels will be hidden.
+            #
             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?
+            #
             debug: false
+
+            #
+            # Color theme for console output: dark or light.
+            # Match this to your terminal's background.
+            #
             theme: #{DEFAULT_THEME}
         TEXT
         return str

data/lib/gloo/core/tokens.rb

@@ -88,12 +88,18 @@ module Gloo
       end
 
       #
-      # Get the index of the given token.
+      # Get the index of the given token. token may also be an array
+      # of candidate keywords -- e.g. [ 'then', 'do' ] -- in which
+      # case the index of whichever one occurs earliest in the token
+      # stream wins (not just whichever is present). This lets a
+      # caller treat several spellings of the same separator as
+      # interchangeable while still keying the split on the first one
+      # actually used (see If/Unless's 'then'/'do').
       #
       def index_of( token )
         return nil unless @tokens
 
-        return @tokens.find_index { |o| o.casecmp( token ).zero? }
+        return Array( token ).filter_map { |t| @tokens.find_index { |o| o.casecmp( t ).zero? } }.min
       end
 
       #

data/lib/gloo/docs/help_shell.rb

@@ -24,6 +24,10 @@ module Gloo
       README_GLOB = 'README*'.freeze
       NO_README_YET = 'No README found for library'.freeze
 
+      # Matches a (possibly indented) markdown bullet line, capturing
+      # its leading whitespace and the text after '- '.
+      BULLET_RE = /\A(\s*)-\s+(.*)\z/.freeze
+
       #
       # Initialize the help shell for the given engine.
       #
@@ -249,10 +253,51 @@ module Gloo
       #
       def page_markdown( md )
         rule = '-' * @engine.platform.cols
-        bracketed = "#{rule}\n#{md.strip}\n#{rule}\n"
+        wrapped = wrap_markdown_for_terminal( md.strip )
+        bracketed = "#{rule}\n#{wrapped}\n#{rule}\n"
         @engine.platform.page( Gloo::Docs::MarkdownRenderer.colorize( bracketed, @engine.theme ) )
       end
 
+      #
+      # Word-wrap plain (pre-color) markdown to the terminal width.
+      # Headings and fenced code blocks are left untouched (code is
+      # never rewrapped); a bullet line's continuation lines are
+      # indented to line up under its text, not under the '-' itself
+      # -- same convention as List#show_doc's doc-line wrapping.
+      #
+      def wrap_markdown_for_terminal( md )
+        width = Gloo::App::Settings.cols( @engine )
+        in_code_fence = false
+        lines = md.split( "\n", -1 ).flat_map do |line|
+          if line.strip.start_with?( '```' )
+            in_code_fence = !in_code_fence
+            next [ line ]
+          end
+          next [ line ] if in_code_fence || line.start_with?( '#' ) || line.strip.empty?
+
+          wrap_markdown_line( line, width )
+        end
+        return lines.join( "\n" )
+      end
+
+      #
+      # Wrap one prose or bullet markdown line to width. A bullet's
+      # continuation lines get a blank-space prefix the same length as
+      # its '{indent}- ', so wrapped text lines up under the bullet's
+      # own text.
+      #
+      def wrap_markdown_line( line, width )
+        match = BULLET_RE.match( line )
+        prefix = match ? "#{match[1]}- " : ''
+        text = match ? match[2] : line
+        cont_indent = ' ' * prefix.length
+
+        wrapped = Gloo::Objs::WordWrap.wrap( text, width - prefix.length )
+        # "".split( "\n", -1 ) is [], not [ '' ] -- keep a blank line as one piece.
+        pieces = wrapped.empty? ? [ '' ] : wrapped.split( "\n", -1 )
+        return pieces.each_with_index.map { |piece, i| "#{i.zero? ? prefix : cont_indent}#{piece}" }
+      end
+
       #
       # Snapshot the verb, object type, doc page, and loaded library
       # names for tab-completion.

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

@@ -55,6 +55,7 @@ module Gloo
           'splitl ({index}) — Get the substring to the left of index {index} (same as split (0, {index})). A parameter is required. Does not change the value of the string. It will have the substring.',
           'splitr ({index}) — Get the substring from index {index} to the end of the string (same as split ({index}, size)). A parameter is required. Does not change the value of the string. It will have the substring.',
           'split_list ({delim} {dst.path}) — Split the string by {delim} and put the parts into children of the container at {dst.path} (or an alias that points to one), one part per child, in order. Existing children are matched by position and have their values set; extra parts get new (untyped) children, numbered from 1; extra existing children are left alone. Both parameters are required. Does not change the value of the string. It will have the number of parts.',
+          'word_wrap ({width}) — Word-wrap the string to {width} columns, breaking on whitespace (never mid-word; an overlong word is left on its own line rather than broken). The {width} parameter is optional; it defaults to the terminal\'s current width. This message changes the value of the string. It will have the wrapped string.',
           'page — Show the value in a pager (less), for viewing long content a screen at a time.'
         ]
       end
@@ -481,6 +482,25 @@ module Gloo
         return s
       end
 
+      #
+      # Word-wrap the string to the given column width, breaking on
+      # whitespace. Defaults to the terminal's current width when no
+      # width parameter is given.
+      #
+      def msg_word_wrap
+        width = Gloo::App::Settings.cols( @engine )
+        if @params&.token_count&.positive?
+          expr = Gloo::Expr::Expression.new( @engine, @params.tokens )
+          data = expr.evaluate
+          width = data.to_i
+        end
+
+        s = Gloo::Objs::WordWrap.wrap( value, width )
+        set_value s
+        @engine.heap.it.set_to s
+        return s
+      end
+
       #
       # Show the value in a pager, for long content.
       #

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

@@ -0,0 +1,58 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Word-wrapping utility.
+# This is a static class.
+#
+
+module Gloo
+  module Objs
+    class WordWrap
+
+      # ---------------------------------------------------------------------
+      #    Wrapping
+      # ---------------------------------------------------------------------
+
+      #
+      # Wrap the given text to the given column width.
+      # Greedy word-wrap: breaks on whitespace, never mid-word. A single
+      # word longer than the width is left on its own line rather than
+      # being hard-broken (e.g. a URL stays intact, just overflows).
+      # Existing line breaks in the text are preserved -- each line is
+      # wrapped independently, so blank lines and paragraph breaks survive.
+      #
+      def self.wrap( text, width )
+        return text.to_s if width.to_i <= 0
+
+        text.to_s.split( "\n", -1 ).map { |line| wrap_line( line, width ) }.join( "\n" )
+      end
+
+      # ---------------------------------------------------------------------
+      #    Private
+      # ---------------------------------------------------------------------
+
+      #
+      # Wrap a single line (no embedded newlines) to the given width.
+      #
+      def self.wrap_line( line, width )
+        words = line.split( ' ' )
+        return line if words.empty?
+
+        lines = []
+        current = words.shift
+        words.each do |word|
+          if "#{current} #{word}".length > width
+            lines << current
+            current = word
+          else
+            current = "#{current} #{word}"
+          end
+        end
+        lines << current
+        return lines.join( "\n" )
+      end
+      private_class_method :wrap_line
+
+    end
+  end
+end

data/lib/gloo/persist/file_loader.rb

@@ -7,7 +7,7 @@
 # raw formatting) -- so a later save can rewrite the file instead of
 # regenerating it from scratch.
 #
-# Work is delegated to CommentBuffer (comment buffering),
+# Work is delegated to TriviaBuffer (comment/blank-line buffering),
 # ScriptBodyCollector (script bodies), IndentStack (nesting shared by
 # the heap and source trees), ShorthandExpander (nested-container
 # shorthand), and DeclarationLedger (this file's roots + cross-file
@@ -42,7 +42,7 @@ module Gloo
         @pn = pn
         @obj = nil
         @source_doc = Gloo::Persist::Source::SourceDoc.new
-        @comments = Gloo::Persist::CommentBuffer.new
+        @trivia = Gloo::Persist::TriviaBuffer.new
         @body = Gloo::Persist::ScriptBodyCollector.new
         @shorthand = Gloo::Persist::ShorthandExpander.new( engine )
         @ledger = Gloo::Persist::DeclarationLedger.new( engine, pn )
@@ -126,7 +126,7 @@ module Gloo
       #
       def finish
         @body.finish
-        @comments.flush_into( @indent_stack.node.children )
+        @trivia.flush_into( @indent_stack.node.children )
       end
 
       # ---------------------------------------------------------------------
@@ -134,18 +134,22 @@ module Gloo
       # ---------------------------------------------------------------------
 
       #
-      # A comment or blank line, outside of any block/body. A comment
-      # is buffered -- it may turn out to be the leading_doc for the
-      # declaration that follows. A blank line always breaks that
-      # association (detaches any buffered comments as floating nodes)
-      # and is itself kept, not discarded.
+      # A comment or blank line, outside of any block/body. Both are
+      # buffered, not placed immediately: a container's own declaration
+      # line doesn't push it as the current node (see IndentStack) until
+      # a genuinely deeper line is seen, so a comment/blank sitting
+      # between the container and its first child has to wait for that
+      # push before it's resolved against the *correct* node -- placing
+      # it against whatever's current right now would land it one level
+      # too shallow. TriviaBuffer#take_leading_doc/#flush_into do that
+      # resolving once the right moment comes (the next declaration, or
+      # end of file).
       #
       def handle_trivia_line( line )
         if line.strip.empty?
-          @comments.flush_into( @indent_stack.node.children )
-          @indent_stack.node.children << Source::BlankNode.new( chomped( line ) )
+          @trivia.push_blank( chomped( line ) )
         else
-          @comments.push( chomped( line ), tab_count( line ) )
+          @trivia.push_comment( chomped( line ), tab_count( line ) )
         end
       end
 
@@ -225,7 +229,7 @@ module Gloo
         @ledger.root( @last ) if parent == @engine.heap.root
 
         node = build_obj_node( leading_ws( line ), name, type, value, style )
-        node.leading_doc = @comments.take_leading_doc( line_tabs, @indent_stack.node.children )
+        node.leading_doc = @trivia.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

data/lib/gloo/persist/file_storage.rb

@@ -11,14 +11,18 @@ module Gloo
       attr_reader :obj, :pn, :roots, :source_doc
 
       #
-      # Set up a file storage for an object.
+      # Set up a file storage for an object. source_doc is optional --
+      # pass one already built (eg. a subtree just extracted into this
+      # file by save {obj} to {path}) so this file's saves rewrite it
+      # in place instead of falling back to plain regeneration; a
+      # bare/never-loaded FileStorage leaves it nil.
       #
-      def initialize( engine, pn, obj = nil )
+      def initialize( engine, pn, obj = nil, source_doc = nil )
         @engine = engine
         @obj = obj
         @pn = pn
         @roots = obj ? [ obj ] : []
-        @source_doc = nil
+        @source_doc = source_doc
       end
 
       #
@@ -31,6 +35,19 @@ module Gloo
         fs.save
       end
 
+      #
+      # This file no longer owns obj as one of its roots -- eg. it was
+      # just extracted into a different file via save {obj} to {path}.
+      # Drops it from roots, and re-points the file's primary obj at
+      # whatever root remains (nil if none left), so a later
+      # single-object reload/save doesn't act on a root that's moved
+      # elsewhere.
+      #
+      def drop_root( obj )
+        @roots.delete( obj )
+        @obj = @roots.first if @obj&.equal?( obj )
+      end
+
       #
       # Load the object from the file.
       #

data/lib/gloo/persist/persist_man.rb

@@ -63,6 +63,13 @@ module Gloo
       # mapping so a future bare save includes it. Refuses to overwrite
       # a file that exists but isn't already mapped to this object.
       #
+      # Unlike a bare save, this extracts: obj's own declaration (and
+      # its descendants) move out of whichever file currently owns
+      # them into the new file -- they don't stay declared in both
+      # places. An object with no file of its own yet (brand new, or
+      # already mapped as part of some root shared with unrelated
+      # objects) is simply written fresh; nothing to remove.
+      #
       def save_to( name, path )
         obj = resolve_for_save( name )
         return unless obj
@@ -72,7 +79,7 @@ module Gloo
         return save_mapped( obj, mapped, pn ) if mapped
         return @engine.err( "#{PATH_EXISTS_ERR}#{pn}" ) if @mech.exist?( pn )
 
-        save_new( obj, pn )
+        extract_to( obj, pn )
       end
 
       #
@@ -333,6 +340,29 @@ module Gloo
         @maps << fs
       end
 
+      #
+      # Extract obj's declaration into a brand-new file at pn: pulled
+      # out of whichever file currently owns it (that file loses it and
+      # gets re-saved), or written fresh if it had no file of its own.
+      # Both saves go through the same save_batch so each correctly
+      # treats the other's declarations as "owned elsewhere" rather
+      # than orphaned/new.
+      #
+      def extract_to( obj, pn )
+        node, source_fs = Gloo::Persist::SubtreeExtractor.new( @engine ).extract( obj, @maps )
+        return unless node
+
+        @engine.event_manager.on_save obj
+        source_doc = Gloo::Persist::Source::SourceDoc.new
+        source_doc.children << node
+
+        target_fs = Gloo::Persist::FileStorage.new( @engine, pn, obj, source_doc )
+        @maps << target_fs
+        # New file first: if writing it fails, the old file (source_fs)
+        # hasn't been touched on disk yet, so nothing is lost.
+        save_batch( [ target_fs, source_fs ].compact )
+      end
+
       #
       # Warn (without blocking) if reloading fs would discard changes
       # that haven't been saved -- any object whose value no longer

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

@@ -35,6 +35,42 @@ module Gloo
           return @children.select { |n| n.is_a?( Source::ObjNode ) }
         end
 
+        #
+        # Find and remove the node for the given heap object, searching
+        # this document's whole tree (not just the top level) -- used to
+        # move a subtree into a different file (see save {obj} to
+        # {path}). Returns the removed node, still carrying its own
+        # children/leading_doc, or nil if this document has no node for
+        # that object (it may be owned by a different file, or never
+        # have had a declaration of its own -- eg. a nested-container
+        # shorthand's auto-created intermediate).
+        #
+        def extract( obj )
+          return remove_matching( @children, obj )
+        end
+
+        private
+
+        #
+        # Depth-first search of nodes (and their children) for the one
+        # linked to obj; removes it from whichever children array it's
+        # actually in and returns it.
+        #
+        def remove_matching( nodes, obj )
+          nodes.each do |node|
+            next unless node.is_a?( Source::ObjNode )
+
+            if node.obj&.equal?( obj )
+              nodes.delete( node )
+              return node
+            end
+
+            found = remove_matching( node.children, obj )
+            return found if found
+          end
+          return nil
+        end
+
       end
     end
   end