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 (now,our,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.
Bare 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 now.
/gen/add-one.hoon
|= n=@ud=<(add-one n)|%++ add-one|= a=@ud^- @ud(add a 1)--
Invoke as +add-one 5.
You could in principle use a |* bartar wet gate as well, but other cores don't pattern-match to what Dojo expects.
%say Generators
A %say generator can have zero, many, or optional arguments, unlike a bare generator. It can also have access to system variables like now, our, and eny.
For instance, the following generator can be run with no arguments:
/gen/say.hoon
:- %say|= *:- %noun(add 40 2)
> +say42
A %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 cask).
The head tag over the entire generator is always %say. The cask tag is most commonly %noun.
We use %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 %talk-command.
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).
Zero arguments
/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
Optional arguments
Let's look at an example that uses all three parts.
/gen/dice.hoon
:- %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 [bet=@ud ~].
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.
%ask Generators
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.
Like %say generators, %ask generators are head-tagged cells of gates, but with %ask.
The code below is an %ask generator that checks if the user inputs "blue" when prompted per a classic Monty Python scene↗.
/gen/axe.hoon
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> to ~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.
The +dbug agent is invoked against an agent to display internal state.
Any app can implement generators to wrap raw pokes (see %ahoy for instance).
For instance, :dojo|wipe is equivalent to :dojo +dojo/wipe. This pokes the %dojo agent with the output from running the generator located at /gen/dojo/wipe.hoon.
The Hood/Helm tooling like |install are generators automatically routed by Dojo to the correct agent. |commit, for instance, is equivalent to :hood +hood/commit. %hood generators are special-cased because it is the system app.