gloo 6.3.0 → 6.4.0

data/lib/gloo/persist/file_storage.rb

@@ -8,7 +8,7 @@ module Gloo
   module Persist
     class FileStorage
 
-      attr_reader :obj, :pn
+      attr_reader :obj, :pn, :roots, :source_doc
 
       #
       # Set up a file storage for an object.
@@ -17,13 +17,17 @@ module Gloo
         @engine = engine
         @obj = obj
         @pn = pn
+        @roots = obj ? [ obj ] : []
+        @source_doc = nil
       end
 
       #
-      # Save the object to the file.
+      # Save the object to the file. batch, when given, lets a
+      # multi-file namespace round-trip -- see PersistMan#save_batch and
+      # FileSaver.
       #
-      def save
-        fs = FileSaver.new( @engine, @pn, @obj )
+      def save( batch = nil )
+        fs = FileSaver.new( @engine, @pn, @obj, @source_doc, batch )
         fs.save
       end
 
@@ -34,6 +38,8 @@ module Gloo
         fl = FileLoader.new( @engine, @pn )
         fl.load
         @obj = fl.obj
+        @roots = fl.roots
+        @source_doc = fl.source_doc
         if @obj
           @engine.log.debug "Loaded object: #{@obj.name}"
         else

data/lib/gloo/persist/indent_stack.rb

@@ -0,0 +1,90 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Tracks the current nesting level shared by the heap tree and the
+# source tree as declaration lines are processed, pushing and popping
+# both stacks in lockstep so their nesting always matches -- an object
+# only becomes a parent once a deeper line actually follows it.
+#
+
+module Gloo
+  module Persist
+    class IndentStack
+
+      attr_reader :tabs
+
+      #
+      # Set up a stack rooted at the given heap object and source node.
+      #
+      def initialize( root_obj, root_node )
+        @tabs = 0
+        @parent_stack = [ root_obj ]
+        @node_stack = [ root_node ]
+      end
+
+      #
+      # The heap object new children should be created under.
+      #
+      def parent
+        return @parent_stack.last
+      end
+
+      #
+      # The source node new declarations/trivia should be appended to.
+      #
+      def node
+        return @node_stack.last
+      end
+
+      #
+      # Move the stacks to the right depth for a line at the given
+      # indentation, then -- if it turned out to be deeper than the
+      # previous line -- push the previous line's object/node as the
+      # new parent. last_obj/last_node are whatever was created for the
+      # previous declaration line.
+      #
+      def place( line_tabs, last_obj, last_node )
+        indent = indent_delta( line_tabs )
+        if indent.positive?
+          # last_obj is nil when the previous line failed to make an
+          # object (eg. an unknown type in a malformed file) -- keep
+          # the current parent rather than pushing nil.
+          @parent_stack.push( last_obj || @parent_stack.last )
+          @node_stack.push( last_node || @node_stack.last )
+        elsif indent.negative?
+          indent.abs.times do
+            # never pop the root -- a file with erratic (mixed
+            # tab/space) indentation can outdent further than it ever
+            # indented; clamp instead of emptying the stack.
+            break if @parent_stack.length <= 1
+
+            @parent_stack.pop
+            @node_stack.pop
+          end
+        end
+      end
+
+      private
+
+      #
+      # Update @tabs for the new line and return the signed change in
+      # nesting depth: positive if it's more indented than the last
+      # line placed, negative if less, zero if the same.
+      #
+      def indent_delta( line_tabs )
+        if line_tabs > @tabs
+          # TODO:  What if indent is more than one more level?
+          @tabs = line_tabs
+          return 1
+        elsif line_tabs < @tabs
+          diff = @tabs - line_tabs
+          @tabs -= diff
+          return -diff
+        end
+
+        return 0
+      end
+
+    end
+  end
+end

data/lib/gloo/persist/line_splitter.rb

@@ -12,7 +12,7 @@ module Gloo
       BEGIN_BLOCK = 'BEGIN'.freeze
       END_BLOCK = 'END'.freeze
 
-      attr_reader :obj
+      attr_reader :obj, :raw_tail
 
       #
       # Set up a line splitter
@@ -20,6 +20,7 @@ module Gloo
       def initialize( line, tabs )
         @line = line
         @tabs = tabs
+        @raw_tail = ''
       end
 
       #
@@ -36,15 +37,26 @@ module Gloo
       #
       # Detect the object name.
       #
+      # Only leading whitespace (the indentation, captured separately by
+      # the loader) and the trailing newline are removed here --
+      # trailing spaces/tabs are left on the line so they survive into
+      # a string value, which can matter when the value is used to
+      # build HTML.
+      #
       def detect_name
-        @line = @line.strip
+        @line = @line.lstrip.chomp
         @idx = @line.index( ' ' )
         @idx = 0 unless @idx
         @name = @line[ 0..@idx - 1 ]
       end
 
       #
-      # Detect the object type.
+      # Detect the object type, and capture the exact source text that
+      # follows it -- everything from the closing ']' (or, for an
+      # untyped declaration with no brackets at all, from right after
+      # the name) to the end of the line. Kept byte-exact so a save can
+      # reproduce a declaration's original spacing when its value
+      # hasn't changed.
       #
       def detect_type
         @line = @line[ @idx + 1..-1 ]
@@ -52,12 +64,15 @@ module Gloo
 
         if @line[ 0 ] == ':'
           @type = 'untyped'
+          @raw_tail = @line
           return
         end
 
         @type = @line[ 0..( @idx ? @idx - 1 : -1 ) ]
         @type = @type[ 1..-1 ] if @type[ 0 ] == '['
         @type = @type[ 0..-2 ] if @type[ -1 ] == ']'
+        close = @line.index( ']' )
+        @raw_tail = close ? @line[ close + 1..-1 ] : ''
       end
 
       #

data/lib/gloo/persist/persist_man.rb

@@ -12,6 +12,10 @@ module Gloo
 
       attr_reader :maps, :mech
 
+      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
+
       #
       # Constructor for the persistence manager.
       #
@@ -22,31 +26,52 @@ module Gloo
       end
 
       #
-      # Save one object to the file.
+      # Save one object to the file, or every open file if no name is
+      # given.
       #
       def save( name = '' )
         name.blank? ? save_all : save_one( name )
       end
 
       #
-      # Save one object to the file.
+      # Save every open file.
       #
       def save_all
-        @maps.each( &:save )
+        save_batch( @maps )
       end
 
       #
-      # Save one object to the file.
+      # Save the given object: every file that owns a declaration in
+      # its root's tree (usually one -- more when the root is a
+      # multi-file namespace). If it isn't mapped to any file yet, it's
+      # saved fresh to a default path derived from its root's name.
       #
       def save_one( name )
-        ref = Gloo::Core::Pn.new( @engine, name )
-        obj = ref.resolve
+        obj = resolve_for_save( name )
+        return unless obj
+
+        fs_list = find_file_storages( obj )
+        return save_new( obj, @mech.resolve_save_path( root_of( obj ).name ) ) if fs_list.empty?
 
-        # Send an on_save event
         @engine.event_manager.on_save obj
+        save_batch( fs_list )
+      end
 
-        fs = find_file_storage( obj )
-        fs.save
+      #
+      # Save the given object to an explicit path. Registers the
+      # mapping so a future bare save includes it. Refuses to overwrite
+      # a file that exists but isn't already mapped to this object.
+      #
+      def save_to( name, path )
+        obj = resolve_for_save( name )
+        return unless obj
+
+        pn = @mech.resolve_save_path( path )
+        mapped = @maps.find { |fs| fs.pn == pn }
+        return save_mapped( obj, mapped, pn ) if mapped
+        return @engine.err( "#{PATH_EXISTS_ERR}#{pn}" ) if @mech.exist?( pn )
+
+        save_new( obj, pn )
       end
 
       #
@@ -61,6 +86,8 @@ module Gloo
           begin
             fs = Gloo::Persist::FileStorage.new( @engine, pn )
             fs.load
+            next unless fs.obj # a failed load -- don't map it
+
             @maps << fs
             @engine.event_manager.on_load fs.obj
           rescue => ex
@@ -74,8 +101,8 @@ module Gloo
       # The engine  is reset to a clean state.
       # 
       def unload_all
-        objs = self.maps.map { |fs| fs.obj }
-        objs.each { |o| o.msg_unload }
+        objs = self.maps.map( &:obj ).compact
+        objs.each( &:msg_unload )
         @engine.reset_state
       end
 
@@ -88,22 +115,21 @@ module Gloo
       def unload( obj )
         @engine.event_manager.on_unload obj
         @engine.heap.unload obj
-        @maps.each_with_index do |o, i|
-          if o.obj.pn === obj.pn
-            @maps.delete_at( i )
-            return
-          end
-        end
+        # Drop every mapping for this object -- more than one when the
+        # root came from several files (the namespace pattern) -- and
+        # sweep out any mapping whose object is already gone.
+        @maps.reject! { |o| o.obj.nil? || ( o.obj.pn === obj.pn ) }
       end
 
-      # 
+      #
       # Reload all objects.
       # First send a message to each object to let it know it is being reloaded.
       # Then let the engine restart to reload the files.
-      # 
+      #
       def reload_all
         return unless @maps
-        
+
+        @maps.each { |fs| warn_if_dirty( fs ) }
         @maps.each do |fs|
           @engine.event_manager.on_reload fs.obj
         end
@@ -112,23 +138,24 @@ module Gloo
         @engine.restart
       end
 
-      # 
+      #
       # Re-load the given object from file.
       # This is used to reload a single object and comes from a
       # message sent to the object.
-      # 
+      #
       def reload( obj )
         fs = find_file_storage( obj )
         return unless fs
 
+        warn_if_dirty( fs )
         @engine.event_manager.on_reload obj
         @engine.heap.unload obj
         fs.load
       end
 
-      # 
+      #
       # Find the objects FileStorage in the list.
-      # 
+      #
       def find_file_storage( obj )
         @maps.each do |o|
           return o if ( o.obj.pn === obj.pn )
@@ -138,6 +165,16 @@ module Gloo
         return nil
       end
 
+      #
+      # Find every FileStorage that owns a declaration in the given
+      # object's root -- usually one, more when the root is shared
+      # across files (the multi-file namespace pattern).
+      #
+      def find_file_storages( obj )
+        root = root_of( obj )
+        return @maps.select { |fs| fs.roots.include?( root ) }
+      end
+
 
       #
       # Get the full path and name of the file.
@@ -176,6 +213,104 @@ module Gloo
         end
       end
 
+      private
+
+      #
+      # Resolve a name to an object for saving, reporting an error and
+      # returning nil if it can't be found.
+      #
+      def resolve_for_save( name )
+        obj = Gloo::Core::Pn.new( @engine, name ).resolve
+        @engine.err( "#{OBJ_NOT_FOUND_ERR}#{name}" ) unless obj
+        return obj
+      end
+
+      #
+      # Walk up to the top-level declared object that contains obj --
+      # its parent is the heap root, not another declared object.
+      #
+      def root_of( obj )
+        o = obj
+        o = o.parent until o.parent.nil? || o.parent.root?
+        return o
+      end
+
+      #
+      # Save a set of files as one batch so a multi-file namespace
+      # round-trips: each file only rewrites the declarations its own
+      # SourceDoc holds and leaves other files' declarations alone; a
+      # brand-new object no file owns is written once, by the first file
+      # in the batch to reach it.
+      #
+      def save_batch( files )
+        claimed = {}.compare_by_identity
+        files.each do |fs|
+          fs.save( :others => owned_elsewhere( fs ), :claimed => claimed )
+        end
+      end
+
+      #
+      # Every heap object declared by some loaded file's SourceDoc
+      # other than fs.
+      #
+      def owned_elsewhere( fs )
+        owned = {}.compare_by_identity
+        @maps.each do |other|
+          next if other.equal?( fs )
+
+          collect_owned( other.source_doc&.children, owned )
+        end
+        return owned
+      end
+
+      #
+      # Recursively collect the objects declared by the given source
+      # nodes into owned.
+      #
+      def collect_owned( nodes, owned )
+        return unless nodes
+
+        nodes.each do |node|
+          next unless node.is_a?( Gloo::Persist::Source::ObjNode )
+
+          owned[ node.obj ] = true if node.obj
+          collect_owned( node.children, owned )
+        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
+      # path belongs to something else.
+      #
+      def save_mapped( obj, mapped, pn )
+        return @engine.err( "#{PATH_EXISTS_ERR}#{pn}" ) unless mapped.roots.include?( root_of( obj ) )
+
+        @engine.event_manager.on_save obj
+        save_batch( [ mapped ] )
+      end
+
+      #
+      # Save an object's root fresh to a new path, and register the
+      # resulting mapping.
+      #
+      def save_new( obj, pn )
+        @engine.event_manager.on_save obj
+        fs = Gloo::Persist::FileStorage.new( @engine, pn, root_of( obj ) )
+        fs.save
+        @maps << fs
+      end
+
+      #
+      # Warn (without blocking) if reloading fs would discard changes
+      # that haven't been saved -- any object whose value no longer
+      # round-trips to what's on disk.
+      #
+      def warn_if_dirty( fs )
+        saver = Gloo::Persist::FileSaver.new( @engine, fs.pn, fs.obj, fs.source_doc )
+        @engine.log.warn "#{RELOAD_DIRTY_WARNING}#{fs.pn}" if saver.dirty?
+      end
+
     end
   end
 end

data/lib/gloo/persist/script_body_collector.rb

@@ -0,0 +1,102 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Collects an indented, unparsed script body (no BEGIN/END) for the
+# object that was just declared. We don't yet know whether a body
+# actually follows -- that's decided by the next line's indentation,
+# so this may close immediately with nothing collected (an empty
+# script).
+#
+
+module Gloo
+  module Persist
+    class ScriptBodyCollector
+
+      attr_reader :active
+
+      #
+      # Set up an inactive collector.
+      #
+      def initialize
+        @active = false
+      end
+
+      #
+      # Start tentatively collecting a body for the object just
+      # declared. node is its Source::ObjNode, heap_obj the object
+      # itself, base_tabs the indentation of the declaration line
+      # (body lines must be indented deeper than this).
+      #
+      def start( node, heap_obj, base_tabs )
+        @active = true
+        @node = node
+        @obj = heap_obj
+        @base_tabs = base_tabs
+        @lines = []
+      end
+
+      #
+      # One line while a body might be open. line_tabs is its
+      # indentation (ignored for a blank line, which is always kept).
+      # Returns true if the line was consumed as body content, or
+      # false if it closed the body and still needs to be dispatched
+      # normally by the caller.
+      #
+      def handle_line( line, line_tabs )
+        if line.strip.empty?
+          @lines << chomped( line )
+          return true
+        end
+
+        if line_tabs <= @base_tabs
+          close
+          return false
+        end
+
+        add_line( line )
+        return true
+      end
+
+      #
+      # End of file with a body still open (eg. the last object in the
+      # file is an empty or in-progress script) -- close it so its
+      # content isn't silently dropped.
+      #
+      def finish
+        close if @active
+      end
+
+      private
+
+      #
+      # Record one real body line: kept verbatim for the source model;
+      # added as a runnable command only if it isn't a comment (a
+      # comment inside a script body is documentation, not something
+      # to execute).
+      #
+      def add_line( line )
+        @lines << chomped( line )
+        @obj.add_line( line ) unless line.strip.start_with?( '#' )
+      end
+
+      #
+      # Close out the body, recording its raw content on the node.
+      #
+      def close
+        @active = false
+        @node.raw_value = @lines.join( "\n" )
+        @node.block_style = :body unless @lines.empty?
+        @node = nil
+        @obj = nil
+      end
+
+      #
+      # A line's raw text with its trailing newline removed.
+      #
+      def chomped( line )
+        return line.chomp( "\n" )
+      end
+
+    end
+  end
+end

data/lib/gloo/persist/shorthand_expander.rb

@@ -0,0 +1,51 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Nested container shorthand: a dotted name in a declaration
+# (page.core.users.list [type] :) means "find or create a container
+# for each prefix segment, then declare the real object under the
+# last one". A segment that already names some other kind of object
+# is used as-is, not forced to a container.
+#
+
+module Gloo
+  module Persist
+    class ShorthandExpander
+
+      #
+      # Set up an expander for the given engine.
+      #
+      def initialize( engine )
+        @engine = engine
+      end
+
+      #
+      # Split a possibly-dotted name against the given parent. Returns
+      # [leaf_name, parent_for_the_leaf, roots_touched, created]:
+      #  - roots_touched: containers created OR reused directly under
+      #    the heap root, for the loader to register as this file's roots
+      #  - created: containers this call actually created (any level),
+      #    for the loader to remember as its own
+      #
+      def expand( name, parent )
+        return [ name, parent, [], [] ] unless name.include?( '.' )
+
+        segments = name.split( '.' )
+        leaf = segments.pop
+        roots = []
+        created = []
+        segments.each do |seg|
+          child = parent.find_child( seg )
+          unless child
+            child = @engine.factory.create_can( seg, parent )
+            created << child
+          end
+          roots << child if parent == @engine.heap.root
+          parent = child
+        end
+        return [ leaf, parent, roots, created ]
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# A blank line between declarations. Kept (not discarded) so a save
+# can reproduce the file's original spacing.
+#
+
+module Gloo
+  module Persist
+    module Source
+      class BlankNode
+
+        attr_reader :raw
+
+        #
+        # Set up a blank line node. raw is the full source line, minus
+        # its trailing newline (may be non-empty if the blank line had
+        # trailing whitespace -- preserved rather than normalized).
+        #
+        def initialize( raw = '' )
+          @raw = raw
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# A whole-line comment that is not attached to any object declaration
+# as its leading_doc -- either because a blank line separated it from
+# the declaration that follows, or nothing follows it at all.
+#
+
+module Gloo
+  module Persist
+    module Source
+      class CommentNode
+
+        attr_reader :raw
+
+        #
+        # Set up a comment node. raw is the full source line, minus
+        # its trailing newline.
+        #
+        def initialize( raw )
+          @raw = raw
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# A top-of-file 'load lib {name}' (or 'load ext {name}') directive,
+# run by the loader itself before the declarations that follow it.
+#
+
+module Gloo
+  module Persist
+    module Source
+      class DirectiveNode
+
+        attr_reader :raw
+
+        #
+        # Set up a directive node. raw is the full source line, minus
+        # its trailing newline.
+        #
+        def initialize( raw )
+          @raw = raw
+        end
+
+      end
+    end
+  end
+end