gloo 6.6.0 → 6.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24b089e57c145daea09ee59a1967bc38ec4482d0a9a137f9e3a32e8b71fb4ece
-  data.tar.gz: 625b347a0ff732f2fe81008c9e7e6d56de92f84ef846ccd37ebeda10948117ab
+  metadata.gz: 7bec0a2a7c9eb15015734a7610359cc6b7c18abbc9abbb239131f9fad9927fcf
+  data.tar.gz: a9d8810c5581416608f4913d1cd7f1b24e385fb4b1d47b74eb5e1dcd8aaafd47
 SHA512:
-  metadata.gz: 3080060d8fea38b00cc1870d9ae07d8149db13395834d72a20c9f18f7b9c43d97b6af97177d653b7eaeeffa49b04f9005a8318f7aaaa56edf65619645dde8016
-  data.tar.gz: f137b40bf30a08e7af993fdd67041084a7f6aefbaf461934f1b4b8bd370e399cf3044537388d1a09be6dd954d73c3487ceddf6c977493287e3aa5ec6894f2b13
+  metadata.gz: 17694e6f6a9019c0071248eb4c59ab80ffba8c352b7aa5341eeca150d0503e5176eabc0e00a0214d8a99c24e98fa045138dfb7783bb55c1c30198f0704235cec
+  data.tar.gz: 6cff2396f6bdc2debed6ab6f03a43e5932a1fa4c5a54a07c40b0e5d18f3686721ca9ae90e05d60ea26fc416c93f66e1acb05de9141e9777afec78406c17181a6

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.6.0
+6.7.0

data/lib/VERSION_NOTES

@@ -1,3 +1,9 @@
+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.

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/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

data/lib/gloo/persist/subtree_extractor.rb

@@ -0,0 +1,184 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Resolves 'save {obj} to {path}' into the Source::ObjNode that should
+# be moved into the target file: pulled out of whichever file already
+# owns it, or built fresh when obj has no file of its own yet. Does
+# not touch disk -- PersistMan wires the result into a new
+# FileStorage and drives the actual save (including re-saving the
+# file the node was pulled out of).
+#
+
+module Gloo
+  module Persist
+    class SubtreeExtractor
+
+      SPANS_MULTIPLE_FILES_ERR =
+        "Can't extract: this object's subtree has declarations in more than one file. " \
+        'Save each contributing file on its own first.'.freeze
+      NO_OWN_DECLARATION_ERR =
+        "Can't extract: this object has no declaration of its own to move " \
+        '(it may be an auto-created intermediate container from nested-container ' \
+        'shorthand) -- extract a child that does, or a shallower ancestor that does.'.freeze
+
+      #
+      # Set up an extractor for the given engine.
+      #
+      def initialize( engine )
+        @engine = engine
+      end
+
+      #
+      # Resolve obj to the Source::ObjNode that should be written to
+      # the new file, with its name set to obj's full dotted path (so
+      # the target file recreates any prefix container chain via
+      # nested-container shorthand) and its indentation recomputed for
+      # life as a fresh top-level declaration.
+      #
+      # Returns [ node, source_fs ]: source_fs is the FileStorage obj
+      # was pulled out of (already updated in memory -- its own save is
+      # still the caller's job), or nil when obj had no file of its own
+      # to remove from. Returns [ nil, nil ] (having already called
+      # engine.err) if extraction isn't possible.
+      #
+      def extract( obj, maps )
+        owners = owning_file_storages( obj, maps )
+        return err( SPANS_MULTIPLE_FILES_ERR ) if owners.count > 1
+
+        source_fs = owners.first
+        node = source_fs ? remove_node( obj, source_fs ) : fresh_node( obj )
+        return err( NO_OWN_DECLARATION_ERR ) unless node
+
+        node.name = dotted_name( obj )
+        reindent( node, 0 )
+        return [ node, source_fs ]
+      end
+
+      private
+
+      #
+      # Report the error and return [ nil, nil ], for a one-line call site.
+      #
+      def err( message )
+        @engine.err( message )
+        return [ nil, nil ]
+      end
+
+      #
+      # Every FileStorage whose SourceDoc has a node for obj itself, or
+      # for any of its descendants (a namespace pattern applied inside
+      # obj's own subtree, not just above it).
+      #
+      def owning_file_storages( obj, maps )
+        subtree = subtree_objects( obj )
+        return maps.select { |fs| fs.source_doc && any_node_for?( fs.source_doc.children, subtree ) }
+      end
+
+      #
+      # obj and every object beneath it in the live heap, as a
+      # (compare-by-identity) set membership check.
+      #
+      def subtree_objects( obj )
+        set = {}.compare_by_identity
+        set[ obj ] = true
+        collect_descendants( obj, set )
+        return set
+      end
+
+      #
+      # Recursively add obj's live children to the set.
+      #
+      def collect_descendants( obj, set )
+        obj.children.each do |child|
+          set[ child ] = true
+          collect_descendants( child, set )
+        end
+      end
+
+      #
+      # Does any node in this list (or their descendants) belong to an
+      # object in the given set?
+      #
+      def any_node_for?( nodes, set )
+        return nodes.any? do |node|
+          next false unless node.is_a?( Source::ObjNode )
+          next true if node.obj && set.key?( node.obj )
+
+          any_node_for?( node.children, set )
+        end
+      end
+
+      #
+      # obj has no file of its own (never loaded, or created at
+      # runtime since) -- build a plain node with no raw text of its
+      # own. FileSaver renders it fresh from the live object, the same
+      # way it already does for any brand-new child.
+      #
+      def fresh_node( obj )
+        node = Source::ObjNode.new( :name => obj.name, :raw_type => obj.type_display )
+        node.obj = obj
+        return node
+      end
+
+      #
+      # Pull obj's node out of the file that owns it. Returns nil if
+      # that file turns out to have no node of obj's own to remove (eg.
+      # obj is an intermediate container ShorthandExpander created,
+      # which never gets a node of its own).
+      #
+      def remove_node( obj, fs )
+        node = fs.source_doc.extract( obj )
+        return nil unless node
+
+        fs.drop_root( obj )
+        return node
+      end
+
+      #
+      # obj's full dotted path from its file-owning root down to
+      # itself, eg. "app.core.settings" -- how the target file
+      # recreates the prefix chain via nested-container shorthand. A
+      # plain top-level object's path is just its own name.
+      #
+      def dotted_name( obj )
+        names = [ obj.name ]
+        o = obj.parent
+        until o.nil? || o.root?
+          names.unshift( o.name )
+          o = o.parent
+        end
+        return names.join( '.' )
+      end
+
+      #
+      # Recompute raw_indent (and, for a BEGIN/END node, raw_end_indent
+      # to match) from scratch for the moved node and every descendant
+      # ObjNode. Their old indentation depth described nesting inside
+      # the file they came from; here obj itself is depth 0, in a
+      # brand-new file. Floating trivia (a blank line or comment not
+      # attached as some declaration's leading_doc) travels along
+      # unindented-adjusted -- purely cosmetic, since indentation never
+      # affects how a comment/blank line is recognized on reload.
+      #
+      def reindent( node, depth )
+        new_indent = "\t" * depth
+        node.raw_indent = new_indent
+        node.raw_end_indent = new_indent if node.block_style == :begin_end
+        node.leading_doc = reindent_doc( node.leading_doc, new_indent ) if node.leading_doc
+        node.children.each do |child|
+          reindent( child, depth + 1 ) if child.is_a?( Source::ObjNode )
+        end
+      end
+
+      #
+      # Re-indent a raw leading_doc's lines to new_indent, replacing
+      # whatever leading whitespace each '#'-prefixed line had in the
+      # file it came from.
+      #
+      def reindent_doc( raw, new_indent )
+        return raw.split( "\n" ).map { |line| "#{new_indent}#{line.lstrip}" }.join( "\n" )
+      end
+
+    end
+  end
+end

data/lib/gloo/persist/trivia_buffer.rb

@@ -0,0 +1,120 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Buffers a run of comment and blank lines while the loader decides
+# where they actually belong -- both what becomes a following
+# declaration's leading_doc, and which source node's children array
+# floating trivia lands in.
+#
+# Both kinds are held here (not placed immediately) because a
+# declaration only becomes a parent -- and its Source::ObjNode only
+# gets pushed as the current node -- once IndentStack#place sees a
+# genuinely deeper line follow it (see IndentStack). A blank or
+# comment line between a container's declaration and its first child
+# arrives *before* that push happens; placing it immediately would
+# attach it one level too shallow. Buffering defers the decision until
+# take_leading_doc/flush_into is called against the *correct*,
+# already-placed node.
+#
+
+module Gloo
+  module Persist
+    class TriviaBuffer
+
+      #
+      # Set up an empty buffer.
+      #
+      def initialize
+        @pending = []
+      end
+
+      #
+      # Buffer one comment line. raw is the full source line (minus
+      # its trailing newline); tabs is its indentation level.
+      #
+      def push_comment( raw, tabs )
+        @pending << { :kind => :comment, :raw => raw, :tabs => tabs }
+      end
+
+      #
+      # Buffer one blank line. raw is its exact source text (may be
+      # non-empty if it had trailing whitespace) -- a blank line always
+      # breaks a comment run's association with whatever declaration
+      # follows, the same as it always has.
+      #
+      def push_blank( raw )
+        @pending << { :kind => :blank, :raw => raw }
+      end
+
+      #
+      # Detach the whole buffered run -- comments and blanks, in
+      # original order -- as floating nodes appended to the given
+      # children array.
+      #
+      def flush_into( children )
+        return if @pending.empty?
+
+        flush_list( @pending, children )
+        @pending = []
+      end
+
+      #
+      # If the run since the last blank (or the whole run, if it has no
+      # blank in it) is one or more comment lines all at the same
+      # indent as line_tabs, claim it as a leading_doc (raw,
+      # newline-joined). Anything before that -- an earlier blank, and
+      # whatever preceded it -- floats into children first, in order,
+      # since a blank always breaks the association. If the trailing
+      # run doesn't qualify (wrong indent, or empty), it floats into
+      # children too and this returns nil. Either way the buffer is
+      # empty afterward.
+      #
+      def take_leading_doc( line_tabs, children )
+        before, after = split_at_last_blank
+        flush_list( before, children )
+
+        if after.any? && after.last[ :tabs ] == line_tabs
+          doc = after.map { |t| t[ :raw ] }.join( "\n" )
+          @pending = []
+          return doc
+        end
+
+        flush_list( after, children )
+        @pending = []
+        return nil
+      end
+
+      private
+
+      #
+      # Split the pending run at its last blank line: everything up to
+      # and including it, and everything after (always comments only,
+      # by construction -- there's no later blank to have split on).
+      # With no blank at all, everything is "after".
+      #
+      def split_at_last_blank
+        idx = @pending.rindex { |t| t[ :kind ] == :blank }
+        return [ [], @pending ] unless idx
+
+        return [ @pending[ 0..idx ], @pending[ idx + 1.. ] ]
+      end
+
+      #
+      # Append each pending entry's node, in order, to children.
+      #
+      def flush_list( list, children )
+        list.each { |t| children << node_for( t ) }
+      end
+
+      #
+      # The source node one pending entry becomes when it floats.
+      #
+      def node_for( t )
+        return Source::BlankNode.new( t[ :raw ] ) if t[ :kind ] == :blank
+
+        return Source::CommentNode.new( t[ :raw ] )
+      end
+
+    end
+  end
+end

data/lib/gloo/verbs/if.rb

@@ -11,7 +11,11 @@ module Gloo
       KEYWORD = 'if'.freeze
       KEYWORD_SHORT = 'if'.freeze
       THEN = 'then'.freeze
+      DO = 'do'.freeze
       ELSE = 'else'.freeze
+      # 'then' and 'do' are interchangeable -- whichever appears first
+      # in the tokens is the actual separator (see Tokens#index_of).
+      SEPARATORS = [ THEN, DO ].freeze
       MISSING_EXPR_ERR = 'Missing Expression!'.freeze
 
       #
@@ -21,7 +25,7 @@ module Gloo
         value = value_tokens
         return if value.nil?
 
-        @then = @tokens.expr_after( THEN, ELSE )
+        @then = @tokens.expr_after( SEPARATORS, ELSE )
         @else = @tokens.expr_after( ELSE )
 
         if evals_true( value )
@@ -56,7 +60,7 @@ module Gloo
       # of the if command.
       #
       def value_tokens
-        value = @tokens.before_token( THEN )
+        value = @tokens.before_token( SEPARATORS )
         if value && value.count > 1
           # The first token is the verb, so we drop it.
           value = value[ 1..-1 ]
@@ -113,19 +117,22 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'If an expression is true then do something.',
+          :description => 'If an expression is true then do something. ' \
+            "'then' and 'do' are interchangeable separators -- pick " \
+            'whichever reads better.',
           :syntax => [
-            'if {true} then {do}',
-            'if {true} then {do} else {do else}'
+            'if {true} then {action}',
+            'if {true} do {action}',
+            'if {true} then {action} else {else action}'
           ],
           :parameters => [
             '{true} — Does the expression evaluate to true?',
-            '{do} — Execute command if the expression is true.',
-            '{do else} — The else command is optional. Execute command if the expression is false.'
+            '{action} — Execute command if the expression is true.',
+            '{else action} — The else command is optional. Execute command if the expression is false.'
           ],
           :result => 'Unchanged if the expression is not true. If true, ' \
             'then the result will be based on the command specified ' \
-            'after the then keyword.',
+            "after the 'then'/'do' keyword.",
           :errors => [
             "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb.",
             'Other errors depend on the command that is run.'
@@ -150,6 +157,9 @@ module Gloo
                 if ^.x \\
                   then show 'T' \\
                   else show 'F'
+
+                # 'do' works the same as 'then'
+                if if.x do show "still true: " + if.true_msg
           EXAMPLES
         }
       end

data/lib/gloo/verbs/save.rb

@@ -73,7 +73,12 @@ module Gloo
             'a namespace shared across several files); with no object ' \
             'at all, saves every open file. An object not yet mapped ' \
             'to a file is saved fresh, either to a given path or to a ' \
-            "default path built from the object's own name.",
+            "default path built from the object's own name. With a " \
+            'path, this extracts: the object (and its descendants) ' \
+            "move out of whichever file currently owns them -- they're " \
+            'no longer declared there too -- into the new file, under ' \
+            'their full dotted path (so any parent containers are ' \
+            'recreated there via nested-container shorthand).',
           :syntax => [
             'save',
             'save {path.to.object}',
@@ -88,21 +93,36 @@ module Gloo
           :result => 'The file(s) are updated with the latest object ' \
             'state. This is a rewrite, not a regeneration: comments, ' \
             'blank lines, and the original formatting are preserved, ' \
-            'and only values that actually changed are re-written.',
+            'and only values that actually changed are re-written. ' \
+            'With a path, the object also stops being declared in its ' \
+            'old file (if it had one) -- both files are rewritten ' \
+            'together.',
           :errors => [
             "#{MISSING_PATH_ERR} — 'to' was given with nothing after it.",
             'Could not resolve object to save — the object was not found.',
             'Will not overwrite a file not already saved there — the ' \
-              'target path exists but is not mapped to this object.'
+              'target path exists but is not mapped to this object.',
+            "Can't extract: this object's subtree has declarations in " \
+              'more than one file — save each contributing file on its ' \
+              'own first, then extract.',
+            "Can't extract: this object has no declaration of its own " \
+              'to move — it may be an auto-created intermediate ' \
+              'container from nested-container shorthand; extract a ' \
+              'child that does, or a shallower ancestor that does.'
           ],
           :notes => 'An object can also be told to save itself: ' \
             '`tell my_obj to save`. When several files contribute to ' \
             'one container (the namespace pattern), each file save only ' \
-            "rewrites that file's own declarations.",
+            "rewrites that file's own declarations. Extraction (save " \
+            '... to {path}) only moves a subtree owned by exactly one ' \
+            'file -- one already spread across several files (that ' \
+            'same namespace pattern, applied inside the subtree being ' \
+            'extracted) is refused rather than guessed at.',
           :examples => <<~EXAMPLES.strip
             > save
             > save my_obj
             > save my_obj to sub/my_obj
+            > save app.core.settings to config/settings
           EXAMPLES
         }
       end

data/lib/gloo/verbs/unless.rb

@@ -11,7 +11,11 @@ module Gloo
       KEYWORD = 'unless'.freeze
       KEYWORD_SHORT = 'if!'.freeze
       DO = 'do'.freeze
+      THEN = 'then'.freeze
       ELSE = 'else'.freeze
+      # 'do' and 'then' are interchangeable -- whichever appears first
+      # in the tokens is the actual separator (see Tokens#index_of).
+      SEPARATORS = [ DO, THEN ].freeze
       MISSING_EXPR_ERR = 'Missing Expression!'.freeze
 
       #
@@ -21,7 +25,7 @@ module Gloo
         value = value_tokens
         return if value.nil?
 
-        @do = @tokens.expr_after( DO, ELSE )
+        @do = @tokens.expr_after( SEPARATORS, ELSE )
         @else = @tokens.expr_after( ELSE )
 
         if evals_false( value )
@@ -56,7 +60,7 @@ module Gloo
       # of the unless command.
       #
       def value_tokens
-        value = @tokens.before_token( DO )
+        value = @tokens.before_token( SEPARATORS )
         if value && value.count > 1
           # The first token is the verb, so we drop it.
           value = value[ 1..-1 ]
@@ -114,9 +118,11 @@ module Gloo
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
           :description => "Unless an expression is true, do something. " \
-            "This is the opposite of the if verb.",
+            "This is the opposite of the if verb. 'do' and 'then' are " \
+            'interchangeable separators -- pick whichever reads better.',
           :syntax => [
             'unless {true} do {command}',
+            'unless {true} then {command}',
             'unless {true} do {command} else {else command}'
           ],
           :parameters => [
@@ -126,7 +132,7 @@ module Gloo
           ],
           :result => 'Unchanged if the expression is true. If not true, ' \
             'then the result will be based on the command specified ' \
-            'after the do keyword.',
+            "after the 'do'/'then' keyword.",
           :errors => [
             "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb.",
             'Other errors depend on the command that is run.'
@@ -148,6 +154,9 @@ module Gloo
                 put false into unless.x
                 unless unless.x do show "second time: " +  unless.false_msg
                 unless ^.x do show 'F' else show 'T'
+
+                # 'then' works the same as 'do'
+                unless unless.x then show "still false: " + unless.false_msg
           EXAMPLES
         }
       end

data/test.gloo/verbs/if.test.gloo

@@ -12,3 +12,24 @@ tests.verbs.if [can] :
       eval false
       if ^^.b then eval true
       assert "expected b to be true"
+
+  if_do [test] :
+    description [string] : 'do' is a synonym for 'then'
+    on_test [script] :
+      eval false
+      if ^^.b do eval true
+      assert "expected 'do' to work the same as 'then'"
+
+  if_then_else [test] :
+    description [string] : else runs when the condition is false
+    on_test [script] :
+      eval false
+      if false then eval false else eval true
+      assert "expected else to run when the condition is false"
+
+  if_do_else [test] :
+    description [string] : else works the same with the 'do' synonym
+    on_test [script] :
+      eval false
+      if false do eval false else eval true
+      assert "expected else to run after a 'do' action"

data/test.gloo/verbs/save.test.gloo

@@ -32,6 +32,27 @@ demo [container] :
   other [string] : world
 END
 
+  #
+  # Regression fixture: a blank line between a container's own
+  # declaration and its first child (not between two siblings, which
+  # already worked) used to land one level too shallow.
+  #
+  blank_before_first_child_fixture [text] : BEGIN
+#
+# The main app container.
+#
+app [can] :
+
+  # Core settings live here.
+  core [can] :
+
+    # Some other core thing.
+    other [string] : hi
+
+  # Something unrelated at the app level.
+  name [string] : My App
+END
+
   round_trip_preserves_comments_and_untouched_lines [test] :
     description [string] : load, change one value, save -- comments and the untouched sibling survive.
     on_test [script] :
@@ -66,6 +87,18 @@ END
       tell demo to unload
       tell ^^.f to delete
 
+  blank_before_first_child [test] :
+    description [string] : An unchanged save reproduces blank lines before a container's first child too.
+    on_test [script] :
+      tell ^^.f to write ( ^^.blank_before_first_child_fixture )
+      load /tmp/gloo_save_test.gloo
+      save app
+      tell ^^.f to read ( ^^.out )
+      eval ^^.out = ^^.blank_before_first_child_fixture
+      assert "an unchanged save should reproduce the original text, blank lines included"
+      tell app to unload
+      tell ^^.f to delete
+
   deleting_an_object_drops_its_line [test] :
     description [string] : removing a child and saving drops just that declaration.
     on_test [script] :
@@ -96,6 +129,59 @@ END
       tell ^^.f to delete
       tell ^^.to_target to delete
 
+  extracting_a_subtree_moves_it_to_the_new_file [test] :
+    description [string] : save {nested obj} to {path} moves its declaration (and its own comment) out of the old file into the new one.
+    on_test [script] :
+      tell ^^.f to write ( ^^.fixture )
+      load /tmp/gloo_save_test.gloo
+      save demo.other to /tmp/gloo_save_test_to
+      check ^^.to_target for exists?
+      assert "extraction should create the target file"
+
+      tell ^^.to_target to read ( ^^.out )
+      check ^^.out for substring? ( "demo.other [string] : world" )
+      assert "the target file should declare the moved object under its full dotted path"
+      check ^^.out for substring? ( "# a comment above other" )
+      assert "the moved object's own comment should travel with it"
+
+      tell ^^.f to read ( ^^.out )
+      check ^^.out for substring? ( "other [string]" )
+      refute "the old file should no longer declare the moved object"
+      check ^^.out for substring? ( "msg [string] : hello" )
+      assert "the old file should keep everything else"
+
+      # a later plain save of demo must not resurrect the moved object
+      save demo
+      tell ^^.f to read ( ^^.out )
+      check ^^.out for substring? ( "other" )
+      refute "a later save of the old root should not re-add the moved object"
+
+      tell demo.other to unload
+      tell demo to unload
+      tell ^^.f to delete
+      tell ^^.to_target to delete
+
+  extracting_a_subtree_spanning_multiple_files_is_an_error [test] :
+    description [string] : save {obj} to {path} refuses when obj's own subtree has declarations in more than one file.
+    on_test [script] :
+      put false into ^^.err
+      tell ^^.f to write ( ^^.fixture )
+      load /tmp/gloo_save_test.gloo
+      # a second file adds its own child under the same 'demo' container --
+      # a namespace pattern applied inside the subtree we'll try to extract
+      tell ^^.g to write ( "demo [container] :\n  extra [string] : too\n" )
+      load /tmp/gloo_save_test_2.gloo
+
+      save demo to /tmp/gloo_save_test_to
+      eval ^^.err = true
+      assert "extraction should refuse a subtree spanning multiple files"
+      check ^^.to_target for exists?
+      refute "the target file should not have been created"
+
+      tell demo to unload
+      tell ^^.f to delete
+      tell ^^.g to delete
+
   reload_discards_unsaved_changes [test] :
     description [string] : reload throws away edits that were not saved.
     on_test [script] :

data/test.gloo/verbs/unless.test.gloo

@@ -18,3 +18,24 @@ tests.verbs.unless [can] :
       eval false
       unless true do eval true
       refute "expected do block to be skipped when condition is true"
+
+  unless_then [test] :
+    description [string] : 'then' is a synonym for 'do'
+    on_test [script] :
+      eval false
+      unless ^^.b then eval true
+      assert "expected 'then' to work the same as 'do'"
+
+  unless_do_else [test] :
+    description [string] : else runs when the condition is true
+    on_test [script] :
+      eval false
+      unless true do eval false else eval true
+      assert "expected else to run when the condition is true"
+
+  unless_then_else [test] :
+    description [string] : else works the same with the 'then' synonym
+    on_test [script] :
+      eval false
+      unless true then eval false else eval true
+      assert "expected else to run after a 'then' action"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gloo
 version: !ruby/object:Gem::Version
-  version: 6.6.0
+  version: 6.7.0
 platform: ruby
 authors:
 - Eric Crane
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-12 00:00:00.000000000 Z
+date: 2026-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -386,7 +386,6 @@ files:
 - lib/gloo/objs/web/http_post.rb
 - lib/gloo/objs/web/json.rb
 - lib/gloo/objs/web/uri.rb
-- lib/gloo/persist/comment_buffer.rb
 - lib/gloo/persist/declaration_ledger.rb
 - lib/gloo/persist/disc_mech.rb
 - lib/gloo/persist/file_loader.rb
@@ -402,6 +401,8 @@ files:
 - lib/gloo/persist/source/directive_node.rb
 - lib/gloo/persist/source/obj_node.rb
 - lib/gloo/persist/source/source_doc.rb
+- lib/gloo/persist/subtree_extractor.rb
+- lib/gloo/persist/trivia_buffer.rb
 - lib/gloo/plugin/base.rb
 - lib/gloo/plugin/callback.rb
 - lib/gloo/plugin/ext_manager.rb

data/lib/gloo/persist/comment_buffer.rb

@@ -1,58 +0,0 @@
-# Author::    Eric Crane  (mailto:eric.crane@mac.com)
-# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
-#
-# Buffers a run of consecutive whole-line comments while the loader
-# decides whether they become a declaration's leading_doc or float as
-# their own comment nodes.
-#
-
-module Gloo
-  module Persist
-    class CommentBuffer
-
-      #
-      # Set up an empty buffer.
-      #
-      def initialize
-        @pending = []
-      end
-
-      #
-      # Buffer one comment line. raw is the full source line (minus
-      # its trailing newline); tabs is its indentation level.
-      #
-      def push( raw, tabs )
-        @pending << { :raw => raw, :tabs => tabs }
-      end
-
-      #
-      # Detach the buffered run as floating comment nodes, appended in
-      # order to the given children array.
-      #
-      def flush_into( children )
-        return if @pending.empty?
-
-        @pending.each { |c| children << Source::CommentNode.new( c[ :raw ] ) }
-        @pending = []
-      end
-
-      #
-      # If the buffered run sits at the same indent as line_tabs, claim
-      # it as a leading_doc (raw, newline-joined) and clear the buffer.
-      # Otherwise flush it into children as floating comments first, so
-      # document order is kept, and return nil.
-      #
-      def take_leading_doc( line_tabs, children )
-        if !@pending.empty? && @pending.last[ :tabs ] == line_tabs
-          doc = @pending.map { |c| c[ :raw ] }.join( "\n" )
-          @pending = []
-          return doc
-        end
-
-        flush_into( children )
-        return nil
-      end
-
-    end
-  end
-end