Add LoopStateMachine and tests

Author: asinghvi17

src/GeometryOps.jl

@@ -36,9 +36,17 @@ const Edge{T} = Tuple{TuplePoint{T},TuplePoint{T}} where T
 
 include("types.jl")
 include("primitives.jl")
-include("utils.jl")
 include("not_implemented_yet.jl")
 
+include("utils/utils.jl")
+
+include("utils/LoopStateMachine/LoopStateMachine.jl")
+using .LoopStateMachine
+
+include("utils/SpatialTreeInterface/SpatialTreeInterface.jl")
+using .SpatialTreeInterface
+
+
 include("methods/angles.jl")
 include("methods/area.jl")
 include("methods/barycentric.jl")

src/utils/LoopStateMachine/LoopStateMachine.jl

@@ -0,0 +1,106 @@
+"""
+    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 `:full_return` actions) 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, basically a way to provoke syntactic
+behaviour from a function called from a inside a loop, where you do not have access to that loop.
+
+## Example
+
+```julia
+```
+"""
+module LoopStateMachine
+
+export Action, @controlflow
+
+import ..GeometryOps as GO
+
+const ALL_ACTION_DESCRIPTIONS = """
+- `:continue`: continue to the next iteration of the loop.  
+  This is the `continue` keyword in Julia.  The contents of the action are not used.
+- `:break`: break out of the loop.  
+  This is the `break` keyword in Julia.  The contents of the action are not used.
+- `:return`: cause the function executing the loop to return with the wrapped value.
+- `:full_return`: cause the function executing the loop to return `Action(:full_return, x)`.  
+  This is very useful to terminate recursive funtions, like tree queries terminating after you 
+  have found a single intersecting segment.
+"""
+
+"""
+    Action(name::Symbol, [x])
+
+Create an `Action` with the name `name` and optional contents `x`.
+
+`Action`s are returned from functions wrapped in a `@controlflow` macro, which
+does something based on the return value of that function if it is an `Action`.
+
+## Available actions
+
+$ALL_ACTION_DESCRIPTIONS
+"""
+struct Action{T}
+    name::Symbol
+    x::T
+end
+
+Action() = Action{Nothing}(:unnamed, nothing)
+Action(x::T) where T = Action{:unnamed, T}(:unnamed, x)
+Action(x::Symbol) = Action(x, nothing)
+
+function Base.show(io::IO, action::Action{T}) where T
+    print(io, "Action ", action.name)
+    if isnothing(action.x)
+        print(io, "()")
+    else
+        print(io, "(", action.x, ")")
+    end
+end
+
+"""
+    @controlflow f(...)
+
+Process the result of `f(...)` and return the result if it's not an `Action`(@ref LoopStateMachine.Action).
+    
+If it is an `Action`, then process it according to the following rules, and throw an error if it's not recognized.
+`:continue`, `:break`, `:return`, or `:full_return` are valid actions.
+
+$ALL_ACTION_DESCRIPTIONS
+
+!!! warning
+    Only use this inside a loop, otherwise you'll get a syntax error, especially if you use `:continue` or `:break`.
+
+## Examples
+"""
+macro controlflow(expr)
+    varname = gensym("loop-state-machine-returned-value")
+    return quote
+        $varname = $(esc(expr))
+        if $varname isa Action
+            if $varname.name == :continue
+                continue
+            elseif $varname.name == :break
+                break
+            elseif $varname.name == :return
+                return $varname.x
+            elseif $varname.name == :full_return
+                return $varname
+            else
+                throw(ArgumentError("Unknown action: $($varname.name)"))
+            end
+        else
+            $varname
+        end
+    end
+end
+
+# You can define more actions as you desire.
+
+end

test/utils/LoopStateMachine.jl

@@ -0,0 +1,43 @@
+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