feat(Shuffle): add child order randomisation mechanism

README.md

@@ -40,6 +40,7 @@ func (n Node) Tick() (Status, error)
   utilising the running status as it's cue to background a newly generated tick (supporting conditional backgrounding)
 - RateLimit is a common building block, and implements a Tick that will return Failure as necessary to maintain a rate
 - Not simply inverts a Tick's Status, but retains error handling (Failure on error value) behavior
+- Shuffle uses encapsulation to apply a random sort on child order prior to calling the underlying Tick
 - Implementations to actually run behavior trees are provided, and include a Ticker and Manager, but both are defined
   by interfaces and are entirely optional
 - I use this implementation for several personal projects and will continue to add functionality after validating it's

any.go

@@ -30,14 +30,7 @@ func Any(tick Tick) Tick {
 		success bool
 	)
 	return func(children []Node) (Status, error) {
-		children = func(src []Node) (dst []Node) {
-			if src == nil {
-				return
-			}
-			dst = make([]Node, len(src))
-			copy(dst, src)
-			return
-		}(children)
+		children = copyNodes(children)
 		for i := range children {
 			child := children[i]
 			if child == nil {
@@ -75,3 +68,12 @@ func Any(tick Tick) Tick {
 		return Success, nil
 	}
 }
+
+func copyNodes(src []Node) (dst []Node) {
+	if src == nil {
+		return
+	}
+	dst = make([]Node, len(src))
+	copy(dst, src)
+	return
+}

shuffle.go

@@ -0,0 +1,42 @@
+/*
+   Copyright 2019 Joseph Cumines
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package behaviortree
+
+import "math/rand"
+
+// Shuffle implements randomised child execution order via encapsulation, using the provided source to shuffle the
+// children prior to passing through to the provided tick (a nil source will use global math/rand), note that this
+// function will return nil if a nil tick is provided
+func Shuffle(tick Tick, source rand.Source) Tick {
+	if tick == nil {
+		return nil
+	}
+	if source == nil {
+		source = defaultSource{}
+	}
+	return func(children []Node) (Status, error) {
+		children = copyNodes(children)
+		rand.New(source).Shuffle(len(children), func(i, j int) { children[i], children[j] = children[j], children[i] })
+		return tick(children)
+	}
+}
+
+type defaultSource struct{ rand.Source }
+
+func (d defaultSource) Int63() int64 {
+	return rand.Int63()
+}

shuffle_test.go

@@ -0,0 +1,113 @@
+package behaviortree
+
+import (
+	"context"
+	"fmt"
+	"math/rand"
+	"testing"
+	"time"
+)
+
+func ExampleShuffle() {
+	rand.Seed(1231244)
+	var (
+		newPrintlnFn = func(fn func() []interface{}) Tick {
+			return func([]Node) (Status, error) {
+				fmt.Println(fn()...)
+				return Success, nil
+			}
+		}
+		newPrintln = func(v ...interface{}) Tick { return newPrintlnFn(func() []interface{} { return v }) }
+		done       bool
+		ticker     = NewTickerStopOnFailure(context.Background(), time.Millisecond, New(
+			Sequence,
+			New(newPrintlnFn(func() func() []interface{} {
+				var i int
+				return func() []interface{} {
+					i++
+					return []interface{}{`tick number`, i}
+				}
+			}())),
+			New(
+				Shuffle(Sequence, nil),
+				New(newPrintln(`node 1`)),
+				New(newPrintln(`node 2`)),
+				New(
+					Selector,
+					New(func() func(children []Node) (Status, error) {
+						remaining := 5
+						return func(children []Node) (Status, error) {
+							if remaining > 0 {
+								remaining--
+								return Success, nil
+							}
+							return Failure, nil
+						}
+					}()),
+					New(
+						Shuffle(Selector, nil),
+						New(newPrintln(`node 3`)),
+						New(newPrintln(`node 4`)),
+						New(newPrintln(`node 5`)),
+						New(newPrintln(`node 6`)),
+						New(func([]Node) (Status, error) {
+							done = true
+							return Success, nil
+						}),
+					),
+				),
+			),
+			New(func([]Node) (Status, error) {
+				if done {
+					return Failure, nil
+				}
+				return Success, nil
+			}),
+		))
+	)
+	<-ticker.Done()
+	if err := ticker.Err(); err != nil {
+		panic(err)
+	}
+	//output:
+	//tick number 1
+	//node 1
+	//node 2
+	//tick number 2
+	//node 2
+	//node 1
+	//tick number 3
+	//node 1
+	//node 2
+	//tick number 4
+	//node 2
+	//node 1
+	//tick number 5
+	//node 2
+	//node 1
+	//tick number 6
+	//node 1
+	//node 2
+	//node 5
+	//tick number 7
+	//node 6
+	//node 1
+	//node 2
+	//tick number 8
+	//node 2
+	//node 5
+	//node 1
+	//tick number 9
+	//node 3
+	//node 2
+	//node 1
+	//tick number 10
+	//node 2
+	//node 1
+}
+
+func TestShuffle_nil(t *testing.T) {
+	if v := Shuffle(nil, nil); v != nil {
+		t.Fatal(v)
+	}
+}