gloo 6.3.1 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 517b0f6358d83303a3e6e7536b9a16abd4a71cf9ef1649faf6abd21443fe652d
-  data.tar.gz: b43125b452393abea79914d54a2f73e7d77791891ed3e14cde8ad51e2bdb44ce
+  metadata.gz: 345f1e1145a1c3e32a2d94f39eda0246c0b36c8a6aa36857cb8a459042b97b0a
+  data.tar.gz: a8cc80d6cfe82bd0f938cf9993e3948c7ae0ca1434fc430bb79a357239f8ac70
 SHA512:
-  metadata.gz: cb9e73f9e4d4281d3ce190258bf744150176ac09c2f0e980b920f185a583015fdd3a5b64180fa0c07b6970f04f8c0eba49840495b35291846bd86e0e57dcf3d7
-  data.tar.gz: ac5e8e247415a01107fee4cc12358559eafc698ac2e5c1ffdd5ee6cc01e6c7cca54d5b9eb44fdc589a8ce692fd36367103125571d5cff038a10b6cabe27ca4ac
+  metadata.gz: 1c6f947e4282de5e585543771f30d42ec3ab85197237e805d1c560c06fc286ecd5053b5627b86f7f017368dcf3ae957c1784f74b498e885feacc247a43b17ea1
+  data.tar.gz: cd6e0ad73493fd5dd7e56dff790ed22dafa31a32d2f2347fb263cb4d6177aef4e83aaab7127ad28899d30802ffdddd6b83415f57ae27f2fc8dc2001494cd86cf

data/CLAUDE.md

@@ -58,6 +58,19 @@ Base classes: inherit from `GlooTest` (defined in `test/base_test.rb`).
 ### Gloo integration tests — `test.gloo/`
 Written in gloo itself. Each file contains `[test]` objects with `on_test` scripts using `assert` and `refute`.
 
+Run with `ruby lib/run.rb --test --quiet <paths...>` — **not** `bundle exec` (the Gemfile doesn't carry `gloo-test` / `gloo-md` / the other core-lib gems, so `[test]` and `load lib` fail under bundler; plain `ruby` uses the system gem env where they're installed).
+
+- Interpreter suite only:
+  `ruby ~/dev/gloo/lib/run.rb --test --quiet ~/dev/gloo/test.gloo/`
+- Interpreter **plus** every extension and core library:
+  ```
+  ruby ~/dev/gloo/lib/run.rb --test --quiet \
+    ~/dev/gloo/test.gloo/ \
+    ~/gloo/extensions/{alert,beep,git,ruby,slack,stats,teams}/test/ \
+    ~/dev/gloo_core_libraries/gloo-{beep,cli,db,email,md,mysql,pg,sqlite,test,web,yaml}/test/
+  ```
+  (brace expansion is shell sugar for the full explicit path list)
+
 ```
 test.gloo/
 ├── basic.test.gloo

data/docs/language_objects.md

@@ -3,6 +3,7 @@
 **Contents**
 
 - Object Naming
+- Nested Container Shorthand
 - Keywords
 - Literals
 - Value Conversion
@@ -39,6 +40,36 @@ naming [container] :
 
 See also: Pathname.
 
+## Nested Container Shorthand
+
+A declaration whose name is a dotted path creates a container for each
+prefix segment, then declares the real object under the last one. These
+two files are equivalent:
+
+```gloo
+page [container] :
+  core [container] :
+    users [container] :
+      list [container] :
+        title [string] : Users
+```
+
+```gloo
+page.core.users.list [container] :
+  title [string] : Users
+```
+
+- Each prefix segment (`page`, `core`, `users`) becomes a container,
+  unless a sibling object of that name already exists — in which case
+  that object is used as-is.
+- The shorthand works at any indent level; the prefix is resolved
+  relative to the current parent.
+- Several shorthand lines can share a prefix — `page.core.users [...]`
+  and `page.core.settings [...]` both reuse the same `page` and
+  `page.core` containers.
+- Indented lines below a shorthand declaration are children of the last
+  segment (`list` above), not of any prefix container.
+
 ## Keywords
 
 Gloo doesn't reserve words the way many languages do. A verb keyword like `put` or an object type name like `string` can also be used as an object name — there's no parser conflict, because verbs are only looked up as the first word of a statement, and object type names are only looked up where a type is expected (inside the `[ ]` on a declaration). Everywhere else, the word is just a pathname segment (see Object Naming, above).
@@ -60,6 +91,11 @@ The following rules apply to literal values:
 
 - Strings
     - Can be delimited by single or double quotes. (`"` or `'`)
+    - A quote of the other kind inside needs no escaping —
+      `'{"x":1}'` is the string `{"x":1}`, which is the usual way to
+      write a JSON literal.
+    - A quote of the same kind inside is escaped with a backslash —
+      `"say \"hi\""` is the string `say "hi"`.
 - Numbers
     - Integer and decimal numbers need no delimiters.
     - To refer to a decimal with no fractional value, include `.0` to indicate a decimal value.
@@ -89,6 +125,8 @@ The following rules apply to literal values:
       show ^.s
       put "You're Awesome!" into ^.s
       show ^.s
+      put '{"lang":"gloo"}' into ^.s
+      show ^.s
 
       # Number literals
       put 1 into ^.i

data/docs/language_scripting.md

@@ -3,6 +3,7 @@
 **Contents**
 
 - Gloo Script Files
+- Comments
 - Gloo Constants
 - Line Continuation
 
@@ -26,6 +27,46 @@ hello [can] :
   on_load [script] : show 'hello world'
 ```
 
+## Comments
+
+A line whose first non-blank character is `#` is a comment. Whole-line comments
+can appear anywhere — between objects, inside a container, or inside a script
+body — and are ignored when the file runs.
+
+```gloo
+#
+# A whole-line comment.
+#
+demo [can] :
+  # a comment inside the container
+  msg [string] : hello
+  on_load [script] :
+    # a comment inside the script body
+    show demo.msg
+```
+
+A statement line may also end with an inline `# ...` comment. It is stripped
+before the statement runs, so it has no effect on execution:
+
+```gloo
+on_load [script] :
+  show 3 + 4        # prints 7
+  check demo.msg for blank?
+  show it           # prints false
+```
+
+Two things are *not* treated as inline comments, and are left alone:
+
+- a `#` inside a quoted string — `show 'a # b'`
+- a `#` with no space before it — a URL fragment such as
+  `http://example.com/page#section`
+
+An inline comment on an object declaration is also left alone — everything after
+the `:` is the object's value, so `note [string] : see item # 5` stores the
+string `see item # 5`.
+
+---
+
 ## Gloo Constants
 
 There is no gloo language construct for constants. They are simply objects. But by convention, constants are named in all caps. They might be in a container or at the root object level.

data/docs/verbs.md

@@ -9,8 +9,9 @@ Verbs aren't just for scripts, though. They're also the interactive language of
 - Run
 - Tell
 - Put
+- Load & Save
 
-This page walks through three of the most commonly used verbs to get a feel for how they work together. For the complete list of verbs, their full syntax, and every error they can raise, use the in-app help: enter `help` (or `?`), then `verbs` to list them all, or `verb {name}` for detail on one (see Application, Help).
+This page walks through the most commonly used verbs to get a feel for how they work together. For the complete list of verbs, their full syntax, and every error they can raise, use the in-app help: enter `help` (or `?`), then `verbs` to list them all, or `verb {name}` for detail on one (see Application, Help).
 
 ## Run
 
@@ -67,6 +68,30 @@ put {expression} into {dst.path}
 
 `it` also picks up the result of the evaluation, same as with other verbs — see It.
 
+## Load & Save
+
+`load` reads a `.gloo` file into the heap and runs its `on_load` script. Give a path relative to the project folder (no extension needed) or a full path (extension required); `*` in place of a file name loads every `.gloo` file in a folder.
+
+```gloo
+> load my/project/config
+> load my/app/*
+> load ~/.my_app/settings.gloo
+```
+
+`save` writes loaded objects back to their files. With no argument it saves every open file; with an object it saves the file (or files) that object's tree came from; with `to {path}` it saves to a new file and remembers the mapping.
+
+```gloo
+> save                        # every open file
+> save config                 # just config's file
+> save config to backups/config
+```
+
+A save is a **rewrite, not a regeneration**: comments, blank lines, and the original spacing are kept, and only the values you actually changed are re-written. A declaration you never touched comes back byte-for-byte.
+
+Several files can contribute to one container — declare `app [container] :` in each and add different children. They merge in the heap, and each file's save only rewrites its own declarations. If two files declare the *same* object with different values, the first one loaded wins and `load` logs a warning.
+
+An object can also save itself: `tell config to save`.
+
 ---
 
-`run`, `tell`, and `put` cover a lot of ground on their own, but there are 26 more verbs — `show`, `if`, `create`, `each`, `check`, and so on — all documented in-app. Enter `help` (or `?`), then `verbs` to browse them. (This page itself is also viewable in-app: `help> doc verbs`.)
+`run`, `tell`, `put`, and `load` / `save` cover a lot of ground, but there are more than two dozen other verbs — `show`, `if`, `create`, `each`, `check`, `reload`, `unload`, and so on — all documented in-app. Enter `help` (or `?`), then `verbs` to browse them. (This page itself is also viewable in-app: `help> doc verbs`.)

data/lib/VERSION

@@ -1 +1 @@
-6.3.1
+6.4.0

data/lib/VERSION_NOTES

@@ -1,3 +1,9 @@
+6.4.0 - 2026.09.06
+ - Persistance refresh with updates for loading and saving
+ - Nested container shortcut syntax
+ - Fixes a number of comment and quoting issues
+
+
 6.3.1 - 2026.09.01
  - Fixes issue with MD in a text block (# ignored as comments)
 

data/lib/gloo/core/obj.rb

@@ -118,6 +118,29 @@ module Gloo
         return false
       end
 
+      #
+      # Serialize this object's value for saving to a file.
+      # Returns the text that follows "name [type]" on the declaration
+      # line -- including the leading ' :' and, for a multi-line string
+      # value, the additional indented lines and the closing END marker.
+      # indent is the indentation level of the declaration line itself.
+      #
+      def serialize_value( indent )
+        return " : #{value_display}" unless value_string? && value.include?( "\n" )
+
+        return serialize_block_value( indent )
+      end
+
+      #
+      # Serialize a multi-line string value as a BEGIN/END block.
+      #
+      def serialize_block_value( indent )
+        t = "\t" * indent
+        inner = "\t" * ( indent + 1 )
+        body = value.split( "\n" ).map { |line| "#{inner}#{line}" }.join( "\n" )
+        return " : BEGIN\n#{body}\n#{t}END"
+      end
+
       #
       # Is the value a String?
       #
@@ -306,7 +329,7 @@ module Gloo
       # Get a list of message names that this object receives.
       #
       def self.messages
-        return %w[reload unload blank? contains? responds_to?]
+        return %w[save reload unload blank? contains? responds_to?]
       end
 
       #
@@ -356,6 +379,22 @@ module Gloo
         @engine.persist_man.unload self
       end
 
+      #
+      # Send the object the save message: tell it to save itself,
+      # rather than going through the save verb. Same rules as
+      # `save {path.to.object}` -- saves every file that owns a
+      # declaration in this object's root, or saves fresh to a default
+      # path if it isn't mapped to a file yet.
+      #
+      def msg_save
+        if self.root?
+          @engine.err 'Cannot save the root object.'
+          return
+        end
+
+        @engine.persist_man.save self.pn
+      end
+
       #
       # Send the object the reload message.
       # Note that this will only work for objects with file assoications.

data/lib/gloo/core/parser.rb

@@ -21,7 +21,11 @@ module Gloo
       # Parse a command from the immediate execution context.
       #
       def parse_immediate( full_cmd )
-        # Break the full command into verb and params
+        # Drop an inline trailing comment first, then break the
+        # command into verb and params.
+        full_cmd = strip_comment( full_cmd )
+        return nil if full_cmd.strip.empty?
+
         cmd, params = split_params full_cmd
 
         # Params are the parenthetical part of the command at the end
@@ -35,6 +39,31 @@ module Gloo
         return nil
       end
 
+      #
+      # Remove an inline trailing comment: the first '#' that starts a
+      # word (at the start of the command, or right after whitespace)
+      # and is not inside a quoted string -- and everything after it.
+      #
+      # Left alone: a '#' inside single or double quotes (show 'a # b'),
+      # a '#' glued to preceding text (a URL fragment like
+      # http://x?id=1#frag), and a command with no such '#'. Object
+      # declaration values in a .gloo file never reach here -- they're
+      # split by LineSplitter, not the parser.
+      #
+      def strip_comment( full_cmd )
+        quote = nil
+        full_cmd.each_char.with_index do |ch, i|
+          if quote
+            quote = nil if ch == quote
+          elsif Gloo::Core::Tokens::QUOTE_CHARS.include?( ch )
+            quote = ch
+          elsif ch == '#' && ( i.zero? || full_cmd[ i - 1 ] =~ /\s/ )
+            return full_cmd[ 0...i ].rstrip
+          end
+        end
+        return full_cmd
+      end
+
       #
       # If additional params were provided, split them out
       # from the token list.

data/lib/gloo/core/tokens.rb

@@ -154,8 +154,9 @@ module Gloo
       # An inline call (invoke( ... ) / ~>( ... )) is checked for
       # first since it needs to be quote-aware in its own right (a
       # call's args can include a quoted string) - see
-      # find_call_range. Falls through to the original quote-then-
-      # plain-split handling, unchanged, when there's no call.
+      # find_call_range. Otherwise the first quoted run (whichever
+      # quote char opens first) becomes one token, and the rest is
+      # split on spaces.
       #
       def tokenize( str )
         range = find_call_range( str )
@@ -163,27 +164,52 @@ module Gloo
           tokenize( str[ 0...range.first ] ) if range.first.positive?
           @tokens << str[ range ]
           tokenize( str[ range.last + 1..-1 ] ) if range.last + 1 < str.length
-        elsif str.index( '"' )
-          i = str.index( '"' )
-          j = str.index( '"', i + 1 )
-          j ||= str.length
-
-          tokenize( str[ 0..i - 1 ] ) if i > 1
-          @tokens << str[ i..j ]
-          tokenize( str[ j + 1..-1 ] ) if j + 1 < str.length
-        elsif str.index( "'" )
-          i = str.index( "'" )
-          j = str.index( "'", i + 1 )
-          j ||= str.length
-
-          tokenize( str[ 0..i - 1 ] ) if i > 1
-          @tokens << str[ i..j ]
-          tokenize( str[ j + 1..-1 ] ) if j + 1 < str.length
+          return
+        end
+
+        qi, qc = first_quote( str )
+        if qi
+          close = closing_quote( str, qi, qc )
+          tokenize( str[ 0...qi ] ) if qi.positive?
+          @tokens << str[ qi..close ]
+          tokenize( str[ close + 1..-1 ] ) if close + 1 < str.length
         else
           str.strip.split( ' ' ).each { |t| @tokens << t }
         end
       end
 
+      #
+      # Find the first quote character in the string, of either kind
+      # -- returns [index, char], or [nil, nil] if there is none. The
+      # kind that opens first wins, so a " inside a '...' literal (and
+      # vice versa) is treated as ordinary content.
+      #
+      def first_quote( str )
+        found = nil
+        QUOTE_CHARS.each do |q|
+          i = str.index( q )
+          found = [ i, q ] if i && ( found.nil? || i < found[ 0 ] )
+        end
+        return found || [ nil, nil ]
+      end
+
+      #
+      # Index of the quote that closes the one opened at open_index.
+      # A backslash-escaped quote (\" or \') does not close the
+      # string. Returns str.length if it is never closed.
+      #
+      def closing_quote( str, open_index, quote_char )
+        i = open_index + 1
+        while i < str.length
+          ch = str[ i ]
+          return i if ch == quote_char
+
+          i += 1
+          i += 1 if ch == '\\'
+        end
+        return str.length
+      end
+
       #
       # Find the char range of the first top-level (not inside a
       # quoted string) invoke(...)/~>(...) call in str. Returns nil

data/lib/gloo/expr/l_string.rb

@@ -31,19 +31,23 @@ module Gloo
       end
 
       #
-      # Given a string with leading and trailing quotes,
-      # strip them out.
+      # Given a string with leading and trailing quotes, strip them
+      # out. A quote of the other kind inside needs nothing done to it
+      # ('{"x":1}' -> {"x":1}); an escaped quote of the same kind is
+      # unescaped ("say \"hi\"" -> say "hi").
       #
       def self.strip_quotes( str )
         if str.start_with?( '"' )
           str = str[ 1..-1 ]
           str = str[ 0..-2 ] if str.end_with?( '"' )
-          return str
+          return str.gsub( '\\"', '"' )
         elsif str.start_with?( "'" )
           str = str[ 1..-1 ]
           str = str[ 0..-2 ] if str.end_with?( "'" )
-          return str
+          return str.gsub( "\\'", "'" )
         end
+
+        return str
       end
 
       #

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.
       #