gloo 6.3.1 → 6.5.0

data/lib/gloo/verbs/list.rb

@@ -74,6 +74,7 @@ module Gloo
       #
       def show_obj( obj, indent = '  ' )
         theme = @engine.theme
+        show_doc( obj, indent ) if @engine.settings.list_docs
         if obj.multiline_value? && obj.value_is_array?
           str = theme.emphasis( "#{indent}#{obj.name}" )
           str << theme.accent( " [#{obj.type_display}] : " )
@@ -89,6 +90,23 @@ module Gloo
         end
       end
 
+      #
+      # Show the object's doc (its leading comment, cleaned up) above
+      # its listing line, one '#'-prefixed line per line of doc.
+      # Silent when the object has none.
+      #
+      def show_doc( obj, indent )
+        return if obj.doc.to_s.strip.empty?
+
+        theme = @engine.theme
+        # split( -1 ), not each_line -- a doc ending in a blank '#' line
+        # ends with "\n", and each_line silently drops that trailing
+        # empty line rather than yielding it.
+        obj.doc.split( "\n", -1 ).each do |line|
+          @engine.log.show theme.muted( "#{indent}# #{line}".rstrip )
+        end
+      end
+
       #
       # Determine how many levels to show.
       #
@@ -130,12 +148,16 @@ module Gloo
             'current context. When a path is provided, it will be ' \
             'listed instead of the current context. When using context, ' \
             'the current context will be shown, but when context has ' \
-            'not been set, the root will be shown.',
+            'not been set, the root will be shown. When the list_docs ' \
+            'setting is on, any listed object that has a doc (the ' \
+            'comment block declared immediately above it in its source ' \
+            'file) shows it too.',
           :syntax => [ 'list {path.to.object}' ],
           :parameters => [
             '{path.to.object} — Optional path to object that will be listed. When no path is provided, the current context is used.'
           ],
-          :result => 'Object and children are listed out in the CLI.',
+          :result => 'Object and children are listed out in the CLI. ' \
+            'Doc lines are included when the list_docs setting is on.',
           :errors => [
             "#{TARGET_MISSING_ERR}{path.to.object} — The object specified that is to be listed could not be found."
           ],

data/lib/gloo/verbs/load.rb

@@ -122,8 +122,16 @@ module Gloo
           :errors => [
             "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb.",
             "#{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)."
+            "#{WRONG_NUM_ARGS_ERR} — load expects 2 or 3 arguments (the verb, an optional reference type, and the file/ext/lib name).",
+            'File not found: {name} — The file name given could not be ' \
+              'resolved to a gloo file (checked as a full path, and ' \
+              'relative to the project and gloo root folders).'
           ],
+          :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/ctrl/each.test.gloo

@@ -2,38 +2,36 @@
 # Each and repeat control object tests
 #
 
-tests [can] :
-  ctrl [can] :
-    each [can] :
+tests.ctrl.each [can] :
 
-      count [int] : 0
+  count [int] : 0
 
-      wrd [each] :
-        word [string] :
-        IN [string] : one two three
-        do [script] :
-          eval ^^.count + 1
-          put it into ^^.count
+  wrd [each] :
+    word [string] :
+    IN [string] : one two three
+    do [script] :
+      eval ^^.count + 1
+      put it into ^^.count
 
-      rpt [repeat] :
-        times [int] : 3
-        index [int] : 0
-        do [script] :
-          eval ^^.count + 1
-          put it into ^^.count
+  rpt [repeat] :
+    times [int] : 3
+    index [int] : 0
+    do [script] :
+      eval ^^.count + 1
+      put it into ^^.count
 
-      each_word [test] :
-        description [string] : Count words with each word
-        on_test [script] :
-          put 0 into ^^.count
-          tell ^^.wrd to run
-          eval ^^.count = 3
-          assert "expected 3 words counted"
+  each_word [test] :
+    description [string] : Count words with each word
+    on_test [script] :
+      put 0 into ^^.count
+      tell ^^.wrd to run
+      eval ^^.count = 3
+      assert "expected 3 words counted"
 
-      repeat_n_times [test] :
-        description [string] : Repeat a script n times
-        on_test [script] :
-          put 0 into ^^.count
-          tell ^^.rpt to run
-          eval ^^.count = 3
-          assert "expected repeat to run 3 times"
+  repeat_n_times [test] :
+    description [string] : Repeat a script n times
+    on_test [script] :
+      put 0 into ^^.count
+      tell ^^.rpt to run
+      eval ^^.count = 3
+      assert "expected repeat to run 3 times"

data/test.gloo/dt/date.test.gloo

@@ -2,87 +2,85 @@
 # Date tests
 #
 
-tests [can] :
-  dt [can] :
-    date [can] :
+tests.dt.date [can] :
 
-      d [date] : 
-      x [date] : 
-      future [date] : 
+  d [date] : 
+  x [date] : 
+  future [date] : 
 
-      now [test] :
-        description [string] : Get the current date
-        on_test [script] :
-          check ^^.x for blank?
-          assert "expected new date to be blank"
+  now [test] :
+    description [string] : Get the current date
+    on_test [script] :
+      check ^^.x for blank?
+      assert "expected new date to be blank"
 
-          tell ^^.x to now
-          check ^^.x for blank?
-          refute "expected date to not be blank"
+      tell ^^.x to now
+      check ^^.x for blank?
+      refute "expected date to not be blank"
 
-          tell ^^.d to now
-          eval ^^.d = ^^.x
-          assert "expected dates to be equal"
+      tell ^^.d to now
+      eval ^^.d = ^^.x
+      assert "expected dates to be equal"
 
-      add [test] :
-        description [string] : Add days to a date
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.future to now          
-          tell ^^.future to add
-          eval ^^.future = ^^.d
-          refute "expected future date to be after current date"
+  add [test] :
+    description [string] : Add days to a date
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.future to now          
+      tell ^^.future to add
+      eval ^^.future = ^^.d
+      refute "expected future date to be after current date"
 
-      subtract [test] :
-        description [string] : Subtract days from a date
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.future to now          
-          tell ^^.future to sub
-          eval ^^.future = ^^.d
-          refute "expected past date to be before current date"
+  subtract [test] :
+    description [string] : Subtract days from a date
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.future to now          
+      tell ^^.future to sub
+      eval ^^.future = ^^.d
+      refute "expected past date to be before current date"
 
-      dd [test] :
-        description [string] : Get the day portion of a date
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.d to dd
-          eval it = ^^.d
-          refute "expected day to not be the same as the date"
+  dd [test] :
+    description [string] : Get the day portion of a date
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.d to dd
+      eval it = ^^.d
+      refute "expected day to not be the same as the date"
 
-      mm [test] :
-        description [string] : Get the month portion of a date
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.d to mm
-          eval it = ^^.d
-          refute "expected month to not be the same as the date"
+  mm [test] :
+    description [string] : Get the month portion of a date
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.d to mm
+      eval it = ^^.d
+      refute "expected month to not be the same as the date"
 
-      yy [test] :
-        description [string] : Get the year portion of a date
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.d to yy
-          eval it = ^^.d
-          refute "expected year to not be the same as the date"
+  yy [test] :
+    description [string] : Get the year portion of a date
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.d to yy
+      eval it = ^^.d
+      refute "expected year to not be the same as the date"
 
-      yyyy [test] :
-        description [string] : Get the 4 digit year portion of a date
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.d to yyyy
-          eval ^^.d = it
-          refute "expected yyyy to not be the same as the date"
+  yyyy [test] :
+    description [string] : Get the 4 digit year portion of a date
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.d to yyyy
+      eval ^^.d = it
+      refute "expected yyyy to not be the same as the date"
 
-      format [test] :
-        description [string] : Format a date
-        on_test [script] :
-          put '2025.10.15' into ^^.d
-          tell ^^.d to format
-          eval it = '2025-10-15'
-          assert "expected formatted date to match"
+  format [test] :
+    description [string] : Format a date
+    on_test [script] :
+      put '2025.10.15' into ^^.d
+      tell ^^.d to format
+      eval it = '2025-10-15'
+      assert "expected formatted date to match"
 
-          tell ^^.d to format ('%m/%d')
-          eval it = '10/15'
-          assert "expected formatted date to match"
+      tell ^^.d to format ('%m/%d')
+      eval it = '10/15'
+      assert "expected formatted date to match"
 

data/test.gloo/dt/datetime.test.gloo

@@ -2,60 +2,58 @@
 # Datetime tests
 #
 
-tests [can] :
-  dt [can] :
-    datetime [can] :
-
-      d [dt] :
-
-      now [test] :
-        description [string] : Get the current datetime
-        on_test [script] :
-          check ^^.d for blank?
-          assert "expected new datetime to be blank"
-
-          tell ^^.d to now
-          check ^^.d for blank?
-          refute "expected datetime to not be blank after now"
-
-      is_today [test] :
-        description [string] : Check if datetime is today
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.d to is_today
-          assert "expected current datetime to be today"
-
-      is_past [test] :
-        description [string] : Check if datetime is in the past
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.d to is_past
-          refute "expected current datetime to not be in the past"
-
-          put 'yesterday' into ^^.d
-          tell ^^.d to is_past
-          assert "expected yesterday to be in the past"
-
-      is_future [test] :
-        description [string] : Check if datetime is in the future
-        on_test [script] :
-          tell ^^.d to now
-          tell ^^.d to is_future
-          refute "expected current datetime to not be in the future"
-
-          put 'tomorrow' into ^^.d
-          tell ^^.d to is_future
-          assert "expected tomorrow to be in the future"
-
-      format [test] :
-        description [string] : Format a datetime
-        f [dt] :
-        on_test [script] :
-          put '2025.10.15 2:30:00 PM' into ^.f
-          tell ^.f to format
-          eval it = '2025-10-15 14:30:00'
-          assert "expected formatted datetime to match"
-
-          tell ^.f to format ('%m/%d/%Y')
-          eval it = '10/15/2025'
-          assert "expected formatted datetime to match"
+tests.dt.datetime [can] :
+
+  d [dt] :
+
+  now [test] :
+    description [string] : Get the current datetime
+    on_test [script] :
+      check ^^.d for blank?
+      assert "expected new datetime to be blank"
+
+      tell ^^.d to now
+      check ^^.d for blank?
+      refute "expected datetime to not be blank after now"
+
+  is_today [test] :
+    description [string] : Check if datetime is today
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.d to is_today
+      assert "expected current datetime to be today"
+
+  is_past [test] :
+    description [string] : Check if datetime is in the past
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.d to is_past
+      refute "expected current datetime to not be in the past"
+
+      put 'yesterday' into ^^.d
+      tell ^^.d to is_past
+      assert "expected yesterday to be in the past"
+
+  is_future [test] :
+    description [string] : Check if datetime is in the future
+    on_test [script] :
+      tell ^^.d to now
+      tell ^^.d to is_future
+      refute "expected current datetime to not be in the future"
+
+      put 'tomorrow' into ^^.d
+      tell ^^.d to is_future
+      assert "expected tomorrow to be in the future"
+
+  format [test] :
+    description [string] : Format a datetime
+    f [dt] :
+    on_test [script] :
+      put '2025.10.15 2:30:00 PM' into ^.f
+      tell ^.f to format
+      eval it = '2025-10-15 14:30:00'
+      assert "expected formatted datetime to match"
+
+      tell ^.f to format ('%m/%d/%Y')
+      eval it = '10/15/2025'
+      assert "expected formatted datetime to match"