:- :~ navhome/'/docs/' navuptwo/'true' next/'true' sort/'6' title/'Shell (Dojo)' == ;> # Shell (Dojo) ;div(class "row") ;div(class "col-md-8") The Dojo is our shell; it processes system commands and returns output. It's a good place to quickly experiment with Urbit. On the surface the Dojo is just a Hoon REPL. On the inside, the Dojo is a system for operating on and transforming data in Urbit. == == ## Quickstart You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system commands. ##### Math Evaluate a Hoon expression (whitespace matters): ``` ~your-urbit:dojo> (add 2 2) ~your-urbit:dojo> %+ add 2 2 ``` Tall-form Hoon may require multiple lines: ``` ~your-urbit:dojo> %+ add ~your-urbit:dojo< 2 ~your-urbit:dojo< 2 ``` Hoon uses something called [the subject](/../../tutorials/hoon-ch1/hoon-ch1-3). The Dojo has its own subject, and that's where Hoon's equivalent of variables are stored. Use `=var` to save variable to the Dojo subject. ``` ~your-urbit:dojo> =foo (add 2 2) ``` Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a variable in a `.hoon` file in this way. ##### System Commands Use `=dir` to set the current working directory: ``` ~your-urbit:dojo> =dir %/web ``` (`%` represents your current directory. For a complete explanation on urbit paths, see the [filesystem section](/docs/using/filesystem)) Generators (files in `/gen`) are run with `+`: ``` ~your-urbit:dojo> +hello 'world' ``` Save output to a file in `%clay` with `*`: ``` ~your-urbit:dojo> *some/file/path/hoon 'hello world' ``` Run system commands from `:hood`, like `reload`, using `|`: ``` ~your-urbit:dojo> |reload %eyre ``` `_See the [Clay](../fileystem) page for more information on system commands.` ### Generators Generators are short Hoon scripts, saved as `.hoon` files in the `/gen` directory. Many Dojo commands exist in the form of generators. The syntax for running a generator is `+genname` for a generator saved as `genname.hoon`. `+cat` - Accepts a path and displays the file. Similar to Unix `cat`. ``` ~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon ``` `+code` - Generates a code to remotely log into your ship. ``` ~your-urbit:dojo> +code ``` `+curl` - Retrives data from a URL. Accepts a `tape`. Similar to Unix `curl`. ``` ~your-urbit:dojo> +curl "http://nyt.com" ``` `+hello` - Just prints the argument. Accepts a `@ta`. ``` ~your-urbit:dojo> +hello 'mars' ``` `+ls` - Similar to Unix `ls`. Accepts a path. ``` ~your-urbit:dojo> +ls %/web ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes ``` `+moon` - Generates a random moon from a planet. No arguments. ``` ~your-urbit:dojo> +moon ``` `+solid` - Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments. ``` ~your-urbit:dojo> .urbit/pill +solid ``` `+test` - Testrunner. Can test multiple generators at once, conventionally ones in the `/test` folder. Accepts a path. ``` ~your-urbit:dojo> +test /lib ``` `+ticket` - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`). ``` ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit ``` `+tree` - Generate a recursive directory listing. Takes a path. ``` ~your-urbit:dojo> +tree %/web ``` ### Hood The hood is the system daemon. See `gen/hood` and `app/hood`. `|hi` - Sends a direct message. Sort of like Unix `write`. Accepts an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes). ``` ~your-urbit:dojo> |hi ~binzod "you there?" ``` `|link` / `|unlink - Link / unlink a remote app. Accepts an Urbit name and an app name. ``` ~your-urbit:dojo> |link ~talsur-todres %octo ``` `|mass` - Prints the current memory usage of all the kernel modules. No arguments. ``` ~your-urbit:dojo> |mass ``` `|reload` - Reloads a kernel module (vane) from source. Accepts any number of vane names. ``` ~your-urbit:dojo> |reload %clay %eyre ``` **`|reset`** - Reloads `hoon.hoon` and all modules. No arguments. ``` ~your-urbit:dojo> |reset ``` **`|start`** - Starts an app. Accepts an app name. ``` ~your-urbit:dojo> |start %curl ``` ## Manual ;h3(class "first child") Sources and sinks == A dojo command is either a source or a sink. A source is just something that can be printed to your console or the result of some computation. A sink is an *effect*: a change to the filesystem, a network message, a change to your environment, or typed message to an app. Sources can be chained together, but we can only produce one effect per command. ### Sinks ##### `=` - Set variable Set any environment variable: ``` ~your-urbit:dojo> =foo 42 ~your-urbit:dojo> (add 2 foo) 44 ``` Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a variable in a `.hoon` file in this way. #### Special Variables There are a few special variables that the dojo maintains. #### `:` - Send to app `:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`. Send a `helm-hi` message to `hood`: ``` ~your-urbit:dojo> :hood &helm-hi 'hi' ``` Apps usually expect marked data, so `&` is often used here. #### `*` - Save in `%clay` Save a new `md` file in `web`: ``` ~your-urbit:dojo> *%/web/foo/md '# hello' ``` The last component of the path is expected to be the mark (or mime type). #### `.` - Export to Unix Export a noun to Unix with `.`: ``` ~your-urbit:dojo> .foo/bar/baz (add 2 2) ``` Which creates a file at `pier/.urb/put/foo/bar.baz`. This is very often used with `+solid`: ``` ~your-urbit:dojo> .urbit/pill +solid ``` Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill` ### Sources #### `&` - Mark conversion Convert between marks using `&`: ``` ~your-urbit:dojo> &html &md '# hello' '

hello

' ``` #### `_` - Run a function Use `_` to run a gate (or function): Write an arbitrary function and pass data to it: ``` ~your-urbit:dojo> _|=({a/@} (mul a 3)) 3 9 ``` Use a function to get the status code from an http request: ``` ~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com 301 ``` #### `+` `-` - HTTP requests `+http[s]://example.com` - sends a GET request `+http[s]://example.com &json [%s 'hi']` - sends a POST request with the JSON `"hi"` in the body. `-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the JSON `"hi"` in the body. Note that the first of these is a source while the last two are sinks. #### `+` - Generators Generators are simple hoon scripts loaded from the filesystem. They live in `gen/`. Create a random moon (from any planet): ``` ~your-urbit:dojo> +moon "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud" ``` ### Variables You can use `=` to set an environment variable in Dojo, but there are a few reserved names that have special uses. #### `dir` Current working `%clay` desk and revision. Read / write. **Examples:** ``` ~your-urbit:dojo> =dir %/web ~your-urbit:dojo> +ls % 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/ ``` #### `lib` Current set of libraries (`/lib`) in your environment. Can also be set with `/+`. Read / write. **Examples:** ``` ~your-urbit:dojo> =lib ~[[%react ~]] ~your-urbit:dojo> :: this also works: ~your-urbit:dojo> /+ react ~your-urbit:dojo> :: now we can use arms from lib/react.hoon ~your-urbit:dojo> (react-vale:react %div) ``` #### `sur` Current set of structures (`/sur`) in your environment. Can also be set with `/-`. Read / write. **Examples:** ``` ~your-urbit:dojo> =sur ~[[%sole ~]] ~your-urbit:dojo> :: this also works: ~your-urbit:dojo> /- sole ~your-urbit:dojo> :: now we can use arms in sur/sole.hoon ~your-urbit:dojo> `sole-effect:sole`[%bel ~] ``` #### `now` The current (128-bit `@da`) time. Read-only. **Example:** ``` ~your-urbit:dojo> now :: produces ~2016.3.21..21.10.57..429a ``` #### `our` The current urbit plot. Read-only. **Example:** ``` ~your-urbit:dojo> our :: produces ~your-urbit ``` #### `eny` 512 bits of entropy. Read-only. **Example:** ``` ~your-urbit:dojo> eny :: produces \/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/ 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn \/ ``` ## Troubleshooting If you encounter `%dy-edit-busy` while entering commands, it is because your dojo is blocked on a timer or an http request. Type backspace and your dojo will end the blocked command.