Implement LoopStateMachine

Utilities for returning state from functions that run inside a loop.

This is used in e.g clipping, where we may need to break or transition states.

The main entry point is to return an [`Action`](@ref) from a function that
is wrapped in a `@controlflow f(...)` macro in a loop.  When a known `Action`
(currently, `Continue`, `Break`, `Return`, or `FullReturn`) is returned, it is processed
by the `@controlflow` macro, which allows the function to break out of the loop
early, continue to the next iteration, or return a value, without being
syntactically inside the loop.

Author: asinghvi17

src/utils/LoopStateMachine/LoopStateMachine.jl

@@ -0,0 +1,101 @@
+"""
+    LoopStateMachine
+
+Utilities for returning state from functions that run inside a loop.
+
+This is used in e.g clipping, where we may need to break or transition states.
+
+The main entry point is to return an [`Action`](@ref) from a function that 
+is wrapped in a `@controlflow f(...)` macro in a loop.  When a known `Action`
+(currently, `Continue`, `Break`, `Return`, or `FullReturn`) is returned, it is processed
+by the `@controlflow` macro, which allows the function to break out of the loop
+early, continue to the next iteration, or return a value, without being 
+syntactically inside the loop.
+"""
+module LoopStateMachine
+
+struct Action{name, T}
+    x::T
+end
+
+Action{name}() where name = Action{name, Nothing}(nothing)
+Action{name}(x::T) where name where T = new{name, T}(x)
+Action(x::T) where T = Action{:unnamed, T}(x)
+
+Action{name, Nothing}() where name = Action{name, Nothing}(nothing)
+
+function Base.show(io::IO, action::Action{name, T}) where {name, T}
+    print(io, "Action ", name)
+    if isnothing(action.x)
+        print(io, "()")
+    else
+        print(io, "(", action.x, ")")
+    end
+end
+
+
+# Some common actions
+"""
+    Break()
+
+Break out of the loop.
+"""
+const Break = Action{:Break, Nothing}
+
+"""
+    Continue()
+
+Continue to the next iteration of the loop.
+"""
+const Continue = Action{:Continue, Nothing}
+
+"""
+    Return(x)
+
+Cause the function executing the loop to return.  Use with great caution!
+"""
+const Return = Action{:Return}
+
+"""
+    FullReturn(x)
+
+Cause the function executing the loop to return `FullReturn(x)`.
+
+This allows you to break completely out of a recursive function.
+"""
+const FullReturn = Action{:FullReturn}
+
+"""
+    @controlflow f(...)
+
+Process the result of `f(...)` and return the result if it's not a [`Continue`](@ref), [`Break`](@ref), or [`Return`](@ref) [`Action`](@ref).
+
+- `Continue`: continue to the next iteration of the loop.
+- `Break`: break out of the loop.
+- `Return`: cause the function executing the loop to return with the wrapped value.
+- `FullReturn`: cause the function executing the loop to return `FullReturn(x)`.
+
+!!! warning
+    Only use this inside a loop, otherwise you'll get a syntax error!
+"""
+macro controlflow(expr)
+    varname = gensym("lsm-f-ret")
+    return quote
+        $varname = $(esc(expr))
+        if $varname isa Continue
+            continue
+        elseif $varname isa Break
+            break
+        elseif $varname isa Return
+            return $varname.x
+        elseif $varname isa FullReturn
+            return $varname
+        else
+            $varname
+        end
+    end
+end
+
+# You can define more actions as you desire.
+
+end

test/runtests.jl

@@ -5,6 +5,7 @@ using SafeTestsets
 include("helpers.jl")
 
 @safetestset "Primitives" begin include("primitives.jl") end
+@safetestset "LoopStateMachine" begin include("utils/LoopStateMachine.jl") end
 # Methods
 @safetestset "Angles" begin include("methods/angles.jl") end
 @safetestset "Area" begin include("methods/area.jl") end

test/utils/LoopStateMachine.jl

@@ -0,0 +1,44 @@
+using Test
+using GeometryOps.LoopStateMachine: @controlflow, Continue, Break
+
+@testset "Continue action" begin
+    count = 0
+    f(i) = begin
+        count += 1
+        if i == 3
+            return Continue()
+        end
+        count += 1
+    end
+    for i in 1:5
+        @controlflow f(i)
+    end
+    @test count == 9 # Adds 1 for each iteration, but skips second +1 on i=3
+end
+
+@testset "Break action" begin
+    count = 0
+    function f(i)
+        count += 1
+        if i == 3
+            return Break()
+        end
+        count += 1
+    end
+    for i in 1:5
+        @controlflow f(i)
+    end
+    @test count == 5 # Counts up to i=3, adding 2 for i=1,2 and 1 for i=3
+end
+
+@testset "Return value" begin
+    results = Int[]
+    for i in 1:3
+        val = @controlflow begin
+            i * 2
+        end
+        push!(results, val)
+    end
+    @test results == [2, 4, 6]
+end
+