gloo 6.3.1 → 6.5.0

data/lib/gloo/objs/basic/script.rb

@@ -47,7 +47,7 @@ module Gloo
         if self.value_string?
           first = self.value
           self.set_array_value []
-          self.value << first unless first.empty?
+          self.value << first unless first.strip.empty?
         elsif self.value_is_blank?
           self.set_array_value []
         end
@@ -62,6 +62,29 @@ module Gloo
         return true
       end
 
+      #
+      # Serialize this object's value for saving to a file.
+      # A script's value is an Array of command lines (once add_line
+      # has been called) or a single-line String. Render as indented
+      # body lines below the declaration, gloo's convention for
+      # scripts -- not a BEGIN/END block, which is reserved for a
+      # literal multi-line string value.
+      #
+      def serialize_value( indent )
+        lines = if value_is_array?
+                  value
+                elsif value_string? && !value.strip.empty?
+                  [ value ]
+                else
+                  []
+                end
+        return ' :' if lines.empty?
+
+        t = "\t" * ( indent + 1 )
+        body = lines.map { |line| "#{t}#{line}" }.join( "\n" )
+        return " :\n#{body}"
+      end
+
       #
       # Get the number of lines in this script.
       #
@@ -105,7 +128,10 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'An executable script — a set of commands to be run.',
+          :description => 'An executable script — a set of commands to ' \
+            'be run. A command line may end with an inline `# ...` ' \
+            'comment; it is ignored when the line runs but kept when ' \
+            'the file is saved.',
           :messages => [
             'run — Run the script. The script can be run by telling the ' \
               'object to run, or via the run verb.'

data/lib/gloo/objs/web/json.rb

@@ -213,7 +213,10 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'JSON data in a text string.',
+          :description => 'JSON data in a text string. Declare it ' \
+            'inline, in a BEGIN/END block, or assign it at run time: a ' \
+            'single-quoted literal keeps its double quotes, so ' \
+            'putting a JSON string into the object works.',
           :messages => [
             'get ({path}) — Get a value from the JSON data. Example: tell myjson to get (\'title\'). The parameter is the path in JSON to the value we want. The value is put into it.',
             'set ({obj.path}) — Convert an object to an approximate JSON value. Example: tell myjson to set (my.object). The parameter is the path to the object used as the source. Note this is an approximate conversion — a gloo object can have both a simple value and be a container for child objects, which JSON can\'t represent the same way.',

data/lib/gloo/persist/comment_buffer.rb

@@ -0,0 +1,58 @@
+# 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

data/lib/gloo/persist/declaration_ledger.rb

@@ -0,0 +1,61 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Tracks what a single file declares as it loads: its top-level
+# objects (for save resolution), and every object it created -- so a
+# re-declaration of a name an earlier file already used can be
+# flagged, since in that case the second value is silently dropped.
+#
+
+module Gloo
+  module Persist
+    class DeclarationLedger
+
+      attr_reader :roots
+
+      #
+      # Set up a ledger for the file at pn.
+      #
+      def initialize( engine, pn )
+        @engine = engine
+        @pn = pn
+        @roots = []
+        @mine = {}.compare_by_identity
+      end
+
+      #
+      # Record a top-level object this file created or reused (shorthand
+      # lines can re-introduce the same root, so dedupe).
+      #
+      def root( obj )
+        @roots << obj unless @roots.include?( obj )
+      end
+
+      #
+      # Record an object this file created, at any level.
+      #
+      def created( obj )
+        @mine[ obj ] = true
+      end
+
+      #
+      # `prior` already existed when this file declared `name` with
+      # `value`. If another file created it and the values differ, the
+      # new value is being ignored -- warn so it isn't a surprise. A
+      # duplicate name inside one file is left alone (a documented
+      # "first one wins").
+      #
+      def clash( prior, name, value )
+        return if @mine.key?( prior )
+        return if value.nil? || value.to_s.strip.empty?
+        return if prior.value.to_s == value.to_s
+
+        @engine.log.warn(
+          "#{@pn}: '#{name}' is already declared in another loaded file with a " \
+          "different value (#{prior.value.inspect} kept, #{value.inspect} ignored)."
+        )
+      end
+
+    end
+  end
+end

data/lib/gloo/persist/disc_mech.rb

@@ -85,13 +85,26 @@ module Gloo
         return nil
       end
 
-      # 
+      #
       # Read in the contents of a single file.
-      # 
+      #
       def read( file )
         return File.read( file )
       end
 
+      #
+      # Resolve a path to save a new (not-yet-existing) file to, given
+      # a name or relative path -- same convention as expand (relative
+      # to the project root, .gloo appended if missing), but without
+      # requiring the file to already exist.
+      #
+      def resolve_save_path( name )
+        full_name = name.end_with?( file_ext ) ? name : "#{name}#{file_ext}"
+        return full_name if full_name.start_with?( '/' )
+
+        return File.join( @engine.settings.project_path, full_name )
+      end
+
       # 
       # Write data to the file.
       # 

data/lib/gloo/persist/file_loader.rb

@@ -1,7 +1,18 @@
 # Author::    Eric Crane  (mailto:eric.crane@mac.com)
 # Copyright:: Copyright (c) 2019 Eric Crane.  All rights reserved.
 #
-# Helper class used to load a file and create objects in the heap.
+# Helper class used to load a file, create objects in the heap, and
+# build a parallel Source::SourceDoc capturing everything about the
+# file that the heap alone can't represent (comments, blank lines,
+# raw formatting) -- so a later save can rewrite the file instead of
+# regenerating it from scratch.
+#
+# Work is delegated to CommentBuffer (comment 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
+# clash warnings) -- this class is the orchestrator: per-line dispatch
+# and BEGIN/END handling.
 #
 
 module Gloo
@@ -20,7 +31,7 @@ module Gloo
       # afterward.
       LIB_DIRECTIVE = /\A(?:load|ld)\s+(?:lib|ext)\s+\S+\s*\z/i.freeze
 
-      attr_reader :obj
+      attr_reader :obj, :source_doc
 
       #
       # Set up a file storage for an object.
@@ -29,16 +40,25 @@ module Gloo
         @engine = engine
         @mech = @engine.platform.get_file_mech( @engine )
         @pn = pn
-        @tabs = 0
         @obj = nil
-        @in_multiline = false
-        @exiting_multiline = false
+        @source_doc = Gloo::Persist::Source::SourceDoc.new
+        @comments = Gloo::Persist::CommentBuffer.new
+        @body = Gloo::Persist::ScriptBodyCollector.new
+        @shorthand = Gloo::Persist::ShorthandExpander.new( engine )
+        @ledger = Gloo::Persist::DeclarationLedger.new( engine, pn )
         @in_block = false
         @block_value = ''
         @body_started = false
         @debug = false
       end
 
+      #
+      # The top-level objects this file declared (for save resolution).
+      #
+      def roots
+        return @ledger.roots
+      end
+
       #
       # Load the objects from the file.
       #
@@ -49,27 +69,12 @@ module Gloo
         end
 
         @engine.log.debug "Loading file '#{@pn}'"
-        @tabs = 0
-        @parent_stack = []
-        @parent = @engine.heap.root
-        @parent_stack.push @parent
+        @indent_stack = IndentStack.new( @engine.heap.root, @source_doc )
         f = @mech.read( @pn )
 
         f = join_continuations( f )
-
-        f.each_line do |line|
-          # Inside a BEGIN/END block every line is literal content -
-          # don't skip blank lines or lines that start with '#'.
-          next if !@in_block && skip_line?( line )
-
-          if !@body_started && line =~ LIB_DIRECTIVE
-            run_lib_directive line
-            next
-          end
-          @body_started = true
-
-          handle_one_line line
-        end
+        f.each_line { |line| dispatch_line( line ) }
+        finish
       end
 
       #
@@ -90,115 +95,202 @@ module Gloo
         return data.gsub( "\\\n", '' )
       end
 
+      # ---------------------------------------------------------------------
+      #    Per-line dispatch
+      # ---------------------------------------------------------------------
+
       #
-      # Process one one of the file we're loading.
+      # Route one line of the file to whichever mode we're currently in:
+      # collecting a script body, collecting a BEGIN/END block, trivia
+      # (comment/blank), a top-of-file directive, or a normal
+      # declaration.
       #
-      def handle_one_line( line )
-        if line.strip.end_with? BEGIN_BLOCK
-          @in_block = true
-          @save_line = line
-        elsif @in_block
-          if line.strip == END_BLOCK
-            @in_block = false
-            determine_indent @save_line
-            process_line @save_line
-          else
-            @block_value << line
-          end
-        else
-          determine_indent line
-          process_line line
+      def dispatch_line( line )
+        return handle_body_line( line ) if @body.active
+        return handle_block_line( line ) if @in_block
+        return handle_trivia_line( line ) if skip_line?( line )
+
+        if !@body_started && line =~ LIB_DIRECTIVE
+          @indent_stack.node.children << Source::DirectiveNode.new( line.strip )
+          run_lib_directive line
+          return
         end
+        @body_started = true
+
+        handle_declaration_line( line )
       end
 
       #
-      # Is this line a comment or a blank line?
-      # If so we'll skip it.
+      # End of file: close out anything still open so its content
+      # isn't silently dropped.
       #
-      def skip_line?( line )
-        line = line.strip
-        return true if line.empty?
-        return true if line[ 0 ] == '#'
-
-        return false
+      def finish
+        @body.finish
+        @comments.flush_into( @indent_stack.node.children )
       end
 
+      # ---------------------------------------------------------------------
+      #    Trivia (comments and blank lines)
+      # ---------------------------------------------------------------------
+
       #
-      # Determine the relative indent level for the line.
+      # 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.
       #
-      def determine_indent( line )
-        tabs = tab_count( line )
-        @indent = 0 # same level as prior line
-        if tabs > @tabs # indent
-          # TODO:  What if indent is more than one more level?
-          @tabs = tabs
-          @indent = 1
-        elsif tabs < @tabs # outdent
-          diff = @tabs - tabs
-          @tabs -= diff
-          @indent -= diff
+      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 ) )
+        else
+          @comments.push( chomped( line ), tab_count( line ) )
         end
-        puts "tabs: #{@tabs}, indent: #{@indent}, line: #{line}" if @debug
       end
 
+      # ---------------------------------------------------------------------
+      #    BEGIN / END blocks
+      # ---------------------------------------------------------------------
+
       #
-      # Process one line and add objects.
+      # Inside a BEGIN/END block every line is literal content -- kept
+      # exactly as-is, comments and blank lines included.
       #
-      def process_line( line )
-        # reset multiline unless we're actually indented
-        if @in_multiline && @multi_indent > @indent
-          puts "Done multiline mi: #{@multi_indent}, i: #{@indent}" if @debug
-          @in_multiline = false
-          @exiting_multiline = true
-        end
-
-        if @in_multiline
-          @last.add_line line
+      def handle_block_line( line )
+        if line.strip == END_BLOCK
+          @in_block = false
+          @block_end_indent = leading_ws( line )
+          finalize_declaration( @save_line )
         else
-          setup_process_obj_line
-          process_obj_line line
+          @block_value << line
         end
       end
 
+      # ---------------------------------------------------------------------
+      #    Script bodies (indented lines, no BEGIN/END)
+      # ---------------------------------------------------------------------
+
       #
-      # Setup and get ready to process an object line.
+      # One line while a script body might be open. Re-dispatches the
+      # line normally if it turns out to have closed the body.
       #
-      def setup_process_obj_line
-        if @exiting_multiline
-          @exiting_multiline = false
-          @indent += 1
-        end
+      def handle_body_line( line )
+        consumed = @body.handle_line( line, tab_count( line ) )
+        dispatch_line( line ) unless consumed
+      end
 
-        if @indent.positive?
-          @parent = @last
-          @parent_stack.push @parent
-        elsif @indent.negative?
-          @indent.abs.times do
-            @parent_stack.pop
-            @parent = @parent_stack.last
-          end
+      # ---------------------------------------------------------------------
+      #    Object declarations
+      # ---------------------------------------------------------------------
+
+      #
+      # A line that starts (or is) an object declaration.
+      #
+      def handle_declaration_line( line )
+        if line.strip.end_with?( BEGIN_BLOCK )
+          @in_block = true
+          @save_line = line
+          return
         end
+
+        finalize_declaration( line )
       end
 
       #
-      # Process one line and add objects.
+      # Place the declaration at its indentation level and create the
+      # object (and its Source::ObjNode).
       #
-      def process_obj_line( line )
-        name, type, value = split_line( line )
-        unless @block_value == ''
-          value = @block_value
-          @block_value = ''
-        end
-        params = { name: name, type: type, value: value, parent: @parent }
+      def finalize_declaration( line )
+        line_tabs = tab_count( line )
+        @indent_stack.place( line_tabs, @last, @last_node )
+        create_declared_obj( line, line_tabs )
+      end
+
+      #
+      # Create the heap object and its source node for one declaration
+      # line, and start body collection if its type calls for one.
+      #
+      def create_declared_obj( line, line_tabs )
+        name, type, value, style = split_declaration( line )
+        leaf, parent, roots, created = @shorthand.expand( name, @indent_stack.parent )
+        roots.each { |r| @ledger.root( r ) }
+        created.each { |c| @ledger.created( c ) }
+
+        prior = parent.find_child( leaf )
+        params = { :name => leaf, :type => type, :value => value, :parent => parent }
         @last = @engine.factory.create( params )
+        @ledger.clash( prior, leaf, value ) if prior
+        @ledger.created( @last )
+        @ledger.root( @last ) if parent == @engine.heap.root
 
-        if value&.empty? && @last&.multiline_value?
-          @multi_indent = 0
-          @in_multiline = true
-          puts "*** Start multiline. multi_indent: #{@multi_indent}" if @debug
-        end
+        node = build_obj_node( leading_ws( line ), name, type, value, style )
+        node.leading_doc = @comments.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
+        # one), so a later, comment-less re-declaration doesn't blank
+        # out an earlier file's doc. @last can be nil for an unknown
+        # type (factory.create logs a warning and returns nil).
+        @last.doc = node.doc if @last && @last.doc.to_s.strip.empty?
+        @indent_stack.node.children << node
+        @last_node = node
+        @obj ||= @ledger.roots.last || @last
+
+        # A whitespace-only inline value (trailing spaces after the ':'
+        # on a `script :` line) counts as no value -- start the body.
+        no_value = value.nil? || value.strip.empty?
+        @body.start( node, @last, @indent_stack.tabs ) if no_value && @last&.multiline_value?
+      end
+
+      #
+      # Split a declaration line into name/type/value, plus a style
+      # hash (:block_style, :raw_tail), folding in any BEGIN/END block
+      # value collected just before it. raw_tail is the exact source
+      # text that followed the type bracket on this line -- eg.
+      # " : BEGIN" or " :" -- kept for a save to reproduce the
+      # declaration's original spacing when unchanged.
+      #
+      def split_declaration( line )
+        splitter = LineSplitter.new( line, @indent_stack&.tabs || 0 )
+        name, type, value = splitter.split
+        style = { :raw_tail => splitter.raw_tail, :block_style => :inline }
+        return name, type, value, style if @block_value == ''
+
+        value = @block_value
+        @block_value = ''
+        style[ :block_style ] = :begin_end
+        style[ :raw_end_indent ] = @block_end_indent
+        return name, type, value, style
+      end
+
+      #
+      # Build the source node for one object declaration. raw_value is
+      # kept byte-exact with whatever was handed to the heap object's
+      # set_value (trailing newline included, for a BEGIN/END block) so
+      # a save can compare the two directly.
+      #
+      def build_obj_node( raw_indent, name, type, value, style )
+        node = Source::ObjNode.new( :name => name, :raw_type => type )
+        node.raw_indent = raw_indent
+        node.raw_tail = style[ :raw_tail ]
+        node.block_style = style[ :block_style ]
+        node.raw_value = value
+        node.raw_end_indent = style[ :raw_end_indent ] || ''
+        node.obj = @last
+        return node
+      end
+
+      #
+      # Is this line a comment or a blank line?
+      # If so we'll skip it.
+      #
+      def skip_line?( line )
+        line = line.strip
+        return true if line.empty?
+        return true if line[ 0 ] == '#'
 
-        @obj = @last if @obj.nil?
+        return false
       end
 
       #
@@ -222,10 +314,24 @@ module Gloo
       # Split the line into 3 parts.
       #
       def split_line( line )
-        o = LineSplitter.new( line, @tabs )
+        o = LineSplitter.new( line, @indent_stack&.tabs || 0 )
         return o.split
       end
 
+      #
+      # The line's leading whitespace, exactly as written.
+      #
+      def leading_ws( line )
+        return line[ /\A[ \t]*/ ]
+      end
+
+      #
+      # A line's raw text with its trailing newline removed.
+      #
+      def chomped( line )
+        return line.chomp( "\n" )
+      end
+
     end
   end
 end