gloo 7.1.2 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3e9f9ec23fd38faee18f95a521fe1d21a8e572b2306c814233c3fc67ae6e5f3
-  data.tar.gz: a1f2f961d1860473c14faefb6c5f9ffe0556bae36479cf3755b8333a1b0db68c
+  metadata.gz: 153d674b150e06c999a0756c90c41f872a410205f516eaa8b560335f93ec0e2b
+  data.tar.gz: 1b11115e161f139b44dc6750713e0e883f638ae58048c8b3007441cbf681f319
 SHA512:
-  metadata.gz: d1665486b345b607c64f98519ac7219ac720ccad75d88d135a88225e3ea527871e6305acc95db9b31a89b7ba5373a6016b7fbcb0a354dfc82ecd04a3f5733bc9
-  data.tar.gz: 35f9a3c3013d394ed4be04106f682ef92b14328279b12524d345f5a5a04f4ce31d7c8645d38a48484ac699a0d9d8ccc231340004a90cb0b5acdb98f890809b58
+  metadata.gz: 3e92b508048653b4e1e4e283a7e90de32605b4a239f56b7b24123c600e5b38a6af582a50a6d2a7130da8ed73d8ded9f0e6aab2a75798a9709939749cf72119dd
+  data.tar.gz: 19cd40e0d35cfed856aa7eb6ffe4fe648adde3c706656d81211d01f0c940a4c38dd63b0bffe2a4b50b3b57d9e76afba997050c7fca99066f2fe6529825d05591

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
 
@@ -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/lib/VERSION

@@ -1 +1 @@
-7.1.2
+7.1.3

data/lib/VERSION_NOTES

@@ -1,3 +1,8 @@
+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.

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
 
 

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/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/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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gloo
 version: !ruby/object:Gem::Version
-  version: 7.1.2
+  version: 7.1.3
 platform: ruby
 authors:
 - Eric Crane