gloo 7.1.1 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d25bb60fb25bb1b42e44eeac62b0ec3bae86a9f3770c696caf4ab39b7f1c9784
-  data.tar.gz: 260731b8d5f1cd1c6f3718be0d26f17d39139795e7e5c13ff8908a4fc3f1c453
+  metadata.gz: 153d674b150e06c999a0756c90c41f872a410205f516eaa8b560335f93ec0e2b
+  data.tar.gz: 1b11115e161f139b44dc6750713e0e883f638ae58048c8b3007441cbf681f319
 SHA512:
-  metadata.gz: 3729efcd7dcfa5964a408fb28750bd2ac7caea3af323b1ea8c8b75503446f51805db7f20b05bfd705a9ac020bd06fe6fba5135013137e937f7dd6f499e134f40
-  data.tar.gz: d69918fdaf8ab491ac5bc21cd7a838048ef4eaf2299d8a867eea017b14c0f5ca3a314e7106e6fc0bf00fad8e949550efaae897121d8ae11de4d964a1a0231218
+  metadata.gz: 3e92b508048653b4e1e4e283a7e90de32605b4a239f56b7b24123c600e5b38a6af582a50a6d2a7130da8ed73d8ded9f0e6aab2a75798a9709939749cf72119dd
+  data.tar.gz: 19cd40e0d35cfed856aa7eb6ffe4fe648adde3c706656d81211d01f0c940a4c38dd63b0bffe2a4b50b3b57d9e76afba997050c7fca99066f2fe6529825d05591

data/Rakefile

@@ -2,8 +2,6 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  ENV[ 'GLOO_ENV' ] = 'TEST'
-
   t.warning = false
   t.libs << 'test'
   t.libs << 'lib'

data/docs/application.md

@@ -31,6 +31,8 @@ gloo [global option] [file]
 
 Running gloo with a file specified will run that file. Once that file is done, gloo will quit. However, by specifying `--cli`, once the file has finished, gloo will remain open in CLI mode.
 
+Gloo can also be started from another Ruby program; see Development, Running Gloo from Ruby.
+
 If a file named on the command line can't be found (a typo, the wrong folder, a missing `.gloo` extension on a full path), gloo prints `File '{name}' was not found.` to stderr and exits with a non-zero status. Any other load or run error also exits non-zero — including syntax errors in a file that otherwise loaded (gloo keeps loading past them, reporting each with its file and line) — so a shell script calling gloo can tell a failed run from a clean one.
 
 When specifying a file there are a couple ways to reference the gloo file to open:
@@ -76,6 +78,11 @@ When specifying a file there are a couple ways to reference the gloo file to ope
              - Exits with status 1 if any test failed, or errors or warnings
                were logged that no test expected; 0 otherwise.
              - See Testing.
+--embed      - Run in Embedded mode
+             - Start the engine and return, for a Ruby program that drives
+               gloo itself.
+             - This is the default when gloo is created in code with no file
+               or mode. See Development, Running Gloo from Ruby.
 --version    - Show application version
 --help       - Show the help screen
 ```

data/docs/development.md

@@ -1,6 +1,6 @@
 # Development
 
-How the interpreter's source is laid out, how to run its tests, and the conventions to follow when changing it. This page is for working on gloo itself; for using gloo, start with Getting Started.
+How the interpreter's source is laid out, how to run its tests, the conventions to follow when changing it, and how to run gloo from your own Ruby code. This page is for working on gloo itself or driving it from Ruby; for using gloo, start with Getting Started.
 
 **Contents**
 
@@ -8,6 +8,7 @@ How the interpreter's source is laid out, how to run its tests, and the conventi
 - Tests
 - Documentation
 - Reporting Errors
+- Running Gloo from Ruby
 
 ## Source Layout
 
@@ -40,7 +41,7 @@ There are two automated suites. Run both when making a change, and add to both:
 
 ### Unit tests — `test/`
 
-Standard Ruby minitest tests. The layout mirrors `lib/gloo/`, one test file per class or verb: `test/<area>/<name>_test.rb`, for example `test/verbs/show_test.rb` for `lib/gloo/verbs/show.rb`. Test classes inherit from `GlooTest` (in `test/base_test.rb`).
+Standard Ruby minitest tests. The layout mirrors `lib/gloo/`, one test file per class or verb: `test/<area>/<name>_test.rb`, for example `test/verbs/show_test.rb` for `lib/gloo/verbs/show.rb`. Test classes inherit from `BaseTest` (in `test/base_test.rb`), or from `BaseEngineTest` (in `test/base_engine_test.rb`) for a test that needs a started engine in `@engine`.
 
 ```
 rake test
@@ -98,3 +99,22 @@ Gloo reports every problem in a way scripts can see (see Language, Syntax, Error
 - A question whose answer is "no" is just a result, not an error.
 
 Don't use `@engine.log.error` or `@engine.log.warn` for these; they only write to the log, and scripts can't see them. Build "not found" messages with `Gloo::Core::NotFound` (for example `NotFound.object( name )`) so they always read the same way.
+
+## Running Gloo from Ruby
+
+Gloo can be started from another Ruby program, such as a test harness or an app that runs gloo commands. Create the engine with the params gloo should see — the same words you would type after `gloo` on the command line:
+
+```ruby
+require 'gloo'
+
+context = Gloo::App::EngineContext.new( [] )
+engine = Gloo::App::Engine.new( context )
+engine.start
+
+engine.process_cmd "create greeting as string : 'hello'"
+engine.process_cmd 'show greeting'
+```
+
+Only those params are used. The Ruby program's own command line (`ARGV`) is never read, so running `ruby harness.rb some_file.gloo` doesn't make gloo load `some_file.gloo`. Pass anything gloo should see explicitly. Only the `gloo` command itself (`Gloo.run`) reads the command line.
+
+With no file and no mode switch, the engine runs in Embedded mode (`--embed`): `start` sets the engine up and returns without loading or running anything, and your code drives it from there, for example with `process_cmd`.

data/docs/iterators.md

@@ -9,7 +9,7 @@
 - Each Line
 - Each Word
 - Repeat
-- Ending a Loop Early
+- Skipping an Item or Ending a Loop
 
 ## Each
 
@@ -215,7 +215,7 @@ Iterate for each line in a text block (string).
 Children:
 
 - `line` (string)
-    - The single line of text.
+    - The single line of text, without its line ending (`\n` or `\r\n`). A blank line is still visited, as an empty string.
 - `in` (text)
     - The block of text or string.
 - `do` (script)
@@ -330,9 +330,26 @@ repeat [can] :
 
 See also: Object Base.
 
-## Ending a Loop Early
+## Skipping an Item or Ending a Loop
 
-`break` in a loop's `do` script ends the whole loop, not just that pass. This works for `repeat` and every kind of `each`. The script that ran the loop carries on with its next line:
+`break` ends the script it's written in. In a loop's `do` script, that skips the rest of this pass, and the loop goes on with the next item. This works for `repeat` and every kind of `each`:
+
+```gloo
+skip [can] :
+  on_load [script] :
+    tell skip.r to run
+    show 'after the loop'
+  r [repeat] :
+    times [int] : 5
+    index [int] :
+    do [script] :
+      if skip.r.index = 2 then break
+      show skip.r.index
+```
+
+This shows `0`, `1`, `3`, `4`, then `after the loop`.
+
+`break loop` ends the whole loop. The script that ran the loop carries on with its next line:
 
 ```gloo
 early [can] :
@@ -343,12 +360,12 @@ early [can] :
     times [int] : 5
     index [int] :
     do [script] :
-      if early.r.index = 2 then break
+      if early.r.index = 2 then break loop
       show early.r.index
 ```
 
 This shows `0`, `1`, then `after the loop`.
 
-`break` ends the script it's written in. So in nested loops, a `break` in the inner loop's `do` ends only the inner loop, and a `break` in a script the `do` script runs (with `run`, or a function it invokes) ends only that script, not the loop. An `each` with `group_by` still runs `on_group_end` for the group that was open when the loop ended.
+`break loop` is only valid directly in a loop's `do` script. In nested loops, a `break loop` in the inner loop's `do` ends only the inner loop. Anywhere else — a script the `do` script runs (with `run`, or a function it invokes), a loop's `on_group_start` or `on_group_end`, or a script that isn't in a loop — it's an error (`Could not break loop: not in a loop.`) and nothing stops. To end a loop from a helper, have the helper set a flag and check it in the `do` script. An `each` with `group_by` still runs `on_group_end` for the group that was open when the loop ended.
 
 See also: Break.

data/docs/plugins.md

@@ -372,7 +372,7 @@ Register it from `stats_ext.rb` with `callback.register_obj( Stats )`.
 
 ### Custom `each` iterators
 
-An extension's object can also plug into the built-in `each` verb by providing its own iterator. `extensions/git/src/each_repo.rb` shows the shape: a plain Ruby class (not a `Gloo::Core::Obj`) with `self.use_for?( iterator_obj )` — which returns `true` when the `each` loop's iterator object looks like a match (here, when it has a `repo` child) — and a `run` method that walks whatever it's iterating over, setting the loop's child value and calling `@iterator_obj.run_do` for each item. `run_do` returns true when a `break` in the `do` script ended it, so stop the walk then: `break if @iterator_obj.run_do`. See the git extension for the full pattern; this hook only makes sense for extensions that also register a matching object type (here, `git_repo`).
+An extension's object can also plug into the built-in `each` verb by providing its own iterator. `extensions/git/src/each_repo.rb` shows the shape: a plain Ruby class (not a `Gloo::Core::Obj`) with `self.use_for?( iterator_obj )` — which returns `true` when the `each` loop's iterator object looks like a match (here, when it has a `repo` child) — and a `run` method that walks whatever it's iterating over, setting the loop's child value and calling `@iterator_obj.run_do` for each item. `run_do` returns true when a `break loop` in the `do` script ended it, so stop the walk then: `break if @iterator_obj.run_do`. (A plain `break` ends only that pass, and `run_do` returns false.) See the git extension for the full pattern; this hook only makes sense for extensions that also register a matching object type (here, `git_repo`).
 
 ### Documenting the extension
 

data/docs/verbs.md

@@ -86,12 +86,13 @@ If the destination doesn't exist, or the expression can't be worked out (eg. 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.
+`load` reads a `.gloo` file into the heap and runs its `on_load` script. Give a path relative to the project folder, a full path, or one starting with `~` for your home folder; the `.gloo` extension is optional. `*` in place of a file name loads every `.gloo` file in a folder, wherever the folder is. Anything before the `*` is the start of the file names, so `my/app/a*` loads just the files whose names start with `a`.
 
 ```gloo
 > load my/project/config
 > load my/app/*
 > load ~/.my_app/settings.gloo
+> load ~/.my_app/plugins/*
 ```
 
 If the name can't be resolved to a file, `load` reports `File '{name}' was not found.` — it fires `on_error` and, when the file was named on the `gloo` command line, prints the message to stderr and exits non-zero. A bad or missing file never fails silently.

data/lib/VERSION

@@ -1 +1 @@
-7.1.1
+7.1.3

data/lib/VERSION_NOTES

@@ -1,3 +1,17 @@
+7.1.3 - 2026.10.29
+ - break in a loop's do skips to the next item again, as it did before 7.1.1.
+ - New: break loop ends the whole loop. It's only valid directly in a loop's do script.
+
+
+7.1.2 - 2026.10.28
+ - Fixes bug with create verb and ^.here reference.
+ - Behaviour change: an each over lines gives each line without its line ending.
+ - Load with * now works for a full path or a ~ folder, not just a folder in the project.
+ - Load no longer needs the .gloo extension for a full or ~ path.
+ - Clean run of gloo from a different ruby process (or test).
+ - Fixes looking for each child with a group by.
+
+
 7.1.1 - 2026.10.26
  - Fixes issues with the value in it after a failed command.
  - Warnings go to stderr, like errors.

data/lib/gloo/app/args.rb

@@ -12,7 +12,6 @@ module Gloo
     class Args
 
       QUIET = 'quiet'.freeze
-      GLOO_ENV = 'GLOO_ENV'.freeze
 
       attr_reader :switches, :files, :app_path, :command_tokens
 
@@ -26,8 +25,9 @@ module Gloo
         @app_path = nil
         @command_tokens = []
 
+        # Only the params given; the host process's ARGV is read by
+        # Gloo.run, when gloo is run as the command.
         params.each { |o| process_one_arg( o ) }
-        ARGV.each { |o| process_one_arg( o ) }
       end
 
       #
@@ -117,9 +117,7 @@ module Gloo
       # Then finally use the default: embedded mode.
       #
       def detect_mode
-        mode = if ENV[ GLOO_ENV ] == Gloo::App::Mode::TEST.to_s
-                 Mode::TEST
-               elsif app?
+        mode = if app?
                  Mode::APP
                elsif version?
                  Mode::VERSION

data/lib/gloo/core/pn.rb

@@ -172,7 +172,12 @@ module Gloo
       # returns nil without reporting an error. A caller that needs the
       # object reports its own error.
       #
+      # A here (^) or context (@) reference is expanded first, as resolve
+      # does, so a new object's parent can be given the same way as any
+      # other path (eg. create ^.x inside a script).
+      #
       def get_parent
+        expand_refs
         o = @engine.heap.root
 
         if self.includes_path?

data/lib/gloo/exec/script.rb

@@ -16,6 +16,7 @@ module Gloo
         @engine = engine
         @obj = obj
         @break_out = false
+        @break_loop = false
         @line = 0
       end
 
@@ -59,10 +60,12 @@ module Gloo
       end
 
       # 
-      # Stop running this script.
+      # Stop running this script. With loop, also end the loop whose
+      # do script this is (break loop).
       # 
-      def break_out
+      def break_out( loop: false )
         @break_out = true
+        @break_loop = loop
       end
 
       #
@@ -72,6 +75,13 @@ module Gloo
         return @break_out
       end
 
+      #
+      # Did a break loop end this script's run, so its loop should end?
+      #
+      def broke_loop?
+        return @break_loop
+      end
+
     end
   end
 end

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

@@ -115,15 +115,15 @@ module Gloo
       def msg_run
         s = Gloo::Exec::Script.new( @engine, self )
         s.run
-        @broke_out = s.broke_out?
+        @broke_loop = s.broke_loop?
       end
 
       #
-      # Did a break end this script's last run? A loop uses this to
-      # stop when its do script breaks.
+      # Did a break loop end this script's last run? A loop uses this
+      # to stop when its do script says break loop.
       #
-      def broke_out?
-        return @broke_out == true
+      def broke_loop?
+        return @broke_loop == true
       end
 
       # ---------------------------------------------------------------------

data/lib/gloo/objs/ctrl/each.rb

@@ -43,15 +43,16 @@ module Gloo
       end
 
       #
-      # Run the do script once. Returns true if a break in it ended the
-      # run, so the loop should stop.
+      # Run the do script once. Returns true if a break loop in it
+      # ended the run, so the loop should stop. A plain break ends only
+      # the do script, and the loop goes on.
       #
       def run_do
         o = find_child DO
         return false unless o
 
         Gloo::Exec::Dispatch.message( @engine, 'run', o )
-        return o.respond_to?( :broke_out? ) && o.broke_out?
+        return o.respond_to?( :broke_loop? ) && o.broke_loop?
       end
 
 
@@ -134,7 +135,7 @@ module Gloo
             'One of the following, whose presence determines which kind of loop this is:',
             'child (alias) — iterate a container\'s children.',
             'word (string) — iterate the words in a string.',
-            'line (string) — iterate the lines in a block of text.',
+            'line (string) — iterate the lines in a block of text. Each line comes without its line ending; a blank line is visited as an empty string.',
             'file (file) — iterate the files in a folder. Optional children: ext (string) limits to files of that extension, ignoring case; recursive (bool) walks the subfolders too; include_dirs (bool) lists folders as well as files.',
             'dir (file) — iterate the directories in a folder. Optional child: recursive (bool) walks the subfolders too.'
           ],

data/lib/gloo/objs/ctrl/each_child.rb

@@ -116,20 +116,24 @@ module Gloo
 
         o = Gloo::Objs::Alias.resolve_alias( @engine, o )
         o.children.each do |child|
+          new_group = false
           if group_mode
             group_value = group_by_value( child )
             if last_group != group_value
               last_group = group_value
+              new_group = true
+              # The ending group's end runs while child is still its last child.
               if first_time
                 first_time = false
               else
                 run_on_group_end
               end
-              run_on_group_start
             end
           end
 
           set_child child
+          # The new group's start runs once child is its first child.
+          run_on_group_start if new_group
           break if @iterator_obj.run_do
         end
 

data/lib/gloo/objs/ctrl/each_line.rb

@@ -40,13 +40,14 @@ module Gloo
       # ---------------------------------------------------------------------
 
       #
-      # Run for each line.
+      # Run for each line, without its line ending (\n or \r\n). A blank
+      # line is still visited, as an empty string.
       #
       def run
         str = @iterator_obj.in_value
         return unless str
 
-        str.each_line do |line|
+        str.each_line( chomp: true ) do |line|
           set_line line
           break if @iterator_obj.run_do
         end

data/lib/gloo/objs/ctrl/repeat.rb

@@ -37,15 +37,16 @@ module Gloo
       end
 
       #
-      # Run the do script once. Returns true if a break in it ended the
-      # run, so the loop should stop.
+      # Run the do script once. Returns true if a break loop in it
+      # ended the run, so the loop should stop. A plain break ends only
+      # the do script, and the loop goes on.
       #
       def run_do
         o = find_child DO
         return false unless o
 
         Gloo::Exec::Dispatch.message( @engine, 'run', o )
-        return o.respond_to?( :broke_out? ) && o.broke_out?
+        return o.respond_to?( :broke_loop? ) && o.broke_loop?
       end
 
       #

data/lib/gloo/persist/disc_mech.rb

@@ -28,22 +28,30 @@ module Gloo
       end
 
       #
-      # Get all the gloo files in the folder (partial path).
+      # Get all the gloo files in the folder (partial path). The folder
+      # can end with the start of a file name, as a prefix (folder/a).
       #
       def get_all_files_in( folder )
-        pns = []
-        dir = File.join( @engine.settings.project_path, folder )
+        dir = folder_for_files( folder )
+        return Dir.glob( "#{dir}*.gloo" )
+      end
 
-        unless Dir.exist?( dir )
-          @log.debug "Folder does not exist in project: #{folder}"
-          dir = File.join( @engine.settings.user_root, folder )
-          @log.debug "Looking in gloo home? found == #{Dir.exist?( dir )}"
-        end
+      #
+      # Where to look for a folder of files: an absolute or ~ folder as
+      # given (~ expanded), anything else in the project folder, or if it
+      # isn't there, in the gloo home.
+      #
+      def folder_for_files( folder )
+        return folder.sub( '~', Dir.home ) if folder.start_with?( '~' )
+        return folder if File.absolute_path?( folder )
 
-        Dir.glob( "#{dir}*.gloo" ).each do |f|
-          pns << f
-        end
-        return pns
+        dir = File.join( @engine.settings.project_path, folder )
+        return dir if Dir.exist?( dir )
+
+        @log.debug "Folder does not exist in project: #{folder}"
+        dir = File.join( @engine.settings.user_root, folder )
+        @log.debug "Looking in gloo home? found == #{Dir.exist?( dir )}"
+        return dir
       end
 
       # 
@@ -65,23 +73,33 @@ module Gloo
         return true
       end
 
-      # 
-      # Expand a single file path.
-      # 
+      #
+      # Expand a single file path. The .gloo extension is optional: it's
+      # added when the name doesn't end with it, for a full or ~ path
+      # and for a name in the project or gloo home.
+      #
       def expand( name )
-        # Try full path
+        # Try the name as given: a full path, or relative to the working
+        # folder (eg. gloo hello_world.gloo).
         ext_path = File.expand_path( name )
         return [ ext_path ] if self.valid?( ext_path )
 
-        # Try in user root, projects
-        full_name = "#{name}#{file_ext}"
+        full_name = name.end_with?( file_ext ) ? name : "#{name}#{file_ext}"
+
+        # A full or ~ path without the extension.
+        if name.start_with?( '~' ) || File.absolute_path?( name )
+          ext_path = File.expand_path( full_name )
+          return [ ext_path ] if self.valid?( ext_path )
+        end
+
+        # Try in projects
         pn = File.join( @engine.settings.project_path, full_name )
         return [ pn ] if self.valid?( pn )
-        
+
         # Try in user root
         pn = File.join( @engine.settings.user_root, full_name )
         return [ pn ] if self.valid?( pn )
-        
+
         return nil
       end
 

data/lib/gloo/verbs/break.rb

@@ -10,14 +10,23 @@ module Gloo
 
       KEYWORD = 'break'.freeze
       KEYWORD_SHORT = 'stop'.freeze
+      LOOP = 'loop'.freeze
+      NOT_IN_A_LOOP = 'Could not break loop: not in a loop.'.freeze
 
       #
       # Run the verb.
-      # Stop the execution of the current script.
+      # Stop the execution of the current script. With loop (break
+      # loop), also end the loop whose do script this is.
       #
       def run
-        warn_extra_words
-        @engine.exec_env.running_script.break_out
+        words = extra_words.split( ' ' )
+        if words.first&.downcase == LOOP
+          warn_words_after_loop( words.drop( 1 ) )
+          break_loop
+        else
+          warn_unknown_words
+          @engine.exec_env.running_script.break_out
+        end
       end
 
       #
@@ -40,6 +49,54 @@ module Gloo
 
       private
 
+      #
+      # End the running script and its loop. Only valid directly in a
+      # loop's do script; anywhere else (a script the do runs, a group
+      # script, outside any loop) it's an error and nothing stops.
+      #
+      def break_loop
+        script = @engine.exec_env.running_script
+        unless loop_do?( script&.obj )
+          @engine.err NOT_IN_A_LOOP
+          return
+        end
+
+        script.break_out( loop: true )
+      end
+
+      #
+      # Is the object the do script of a loop (a repeat or an each)?
+      #
+      def loop_do?( obj )
+        parent = obj&.parent
+        return false unless parent.is_a?( Gloo::Objs::Repeat ) ||
+                            parent.is_a?( Gloo::Objs::Each )
+
+        return parent.find_child( Gloo::Objs::Each::DO ).equal?( obj )
+      end
+
+      #
+      # Warn about anything written after break other than loop.
+      # The break still happens.
+      #
+      def warn_unknown_words
+        extra = extra_words
+        return if extra.empty?
+
+        @engine.warn "#{written_verb} takes only '#{LOOP}'; ignoring '#{extra}'."
+      end
+
+      #
+      # Warn about anything written after break loop. The loop still
+      # ends.
+      #
+      def warn_words_after_loop( words )
+        return if words.empty?
+
+        @engine.warn "#{written_verb} #{LOOP} takes no object; " \
+                     "ignoring '#{words.join( ' ' )}'."
+      end
+
       # ---------------------------------------------------------------------
       #    Verb Documentation
       # ---------------------------------------------------------------------
@@ -52,15 +109,26 @@ module Gloo
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
           :description => 'Break out of the current script, stop running. ' \
-            'If that script is the do script of a loop (repeat, or any ' \
-            'kind of each), the whole loop ends.',
-          :syntax => [ 'break' ],
+            'In a loop\'s do script, break skips the rest of that pass ' \
+            'and the loop goes on; break loop ends the whole loop.',
+          :syntax => [ 'break', 'break loop' ],
+          :parameters => [
+            'loop — Optional. Also end the loop whose do script this is. ' \
+            'Only valid directly in a loop\'s do script (repeat, or any ' \
+            'kind of each).'
+          ],
           :result => 'No more commands are executed in the currently ' \
             'running script. If there are other scripts in the stack, ' \
-            'they will resume normally. In a loop\'s do script, the loop ' \
-            'ends too and runs no more passes; the script that ran the ' \
-            'loop carries on. A break in a script the do script runs ' \
-            '(eg. with run) ends only that script, not the loop.',
+            'they will resume normally. In a loop\'s do script, a plain ' \
+            'break ends that pass and the loop goes on with the next ' \
+            'item. With break loop, the loop ends too and the script ' \
+            'that ran it carries on.',
+          :errors => [
+            "#{NOT_IN_A_LOOP} — break loop in a script that isn't a " \
+            'loop\'s do script: one the do script runs (with run, or a ' \
+            'function), a loop\'s on_group_start or on_group_end, or a ' \
+            'script outside any loop. Nothing stops.'
+          ],
           :examples => <<~EXAMPLES.strip
             #
             # Break out of a script.
@@ -73,6 +141,27 @@ module Gloo
                 put true into ^.x
                 if ^.x then break
                 show 'should not see this'
+
+            #
+            # In a loop: break skips an item, break loop ends the loop.
+            # Shows 0, 1, 3, then 0, 1.
+            #
+            loops [can] :
+              on_load [script] :
+                tell loops.skip to run
+                tell loops.early to run
+              skip [repeat] :
+                times [int] : 4
+                index [int] :
+                do [script] :
+                  if loops.skip.index = 2 then break
+                  show loops.skip.index
+              early [repeat] :
+                times [int] : 4
+                index [int] :
+                do [script] :
+                  if loops.early.index = 2 then break loop
+                  show loops.early.index
           EXAMPLES
         }
       end

data/lib/gloo/verbs/create.rb

@@ -111,7 +111,9 @@ module Gloo
             'value. Both type and value are optional when creating an object.',
           :syntax => [ 'create {new.object.path} as {type} : {value}' ],
           :parameters => [
-            '{new.object.path} — The path and name of the new object.',
+            '{new.object.path} — The path and name of the new object. ' \
+              'Like any path, it can start from the root, from here in ' \
+              'a script (^.box.new, ^^.new), or from the context (@.new).',
             '{type} — The type of the new object. Optional; if not provided the object will be untyped.',
             "{value} — The initial value for the new object. Optional; if not provided the object will have the default value for the type."
           ],
@@ -123,7 +125,7 @@ module Gloo
             "to the existing object's current value.",
           :errors => [
             "#{NO_NAME_ERR} — The name of the object was not specified and the object cannot be created.",
-            "Could not create '{path}': Object '{parent.path}' was not found. — The parent container named in the path does not exist. The path is root-relative and every container above the new object must already exist. Nothing is created, and it is false.",
+            "Could not create '{path}': Object '{parent.path}' was not found. — The parent container named in the path does not exist. Every container above the new object must already exist. Nothing is created, and it is false.",
             "#{format( BAD_NAME_ERR, '{name}' )} — The name has parentheses or quotes, or there are extra words between the name and as / : — create takes a name as written. Nothing is created, and it is false."
           ],
           :examples => <<~EXAMPLES.strip

data/lib/gloo/verbs/load.rb

@@ -115,7 +115,12 @@ module Gloo
             'load [ext|lib] ( {expression} )'
           ],
           :parameters => [
-            '{file_name} — Name of the object file that is to be loaded.',
+            '{file_name} — Name of the object file that is to be loaded: ' \
+              'relative to the project, a full path, or starting with ~. ' \
+              'The .gloo extension is optional. ' \
+              'End it with * to load every .gloo file in a folder (a ' \
+              'folder in the project, a full path, or one starting with ' \
+              '~); anything before the * is the start of the file names.',
             'reference type — By default, the type is file. File can be ' \
               'specified, but does not need to be. Use ext to load a ' \
               'User Extension. Use lib to load a Core Library.',
@@ -154,6 +159,7 @@ module Gloo
             > load my/project/file
             > load my/app/*
             > load ~/.my_app/settings.gloo
+            > load ~/.my_app/plugins/*
 
             # Load a file whose name is worked out
             > load ( $.gloo_tmp '/scratch.gloo' )

data/lib/gloo.rb

@@ -9,13 +9,27 @@ path = File.dirname( File.absolute_path( __FILE__ ) )
 require File.join( path, 'dependencies.rb' )
 
 module Gloo
-  def self.run
-    params = []
-    ( params << '--cli' ) if ARGV.count.zero?
 
+  #
+  # Run gloo as the command, with the command line's arguments.
+  # This is the only place that reads ARGV; an engine created
+  # in code uses only the params it's given.
+  #
+  def self.run( argv = ARGV )
     platform = Gloo::App::Platform.new
     context = Gloo::App::EngineContext.new(
-      params, platform, Gloo::App::Log, nil )
+      params_for( argv ), platform, Gloo::App::Log, nil )
     Gloo::App::Engine.new( context ).start
   end
+
+  #
+  # Get the engine params for the given command line arguments.
+  # With no arguments, gloo runs in CLI mode.
+  #
+  def self.params_for( argv )
+    params = argv.dup
+    ( params << '--cli' ) if params.empty?
+    return params
+  end
+
 end

data/lib/run.rb

@@ -5,14 +5,8 @@
 # From the /lib/ directory:  ruby run.rb
 #
 
-# Look for all required dependencies.
+# Load gloo from source, then run it with the command line's arguments.
 path = File.dirname( File.absolute_path( __FILE__ ) )
-require File.join( path, 'dependencies.rb' )
+require File.join( path, 'gloo.rb' )
 
-params = []
-( params << '--cli' ) if ARGV.count.zero?
-
-platform = Gloo::App::Platform.new
-context = Gloo::App::EngineContext.new(
-  params, platform, Gloo::App::Log, nil )
-Gloo::App::Engine.new( context ).start
+Gloo.run

data/test.gloo/app/embed.test.gloo

@@ -0,0 +1,31 @@
+#
+# Embedded gloo tests.
+# An engine created in code by another Ruby program uses only the
+# params it's given, never that program's command line (ARGV).
+# The engine running these tests was started as the command, so the
+# check runs a separate Ruby program (a fixture) with [system].
+#
+
+tests.app.embed [can] :
+
+  # The harness, beside this file; found with source_dir.
+  harness [string] : /fixtures/embed_harness.rb
+  host_arg [string] : host_arg.gloo
+  no_files [string] : 0
+  where [string] :
+
+  run_harness [system] :
+    command [string] :
+    get_output [bool] : true
+    result [string] :
+
+  ignores_host_argv [test] :
+    description [string] : An engine created in code ignores the host program's command line.
+    on_test [script] :
+      check ^^ for source_dir
+      put it into ^^.where
+      # Paths are quoted in case the folder has spaces.
+      put "ruby '" ^^.where ^^.harness "' " ^^.host_arg into ^^.run_harness.command
+      tell ^^.run_harness to run
+      eval ^^.run_harness.result = ^^.no_files
+      assert "expected the embedded engine to be given no files"

data/test.gloo/app/fixtures/embed_harness.rb

@@ -0,0 +1,15 @@
+#
+# A Ruby program that creates a gloo engine in code, as an embedding
+# app would, and prints how many files the engine was given.
+#
+# Run it with words on its own command line: the engine must not
+# take them as files, so this should always print 0. The engine is
+# never started, so nothing is loaded or saved even if it does.
+#
+# Requires this repo's lib/gloo by path, so it checks the source,
+# not an installed gloo gem.
+#
+require_relative '../../../lib/gloo'
+
+context = Gloo::App::EngineContext.new( [ '--quiet' ] )
+print Gloo::App::Engine.new( context ).args.files.count

data/test.gloo/ctrl/each.test.gloo

@@ -20,6 +20,27 @@ tests.ctrl.each [can] :
       eval ^^.count + 1
       put it into ^^.count
 
+  seen [string] :
+  lines [text] : BEGIN
+one
+
+two
+END
+
+  lns [each] :
+    line [string] :
+    in [alias] : tests.ctrl.each.lines
+    do [script] :
+      put tests.ctrl.each.seen + '[' + ^.line + ']' into tests.ctrl.each.seen
+
+  each_line_without_line_endings [test] :
+    description [string] : each line gives each line without its line ending; a blank line is empty.
+    on_test [script] :
+      put '' into ^^.seen
+      tell ^^.lns to run
+      eval ^^.seen = '[one][][two]'
+      assert "expected each line without its line ending"
+
   each_word [test] :
     description [string] : Count words with each word
     on_test [script] :
@@ -137,3 +158,54 @@ tests.ctrl.each_folder [can] :
       eval ^^.count = 2
       assert "expected a and a/deep"
       tell ^^.remove_tree to run
+
+#
+# Each child with group_by: on_group_start sees the group's first
+# child and on_group_end its last. Each start and end logs the id of
+# the child it sees.
+#
+
+tests.ctrl.each_group [can] :
+
+  starts [string] :
+  ends [string] :
+
+  items [can] :
+    a [can] :
+      id [string] : a
+      kind [string] : x
+    b [can] :
+      id [string] : b
+      kind [string] : x
+    c [can] :
+      id [string] : c
+      kind [string] : y
+    d [can] :
+      id [string] : d
+      kind [string] : y
+
+  grouped [each] :
+    child [alias] :
+    in [alias] : tests.ctrl.each_group.items
+    group_by [string] : kind
+    on_group_start [script] :
+      put tests.ctrl.each_group.starts + tests.ctrl.each_group.grouped.child.id into tests.ctrl.each_group.starts
+    on_group_end [script] :
+      put tests.ctrl.each_group.ends + tests.ctrl.each_group.grouped.child.id into tests.ctrl.each_group.ends
+    do [script] :
+
+  group_start_sees_first_child [test] :
+    description [string] : on_group_start sees the first child of the new group.
+    on_test [script] :
+      put '' into ^^.starts
+      tell ^^.grouped to run
+      eval ^^.starts = 'ac'
+      assert "expected each group to start with its first child"
+
+  group_end_sees_last_child [test] :
+    description [string] : on_group_end sees the last child of the group that's ending.
+    on_test [script] :
+      put '' into ^^.ends
+      tell ^^.grouped to run
+      eval ^^.ends = 'bd'
+      assert "expected each group to end with its last child"

data/test.gloo/verbs/break.test.gloo

@@ -8,7 +8,7 @@ tests.verbs.break [can] :
 
   s [script] :
     if ^.b  then break
-        
+
     # Should not get here
     put false into ^.b
 
@@ -19,16 +19,27 @@ tests.verbs.break [can] :
       eval ^^.b
       assert "expected b to be true"
 
-  # Loops whose do script breaks on its second pass.
+  # The last error, for the break loop errors.
+  on_error [script] :
+  error_data [can] :
+    message [string] :
+
+  not_in_a_loop [string] : Could not break loop: not in a loop.
+
+  # Loops whose do script breaks on one pass: skip_on for a plain
+  # break, end_on for break loop (0 never breaks).
   passes [int] : 0
   after [int] : 0
+  skip_on [int] : 0
+  end_on [int] : 0
 
   rep [repeat] :
     times [int] : 4
     index [int] :
     do [script] :
       put tests.verbs.break.passes + 1 into tests.verbs.break.passes
-      if tests.verbs.break.passes = 2 then break
+      if tests.verbs.break.passes = tests.verbs.break.skip_on then break
+      if tests.verbs.break.passes = tests.verbs.break.end_on then break loop
       put tests.verbs.break.after + 1 into tests.verbs.break.after
 
   kids [can] :
@@ -41,14 +52,15 @@ tests.verbs.break [can] :
     in [alias] : tests.verbs.break.kids
     do [script] :
       put tests.verbs.break.passes + 1 into tests.verbs.break.passes
-      if tests.verbs.break.passes = 2 then break
+      if tests.verbs.break.passes = tests.verbs.break.skip_on then break
+      if tests.verbs.break.passes = tests.verbs.break.end_on then break loop
       put tests.verbs.break.after + 1 into tests.verbs.break.after
 
   inner [repeat] :
     times [int] : 3
     index [int] :
     do [script] :
-      if tests.verbs.break.inner.index = 1 then break
+      if tests.verbs.break.inner.index = 1 then break loop
       put tests.verbs.break.after + 1 into tests.verbs.break.after
 
   outer [repeat] :
@@ -57,30 +69,111 @@ tests.verbs.break [can] :
     do [script] :
       tell tests.verbs.break.inner to run
 
-  break_ends_a_repeat [test] :
-    description [string] : break in a repeat's do script ends the loop.
+  # The form the apps use to skip an item: unless ... do break.
+  skipped [string] :
+  skip_b [each] :
+    child [alias] :
+    in [alias] : tests.verbs.break.kids
+    do [script] :
+      check tests.verbs.break.skip_b.child for starts_with?( 'b' )
+      unless it = false do break
+      put tests.verbs.break.skipped + tests.verbs.break.skip_b.child into tests.verbs.break.skipped
+
+  # break loop is only valid directly in a loop's do script.
+  lone [script] :
+    break loop
+
+  loop_helper [script] :
+    break loop
+
+  via_loop [repeat] :
+    times [int] : 2
+    index [int] :
+    do [script] :
+      put tests.verbs.break.passes + 1 into tests.verbs.break.passes
+      run tests.verbs.break.loop_helper
+
+  break_skips_the_rest_of_a_repeat_pass [test] :
+    description [string] : break in a repeat's do script skips to the next pass.
     on_test [script] :
       put 0 into ^^.passes
       put 0 into ^^.after
+      put 0 into ^^.end_on
+      put 2 into ^^.skip_on
+      tell ^^.rep to run
+      eval ^^.passes = 4
+      assert "expected every pass to run"
+      eval ^^.after = 3
+      assert "expected only the pass that broke to stop early"
+
+  break_skips_the_rest_of_an_each_pass [test] :
+    description [string] : break in an each's do script skips to the next child.
+    on_test [script] :
+      put 0 into ^^.passes
+      put 0 into ^^.after
+      put 0 into ^^.end_on
+      put 2 into ^^.skip_on
+      tell ^^.each_kid to run
+      eval ^^.after = 2
+      assert "expected every child but the one that broke to get past it"
+
+  unless_do_break_skips_an_item [test] :
+    description [string] : unless ... do break in an each skips that item, as the apps use it.
+    on_test [script] :
+      put '' into ^^.skipped
+      tell ^^.skip_b to run
+      eval ^^.skipped = 'ac'
+      assert "expected b to be skipped and c still reached"
+
+  break_loop_ends_a_repeat [test] :
+    description [string] : break loop in a repeat's do script ends the loop.
+    on_test [script] :
+      put 0 into ^^.passes
+      put 0 into ^^.after
+      put 0 into ^^.skip_on
+      put 2 into ^^.end_on
       tell ^^.rep to run
       eval ^^.passes = 2
       assert "expected the loop to stop on the pass that broke"
       eval ^^.after = 1
       assert "expected only the first pass to get past the break"
 
-  break_ends_an_each [test] :
-    description [string] : break in an each's do script ends the loop.
+  break_loop_ends_an_each [test] :
+    description [string] : break loop in an each's do script ends the loop.
     on_test [script] :
       put 0 into ^^.passes
       put 0 into ^^.after
+      put 0 into ^^.skip_on
+      put 2 into ^^.end_on
       tell ^^.each_kid to run
       eval ^^.passes = 2
       assert "expected the loop to stop on the pass that broke"
 
-  break_ends_only_the_inner_loop [test] :
-    description [string] : break in an inner loop ends that loop, not the outer one.
+  break_loop_ends_only_the_inner_loop [test] :
+    description [string] : break loop in an inner loop ends that loop, not the outer one.
     on_test [script] :
       put 0 into ^^.after
       tell ^^.outer to run
       eval ^^.after = 2
       assert "expected each of the 2 inner loops to get past its break once"
+
+  break_loop_outside_a_loop_is_an_error [test] :
+    description [string] : break loop in a script that isn't a loop's do is an error.
+    expect_errors [bool] : true
+    on_test [script] :
+      put '' into ^^.error_data.message
+      run ^^.lone
+      eval ^^.error_data.message = ^^.not_in_a_loop
+      assert "expected the not-in-a-loop error"
+
+  break_loop_in_a_helper_is_an_error [test] :
+    description [string] : break loop in a script the do runs is an error, and the loop goes on.
+    expect_errors [bool] : true
+    on_test [script] :
+      put '' into ^^.error_data.message
+      put 0 into ^^.passes
+      tell ^^.via_loop to run
+      eval ^^.error_data.message = ^^.not_in_a_loop
+      assert "expected the not-in-a-loop error"
+      eval ^^.passes = 2
+      assert "expected the loop to go on"

data/test.gloo/verbs/create.test.gloo

@@ -11,6 +11,31 @@ tests.verbs.create [can] :
       eval it = 'hello'
       assert "expected it to equal the created value"
 
+  here_box [can] :
+
+  create_with_a_here_path [test] :
+    description [string] : create takes a ^ path inside a script, like other verbs.
+    on_test [script] :
+      create ^^.here_box.made as string : 'made here'
+      eval tests.verbs.create.here_box.made = 'made here'
+      assert "expected ^^.here_box.made to be created"
+
+  create_with_a_one_level_here_path [test] :
+    description [string] : create ^.name makes a child of the script's parent (here, the test).
+    on_test [script] :
+      create ^.child_of_test as int : 3
+      eval tests.verbs.create.create_with_a_one_level_here_path.child_of_test = 3
+      assert "expected ^.child_of_test under the test"
+
+  create_with_a_context_path [test] :
+    description [string] : create takes an @ path, relative to the context.
+    on_test [script] :
+      context tests.verbs.create.here_box
+      create @.via_context as int : 5
+      context root
+      eval tests.verbs.create.here_box.via_context = 5
+      assert "expected @.via_context to be created in the context"
+
 tests.verbs.create_names [can] :
 
   err_fired [bool] : false

data/test.gloo/verbs/load.test.gloo

@@ -13,6 +13,9 @@ tests.verbs.load [can] :
   # Scratch files live in the gloo tmp folder ($.gloo_tmp).
   on_load [script] :
     put $.gloo_tmp '/gloo_load_no_objects_test.gloo' into ^.f
+    put $.gloo_tmp ^.wild_name into ^.wild_dir
+    put ^.wild_dir '/wild_a.gloo' into ^.wild_a
+    put ^.wild_dir '/wild_b.gloo' into ^.wild_b
 
   comments_only [text] : BEGIN
 # This file has comments,
@@ -26,6 +29,10 @@ END
 
   computed_name [string] : /gloo_load_computed_test.gloo
   lib_name [string] : md
+  wild_name [string] : /gloo_load_wild_test
+  wild_dir [file] :
+  wild_a [file] :
+  wild_b [file] :
   computed_f [file] :
   computed_fixture [text] : BEGIN
 computed_demo [can] :
@@ -138,3 +145,30 @@ END
       assert "expected load lib ( expr ) not to fire on_error"
       exists? object markdown
       assert "expected the markdown type to be registered"
+
+  load_an_absolute_wildcard_path [test] :
+    description [string] : load {absolute folder}/* loads every .gloo file in the folder.
+    on_test [script] :
+      tell ^^.wild_dir to mkdir
+      tell ^^.wild_a to write ( 'wild_a [can] :' )
+      tell ^^.wild_b to write ( 'wild_b [can] :' )
+      load ( ^^.wild_dir '/*' )
+      exists? wild_a
+      assert "expected wild_a.gloo to be loaded"
+      exists? wild_b
+      assert "expected wild_b.gloo to be loaded"
+      tell wild_a to unload
+      tell wild_b to unload
+      tell ^^.wild_a to delete
+      tell ^^.wild_b to delete
+
+  load_a_full_path_without_the_extension [test] :
+    description [string] : load of a full path finds the .gloo file without the extension being given.
+    on_test [script] :
+      put $.gloo_tmp ^^.computed_name into ^^.computed_f
+      tell ^^.computed_f to write ( ^^.computed_fixture )
+      load ( $.gloo_tmp '/gloo_load_computed_test' )
+      eval computed_demo.s = 'hi'
+      assert "expected the full path without .gloo to load"
+      tell computed_demo to unload
+      tell ^^.computed_f to delete

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gloo
 version: !ruby/object:Gem::Version
-  version: 7.1.1
+  version: 7.1.3
 platform: ruby
 authors:
 - Eric Crane
@@ -442,6 +442,8 @@ files:
 - lib/gloo/verbs/version.rb
 - lib/gloo/verbs/wait.rb
 - lib/run.rb
+- test.gloo/app/embed.test.gloo
+- test.gloo/app/fixtures/embed_harness.rb
 - test.gloo/basic.test.gloo
 - test.gloo/ctrl/each.test.gloo
 - test.gloo/dt/date.test.gloo