gloo 6.5.1 → 6.7.0

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/list.rb

@@ -92,21 +92,53 @@ module Gloo
 
       #
       # 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.
+      # its listing line, one '#'-prefixed line per line of doc, word-
+      # wrapped to fit the terminal. Silent when the object has none.
       #
       def show_doc( obj, indent )
         return if obj.doc.to_s.strip.empty?
 
-        theme = @engine.theme
+        prefix = "#{indent}# "
+        cont_indent = "#{indent}  " # lines up under the text after '# '
+        width = doc_wrap_width( prefix.length )
+
         # 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 )
+          show_doc_line( line, prefix, cont_indent, width )
         end
       end
 
+      #
+      # Word-wrap a single doc line to width, then show each wrapped
+      # piece: the '#' prefix on the first, the aligned continuation
+      # indent on the rest.
+      #
+      def show_doc_line( line, prefix, cont_indent, width )
+        theme = @engine.theme
+        wrapped = Gloo::Objs::WordWrap.wrap( line, width )
+        # "".split( "\n", -1 ) is [], not [ '' ] -- a blank line still
+        # needs one piece so it renders as a bare '#', not nothing.
+        pieces = wrapped.empty? ? [ '' ] : wrapped.split( "\n", -1 )
+        pieces.each_with_index do |piece, i|
+          p = i.zero? ? prefix : cont_indent
+          @engine.log.show theme.muted( "#{p}#{piece}".rstrip )
+        end
+      end
+
+      #
+      # How many columns of text fit after the doc-line prefix. Falls
+      # back to a small minimum rather than a zero/negative width when
+      # the terminal is very narrow or the indent is very deep.
+      #
+      def doc_wrap_width( prefix_length )
+        width = Gloo::App::Settings.cols( @engine ) - prefix_length
+        return width if width.positive?
+
+        return 20
+      end
+
       #
       # Determine how many levels to show.
       #

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/objs/string.test.gloo

@@ -79,6 +79,23 @@ tests.objs.string [can] :
       eval it = 'three'
       assert "expected split (8 100) to clamp to 'three'"
 
+  word_wrap [test] :
+    description [string] : Word-wrap a string to an explicit width
+    on_test [script] :
+      put 'one two three four five' into ^^.s
+      tell ^^.s to word_wrap (10)
+      tell ^^.s to count_lines
+      eval it = 3
+      assert "expected word_wrap (10) to produce 3 lines"
+
+  word_wrap_keeps_long_word_intact [test] :
+    description [string] : word_wrap never breaks a word, even one wider than the width
+    on_test [script] :
+      put 'http://example.com/a-really-long-url short' into ^^.s
+      tell ^^.s to word_wrap (10)
+      check ^^.s for substring? ('http://example.com/a-really-long-url')
+      assert "expected the long word to remain intact on its own line"
+
   split_list [test] :
     description [string] : Split a string into children of a target container
     on_test [script] :

data/test.gloo/objs/text.test.gloo

@@ -101,3 +101,12 @@ tests.objs.text [can] :
       put 'hello world' into ^^.b
       tell ^^.b to substring? ('lo w')
       assert "expected it to be true that it contains 'lo w'"
+
+  word_wrap [test] :
+    description [string] : Word-wrap text to an explicit width
+    on_test [script] :
+      put 'one two three four five' into ^^.b
+      tell ^^.b to word_wrap (10)
+      tell ^^.b to count_lines
+      eval it = 3
+      assert "expected word_wrap (10) to produce 3 lines"

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"