Generator files provide a way for users to interact with code "scripts" through the Dojo prompt. There are three basic kinds of generators:
- Bare or naked generators, standalone computations that can accept input and carry out a single calculation.
%saygenerators, scripts which can utilize the full system knowledge (
eny) and accept optional input arguments.
%askgenerators, scripts driven by interactive prompts.
(Threads have some commonalities with generators, q.v.)
Generators are a Dojo concept, although they can also be applied to agents (such as
+dbug). This guide will show you how to build and invoke all kinds of generators.
A basic generator is a gate, a core with a
$ buc arm and a sample.
The Dojo will supply the sample directly to the core in the
$ buc arm.
A bare generator must be a gate but can have more complicated internal structure, as with all Hoon code. It does not know about entropy
eny, ship identity
our, or the timestamp
|= n=@ud=<(add-one n)|%++ add-one|= a=@ud^- @ud(add a 1)--
You could in principle use a
|* bartar wet gate as well, but other cores don't pattern-match to what Dojo expects.
%say generator can have zero, many, or optional arguments, unlike a bare generator. It can also have access to system variables like
For instance, the following generator can be run with no arguments:
:- %say|= *:- %noun(add 40 2)
%say generator is structurally a head-tagged cell of a gate which returns a head-tagged cell of a mark and a value (or a
The head tag over the entire generator is always
cask tag is most commonly
%say generators when we want to provide something else in Arvo, the Urbit operating system, with metadata about the generator's output. This is useful when a generator is needed to pipe data to another program, a frequent occurrence.
To that end,
%say generators use
marks to make it clear, to other Arvo computations, exactly what kind of data their output is. A
mark is akin to a MIME type on the Arvo level. A
mark describes the data in some way, indicating that it's an
%atom, or that it's a standard such as
%json, or even that it's an application-specific data structure like
The gate sample follows this pattern, with undesired elements stubbed out by
|= $: :: environment$: now=@da :: timestampeny=@uvJ :: entropybec=beak :: clay beak==:: :: unnamed args$=$: arg=@ :: required arguments==~==:: :: named args$=$: named-arg=@ :: optional arguments==~====
The Dojo will modify the sample by inserting
%~ (constant null) at the end of each collection, since the Dojo adapts the input arguments into a list (either the unnamed/required argument list or the named/optional argument list).
/gen/vats.hoon is commonly used to check on the status of installed desks. It can be invoked with optional arguments:
> +vats%base/sys/kelvin: [%zuse 414]base hash ends in: drceb%cz hash ends in: drcebapp status: runningpending updates: ~> +vats, =verb %.n%base/sys/kelvin: [%zuse 414]base hash ends in: drceb%cz hash ends in: drcebapp status: runningpending updates: ~> +vats, =filt %suspended
Let's look at an example that uses all three parts.
:- %say|= [[now=@da eny=@uvJ bec=beak] [n=@ud ~] [bet=@ud ~]]:- %noun[(~(rad og eny) n) bet]
This is a very simple dice program with an optional betting functionality. In the code, our sample specifies faces on all of the Arvo data, meaning that we can easily access them. We also require the argument
[n=@ud ~], and allow the optional argument
We can run this generator like so:
> +dice 6, =bet 2[4 2]> +dice 6[5 0]> +dice 6[2 0]> +dice 6, =bet 200[0 200]> +dicenest-fail
Notice how the
, com works to separate arguments and how the name of the optional argument must be included.
We get a different value from the same generator between runs, something that isn't possible with a bare generator. Another novelty is the ability to choose to not use the second argument.
We use an
%ask generator when we want to create an interactive program that prompts for inputs as it runs, rather than expecting arguments to be passed in at the time of initiation.
%ask generators are head-tagged cells of gates, but with
The code below is an
%ask generator that checks if the user inputs
"blue" when prompted per a classic Monty Python scene.
Click to expand
/- sole/+ generators=, [sole generators]:- %ask|= *^- (sole-result (cask tang))%+ print leaf+"What is your favorite color?"%+ prompt [%& %prompt "color: "]|= t=tape%+ produce %tang?: =(t "blue"):~ leaf+"Oh. Thank you very much."leaf+"Right. Off you go then."==:~ leaf+"Aaaaagh!"leaf+"Into the Gorge of Eternal Peril with you!"==
Run the generator from the Dojo:
> +axeWhat is your favorite color?: color:
Instead of simply returning something, your Dojo's prompt changed from
~sampel-palnet:dojo: color:, and now expects additional input. Let's give it an answer:
: color: redInto the Gorge of Eternal Peril with you!Aaaaagh!
%ask generators return
sole-effects. For more information on these, consult the guide on command-line agents.
%ask generators can also accept arguments, although this is uncommon.
Generators for Agents
Generators can furthermore interact specifically with agents.
+dbug agent is invoked against an agent to display internal state.
Any app can implement generators to wrap raw pokes (see
%ahoy for instance).
:dojo|wipe is equivalent to
:dojo +dojo/wipe. This pokes the
%dojo agent with the output from running the generator located at
The Hood/Helm tooling like
|install are generators automatically routed by Dojo to the correct agent.
|commit, for instance, is equivalent to
%hood generators are special-cased because it is the system app.