Liking cljdoc? Tell your friends :D

sc.api


brkclj/smacro

(brk)
(brk expr)
(brk opts expr)

Like spy, but will block the executing Thread until you release it from the REPL.

There are 3 ways of resuming execution at an Execution Point where it was suspended by brk:

  • (sc.api/loose ep-id): resumes execution by evaluating the wrapped expression.
  • (sc.api/loose-with ep-id value): resumes execution by yielding value instead of evaluating the wrapped expression.
  • (sc.api/loose-with-err ep-id err): resumes execution by throwing err instead of evaluating the wrapped expression.

Similarly to spy, you can customize the behaviour of brk by passing a literal map of options; the accepted keys are:

  • :sc/brk-cs-logger-id
  • :sc/brk-ep-pre-eval-logger
  • :sc/brk-ep-post-eval-logger
  • :sc/dynamic-vars
  • :sc/called-from

You can completely disable the logging, recording, and blocking behaviour of spy at a given Code Site by using (cs.api/disable! cs-id).

You can discard the recorded information about a given Execution Point (typically for freeing memory) by using (sc.api/dispose! ep-id). Execution Points which are being blocked will see their execution resumed by throwing an Exception.

Since you will likely need your REPL to un-block, you should never execute a (brk ...) block directly from your REPL thread!

Like `spy`, but will block the executing Thread until
you release it from the REPL.

There are 3 ways of resuming execution at an Execution Point
where it was suspended by `brk`:

- `(sc.api/loose ep-id)`: resumes execution by evaluating
the wrapped expression.
- `(sc.api/loose-with ep-id value)`: resumes execution by
yielding `value` instead of evaluating the wrapped expression.
- `(sc.api/loose-with-err ep-id err)`: resumes execution by
throwing `err` instead of evaluating the wrapped expression.

Similarly to `spy`, you can customize the behaviour of `brk`
by passing a literal map of options; the accepted keys are:
- :sc/brk-cs-logger-id
- :sc/brk-ep-pre-eval-logger
- :sc/brk-ep-post-eval-logger
- :sc/dynamic-vars
- :sc/called-from

You can completely disable the logging, recording, and blocking behaviour of `spy`
at a given Code Site by using `(cs.api/disable! cs-id)`.

You can discard the recorded information about a given Execution Point
(typically for freeing memory) by using `(sc.api/dispose! ep-id)`. Execution
Points which are being blocked will see their execution resumed by
throwing an Exception.

Since you will likely need your REPL to un-block, you should never
execute a `(brk ...)` block directly from your REPL thread!
sourceraw docstring

brk-emitclj/s

(brk-emit opts expr amp-env amp-form)

Helper function for implementing (your own version of) the brk macro. See the source of brk for a usage example.

Helper function for implementing (your own version of) the
`brk` macro. See the source of `brk` for a usage example.
sourceraw docstring

brkqtclj/smacro

(brkqt)
(brkqt expr)
(brkqt opts expr)

'BReaK QuieTly' - like sc.api/brk but less verbose. Will not print the :sc.ep/value, :sc.ep/error nor :sc.cs/expr; useful when dealing with large values.

'BReaK QuieTly' - like sc.api/brk but less verbose.
Will not print the :sc.ep/value, :sc.ep/error nor :sc.cs/expr;
useful when dealing with large values.
sourceraw docstring

calling-fromclj/smacro

(calling-from from-v & body)

Binds sc.api.from/caller to from-v; to be used in combination with the :sc/called-from option.

When a Code Site has the :sc/called-from option set to a non-nil value v, (e.g via a SPY call of the form (sc.api/spy{:sc/called-from :foo} MY-EXPR)) logging and recording of Execution Points at this Code Site will only occur when the Dynamic Varsc.api.from/calleris bound tov`.

Any non-nil value is legal for from-v; you'll typically use a keyword, number or boolean.

Use this when you're only interested in the executions of a Code Site that are invoked from a given other place in your code (which you wrap with (sc.api/calling-from ...))

Binds sc.api.from/*caller* to `from-v`; to be used in combination with the :sc/called-from option.

When a Code Site has the :sc/called-from option set to a non-nil value `v`,
(e.g via a SPY call of the form `(sc.api/spy `{:sc/called-from :foo} MY-EXPR)`)
logging and recording of Execution Points at this Code Site will only occur
when the Dynamic Var `sc.api.from/*caller*` is bound to `v`.

Any non-nil value is legal for `from-v`; you'll typically use a keyword, number or boolean.

Use this when you're only interested in the executions of a Code Site that
are invoked from a given other place in your code
(which you wrap with `(sc.api/calling-from ...)`)
sourceraw docstring

cs-infoclj/s

(cs-info cs-id)

Given a Code Site Id, retrieves a map of information about that Code Site, featuring the following keys:

  • :sc.cs/id (negative integer): the ID of the Code Site
  • :sc.cs/expr (code form): the wrapped code expression
  • :sc.cs/local-names (vector of symbols): the names of the locals that are in the lexical environment of the Code Site.
  • :sc.cs/dynamic-vars (vector of symbols); the names of the dynamic Vars which bindings will be recorded at that Code Site.
  • :sc.cs/file (String): the path of the source file of the wrapped expr, when available
  • :sc.cs/line (integer): the line number of the spy or brk call in the source file, when available
  • :sc.cs/column (integer): the column number of the spy or brk call in the source file, when available
  • :sc.cs/disabled (boolean): whether this Code Site is in a disabled state.
Given a Code Site Id, retrieves a map of information about that Code Site,
featuring the following keys:

- :sc.cs/id (negative integer):
the ID of the Code Site
- :sc.cs/expr (code form):
the wrapped code expression
- :sc.cs/local-names (vector of symbols):
the names of the locals that are in the lexical environment of the Code Site.
- :sc.cs/dynamic-vars (vector of symbols);
the names of the dynamic Vars which bindings will be recorded at that Code Site.
- :sc.cs/file (String):
the path of the source file of the wrapped expr, when available
- :sc.cs/line (integer):
the line number of the `spy` or `brk` call in the source file, when available
- :sc.cs/column (integer):
the column number of the `spy` or `brk` call in the source file, when available
- :sc.cs/disabled (boolean):
whether this Code Site is in a disabled state.
sourceraw docstring

defscclj/smacro

(defsc ep-id)

Given an Execution Point Id, expands to several (def ...) expressions, defining Vars which names match the names of the locals captured by the spy or brk macros at the Execution Point.

In practice, this enables you to make some local, temporary bindings available globally and durably in a namespace (as Vars), which is convenient for evaluating forms using these bindings at the REPL.

Note: defsc will not recreate the dynamic Var bindings at this Execution Point.

You can un-define (via ns-unmap) the Vars defined by defsc for a code site by using sc.api/undefsc.

ep-id may be provided either as a positive integer literal (the Execution Point Id, e.g 8), or as a vector literal of one positive integer (the Execution Point Id) and one negative integer (the Code Site Id), e.g [8 -3]. Note that in Clojure environments where compilation and execution don't happen in the same address space (which is the case for JVM-compiled ClojureScript), only the second form is accepted, as there is no way of inferring the Code Site Id from the Execution Point Id at macro-expansion.

Given an Execution Point Id, expands to several `(def ...)` expressions,
defining Vars which names match the names of the locals captured
by the `spy` or `brk` macros at the Execution Point.

In practice, this enables you to make some local, temporary bindings available
globally and durably in a namespace (as Vars), which is convenient
for evaluating forms using these bindings at the REPL.

Note: `defsc` will not recreate the dynamic Var bindings at this Execution Point.

You can un-define (via ns-unmap) the Vars `def`ined by `defsc`
for a code site by using `sc.api/undefsc`.

`ep-id` may be provided either as a positive integer literal (the Execution Point Id, e.g 8),
or as a vector literal of one positive integer (the Execution Point Id) and one
negative integer (the Code Site Id), e.g [8 -3]. Note that in Clojure environments
where compilation and execution don't happen in the same address space
(which is the case for JVM-compiled ClojureScript), only the second form is accepted,
as there is no way of inferring the Code Site Id from the Execution Point Id
at macro-expansion.
sourceraw docstring

disable!clj/s

(disable! cs-id)

Disables all logging, recording, and blocking behaviour at a Code Site. No more Execution Points will be created at that Code Site, but the previously collected ones remain fully available. Idempotent. The Code Site can be re-enabled by calling sc.api/enable!

Disables all logging, recording, and blocking behaviour at a Code Site.
No more Execution Points will be created at that Code Site, but the previously
collected ones remain fully available. Idempotent. The Code Site can be re-enabled
by calling `sc.api/enable!`
sourceraw docstring

dispose!clj/s

(dispose! ep-id)

Frees up resources held by the given Execution Point. Useful for freeing memory.

If the Execution Point is in a suspened state (as by brk), will resume execution by throwing an Exception.

Frees up resources held by the given Execution Point.
Useful for freeing memory.

If the Execution Point is in a suspened state (as by `brk`),
will resume execution by throwing an Exception.
sourceraw docstring

dispose-all!clj/s

(dispose-all!)

Disposes of all Execution Points (as per sc.api/dispose!)

Disposes of all Execution Points (as per `sc.api/dispose!`)
sourceraw docstring

enable!clj/s

(enable! cs-id)

Undoes the action of sc.api/disable!. Idempotent.

Undoes the action of `sc.api/disable!`. Idempotent.
sourceraw docstring

ep-infoclj/s

(ep-info)
(ep-info ep-id)

Given an Execution Point Id, returns a map of information about that Execution Point, and the associated Code Site.

Returns a map featuring the following keys:

  • :sc.ep/id (positive integer) The id of the Execution Point
  • :sc.ep/code-site A map of data about the associated Code Site, see sc.api/cs-info
  • :sc.ep/value The value the wrapped expression evaluated to (if any)
  • :sc.ep/error The exception thrown by the evaluation of the wrapped exception (if any)
  • :sc.ep/local-bindings A map which keys are the names of the locals in the scope of the wrapped expression, and which values are the values the locals were bound to at this Execution Point.
  • :sc.ep/dynamic-var-bindings A map which keys are the fully-qualified names of the dynamic Vars recorded for the Code Site, and which values are the values they were bound to at the Execution Point.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).

Given an Execution Point Id,
returns a map of information about that Execution Point,
and the associated Code Site.

Returns a map featuring the following keys:
- :sc.ep/id (positive integer)
The id of the Execution Point
- :sc.ep/code-site
A map of data about the associated Code Site, see `sc.api/cs-info`
- :sc.ep/value
The value the wrapped expression evaluated to (if any)
- :sc.ep/error
The exception thrown by the evaluation of the wrapped exception (if any)
- :sc.ep/local-bindings
A map which keys are the names of the locals in the scope of the wrapped expression,
and which values are the values the locals were bound to at this Execution Point.
- :sc.ep/dynamic-var-bindings
A map which keys are the fully-qualified names of the dynamic Vars recorded
for the Code Site, and which values are the values they were bound to at
the Execution Point.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).
sourceraw docstring

ep-valueclj/s

(ep-value)
(ep-value ep-id)

Returns the value that was saved at the Execution Point identified by ep-id (or nil if none was saved). Shorthand for (:sc.ep/value (sc.api/ep-info ep-id)).

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).

Returns the value that was saved at the Execution Point
identified by ep-id (or nil if none was saved).
Shorthand for (:sc.ep/value (sc.api/ep-info ep-id)).

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).
sourceraw docstring

gen-ep-idclj/s

(gen-ep-id)

Generates a unique Execution Point Id, a positive integer.

Generates a unique Execution Point Id, a positive integer.
sourceraw docstring

last-ep-idclj/s

(last-ep-id)

Returns the id of the last saved Execution Point, in [ep-id cs-id] form. Throws an Exception if no Execution Point has been saved.

Returns the id of the last saved Execution Point, in [ep-id cs-id] form.
Throws an Exception if no Execution Point has been saved.
sourceraw docstring

letscclj/smacro

(letsc ep-id & body)

Given an Execution Point Id ep-id, will expand to let and binding forms wrapping body which will reproduce the local and dynamic Var bindings that were recorded by the spy and brk macro at the Execution Point.

In practice, this enables you to run body in the same local environment where the Execution Point was recorded.

ep-id may be provided either as a positive integer literal (the Execution Point Id, e.g 8), or as a vector literal of one positive integer (the Execution Point Id) and one negative integer (the Code Site Id), e.g [8 -3]. Note that in Clojure environments where compilation and execution don't happen in the same address space (which is the case for JVM-compiled ClojureScript), only the second form is accepted, as there is no way of inferring the Code Site Id from the Execution Point Id at macro-expansion.

Given an Execution Point Id `ep-id`, will expand to `let` and `binding`
forms wrapping `body` which will reproduce the local and dynamic Var bindings
that were recorded by the `spy` and `brk` macro at the Execution Point.

In practice, this enables you to run `body` in the same local environment where
the Execution Point was recorded.

`ep-id` may be provided either as a positive integer literal (the Execution Point Id, e.g 8),
or as a vector literal of one positive integer (the Execution Point Id) and one
negative integer (the Code Site Id), e.g [8 -3]. Note that in Clojure environments
where compilation and execution don't happen in the same address space
(which is the case for JVM-compiled ClojureScript), only the second form is accepted,
as there is no way of inferring the Code Site Id from the Execution Point Id
at macro-expansion.
sourceraw docstring

looseclj/s

(loose)
(loose ep-id)

Given an Execution Point Id ep-id for an Execution Point created by brk which is currently in a suspended state, resumes execution by evaluating the wrapped form.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).

Given an Execution Point Id `ep-id` for an Execution Point
created by `brk` which is currently in a suspended state,
resumes execution by evaluating the wrapped form.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).
sourceraw docstring

loose-withclj/s

(loose-with v)
(loose-with ep-id v)

Same as sc.api/loose, except that execution is resumed by yielding the provided value v instead of evaluating the wrapped expression.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).

Same as `sc.api/loose`, except that execution is resumed by
yielding the provided value `v` instead of evaluating the wrapped
expression.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).
sourceraw docstring

loose-with-errclj/s

(loose-with-err err)
(loose-with-err ep-id err)

Same as sc.api/loose, except that execution is resumed by throwing err instead of evaluating the wrapped expression.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).

Same as `sc.api/loose`, except that execution is resumed by
throwing `err` instead of evaluating the wrapped
expression.

As a convenience, when ep-id is not supplied, uses (sc.api/last-ep-id).
sourceraw docstring

save-epclj/s

(save-ep ep-id ep-data)

Creates or updates an Execution Point. ep-data should follow the same schema as what is returned by ep-info; only the :sc.ep/local-bindings and :sc.ep/code-site keys are required, and only :sc.cs/id will be taken in account for the Code Site. Returns ep-id.

Useful for artificially creating an Execution Point that is a slight variation of another one, e.g:

(sc.api/save-ep (sc.api/gen-ep-id) (-> (sc.api/ep-info 17) (select-keys [:sc.ep/local-bindings :sc.ep/code-site]) (assoc-in [:sc.ep/local-bindings 'x] 32)))

Creates or updates an Execution Point. `ep-data` should follow
the same schema as what is returned by ep-info; only the :sc.ep/local-bindings
and :sc.ep/code-site keys are required, and only :sc.cs/id will be taken in account
for the Code Site. Returns ep-id.

Useful for artificially creating an Execution Point that is a slight variation
of another one, e.g:

(sc.api/save-ep (sc.api/gen-ep-id)
  (-> (sc.api/ep-info 17)
    (select-keys [:sc.ep/local-bindings :sc.ep/code-site])
    (assoc-in [:sc.ep/local-bindings 'x] 32)))
sourceraw docstring

spyclj/smacro

(spy)
(spy expr)
(spy opts expr)

Records the scope (i.e bindings of local names) and value of the expression it wraps at runtime; yields the value of the wrapped expression.

At macro-expansion time, a Code Site Id (a negative integer) will be created and logged. Using this id, static information about the Code Site may be retrieved using (sc.api/cs-info cs-id).

Each time the expression is evaluated, an Execution Point Id (a positive integer) will be created and logged. Dynamic information about this Execution Point (and the associated Code Site) may be retrieved using (sc.api/ep-info ep-id).

Having noted the Execution Point Id, you can then 'recreate' the local runtime environment of the expression (its scope) using the letsc and defsc macros:

(letsc ep-id ...)

(defsc ep-id)

The behaviour of this macro may be customized by passing a map literal as a first argument, containing some of the following keys:

  • :sc/spy-cs-logger-id (keyword, defaults to :sc.api.logging/log-spy-cs) The id of the logger function that will be called at macro-expansion time with Code Site information. This function must have been registered using sc.api/register-cs-logger.

  • :sc/spy-ep-pre-eval-logger-fn (expression, defaults to `sc.api.logging/log-spy-ep-pre-eval) An expression which evaluates to a function (typically a Var name), which will be invoked at runtime before the wrapped expression is evaluated with Execution Point information - typically to log the Execution Point Id.

  • :sc/spy-ep-post-eval-logger (expression, defaults to `sc.api.logging/log-spy-ep-post-eval) Like :sc/spy-ep-pre-eval-logger-fn, but the function will be invoked after the wrapped expression is evaluated - typically to log the value of the expression.

  • :sc/dynamic-vars (Seq of symbols, defaults to []) The names of the dynamic Vars which bindings should be captured at evaluation time.

  • :sc/called-from (expression, defaults to nil) When set, recording and logging will only occur when the Dynamic Var sc.api.from/from holds the same value as the :sc/called-from expression (typically a keyword). Useful in generic functions, for only spying downstream of some caller. See also: sc.api/calling-from.

You may also provide your own defaults for these options by defining your own version of the spy macro: to do that, use sc.api/spy-emit.

You can completely disable the logging and recording behaviour of spy at a given Code Site by using (cs.api/disable! cs-id).

You can discard the recorded information about a given Execution Point (typically for freeing memory) by using (sc.api/dispose! ep-id).

Records the scope (i.e bindings of local names) and value
of the expression it wraps at runtime;
yields the value of the wrapped expression.

At macro-expansion time, a Code Site Id (a negative integer)
will be created and logged. Using this id, static information
about the Code Site may be retrieved using (sc.api/cs-info cs-id).

Each time the expression is evaluated, an Execution Point Id
(a positive integer) will be created and logged.
Dynamic information about this Execution Point
(and the associated Code Site) may be retrieved using
(sc.api/ep-info ep-id).

Having noted the Execution Point Id, you can then 'recreate'
the local runtime environment of the expression (its scope)
using the `letsc` and `defsc` macros:

(letsc ep-id
  ...)

(defsc ep-id)

The behaviour of this macro may be customized by passing a map literal
as a first argument, containing some of the following keys:

- :sc/spy-cs-logger-id (keyword, defaults to :sc.api.logging/log-spy-cs)
The id of the logger function that will be called at macro-expansion time
with Code Site information. This function must have been registered using
`sc.api/register-cs-logger`.

- :sc/spy-ep-pre-eval-logger-fn (expression, defaults to `sc.api.logging/log-spy-ep-pre-eval)
An expression which evaluates to a function (typically a Var name), which will
be invoked at runtime before the wrapped expression is evaluated with
Execution Point information - typically to log the Execution Point Id.

- :sc/spy-ep-post-eval-logger (expression, defaults to `sc.api.logging/log-spy-ep-post-eval)
Like :sc/spy-ep-pre-eval-logger-fn, but the function will be invoked after the
wrapped expression is evaluated - typically to log the value of the
expression.

- :sc/dynamic-vars (Seq of symbols, defaults to [])
The names of the dynamic Vars which bindings should be captured at evaluation
time.

- :sc/called-from (expression, defaults to nil)
When set, recording and logging will only occur when the Dynamic Var sc.api.from/*from*
holds the same value as the :sc/called-from expression (typically a keyword).
Useful in generic functions, for only spying downstream of some caller.
See also: sc.api/calling-from.

You may also provide your own defaults for these options by defining
your own version of the `spy` macro: to do that,
use `sc.api/spy-emit`.

You can completely disable the logging and recording behaviour of `spy`
at a given Code Site by using `(cs.api/disable! cs-id)`.

You can discard the recorded information about a given Execution Point
(typically for freeing memory) by using `(sc.api/dispose! ep-id)`.
sourceraw docstring

spy-emitclj/s

(spy-emit opts expr amp-env amp-form)

Helper function for implementing (your own version of) the spy macro. See the source of spy for a usage example.

Helper function for implementing (your own version of) the
`spy` macro. See the source of `spy` for a usage example.
sourceraw docstring

spyqtclj/smacro

(spyqt)
(spyqt expr)
(spyqt opts expr)

'Spy QuieTly' - like sc.api/spy but less verbose. Will not print the :sc.ep/value, :sc.ep/error nor :sc.cs/expr; useful when dealing with large values.

'Spy QuieTly' - like sc.api/spy but less verbose.
Will not print the :sc.ep/value, :sc.ep/error nor :sc.cs/expr;
useful when dealing with large values.
sourceraw docstring

undefscclj/smacro

(undefsc ep-or-cs-id)

Given an identifier ep-or-cs-id for a Code Site, undoes the effect of defsc by undefing the Vars defined by defsc (via ns-unmap).

ep-or-cs-id may be provided in one of the following forms:

  • a positive integer literal, identifying an Execution Point, e.g 8
  • a negative integer literal, identifying a Code Site, e.g -3
  • an [ep-id cs-id] vector literal, e.g [8 -3]
Given an identifier `ep-or-cs-id` for a Code Site,
undoes the effect of `defsc` by un`def`ing the Vars defined by `defsc`
(via `ns-unmap`).

`ep-or-cs-id` may be provided in one of the following forms:
- a positive integer literal, identifying an Execution Point, e.g 8
- a negative integer literal, identifying a Code Site, e.g -3
- an [ep-id cs-id] vector literal, e.g [8 -3]
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close