gloo 6.3.1 → 6.5.0

data/lib/gloo/persist/persist_man.rb

@@ -12,6 +12,11 @@ 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
+      FILE_NOT_FOUND_ERR = 'File not found: '.freeze
+
       #
       # Constructor for the persistence manager.
       #
@@ -22,51 +27,84 @@ 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
 
       #
-      # Load the object from the file.
+      # Load the object(s) from the file (or files, for a wildcard).
+      # Returns true if at least one object was loaded, false if the
+      # name couldn't be resolved to any file or nothing loaded --
+      # a missing/unresolvable file is reported via engine.err rather
+      # than failing silently.
       #
       def load( name )
         pns = get_full_path_names name
-        return unless pns
+        if pns.nil? || pns.empty?
+          @engine.err( "#{FILE_NOT_FOUND_ERR}#{name}" ) unless name.to_s.strip.empty?
+          return false
+        end
 
+        loaded = false
         pns.each do |pn|
           @engine.log.debug "Load file(s) at: #{pn}"
           begin
             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
+            loaded = true
           rescue => ex
             @engine.handle_exception( ex )
           end
         end
+        return loaded
       end
 
       # 
@@ -74,8 +112,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 +126,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 +149,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 +176,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 +224,125 @@ 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 )
+
+          if node.obj
+            owned[ node.obj ] = true
+            mark_shorthand_ancestors( node, owned )
+          end
+          collect_owned( node.children, owned )
+        end
+      end
+
+      #
+      # A nested-container shorthand declaration (a.b.c [type] :) only
+      # records a source node for the leaf; the intermediate containers
+      # (a, a.b) are real heap objects with no node of their own. Mark
+      # them owned too, walking up from the leaf, so another file's save
+      # doesn't see an intermediate as an orphan and adopt its whole
+      # subtree.
+      #
+      def mark_shorthand_ancestors( node, owned )
+        return unless node.name.include?( '.' )
+
+        o = node.obj.parent
+        while o && !o.root?
+          owned[ o ] = true
+          o = o.parent
+        end
+      end
+
+      #
+      # Save to a path that's already mapped to some file. If that
+      # mapping is for a different root, it's a real collision -- the
+      # 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

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

@@ -0,0 +1,91 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# One object declaration in a source file, eg.
+#   name [type] : value
+# Carries the raw text needed to reproduce the declaration unchanged,
+# plus a back-reference to the heap object it created (or updated),
+# so a save can tell whether the live value still matches what's on
+# disk and, if so, leave the raw text alone.
+#
+
+module Gloo
+  module Persist
+    module Source
+      class ObjNode
+
+        # block_style is one of:
+        #  :inline    -- name [type] : value, all on one line
+        #  :begin_end -- name [type] : BEGIN ... END
+        #  :body      -- name [type] :, followed by an indented,
+        #                unparsed body (script commands)
+        attr_accessor :name, :raw_type, :raw_indent, :raw_tail, :block_style,
+                      :raw_value, :raw_end_indent, :leading_doc, :trailing_comment, :obj
+        attr_reader :children
+
+        #
+        # Set up an object declaration node. Everything but the name
+        # and raw type is optional and commonly set afterward via the
+        # accessors above -- keeping the initializer small.
+        #
+        def initialize( name:, raw_type: )
+          @name = name
+          @raw_type = raw_type
+          @raw_indent = ''
+          @raw_tail = ''
+          @block_style = :inline
+          @raw_value = nil
+          # a begin_end block's closing END is not necessarily indented
+          # to match its declaration -- kept separately, raw.
+          @raw_end_indent = ''
+          @leading_doc = nil
+          @trailing_comment = nil
+          @obj = nil
+          @children = []
+        end
+
+        #
+        # The cleaned-up leading_doc: each line's leading whitespace and
+        # its '#' marker (plus one following space, if any) stripped,
+        # then the result dedented to its shallowest line. The full
+        # block is kept as written, blank '#' lines at the top/bottom
+        # included -- it's a faithful reproduction of the comment, not
+        # a trimmed summary. '' when there's no leading_doc at all.
+        #
+        def doc
+          return '' unless @leading_doc
+
+          lines = @leading_doc.split( "\n" ).map { |l| strip_marker( l ) }
+          return dedent( lines ).join( "\n" )
+        end
+
+        private
+
+        #
+        # One raw comment line -> its text past the '#': leading
+        # whitespace dropped, then the '#' and at most one space after
+        # it, then trailing whitespace dropped.
+        #
+        def strip_marker( raw )
+          return raw.lstrip.sub( /\A#\x20?/, '' ).rstrip
+        end
+
+        #
+        # Remove the common leading whitespace shared by every non-blank
+        # line, so a comment block indented for readability (eg. a
+        # bullet list within it) keeps its relative indentation.
+        #
+        def dedent( lines )
+          non_blank = lines.reject( &:empty? )
+          return lines if non_blank.empty?
+
+          n = non_blank.map { |l| l[ /\A */ ].length }.min
+          return lines if n.zero?
+
+          return lines.map { |l| l.empty? ? l : l[ n.. ] }
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# The concrete source model for one loaded file: an ordered list of
+# nodes (comments, blank lines, directives, and object declarations)
+# that mirrors what the loader actually read, so a save can rewrite
+# the file instead of regenerating it from the heap.
+#
+# The top level plays the same role as an Source::ObjNode's children
+# list -- there is no special "root" wrapper, just the file's own
+# ordered content, which may include more than one top-level object
+# declaration (a file may legitimately declare several roots).
+#
+
+module Gloo
+  module Persist
+    module Source
+      class SourceDoc
+
+        attr_reader :children
+
+        #
+        # Set up an empty source document.
+        #
+        def initialize
+          @children = []
+        end
+
+        #
+        # The top-level object declarations in this file (usually one,
+        # per the "a file owns its declarations" model -- more than one
+        # only when the file legitimately declares several roots).
+        #
+        def roots
+          return @children.select { |n| n.is_a?( Source::ObjNode ) }
+        end
+
+      end
+    end
+  end
+end