wikla.tree — wikla 0.9.0

Behavior Tree branches, leaves and tools.

->dot clj

(->dot node file-name)

Eats node, saves tree to DOT file. (Uses spit -- Clojure only.)

->png clj

(->png node file-name)

Eats node, saves tree to PNG. (Shells out to dot -- Clojure only.)

->svg clj

(->svg node file-name)

Eats node, saves tree to SVG. (Shells out to dot -- Clojure only.)

action clj/s

(action seed)

Create an Action node from given seed, which must at least contain :tick-fn.

Expectation regarding the tick-fn:

(tick-fn node) => node'

Action clj/s

as-parallel clj/s

(as-parallel coll)

Create a Parallel from collection of nodes.

as-robin clj/s

(as-robin coll)

Create a Robin from collection of nodes.

as-selector clj/s

(as-selector coll)

Create a Selector from collection of nodes.

as-sequence clj/s

(as-sequence coll)

Create a Sequence from collection of nodes.

attach-hook clj/s

(attach-hook node hook-fn)

(attach-hook node on-status hook-fn)

Attach hook on SUCCESS, FAILURE, RUNNING, READY or :* key.

Hook function should have the signature:

(hook-fn node') => nil

condition clj/s

(condition seed)

Create a Condition node from given seed, which must at least contain :pred-fn.

Expectation regarding the pred-fn:

(pred-fn node) => Boolean-ish

Condition clj/s

decided? clj/s

(decided? node)

Is node shifted to SUCCESS, FAILURE or RUNNING?

decorate clj/s

(decorate child)

Decorate a child with default, pass-through Decorator.

Decorator clj/s

decorator clj/s

(decorator seed)

Decorator is a hybrid node, defining both tick and part/join calls.

It holds a single child and decides if it should be executed: first tick is executed and calls:

(branch-pred decorator) => true | false

branch-pred returns true: child will be executed. Decorator changes its type to composite and signals Ready. During join child node is back and Decorator, it immediately runs post-join-fn:

(post-join-fn decorator) => decorator'

This function is fed Decorator containing ticked child, will decide final shape of the node. If post-join-fn is nil the decorator will just pass through flag and stash of the child.

branch-pred returns false: child is not used, own-tick-fn runs:

(own-tick-fn decorator) => decorator'

This constructor accepts a seed of:

• child, a node to be decorated,
• branch-pred used for branching? decision if first tick, defaut: yes,
• own-tick-fn used to tick on decorator if branch-pred returned false, default: success,
• post-join-fn used to tick after join of finalized child, default: nil,
• flag preset, default: READY,
• properties for the node, default: nil,
• paramteres for the node, default: nil,
• stash for the node, default: nil.

By default Decorator will try to execute the child and pass its status up. If forced to tick default own-tick will just succeed.

Callable expectations, stash and stashless:

(branch-pred decorator) => true | false

(post-join-fn decorator) => Success | Failure | Running | Ready

(own-tick-fn decorator) => Success | Failure | Running | Ready

detach-hook clj/s

(detach-hook node)

(detach-hook node on-status)

Detach hook on SUCCESS, FAILURE, RUNNING, READY or :* key.

done? clj/s

(done? node)

Is node shifted to SUCCESS or FAILURE?

dot-colors clj/s

dot-string clj/s

(dot-string node)

Eats node, returns DOT graph string.

Walks the tree Depth-First, numbers nodes and links them.

FAILURE clj/s

failure clj/s

(failure node)

(failure node stash)

Shift node to FAILURE. Optionally with stash.

failure-action clj/s

Predefined Action that will fail on tick.

failure-condition clj/s

Predefined failing condition.

failure? clj/s

(failure? node)

Is node shifted to FAILURE?

fn->action clj/s

(fn->action tick-fn)

(fn->action name tick-fn)

Create Action out of a tick-fn function.

fn->condition clj/s

(fn->condition pred-fn)

(fn->condition name pred-fn)

Create Condition out of a pred-fn function.

mu clj/s

(mu & _)

Always nil, just like (constantly nil), except interned.

no clj/s

(no & _)

Always false, just like (constantly false), except interned.

Node clj/s protocol

Branching and ticking, access and viz helpers, just node things.

-node? clj/s

(-node? _)

Is this a Node?

dot-color clj/s

(dot-color this)

Node color in the visualization.

dot-shape clj/s

(dot-shape this)

Desired Shape in the visualization.

join clj/s

(join this child*)

Join current child.

shift clj/s

(shift this)

(shift this flag*)

Get-set flag.

tick clj/s

(tick this)

Update node.

branch? clj/s

(branch? this)

Is this a branch?

yield clj/s

(yield this)

(yield this yield*)

Get-set stash.

hooks clj/s

(hooks this)

(hooks this hook*)

Get-set hooks.

part clj/s

(part this)

Get next child.

params clj/s

(params this)

(params this params*)

Get-set parameters.

branches clj/s

(branches this)

(branches this children*)

Get-set children.

label clj/s

(label this)

(label this label*)

Get-set name.

stem clj/s

(stem this)

(stem this stem*)

Get-set node.

dot-label clj/s

(dot-label this)

Node Description in the visualization.

node-seq clj/s

(node-seq node)

Eat node, return seq.

node? clj/s

(node? o)

Is this a Node?

parallel clj/s

(parallel seed)

Create a Parallel node with given seed and nodes. Children will run in order, child that is RUNNING will be put in queue and Parallel will get READY to execute next child immediately. Parallel will itself return RUNNING on retry and full cycle, which can be changed.

When all children are either SUCCESS or FAILURE final tally will executes. If no threshold is reached, then fresh copy of children will be brought back for execution and Parallel will raise retry count and retry.

Parallel will evalute to, in order:

• SUCCESS if all children are done and success-th was reached
• FAILURE if all children are done and failure-th was reached
• cycle-flag on cycle completion (all children ran once)
• retry-flag on retry initiation.

If both success-th and failure-th were reached SUCCESS will be returned.

The rewind-fn is given Parallel to prepare it for re-run, defaults to nil, in which case fresh copy of children is used. The rewind-fn can overwrite retry-flag, which is set before that function runs.

For alternate Parallel implementation see: Robin.

Parallel clj/s

parallel* clj/s

(parallel* & nodes)

Create a Parallel from node arguments.

print-callstack clj/s

(print-callstack a-root)

Print callstack from given a Stepper implementing callstack.

print-tree clj/s

(print-tree start-node)

(print-tree marker-pred start-node)

Print nodes of a tree, indented by depth, marked via predicate.

ready clj/s

(ready node)

(ready node stash)

Shift node to READY. Optionally with stash.

READY clj/s

ready? clj/s

(ready? node)

Is node shifted to READY?

Robin clj/s

robin clj/s

(robin seed)

Create a Robin node with given seed and nodes. Children will run in order, child that is RUNNING will be put in queue and Robin will get READY to execute next child immediately. Robin will be RUNNING on retry and cycle completion which can be customized.

When all children are either SUCCESS or FAILURE summary-fn will execute on Robin. If it returns SUCCESS or FAILURE then Robin ends its run with that. If it returns RUNNING Robin will retry.

Robin will evalute to:

• SUCCESS if all children are done and summary-fn sets SUCCESS
• FAILURE if all children are done and summary-fn sets FAILURE
• cycle-flag on cycle completion (all children ran once)
• retry-flag on retry initiation.

If no summary-fn is provided Robin returns SUCCESS once all children are done.

The rewind-fn is given Robin to prepare it for re-run, defaults to nil, in which case fresh copy of children is used. The rewind-fn is able to overwrite retry-flag, because that is set before it runs.

Robin is a non-canon Parallel implementation.

robin* clj/s

(robin* & nodes)

Create a Robin from node arguments.

Root clj/s

root clj/s

(root seed)

Create Root node with given seed and tree.

root-of clj/s

(root-of tree)

Create Root node with given tree node.

run-hooks! clj/s

(run-hooks! node)

Try to execute hooks for side-effects, return node.

running clj/s

(running node)

(running node stash)

Shift node to RUNNING. Optionally with stash.

RUNNING clj/s

running-action clj/s

Predefined Action that will be running on tick.

running? clj/s

(running? node)

Is node shifted to RUNNING?

Selector clj/s

selector clj/s

(selector seed)

Create a Selector node from given seed, which must at least contain :children.

Sequence will evalute to:

• SUCCESS if a child returns SUCCESS.
• FAILURE if all children ran and resulted in FAILURE.
• RUNNING immediately if any child is RUNNING.

selector* clj/s

(selector* & nodes)

Create a Selector from node arguments.

Sequence clj/s

sequence clj/s

(sequence seed)

Create a Sequence node from given seed which must at least contain :children.

Sequence will evalute to:

• SUCCESS if all children ran and were SUCCESS.
• FAILURE immediately if any child is FAILURE.
• RUNNING immediately if any child is RUNNING.

sequence* clj/s

(sequence* & nodes)

Create a Sequence from node arguments.

Stepper clj/s protocol

Step-by-step ticking.

-stepper? clj/s

(-stepper? this)

Is this a Stepper?

callstack clj/s

(callstack this)

Return full stack from root to current node.

exhaust clj/s

(exhaust this)

Step through tree until finished.

finished? clj/s

(finished? this)

Is this tick completed?.

handle-branch clj/s

(handle-branch this)

Perform branch op.

handle-leaf clj/s

(handle-leaf this)

Perform leaf op.

step clj/s

(step this)

Perform single op.

step-until clj/s

(step-until this pred)

Perform steps until predicate is true.

stepper? clj/s

(stepper? o)

Is this a Stepper?

success clj/s

(success node)

(success node stash)

Shift node to SUCCESS. Optionally with stash.

SUCCESS clj/s

success-action clj/s

Predefined Action that will succeed on tick.

success-condition clj/s

Predefined succeeding condition.

success? clj/s

(success? node)

Is node shifted to SUCCESS?

to-failure clj/s

(to-failure a-fn)

Create an Action that runs given function on stash and fails.

to-success clj/s

(to-success a-fn)

Create an Action that runs given function on stash and succeeds.

via-pred clj/s

(via-pred pred)

Create a Condition that runs given predicate on stash.

yes clj/s

(yes & _)

Always true, just like (constantly true), except interned.

zipper clj/s

(zipper node)

Eat node, return zipper.