Skip to content

Commit

Permalink
Updating readme.
Browse files Browse the repository at this point in the history 
Updating documentation.
Renaming Routine.BlockByName() => Routine.BlockByID().
Renaming actions.NewFunc() > actions.NewFunction().
  • Loading branch information
@SolarLune
SolarLune committed Nov 7, 2023
1 parent 996877c commit 1cd5571
Show file tree
Hide file tree
Showing 10 changed files with 64 additions and 51 deletions.
18 changes: 9 additions & 9 deletions actions/actions.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,10 @@ type Function struct {
PollFunc func(block *routine.Block) routine.Flow // The function to run when polled
}

// NewFunc creates and returns a ActionFunc object with the polling function set to the
// NewFunction creates and returns a ActionFunc object with the polling function set to the
// provided function. The routine.Flow returned from the customizeable function influences
// the Routine does after running the function.
func NewFunc(function func(block *routine.Block) routine.Flow) *Function {
func NewFunction(function func(block *routine.Block) routine.Flow) *Function {
return &Function{
PollFunc: function,
}
Expand Down Expand Up @@ -275,18 +275,18 @@ func (l *Label) ID() any { return l.Label }
// NewJumpTo creates a Function action that jumps the Block to the ActionLabel that has
// the specified label ID.
func NewJumpTo(label any) *Function {
return NewFunc(
return NewFunction(
func(block *routine.Block) routine.Flow {
block.JumpTo(label)
return routine.FlowNext
},
)
}

// NewSwitchBlock creates a Function action that switches the routine to only blocks with
// NewSwitchBlock creates a Function action that switches the routine to only activate blocks with
// the specified IDs.
func NewSwitchBlock(blockIDs ...any) *Function {
return NewFunc(
return NewFunction(
func(block *routine.Block) routine.Flow {
block.Routine.SwitchBlock(blockIDs...)
return routine.FlowNext
Expand All @@ -297,7 +297,7 @@ func NewSwitchBlock(blockIDs ...any) *Function {
// NewActivateBlock creates a Function action that activates the specified blocks in the
// currently running Routine. Any other blocks are unaffected.
func NewActivateBlock(blockIDs ...any) *Function {
return NewFunc(
return NewFunction(
func(block *routine.Block) routine.Flow {
block.Routine.ActivateBlock(blockIDs...)
return routine.FlowNext
Expand All @@ -308,7 +308,7 @@ func NewActivateBlock(blockIDs ...any) *Function {
// NewDeactivateBlock creates a Function action that deactivates the specified blocks
// in the currently running Routine. Any other blocks are unaffected.
func NewDeactivateBlock(blockIDs ...any) *Function {
return NewFunc(
return NewFunction(
func(block *routine.Block) routine.Flow {
block.Routine.DeactivateBlock(blockIDs...)
return routine.FlowNext
Expand All @@ -320,7 +320,7 @@ func NewDeactivateBlock(blockIDs ...any) *Function {
// specified Action index number.
// (In other words, NewSetIndex(0) restarts the Block.)
func NewSetIndex(index int) *Function {
return NewFunc(
return NewFunction(
func(block *routine.Block) routine.Flow {
block.SetIndex(index)
return routine.FlowNext
Expand All @@ -331,7 +331,7 @@ func NewSetIndex(index int) *Function {
// NewFinish creates a ActionFunc that simply returns routine.FlowFinish, indicating
// that the Routine has finished and should stop running.
func NewFinish() *Function {
return NewFunc(
return NewFunction(
func(block *routine.Block) routine.Flow {
return routine.FlowFinish
},
Expand Down
8 changes: 4 additions & 4 deletions examples/blocks/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ func defineRoutine(myRoutine *routine.Routine) {
return routine.FlowNext
}

return actions.NewFunc(f)
return actions.NewFunction(f)

}

Expand All @@ -47,7 +47,7 @@ func defineRoutine(myRoutine *routine.Routine) {

actions.NewWait(time.Second*1),

// We can switch blocks using SetBlocks; any blocks with the given names will be activated.
// We can switch blocks using actions.NewSwitchBlock() or Routine.SwitchBlock(). Any blocks with the given names will be activated.
actions.NewSwitchBlock("progress"),
)

Expand All @@ -61,7 +61,7 @@ func defineRoutine(myRoutine *routine.Routine) {

actions.NewWait(time.Second*2),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
drawProgress = true
progress += 5
if progress >= 100 {
Expand All @@ -74,7 +74,7 @@ func defineRoutine(myRoutine *routine.Routine) {

customPrint("Done!"),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
return routine.FlowNext
}),

Expand Down
12 changes: 7 additions & 5 deletions examples/collections/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,13 @@ import (
"github.com/solarlune/routine/actions"
)

// The point of this example is to show how you can create your own functions, and how Collections work.

func defineRoutine(myRoutine *routine.Routine) {

// You can create your own Actions easily by making functions.
print := func(text string) *actions.Function {
return actions.NewFunc(
return actions.NewFunction(
func(b *routine.Block) routine.Flow {
fmt.Println(text)
return routine.FlowNext
Expand All @@ -21,9 +23,9 @@ func defineRoutine(myRoutine *routine.Routine) {
}

// However, Blocks and ActionGates take a variable number of individual Actions -
// because of this, you can't supply to them a pre-made slice of Actions, like from
// a function. To bypass this, you can use ActionCollections. They are groups of Actions
// that are substituted internally for the Actions you supply to those functions.
// because of this, you can't supply to them a pre-made slice of multiple Actions, like from
// a function. To bypass this, you can use Collections. They are groups of Actions
// that are substituted internally for the Actions they contain.
slowType := func(text string) *actions.Collection {

textIndex := 0
Expand All @@ -32,7 +34,7 @@ func defineRoutine(myRoutine *routine.Routine) {

actions.NewLabel("loop:"+text),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Print(text[:textIndex] + "\r")
textIndex++
if textIndex >= len(text)+1 {
Expand Down
12 changes: 6 additions & 6 deletions examples/gates/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,12 @@ func defineRoutine(myRoutine *routine.Routine) {

return actions.NewCollection(

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println(text)
return routine.FlowNext
}),

actions.NewWait(time.Second*2),
actions.NewWait(time.Second*1),
)

}
Expand All @@ -31,10 +31,10 @@ func defineRoutine(myRoutine *routine.Routine) {

myRoutine.DefineBlock("first",

print("OK, so let's try an ActionGate out."),
print("Let's see which option we get..."),
print("OK, so let's try an ActionGate."),
print("Let's see which option we randomly get..."),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
choice = rand.Intn(3)
return routine.FlowNext
}),
Expand Down Expand Up @@ -62,7 +62,7 @@ func defineRoutine(myRoutine *routine.Routine) {
),
),

print("Nice!"),
print("Nice! Let's try again."),
)

}
Expand Down
12 changes: 8 additions & 4 deletions examples/jumps/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,17 @@ import (
"github.com/solarlune/routine/actions"
)

// This example shows how jumping to a label works.
// All you have to do is create a new Label action, and then jump to it, either from within a function with block.JumpTo(), or from
// the block definition with actions.NewJumpTo().
func defineRoutine(myRoutine *routine.Routine) {

myRoutine.DefineBlock("first",

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("Let's test jumping to a label.")
// We can also jump within a function with actions.NewCurrentBlock.JumpTo()
// We can also jump within a function with block.JumpTo(). Note that this, of course, wouldn't end the function early
// automatically; we would still have to return a routine.Flow.
return routine.FlowNext
}),

Expand All @@ -26,14 +30,14 @@ func defineRoutine(myRoutine *routine.Routine) {

actions.NewLabel("after finish"),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("This wouldn't have printed unless we jumped.")
return routine.FlowNext
}),

actions.NewWait(time.Second*3),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("OK, that's it.")
return routine.FlowFinish
}),
Expand Down
6 changes: 3 additions & 3 deletions examples/loops/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import (
"github.com/solarlune/routine/actions"
)

// In this example, it shows how blocks loop by default.
// In this example, we see how blocks loop by default.
// If an Action doesn't explicitly finish a Routine's execution, then returning routine.FlowNext at the end
// of a Block will cause the Block to loop.

Expand All @@ -18,7 +18,7 @@ func defineRoutine(myRoutine *routine.Routine) {

myRoutine.DefineBlock("loop",

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {

if loopCount == 0 {
fmt.Println("Welp, that's it. Routine over~")
Expand All @@ -33,7 +33,7 @@ func defineRoutine(myRoutine *routine.Routine) {

actions.NewWait(time.Second*2),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {

// You can reference global or even local variables outside of a block definition
// to act as a kind of temporary memory.
Expand Down
10 changes: 5 additions & 5 deletions examples/parallel/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ func defineRoutine(myRoutine *routine.Routine) {
// The first block executes every 2 seconds.
myRoutine.DefineBlock(0,

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("First block is just the beginning...")

// Activate the next block; this happens every 2 seconds.
Expand All @@ -37,7 +37,7 @@ func defineRoutine(myRoutine *routine.Routine) {
// The second block executes every half second.
myRoutine.DefineBlock(1,

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("second block is alive and well...")
return routine.FlowNext
}),
Expand All @@ -48,7 +48,7 @@ func defineRoutine(myRoutine *routine.Routine) {
// The third block executes 10 times a second.
myRoutine.DefineBlock(2,

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("third block is going crazy...")
return routine.FlowNext
}),
Expand All @@ -59,7 +59,7 @@ func defineRoutine(myRoutine *routine.Routine) {
// The fourth block executes 20 times a second.
myRoutine.DefineBlock(3,

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("fourth block is kinda insane...!!!")
return routine.FlowNext
}),
Expand All @@ -70,7 +70,7 @@ func defineRoutine(myRoutine *routine.Routine) {
// The last block ends it.
myRoutine.DefineBlock(4,

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
// Set only this block to be active
myRoutine.SwitchBlock(4)
fmt.Println("OK, I'm done. All tuckered out.")
Expand Down
19 changes: 10 additions & 9 deletions examples/simple/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,43 +14,44 @@ import (
// this is just to make it easier-to-understand by segmenting it out from the main function.
func defineRoutine(myRoutine *routine.Routine) {

// Actions, to their name, Action a Routine's flow.
// Actions, to their name, perform an action and alter a Routine's flow.

// A Routine runs through its Blocks.
// You customize Actions that live within Blocks, and can change execution for Blocks freely - that's how
// you create a Routine that does what you want.

// Routine.DefineBlock defines a block of Actions to execute in seactionsuence.
// Routine.DefineBlock defines a block of Actions to execute in sequence.
// Whatever block is the first to be defined will be the default block to run when a Routine is run.
// When a Action has completed its behavior, the Block will move on to the next one, until it's at the end.

// When an Action has completed its behavior, the Block will move on to the next one, until it's at the end.
// At that point, the Block will loop.

// Below, we define a Block with the ID "first". The ID is a string here, but can be any comparable object.
myRoutine.DefineBlock("first",

// actions.NewFunc() creates a Func, which is a Action that executes a customizeable function.
// actions.NewFunction() creates a Funcion Action that executes a customizeable function.
// This function must take the current block and return a RoutineFlow.
// A RoutineFlow signals to the running Block in the Routine what to do after the Action ends.

// The Block can:
// Depending on the RoutineFlow received, the Block can:

// - Stay on the current Action, repeating the Action the next time Routine.Update() is called (routine.FlowIdle)
// - Move to the next Action (routine.FlowNext), or
// - End the Routine entirely (routine.FlowFinish).

// If you want to simply stop a Block after it's done running, you can do so using Routine.DeactivateBlocks().
actions.NewFunc(func(block *routine.Block) routine.Flow {
// If you want to simply stop a Block at some point, you can do so using Routine.DeactivateBlocks().
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("Here's a simple block that prints some text, and waits three seconds.")
return routine.FlowNext
}),

actions.NewWait(time.Second*3),

actions.NewFunc(func(block *routine.Block) routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {

fmt.Println("Done!")

// We can return RoutineFlowFinish here, or use Flow.Finish() as a following Action to end the
// We can return RoutineFlowFinish here, or use actions.NewFinish() to create a finishing Action to end the
// Routine; whichever works.
return routine.FlowFinish

Expand Down
13 changes: 9 additions & 4 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ The general idea is that you create a Routine, and then define a Block. Blocks a

By utilizing Actions and Blocks, you can make up complex behaviors, or sequences of events.

_Note: This package supercedes [gocoro](github.com/solarlune/gocoro), which was my previous attempt at coroutines. If you want something with a more functional design and that is more traditionally coroutine-y, check out stealthrocket's [coroutine](https://github.com/stealthrocket/coroutine)._

## How do I get it?

`go get github.com/solarlune/routine`
Expand All @@ -24,14 +26,17 @@ func main() {
// Create a new Routine.
routine := routine.New()

// And now we begin to define our Blocks, which consist of Action objects that execute in sequence.
// A Block has an ID (in this case, a string set to "first block"), but the ID can be anything.
// And now we begin to define our Blocks, which consist of Actions
// that execute in sequence.
// A Block has an ID (in this case, a string set to "first block"),
// but the ID can be anything.
routine.DefineBlock("first block",

// actions.NewFunction() returns a ActionFunc, which is a function that will run the action provided.
// actions.NewFunction() returns a Function action. You provide it
// with a customizeable function.
// Depending on the Flow object returned, the Block will either idle on this Action, or move
// on to another one.
actions.NewFunction(func() routine.Flow {
actions.NewFunction(func(block *routine.Block) routine.Flow {
fmt.Println("Hi!")
return routine.FlowNext // FlowNext means to move to the next Action.
}),
Expand Down
5 changes: 3 additions & 2 deletions routine.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,7 @@ func (r *Routine) DeactivateBlock(blockIDs ...any) {
}
}

// SwitchBlock will switch only blocks with the given label names to be active.
// SwitchBlock will only activate blocks with any of the given label names, and deactivates all others.
func (r *Routine) SwitchBlock(labels ...any) {

for _, block := range r.Blocks {
Expand All @@ -328,7 +328,8 @@ func (r *Routine) SwitchBlock(labels ...any) {

}

func (r *Routine) BlockByName(idLabel any) *Block {
// BlockByID returns any Block found with the given ID.
func (r *Routine) BlockByID(idLabel any) *Block {
for _, block := range r.Blocks {
if block.ID == idLabel {
return block
Expand Down

0 comments on commit 1cd5571

Please sign in to comment.