diff --git a/content/build-on-urbit/app-school/3-imports-and-aliases.md b/content/build-on-urbit/app-school/3-imports-and-aliases.md index aeb40710..6891a97f 100644 --- a/content/build-on-urbit/app-school/3-imports-and-aliases.md +++ b/content/build-on-urbit/app-school/3-imports-and-aliases.md @@ -208,5 +208,5 @@ The key takeaways are: * Run through the [example](3-imports-and-aliases.md#example) yourself on a fake ship if you've not done so already. * Have a read through the [Ford rune documentation](../../hoon/rune/fas.md) for details about importing libraries, structures and other things. -* Try the `+dbug` generator out on some other agents, like `:settings +dbug`, `:contacts +dbug`, etc, and try some of its options [described above](3-imports-and-aliases.md#dbug). +* Try the `+dbug` generator out on some other agents, like `:azimuth +dbug`, `:spider +dbug`, `:hood +dbug`, etc, and try some of its options [described above](3-imports-and-aliases.md#dbug). * Have a quick look over the source of the `/lib/default-agent.hoon` library, located at `/lib/default-agent.hoon` in the `%base` desk. We've not yet covered what the different arms do but it's still useful to get a general idea, and you'll likely want to refer back to it later. diff --git a/content/build-on-urbit/userspace/examples/dbug.md b/content/build-on-urbit/userspace/examples/dbug.md index d9e77927..9eb44edf 100644 --- a/content/build-on-urbit/userspace/examples/dbug.md +++ b/content/build-on-urbit/userspace/examples/dbug.md @@ -89,9 +89,12 @@ There are four actions exposed by the wrapper via the `+dbug` generator: :: inline arguments args=?(~ [what=?(%bowl %state) ~] [=poke ~]) :: named arguments - ~ + depth=@ud == :- %dbug +=; =poke + ?: =(0 depth) poke + [%skip depth poke] ?- args ~ [%state ''] [@ ~] ?-(what.args %bowl [%bowl ~], %state [%state '']) @@ -111,7 +114,8 @@ There are four actions exposed by the wrapper via the `+dbug` generator: :: |% +$ poke - $% [%bowl ~] + $% [%skip depth=@ud =poke] + [%bowl ~] [%state grab=cord] [%incoming =about] [%outgoing =about] @@ -141,6 +145,12 @@ There are four actions exposed by the wrapper via the `+dbug` generator: [cards this] =/ dbug !<(poke vase) + =? dbug ?=([%skip %0 *] dbug) poke.dbug + ?: ?=(%skip -.dbug) + =^ cards agent + %+ on-poke:ag %dbug + !>(`poke`dbug(depth (dec depth.dbug))) + [cards this] =; =tang ((%*(. slog pri 1) tang) [~ this]) ?- -.dbug @@ -289,6 +299,12 @@ By applying this door builder using `%-` censig, the `+on-poke` and `+on-peek` a [cards this] =/ dbug !<(poke vase) + =? dbug ?=([%skip %0 *] dbug) poke.dbug + ?: ?=(%skip -.dbug) + =^ cards agent + %+ on-poke:ag %dbug + !>(`poke`dbug(depth (dec depth.dbug))) + [cards this] =; =tang ((%*(. slog pri 1) tang) [~ this]) ?- -.dbug diff --git a/content/build-on-urbit/userspace/unit-tests.md b/content/build-on-urbit/userspace/unit-tests.md index 079373c3..faf2f960 100644 --- a/content/build-on-urbit/userspace/unit-tests.md +++ b/content/build-on-urbit/userspace/unit-tests.md @@ -36,11 +36,14 @@ The `%base` desk includes a `-test` thread which can run unit tests you've writt Any arms that don't begin with `test-` will be ignored. Each `+test-*` arm must produce a `$tang` (a `(list tank)`). If the `$tang` is empty (`~`), it indicates success. If the `$tang` is non-empty, it indicates failure, and the contents of the `$tang` is the error message. -To make test-writing easier, the `%base` desk includes the `/lib/test.hoon` library which you can import into your test file. The library contains four functions which all produce `$tang`s: +To make test-writing easier, the `%base` desk includes the `/lib/test.hoon` library which you can import into your test file. The library contains the following functions, which all produce `$tang`s: - `+expect-eq` - test whether an expression produces the expected value. This function takes `[expected=vase actual=vase]`, comparing `.expected` to `.actual`. - `+expect` - test whether an expression produces `%.y`. This function takes a `$vase` containing the result to check. - `+expect-fail` - tests whether the given `$trap` crashes, failing if it succeeds. +- `+expect-success` - the converse of `+expect-fail`: tests whether the given `$trap` succeeds, failing if it crashes. +- `+expect-fail-message` - takes `[msg=@t a=(trap)]`. Like `+expect-fail`, but also requires that `.msg` appear in the resulting error message, so you can assert on *why* something failed rather than just that it did. +- `+run-chain` - takes an `$a-test-chain` and runs a sequence of tests, stopping at the first failure. Note that arms in the chain should not begin with `test-`, so that `-test %/... ~` does not also run them individually. - `+category` - this is a utility that prepends an error message to a failed test (non-null `$tang`), passing through an empty `$tang` (successful test) unchanged. The most commonly used function is `+expect-eq`, which is used like: diff --git a/content/user-manual/os/dojo-tools.md b/content/user-manual/os/dojo-tools.md index 4ce51bdd..c520b789 100644 --- a/content/user-manual/os/dojo-tools.md +++ b/content/user-manual/os/dojo-tools.md @@ -1185,16 +1185,61 @@ Query the state or bowl of a running agent. #### Arguments -See the [dbug section of App School lesson 3](../../build-on-urbit/app-school/3-imports-and-aliases.md#dbug) for details of usage. +``` +?(~ [?(%bowl %state) ~] [poke ~]), =depth @ud +``` + +See the [dbug section of App School lesson 3](../../build-on-urbit/app-school/3-imports-and-aliases.md#dbug) for details of the positional argument. + +The named `=depth` argument addresses an agent running *underneath* a wrapper +agent. With a non-zero depth the poke is wrapped as `[%skip depth poke]`, and +each layer of `/lib/dbug` decrements it before passing the poke down. It is only +meaningful for a nested agent; sending it to an ordinary agent produces +`unexpected poke to %agent with mark %dbug`. #### Example This is only used with an `:agent`, not by itself. ``` -> :graph-store +dbug [%state '(~(got by graphs) ~zod %dm-inbox)'] +> :azimuth +dbug [%state 'whos'] >= -> [p={} q=[~ %graph-validator-dm]] +> {} +``` + +--- + +### `|eyre/clean` {#eyreclean} + +Delete stale incoming HTTP subscriptions. + +Eyre channel subscriptions can be left behind when a channel goes away without +its subscriptions being torn down. This generator finds those and can remove +them. + +**It runs in dry mode by default**, only reporting how many stale subscriptions +it found. Pass `=dry |` to actually delete them. + +#### Arguments + +``` +=dry ?, =veb ?(%1 %2 ~) +``` + +- `=dry` - defaults to `&` (dry run). Pass `|` to delete. +- `=veb` - verbosity. `%1` prints each stale subscription; `%2` prints each + subscription that still exists. + +#### Examples + +``` +> |eyre/clean +>= +"#0 stale incoming subscriptions" +``` + +``` +> |eyre/clean, =dry | ``` --- @@ -1822,7 +1867,7 @@ These are more advanced desk and filesystem tools. Enable automatic commits for a mounted desk -Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancelautocommit). +Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancel-autocommit). #### Arguments @@ -1886,7 +1931,7 @@ The `$desk` is mandatory, the `.auto` is optional. If `.auto` is `%.y`, auto-commits will be enabled, meaning changes to that desk on the host side will automatically be committed as soon as they happen. -Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancelautocommit). +Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancel-autocommit). #### Example