(execute registry instruction)(execute registry instruction opts)Evaluates an instruction with a command registry.
The optional third argument is a config map:
:error-data-string - (boolean) serialize exception data as strings
:hook-execute-start - (fn [status-map]) called before execution;
return value is discarded (pure observer)
:hook-execute-end - (fn [status-map]) called after execution;
return value is discarded (pure observer)
:hook-command-guard-outer-fn - (fn [status-map] status-map) called once
right after commands are found, only on the outermost execute call
(stack depth 1); unlike the hooks above its return value IS used —
it can call status-map-handle-error to reject the whole execution
before step-build-deps-tree/step-execute-commands! run. See
commando.utils/hook-reject-commands-fn for a per-command convenience
helper to call from inside it.
:hook-command-guard-inner-fn - same contract, only on nested execute
calls (e.g. from :commando/macro or :commando/resolve)
:hook-command-guard-all-fn - same contract, on every execute call
regardless of depth (used instead of the outer/inner keys, not
combined with them)
Config keys are inherited by nested execute calls. Inner calls can override specific keys — non-overridden keys come from the parent.
execute itself is a thin wrapper around steps-pipeline-default/execute-steps/
with-execute-context — see those for stopping the pipeline at a chosen
step (e.g. to inspect :internal/cm-running-order before anything runs)
and resuming it later.
Examples: ;; Full execution (execute reg instruction)
;; With config (execute reg instruction {:error-data-string false})
Evaluates an instruction with a command registry.
The optional third argument is a config map:
:error-data-string - (boolean) serialize exception data as strings
:hook-execute-start - (fn [status-map]) called before execution;
return value is discarded (pure observer)
:hook-execute-end - (fn [status-map]) called after execution;
return value is discarded (pure observer)
:hook-command-guard-outer-fn - (fn [status-map] status-map) called once
right after commands are found, only on the outermost execute call
(stack depth 1); unlike the hooks above its return value IS used —
it can call status-map-handle-error to reject the whole execution
before step-build-deps-tree/step-execute-commands! run. See
`commando.utils/hook-reject-commands-fn` for a per-command convenience
helper to call from inside it.
:hook-command-guard-inner-fn - same contract, only on nested execute
calls (e.g. from :commando/macro or :commando/resolve)
:hook-command-guard-all-fn - same contract, on every execute call
regardless of depth (used instead of the outer/inner keys, not
combined with them)
Config keys are inherited by nested execute calls. Inner calls can
override specific keys — non-overridden keys come from the parent.
`execute` itself is a thin wrapper around `steps-pipeline-default`/`execute-steps`/
`with-execute-context` — see those for stopping the pipeline at a chosen
step (e.g. to inspect `:internal/cm-running-order` before anything runs)
and resuming it later.
Examples:
;; Full execution
(execute reg instruction)
;; With config
(execute reg instruction {:error-data-string false})(execute-steps status-map steps)Runs steps over status-map — the same mechanism execute uses
internally, exposed for running only part of the pipeline. Must run
inside with-execute-context. Before each step, calls its :step-assert
(skipped once status-map is :failed) — execute-steps doesn't
interpret what that does; a :step-assert throwing is entirely up to
the step author, e.g. commando.core/step-assert-keys.
Examples
;; equivalent to a plain execute call
(with-execute-context nil
(fn []
(execute-steps (smap/status-map-pure {:instruction instruction})
(steps-pipeline-default registry))))
;; stop before commands run, inspect, resume later (def steps (steps-pipeline-default registry)) (def halted (with-execute-context nil (fn [] (execute-steps (smap/status-map-pure {:instruction instruction}) (take-while #(not= (:step-name %) :step-execute-commands!) steps)))))
See
commando.core/steps-pipeline-defaultcommando.core/with-execute-contextRuns `steps` over `status-map` — the same mechanism `execute` uses
internally, exposed for running only part of the pipeline. Must run
inside `with-execute-context`. Before each step, calls its `:step-assert`
(skipped once `status-map` is `:failed`) — `execute-steps` doesn't
interpret what that does; a `:step-assert` throwing is entirely up to
the step author, e.g. `commando.core/step-assert-keys`.
Examples
;; equivalent to a plain `execute` call
(with-execute-context nil
(fn []
(execute-steps (smap/status-map-pure {:instruction instruction})
(steps-pipeline-default registry))))
;; stop before commands run, inspect, resume later
(def steps (steps-pipeline-default registry))
(def halted
(with-execute-context nil
(fn []
(execute-steps (smap/status-map-pure {:instruction instruction})
(take-while #(not= (:step-name %) :step-execute-commands!) steps)))))
See
- `commando.core/steps-pipeline-default`
- `commando.core/with-execute-context`(registry-add built-registry command-map-spec)Adds or replaces a CommandMapSpec in a built registry. Identification is by the spec's :type key. If a spec with the same :type already exists it is replaced; otherwise the new spec is appended. Revalidates the registry.
Example: (-> (registry-create [...]) (registry-add my-cmd-spec))
Adds or replaces a CommandMapSpec in a built registry.
Identification is by the spec's :type key. If a spec with the same :type
already exists it is replaced; otherwise the new spec is appended.
Revalidates the registry.
Example:
(-> (registry-create [...])
(registry-add my-cmd-spec))(registry-create registry)Creates a 'Command' registry from a vector of CommandMapSpecs.
Accepts either:
Each command specification (CommandMapSpec) should be a map containing at least:
:type - a unique keyword identifying the command type:recognize-fn - a function to recognize the command in the instruction map
(fn [element] (and (map? element) (contains? element :your-command-key)):apply - a function to execute the command:
(fn [instruction command-map-obj command-data] ...):dependencies - declare way the command should build dependency
{:mode :all-inside} - all commands inside the current map are dependencies
{:mode :none} - no dependencies, the other commands may depend from it.
{:mode :point :point-key [:commando/from]} - special type of dependency
which declare that current command depends from the command it refer by
exampled :commando/from key.Additional optional keys can include:
:validate-params-fn - a function to validate command structures, and catch
invalid parameters at the analysis stage. Only if the function
return 'true' it meant that the command structure is valid.
(fn [data] (throw ...)) => Failure
(fn [data] {:reason "why"}) => Failure
(fn [data] nil ) => Failure
(fn [data] false ) => Failure
(fn [data] true ) => OKThe function returns a built registry that can be used to resolve Instruction
Example: (registry-create [commando.commands.builtin/command-from-spec commando.commands.builtin/command-fn-spec])
Creates a 'Command' registry from a vector of CommandMapSpecs.
Accepts either:
- A vector of CommandMapSpecs (order defines command scan priority)
- An already-built registry (returned as-is)
Each command specification (CommandMapSpec) should be a map containing at least:
- `:type` - a unique keyword identifying the command type
- `:recognize-fn` - a function to recognize the command in the instruction map
(fn [element] (and (map? element) (contains? element :your-command-key))
- `:apply` - a function to execute the command:
(fn [instruction command-map-obj command-data] ...)
- `:dependencies` - declare way the command should build dependency
{:mode :all-inside} - all commands inside the current map are dependencies
{:mode :none} - no dependencies, the other commands may depend from it.
{:mode :point :point-key [:commando/from]} - special type of dependency
which declare that current command depends from the command it refer by
exampled :commando/from key.
Additional optional keys can include:
- `:validate-params-fn` - a function to validate command structures, and catch
invalid parameters at the analysis stage. Only if the function
return 'true' it meant that the command structure is valid.
(fn [data] (throw ...)) => Failure
(fn [data] {:reason "why"}) => Failure
(fn [data] nil ) => Failure
(fn [data] false ) => Failure
(fn [data] true ) => OK
The function returns a built registry that can be used to resolve Instruction
Example:
(registry-create
[commando.commands.builtin/command-from-spec
commando.commands.builtin/command-fn-spec])(registry-remove built-registry command-map-spec-type)Removes a CommandMapSpec from a built registry by its :type. Revalidates the registry.
Example: (-> (registry-create [...]) (registry-remove :my/cmd))
Removes a CommandMapSpec from a built registry by its :type.
Revalidates the registry.
Example:
(-> (registry-create [...])
(registry-remove :my/cmd))(step-assert-keys step-name keys)Builds a :step-assert fn: throws if status-map is missing any of
keys. The throwing is the assert's own job, not execute-steps's —
see execute-steps.
Builds a `:step-assert` fn: throws if `status-map` is missing any of `keys`. The throwing is the assert's own job, not `execute-steps`'s — see `execute-steps`.
(step-build-deps-tree
{:keys [instruction] :internal/keys [cm-list path-trie] :as status-map})Builds forward dependency graph using the path-trie produced by step-find-commands.
Builds forward dependency graph using the path-trie produced by step-find-commands.
(step-execute-commands! {:keys [instruction registry]
:internal/keys [cm-running-order]
:as status-map})(step-guard-commands status-map)Runs the configured :hook-command-guard-*-fn once, right after step-find-commands and before step-build-deps-tree/step-execute-commands! run.
See
commando.impl.utils/*execute-config*commando.utils/hook-reject-commands-fnRuns the configured :hook-command-guard-*-fn once, right after step-find-commands and before step-build-deps-tree/step-execute-commands! run. See - `commando.impl.utils/*execute-config*` - `commando.utils/hook-reject-commands-fn`
(step-prepare-execution-status-map status-map)Strips runtime-registry-only commands out of the running order and resets the runtime registry back to its pre-execution shape. Must run after step-sort-commands-by-deps and before step-execute-commands!.
Strips runtime-registry-only commands out of the running order and resets the runtime registry back to its pre-execution shape. Must run after step-sort-commands-by-deps and before step-execute-commands!.
(steps-pipeline-default registry)execute's pipeline as data — an ordered vector of maps:
:step-name keyword matching the step-* fn it wraps
:step-fn (fn [status-map]) => status-map
:step-assert (fn [status-map]) — a wiring precondition (not a data
check): throws if it fails, since that means the step
chain itself was assembled wrong, not that the
instruction/config is bad.
registry is baked into :step-use-registry's step-fn via closure.
See
commando.core/execute-stepsexecute's pipeline as data — an ordered vector of maps:
:step-name keyword matching the `step-*` fn it wraps
:step-fn `(fn [status-map]) => status-map`
:step-assert `(fn [status-map])` — a wiring precondition (not a data
check): throws if it fails, since that means the step
chain itself was assembled wrong, not that the
instruction/config is bad.
`registry` is baked into `:step-use-registry`'s `step-fn` via closure.
See
- `commando.core/execute-steps`(with-execute-context opts thunk)Creates the internal execution context for execute (and nested calls),
preparing opts for use by the steps.
See
commando.impl.utils/*execute-config*commando.impl.utils/*execute-internals*commando.core/executecommando.core/execute-stepsCreates the internal execution context for `execute` (and nested calls), preparing `opts` for use by the steps. See - `commando.impl.utils/*execute-config*` - `commando.impl.utils/*execute-internals*` - `commando.core/execute` - `commando.core/execute-steps`
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |