wikla.tree — wikla 1.1.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'

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

Result of hook-fn call will be discarded.

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

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 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.

dtx clj/s

(dtx a-root)

Run Stepper until Exception is thrown, rethrows with one step prior.

:root key of ExceptionInfo holds a callable containing throwing step.

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.

friendlify clj/s

(friendlify a-something)

Try to get a friendlier function name.

In Clojure class is turned into String, then processed with regexps.

In ClojureScript string is expected to start with 'function' followed by name that will be extracted and processed in similar fashion. Fallback returns 48 starting characters of the stringified object.

in-params clj/s

(in-params node f)

(in-params node f x)

(in-params node f x y)

(in-params node f x y z)

(in-params node f x y z & more)

Extract parameters from node, feed them to function f, put them back in.

in-props clj/s

(in-props node f)

(in-props node f x)

(in-props node f x y)

(in-props node f x y z)

(in-props node f x y z & more)

Extract properties from node, feed them to function f, put them back in.

in-stash clj/s

(in-stash node f)

(in-stash node f x)

(in-stash node f x y)

(in-stash node f x y z)

(in-stash node f x y z & more)

Extract stash from node, feed it to function f, put it back in.

merge-hooks clj/s

(merge-hooks sub-tree new-hooks)

(merge-hooks sub-tree new-hooks missing-only?)

Zip down sub-tree and update hooks from new-hooks map.

Set missing-only? to not overwrite existing values. Defaults to false.

merge-params clj/s

(merge-params sub-tree new-params)

(merge-params sub-tree new-params missing-only?)

Zip down sub-tree and update properties from new-props map.

Set missing-only? to not overwrite existing values. Defaults to false.

merge-props clj/s

(merge-props sub-tree new-props)

(merge-props sub-tree new-props missing-only?)

Zip down sub-tree and update properties from new-props map.

Set missing-only? to not overwrite existing values. Defaults to false.

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.

props clj/s

(props this)

(props this props*)

Get-set properties.

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 READY on retry and full cycle.

When all children are either SUCCESS or FAILURE final tally happens. 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, READY by default
• retry-flag on retry initiation, READY by default.

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* & nodes)

Create a Parallel from node arguments.

persistent-queue clj/s

Empty PersistentQueue.

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.

queue clj/s

(queue o)

Make object o a PersistentQueue.

queue? clj/s

(queue? o)

Is object o a instance of PersistentQueue?

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 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 READY on retry and cycle completion.

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 either summary-fn sets SUCCESS or summary-fn is nil
• FAILURE if all children are done and summary-fn sets FAILURE
• cycle-flag on cycle completion, READY by default
• retry-flag on retry initiation, READY by default.

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 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, discard results, 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 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 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.