gloo 6.3.0 → 6.4.0

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

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

data/lib/gloo/verbs/load.rb

@@ -124,6 +124,11 @@ module Gloo
             "#{UNKNOWN_OPT_ERR} — The reference type given isn't file, ext, or lib.",
             "#{WRONG_NUM_ARGS_ERR} — load expects 2 or 3 arguments (the verb, an optional reference type, and the file/ext/lib name)."
           ],
+          :notes => 'Several files can contribute to one container: ' \
+            'declare it in each file and add different children, and ' \
+            'they merge in the heap. If two loaded files declare the ' \
+            'same object with different values, the first one loaded ' \
+            'wins and a warning is logged.',
           :examples => <<~EXAMPLES.strip
             > load my/project/file
             > load my/app/*

data/lib/gloo/verbs/reload.rb

@@ -61,6 +61,9 @@ module Gloo
             'loaded again. Note that re-load does not trigger the ' \
             'on_load script to run. There is an on_reload message sent ' \
             'to all open files.',
+          :notes => 'If a file has changes that have not been saved, ' \
+            'reloading discards them (a warning is logged, but the ' \
+            'reload still proceeds).',
           :examples => <<~EXAMPLES.strip
             > reload
           EXAMPLES

data/lib/gloo/verbs/save.rb

@@ -10,14 +10,16 @@ module Gloo
 
       KEYWORD = 'save'.freeze
       KEYWORD_SHORT = 'sv'.freeze
+      TO = 'to'.freeze
+      MISSING_PATH_ERR = "'Save ... to' must include a path!".freeze
 
       #
       # Run the verb.
       #
       def run
-        # TODO:  Not currently using folders or keeping
-        # track of where the object was loaded from.
-        @engine.persist_man.save @tokens.second
+        return @engine.persist_man.save @tokens.second unless @tokens.index_of( TO )
+
+        run_save_to
       end
 
       #
@@ -34,6 +36,26 @@ module Gloo
         return KEYWORD_SHORT
       end
 
+      # ---------------------------------------------------------------------
+      #    Private functions
+      # ---------------------------------------------------------------------
+
+      private
+
+      #
+      # Run 'save {obj} to {path}'.
+      #
+      def run_save_to
+        name = @tokens.before_token( TO )[ 1 ]
+        path = @tokens.after_token( TO )
+        unless path
+          @engine.err MISSING_PATH_ERR
+          return
+        end
+
+        @engine.persist_man.save_to( name, path )
+      end
+
       # ---------------------------------------------------------------------
       #    Verb Documentation
       # ---------------------------------------------------------------------
@@ -45,17 +67,42 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'Save a previously loaded object to a .gloo ' \
-            'file. The path will be for the root level object that was ' \
-            'loaded earlier.',
-          :syntax => [ 'save {path.to.object}' ],
+          :description => 'Save an object to a .gloo file. With no ' \
+            'path, saves every file that owns a declaration in the ' \
+            "object's root (its file, or every contributing file for " \
+            '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.",
+          :syntax => [
+            'save',
+            'save {path.to.object}',
+            'save {path.to.object} to {path}'
+          ],
           :parameters => [
-            '{path.to.object} — Name of the object file that is to be saved.'
+            '{path.to.object} — Name of the object to save.',
+            '{path} — Where to save it, relative to the project root ' \
+              '(.gloo appended if omitted). Registers the mapping, so ' \
+              'a later bare save includes it.'
+          ],
+          :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.',
+          :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.'
           ],
-          :result => 'The file is updated with the latest object state.',
-          :notes => 'The save verb is not currently fully functional.',
+          :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.",
           :examples => <<~EXAMPLES.strip
+            > save
             > save my_obj
+            > save my_obj to sub/my_obj
           EXAMPLES
         }
       end

data/test.gloo/lang/shorthand.test.gloo

@@ -0,0 +1,29 @@
+#
+# Nested container shorthand tests
+#
+# A dotted name in a declaration (page.core.title [string] :) creates
+# a container for each prefix segment, then declares the real object
+# under the last one.
+#
+
+tests [can] :
+  lang [can] :
+    shorthand [can] :
+
+      page.core.title [string] : Home
+      page.core.count [int] : 3
+
+      builds_the_container_chain [test] :
+        description [string] : a dotted name creates a container for each prefix segment.
+        on_test [script] :
+          eval ^^.page.core.title = 'Home'
+          assert "expected the shorthand-built value to be reachable"
+
+          check ^^.page for contains?
+          assert "expected 'page' to be a real container"
+
+      reuses_an_existing_prefix [test] :
+        description [string] : a second shorthand line reuses the same containers.
+        on_test [script] :
+          eval ^^.page.core.count = 3
+          assert "expected both shorthand lines to share the 'core' container"

data/test.gloo/objs/json.test.gloo

@@ -20,6 +20,7 @@ tests [can] :
       built [json] :
       out [can] :
       found [string] :
+      assigned [json] :
 
       get_a_value [test] :
         description [string] : get pulls a value out by dotted path.
@@ -68,3 +69,11 @@ tests [can] :
           tell ^^.compact to get ( 'b.c' )
           eval it = '2'
           assert "expected the value to still be reachable after pretty"
+
+      assign_a_json_string_at_run_time [test] :
+        description [string] : a quote-containing literal can be put into an object at run time.
+        on_test [script] :
+          put '{"lang":"gloo","ok":true}' into tests.objs.json.assigned
+          tell ^^.assigned to get ( 'lang' )
+          eval it = 'gloo'
+          assert "expected the run-time JSON string to be assigned and readable"

data/test.gloo/objs/script.test.gloo

@@ -18,6 +18,6 @@ tests [can] :
           assert "expected it to be 7"
 
           put "eval ^.b = true" into ^^.a
-          tell run ^^.a
+          run ^^.a
           assert "expected it to be true"
 

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

@@ -12,6 +12,14 @@ tests [can] :
         three 3 tree
       END
 
+      # inside a block every line is literal - '#' lines and blank
+      # lines are kept, not treated as comments/blanks
+      hashed [text] : BEGIN
+# a heading
+
+- a list item
+      END
+
       b [string] :
 
       verify_text [test] :
@@ -56,12 +64,25 @@ tests [can] :
           assert "expected text to have 5 words"
 
       count_lines [test] :
-        description [string] : Get the number of lines 
+        description [string] : Get the number of lines
         on_test [script] :
           tell ^^.a to count_lines
           eval it = 3
           assert "expected text to have 3 lines"
 
+      block_keeps_hash_and_blank_lines [test] :
+        description [string] : a BEGIN/END block keeps '#' lines and blank lines verbatim
+        on_test [script] :
+          check ^^.hashed for substring? ( "# a heading" )
+          assert "expected the '#' line to be kept, not stripped as a comment"
+
+          check ^^.hashed for substring? ( "- a list item" )
+          assert "expected content after the blank line to be kept"
+
+          tell ^^.hashed to count_lines
+          eval it = 3
+          assert "expected 3 lines: heading, blank, list item"
+
       starts_with [test] :
         description [string] : Check if the string starts with a value
         on_test [script] :

data/test.gloo/string/str.test.gloo

@@ -21,6 +21,21 @@ tests [can] :
         eval ^^.s = "hello world"
         assert "expected s to be 'hello world'"
 
+    put_a_quote_containing_value [test] :
+      description [string] : Put a literal that contains quote characters
+      on_test [script] :
+        put '{"x":1}' into ^^.s
+        eval ^^.s = '{"x":1}'
+        assert "expected s to hold the JSON string"
+
+        put "it's here" into ^^.s
+        eval ^^.s = "it's here"
+        assert "expected s to hold the apostrophe string"
+
+        put "say \"hi\"" into ^^.s
+        eval ^^.s = 'say "hi"'
+        assert "expected s to hold the unescaped double-quote string"
+
     blank [test] :
       description [string] : Check to see if the string is blank
       on_test [script] :

data/test.gloo/verbs/reload.test.gloo

@@ -0,0 +1,57 @@
+#
+# Reload message tests -- 'tell {obj} to reload' re-reads the file.
+#
+# The bare 'reload' verb restarts the engine (covered by the unit
+# tests). These exercise per-object reload against a /tmp scratch file
+# that gets rewritten between load and reload.
+#
+
+tests [can] :
+  verbs [can] :
+    reload [can] :
+
+      f [file] : /tmp/gloo_reload_test.gloo
+      v1 [text] : BEGIN
+demo [container] :
+  msg [string] : original
+END
+
+      v2 [text] : BEGIN
+demo [container] :
+  msg [string] : edited outside gloo
+  added [string] : brand new
+END
+
+      reload_picks_up_an_external_change [test] :
+        description [string] : editing the file on disk then reloading takes effect.
+        on_test [script] :
+          tell ^^.f to write ( ^^.v1 )
+          load /tmp/gloo_reload_test.gloo
+          eval demo.msg = 'original'
+          assert "sanity: loaded the first version"
+
+          tell ^^.f to write ( ^^.v2 )
+          tell demo to reload
+
+          eval demo.msg = 'edited outside gloo'
+          assert "reload should pick up the changed value"
+          eval demo.added = 'brand new'
+          assert "reload should pick up a newly added child"
+
+          tell demo to unload
+          tell ^^.f to delete
+
+      reload_discards_an_in_memory_edit [test] :
+        description [string] : an unsaved change is thrown away by reload.
+        on_test [script] :
+          tell ^^.f to write ( ^^.v1 )
+          load /tmp/gloo_reload_test.gloo
+
+          put 'not saved' into demo.msg
+          tell demo to reload
+
+          eval demo.msg = 'original'
+          assert "reload should restore the on-disk value"
+
+          tell demo to unload
+          tell ^^.f to delete

data/test.gloo/verbs/save.test.gloo

@@ -0,0 +1,115 @@
+#
+# Save verb tests -- real load -> edit -> save round trips.
+#
+# Each test writes a .gloo fixture to /tmp, loads it, does something,
+# saves, reads the file back, and asserts on the raw text. Every test
+# unloads its object and deletes its scratch file at the end so the
+# next one starts clean.
+#
+
+tests [can] :
+  verbs [can] :
+    save [can] :
+      f [file] : /tmp/gloo_save_test.gloo
+      g [file] : /tmp/gloo_save_test_2.gloo
+      to_target [file] : /tmp/gloo_save_test_to.gloo
+      out [string] : BEGIN
+				#
+				# a comment above demo
+				#
+				demo [container] :
+				  msg [string] : hello
+			END
+      err [bool] : false
+
+      on_error [script] :
+        put true into ^.err
+
+      #
+      # The fixture used by most tests: two comments, a changed-in-place
+      # value, and an untouched sibling.
+      #
+      fixture [text] : BEGIN
+#
+# a comment above demo
+#
+demo [container] :
+  msg [string] : hello
+  # a comment above other
+  other [string] : world
+END
+
+      round_trip_preserves_comments_and_untouched_lines [test] :
+        description [string] : load, change one value, save -- comments and the untouched sibling survive.
+        on_test [script] :
+					put false into ^^.err
+					tell ^^.f to write ( ^^.fixture )
+					load /tmp/gloo_save_test.gloo
+					put 'changed' into demo.msg
+					save demo
+					eval ^^.err = false
+					assert "save should not error"
+					tell ^^.f to read ( ^^.out )
+					check ^^.out for substring? ( "# a comment above demo" )
+					assert "the leading comment block should survive"
+					check ^^.out for substring? ( "# a comment above other" )
+					assert "the inner comment should survive"
+					check ^^.out for substring? ( "msg [string] : changed" )
+					assert "the changed value should be written"
+					check ^^.out for substring? ( "other [string] : world" )
+					assert "the untouched sibling should be unchanged"
+					tell demo to unload
+					tell ^^.f to delete
+      unchanged_file_round_trips_byte_for_byte [test] :
+        description [string] : load then save with no change reproduces the file exactly.
+        on_test [script] :
+					tell ^^.f to write ( ^^.fixture )
+					load /tmp/gloo_save_test.gloo
+					save demo
+					tell ^^.f to read ( ^^.out )
+					eval ^^.out = ^^.fixture
+					assert "an unchanged save should reproduce the original text"
+					tell demo to unload
+					tell ^^.f to delete
+      deleting_an_object_drops_its_line [test] :
+        description [string] : removing a child and saving drops just that declaration.
+        on_test [script] :
+					tell ^^.f to write ( ^^.fixture )
+					load /tmp/gloo_save_test.gloo
+					tell demo.other to unload
+					save demo
+					tell ^^.f to read ( ^^.out )
+					check ^^.out for substring? ( "msg [string] : hello" )
+					assert "the kept sibling should still be there"
+					check ^^.out for substring? ( "other [string]" )
+					refute "the removed child's line should be gone"
+					tell demo to unload
+					tell ^^.f to delete
+      save_to_a_new_path_creates_the_file [test] :
+        description [string] : save {obj} to {path} writes a new file and registers it.
+        on_test [script] :
+					tell ^^.f to write ( ^^.fixture )
+					load /tmp/gloo_save_test.gloo
+					save demo to /tmp/gloo_save_test_to
+					check ^^.to_target for exists?
+					assert "save ... to should create the target file"
+					tell ^^.to_target to read ( ^^.out )
+					check ^^.out for substring? ( "msg [string] : hello" )
+					assert "the new file should hold the object"
+					tell demo to unload
+					tell ^^.f to delete
+					tell ^^.to_target to delete
+      reload_discards_unsaved_changes [test] :
+        description [string] : reload throws away edits that were not saved.
+        on_test [script] :
+					tell ^^.f to write ( ^^.fixture )
+					load /tmp/gloo_save_test.gloo
+					put 'not saved' into demo.msg
+					eval demo.msg = 'not saved'
+					assert "sanity: the edit landed"
+					tell demo to reload
+					eval demo.msg = 'hello'
+					assert "reload should restore the on-disk value"
+					tell demo to unload
+					tell ^^.f to delete
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gloo
 version: !ruby/object:Gem::Version
-  version: 6.3.0
+  version: 6.4.0
 platform: ruby
 authors:
 - Eric Crane
@@ -384,12 +384,22 @@ files:
 - lib/gloo/objs/web/http_post.rb
 - lib/gloo/objs/web/json.rb
 - lib/gloo/objs/web/uri.rb
+- lib/gloo/persist/comment_buffer.rb
+- lib/gloo/persist/declaration_ledger.rb
 - lib/gloo/persist/disc_mech.rb
 - lib/gloo/persist/file_loader.rb
 - lib/gloo/persist/file_saver.rb
 - lib/gloo/persist/file_storage.rb
+- lib/gloo/persist/indent_stack.rb
 - lib/gloo/persist/line_splitter.rb
 - lib/gloo/persist/persist_man.rb
+- lib/gloo/persist/script_body_collector.rb
+- lib/gloo/persist/shorthand_expander.rb
+- lib/gloo/persist/source/blank_node.rb
+- lib/gloo/persist/source/comment_node.rb
+- lib/gloo/persist/source/directive_node.rb
+- lib/gloo/persist/source/obj_node.rb
+- lib/gloo/persist/source/source_doc.rb
 - lib/gloo/plugin/base.rb
 - lib/gloo/plugin/callback.rb
 - lib/gloo/plugin/ext_manager.rb
@@ -443,6 +453,7 @@ files:
 - test.gloo/lang/load_lib_directive.test.gloo
 - test.gloo/lang/naming.test.gloo
 - test.gloo/lang/ops.test.gloo
+- test.gloo/lang/shorthand.test.gloo
 - test.gloo/math/add.test.gloo
 - test.gloo/math/div.test.gloo
 - test.gloo/math/mult.test.gloo
@@ -481,7 +492,9 @@ files:
 - test.gloo/verbs/log.test.gloo
 - test.gloo/verbs/move.test.gloo
 - test.gloo/verbs/put.test.gloo
+- test.gloo/verbs/reload.test.gloo
 - test.gloo/verbs/run.test.gloo
+- test.gloo/verbs/save.test.gloo
 - test.gloo/verbs/show.test.gloo
 - test.gloo/verbs/tell.test.gloo
 - test.gloo/verbs/throw.test.gloo