gloo 6.3.1 → 6.5.0

data/lib/gloo/persist/file_saver.rb

@@ -3,26 +3,52 @@
 #
 # Helper class used to save an object to a file.
 #
+# Given a Source::SourceDoc (captured at load time), this is a
+# rewriter, not a regenerator: trivia (comments, blank lines,
+# directives) is emitted verbatim, and a declaration's raw text is
+# kept as-is unless the live object's value has actually changed --
+# only then is the value re-rendered, via the object's own
+# serialize_value. Deleted objects drop out; objects created since
+# load are rendered fresh and appended.
+#
+# With no SourceDoc at all (the object was never loaded from a file),
+# this falls back to plain regeneration from the heap, so saving a
+# brand-new in-memory object still works.
+#
 
 module Gloo
   module Persist
     class FileSaver
 
       #
-      # Set up a file storage for an object.
+      # Set up a file saver. source_doc is optional -- when given, the
+      # save rewrites it in place; otherwise the file is regenerated
+      # from the heap.
+      #
+      # For a multi-file namespace to round-trip, batch carries two sets
+      # (PersistMan#save_batch builds them):
+      #  - :others -- objects declared by *other* loaded files'
+      #    SourceDocs; this saver leaves them out even though they're
+      #    live children of a container it shares.
+      #  - :claimed -- a set shared across the whole save batch; a
+      #    brand-new object no file owns is written by the first saver to
+      #    reach it, which adds it here so the rest skip it.
       #
-      def initialize( engine, pn, obj )
+      def initialize( engine, pn, obj, source_doc = nil, batch = nil )
         @engine = engine
         @mech = @engine.platform.get_file_mech( @engine )
         @pn = pn
         @obj = obj
+        @source_doc = source_doc
+        @others = batch && batch[ :others ]
+        @claimed = batch && batch[ :claimed ]
       end
 
       #
       # Save the object to the file.
       #
       def save
-        data = get_obj( @obj )
+        data = @source_doc ? rewrite : regenerate
         @mech.write( @pn, data )
       end
 
@@ -34,18 +60,237 @@ module Gloo
       end
 
       #
-      # Convert an object to textual representation.
-      # This is a recursive function.
+      # Would saving now actually change anything on disk? True if any
+      # known declaration's value no longer matches its raw source, or
+      # its object was deleted. (Doesn't detect a brand-new object with
+      # no source node of its own -- an approximation, not a guarantee,
+      # good enough to warn before a reload discards changes.)
+      #
+      def dirty?
+        return false unless @source_doc
+
+        return any_dirty?( @source_doc.children, @engine.heap.root )
+      end
+
+      #
+      # Convert an object to textual representation from scratch, with
+      # no source text to preserve. This is a recursive function, and
+      # is also reused by the rewriter for any object created since
+      # load (which has no source node of its own to rewrite).
       #
       def get_obj( obj, indent = 0 )
         t = tabs( indent )
-        str = "#{t}#{obj.name} [#{obj.type_display}] : #{obj.value_display}\n"
+        str = "#{t}#{obj.name} [#{obj.type_display}]#{obj.serialize_value( indent )}\n"
         obj.children.each do |child|
           str << get_obj( child, indent + 1 )
         end
         return str
       end
 
+      private
+
+      #
+      # Regenerate the whole file from the heap (the pre-Source::SourceDoc
+      # behavior), used when there's no source text to rewrite.
+      #
+      def regenerate
+        return get_obj( @obj )
+      end
+
+      #
+      # Does any node in the given list represent a change from what's
+      # on disk -- its object gone from live_parent's children (an
+      # untracked deletion counts too), or its value changed?
+      #
+      def any_dirty?( nodes, live_parent )
+        nodes.any? do |node|
+          next false unless node.is_a?( Source::ObjNode )
+
+          _top, leaf = locate( node, live_parent )
+          next true unless leaf
+          next true unless value_unchanged?( node )
+
+          any_dirty?( node.children, leaf )
+        end
+      end
+
+      # ---------------------------------------------------------------------
+      #    Rewrite (Source::SourceDoc-driven)
+      # ---------------------------------------------------------------------
+
+      #
+      # Rewrite the file from its source document: known declarations
+      # are patched in place, deleted ones dropped, and anything new
+      # appended.
+      #
+      def rewrite
+        return render_children( @source_doc.children, @engine.heap.root, 0 )
+      end
+
+      #
+      # Render one level of source nodes against the live children of
+      # live_parent: trivia passes through untouched; a declaration
+      # whose object is still present is patched in place; one whose
+      # object is gone is dropped; anything in live_parent.children
+      # with no matching source node is new and gets rendered fresh
+      # (unless another file owns it -- see #owned).
+      #
+      def render_children( nodes, live_parent, indent )
+        str = ''
+        seen = []
+        nodes.each do |node|
+          if node.is_a?( Source::ObjNode )
+            top, leaf = locate( node, live_parent )
+            next unless leaf
+
+            seen << top
+            str << render_obj_node( node, indent )
+          else
+            str << render_trivia( node )
+          end
+        end
+
+        ( live_parent.children - seen ).each do |child|
+          next unless write_new_child?( child )
+
+          str << get_obj( child, indent )
+        end
+        return str
+      end
+
+      #
+      # A live child with no source node at this level. Write it unless
+      # another file owns it, or another file in this batch already
+      # wrote it as a brand-new object. A genuinely new object is
+      # written here and claimed.
+      #
+      def write_new_child?( child )
+        return false if @others&.key?( child )
+        return false if @claimed&.key?( child )
+
+        @claimed[ child ] = true if @claimed
+        return true
+      end
+
+      #
+      # Resolve a source node against the live tree under live_parent.
+      # A plain name is a direct child; a dotted name (nested container
+      # shorthand, page.core.users.list) walks the chain. Returns
+      # [top-level object to mark as handled, the node's own object],
+      # or [nil, nil] if the node's object is no longer there.
+      #
+      def locate( node, live_parent )
+        return [ nil, nil ] unless node.obj
+
+        segments = node.name.split( '.' )
+        if segments.length == 1
+          return live_parent.children.include?( node.obj ) ? [ node.obj, node.obj ] : [ nil, nil ]
+        end
+
+        top = live_parent.find_child( segments.first )
+        return [ nil, nil ] unless top
+
+        leaf = top
+        segments[ 1..-1 ].each do |seg|
+          leaf = leaf.find_child( seg )
+          return [ nil, nil ] unless leaf
+        end
+        return leaf.equal?( node.obj ) ? [ top, leaf ] : [ nil, nil ]
+      end
+
+      #
+      # A comment, blank line, or top-of-file directive -- passed
+      # through exactly as read.
+      #
+      def render_trivia( node )
+        return "#{node.raw}\n"
+      end
+
+      #
+      # One declaration whose object is still live: its leading_doc (if
+      # any) and its own line are kept (name/type/indent never change
+      # once declared), its value is kept raw or re-rendered depending
+      # on whether it changed, and its children are rewritten the same
+      # way, one level deeper.
+      #
+      def render_obj_node( node, indent )
+        str = node.leading_doc ? "#{node.leading_doc}\n" : ''
+        str << "#{node.raw_indent}#{node.name} [#{node.raw_type}]#{declaration_tail( node, indent )}\n"
+        str << render_children( node.children, node.obj, indent + 1 )
+        return str
+      end
+
+      #
+      # The text that follows "name [type]" on the declaration line:
+      # the raw source, unless the live value no longer matches it.
+      #
+      def declaration_tail( node, indent )
+        return raw_declaration_tail( node ) if value_unchanged?( node )
+
+        return node.obj.serialize_value( indent )
+      end
+
+      #
+      # Reproduce the original declaration's value text exactly as it
+      # was read. raw_tail is the declaration line's own exact tail
+      # (eg. " : BEGIN" or " :"); a begin_end/body style has further
+      # raw content following it.
+      #
+      def raw_declaration_tail( node )
+        case node.block_style
+        when :begin_end
+          return "#{node.raw_tail}\n#{node.raw_value}#{node.raw_end_indent}END"
+        when :body
+          return node.raw_value.to_s.empty? ? node.raw_tail : "#{node.raw_tail}\n#{node.raw_value}"
+        else
+          return node.raw_tail
+        end
+      end
+
+      # ---------------------------------------------------------------------
+      #    Has the value actually changed since load?
+      # ---------------------------------------------------------------------
+
+      #
+      # Does the live object's value still match what raw_value would
+      # produce? A script body is compared line by line (raw comments
+      # excluded, since they were never run); everything else is
+      # compared by re-running the raw text through the same set_value
+      # conversion the loader used, and comparing the result.
+      #
+      def value_unchanged?( node )
+        return false unless node.obj
+        return body_value_unchanged?( node ) if node.block_style == :body
+
+        trial = node.obj.class.new( @engine )
+        trial.set_value( node.raw_value )
+        return trial.value == node.obj.value
+      rescue
+        return false
+      end
+
+      #
+      # A script body's raw text, minus its comment lines (never
+      # executed) and with each line stripped, should equal the live
+      # object's own command lines.
+      #
+      def body_value_unchanged?( node )
+        raw_lines = node.raw_value.to_s.split( "\n" )
+        executable = raw_lines.reject { |l| l.strip.start_with?( '#' ) }.map( &:strip )
+        return executable == current_script_lines( node.obj )
+      end
+
+      #
+      # The live object's command lines, whatever form its value is
+      # currently in.
+      #
+      def current_script_lines( obj )
+        return obj.value if obj.value_is_array?
+        return [] if obj.value_is_blank?
+
+        return [ obj.value.to_s.strip ]
+      end
+
     end
   end
 end

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
 
       #