git.iko.soy/urbit.org
on master help sign in
ok shell
ed82126Galen Wolfe-Pauly
docs/walkthroughs/shell.md+96−40
compare with master
unifiedsplit
@@ -8,8 +8,6 @@ title: Shell
8
8
9The dojo is a typed functional shell.
9The dojo is a typed functional shell.
10
10
11−(Goals of a REPL+IFTTT, hood)
12−
13## Quickstart
11## Quickstart
14
12
15Evaluate a hoon expression:
13Evaluate a hoon expression:
@@ -53,7 +51,7 @@ Sources can be chained together, but we can only produce one effect per command.
53
51
54### Sinks
52### Sinks
55
53
56−### `=` - Set variable
54+#### `=` - Set variable
57
55
58Set any envronment variable:
56Set any envronment variable:
59
57
@@ -64,42 +62,80 @@ Set any envronment variable:
64
62
65(There are a few special variables that the dojo expects. See below.)
63(There are a few special variables that the dojo expects. See below.)
66
64
67−### `:` - Send to app
65+#### `:` - Send to app
66+
67+`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
68+
69+Send a `helm-hi` message to `hood`:
68
70
69 ~fintud-macrep:dojo> :hood &helm-hi 'hi'
71 ~fintud-macrep:dojo> :hood &helm-hi 'hi'
70
72
73+App usually expect marked data, so `&` is often used here.
74+
71−### `*` - Save in `%clay`
75+#### `*` - Save in `%clay`
76+
77+Save a new `md` file in `web`:
72
78
73 ~fintud-macrep:dojo> *%/web/foo/md '# hello'
79 ~fintud-macrep:dojo> *%/web/foo/md '# hello'
74
80
81+The last component of the path is expected to be the mark (or mime type).
82+
75−### `.` - Download to Unix
83+#### `.` - Download to Unix
76
84
77Download a noun to Unix with `.`:
85Download a noun to Unix with `.`:
78
86
79 ~fintud-macrep:dojo> .foo/bar/baz (add 2 2)
87 ~fintud-macrep:dojo> .foo/bar/baz (add 2 2)
80
88
89+Which creates a file at `pier/.urb/put/foo/bar.baz`.
90+
91+This is very often used with `+solid`:
92+
93+ ~fintud-macrep:dojo> .urbit/pill +solid
94+
95+Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
96+
81### Sources
97### Sources
82
98
83−### `&` - Mark conversion
99+#### `&` - Mark conversion
100+
101+Convert between marks using `&`:
102+
103+ ~fintud-macrep:dojo> &html &md '# hello'
104+ :: produces
105+ '<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
106+
107+#### `_` - Run a function
108+
109+Use `_` to run a gate (or function):
84
110
85−### `_` - Run a function
111+ :: assign an arbitrary function and pass data to it
112+ ~fintud-macrep:dojo> _|=({a/@} (mul a 3)) 3
113+ :: produces
114+ 9
115+ :: assign an arbitrary function to get the status code from an http request
116+ ~fintud-macrep:dojo> _|=({p/@ud q/* r/*} p) +http://google.com
117+ :: produces
118+ 301
86
119
87− _trip &html &md 'foo'
120+#### `+` `-` - HTTP requests
88
121
89−### `+` `-` - HTTP requests
122+`+http[s]://example.com` - sends a GET request
90
123
91− +http://google.com is get
124+`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the JSON `"hi"` in the body.
92− +http://google.com &json (joba %a ~) is post {a:null}
93− -http://localhost:6000/foobar &json (joba %a ~) is put {a:null}
94
125
95− +curl "http://google.com?q={(urle "my params")}"
126+`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the JSON `"hi"` in the body.
96− the trivial generator that sends a get request, the baseline on which you could write a scraper
97
127
98−### `+` - Generators
128+#### `+` - Generators
99
129
100−### `[1 2 +hello 'world']` - Tuples
130+Generators are simple hoon scripts loaded from the filesystem. They live in `gen/`.
101
131
132+Create a random moon (from any planet):
133+
134+ ~fintud-macrep:dojo> +moon
135+ :: produces
136+ "moon: ~docsun-tamtem-fintud-macrep; ticket: ~bartug-hodbyr-fognum-ralmud"
137+
102−<h3 class="first child">Variables</h3>
138+### Variables
103
139
104You can use `=` to set an environment variable in `:dojo`, but there are a few reserved names that have special uses.
140You can use `=` to set an environment variable in `:dojo`, but there are a few reserved names that have special uses.
105
141
@@ -145,7 +181,7 @@ The current (128-bit `@da`) time. Read-only.
145**Example:**
181**Example:**
146
182
147 ~fintud-macrep:dojo> now
183 ~fintud-macrep:dojo> now
148−
184+ :: produces
149 ~2016.3.21..21.10.57..429a
185 ~2016.3.21..21.10.57..429a
150
186
151#### `our`
187#### `our`
@@ -155,7 +191,7 @@ The current urbit plot. Read-only.
155**Example:**
191**Example:**
156
192
157 ~fintud-macrep:dojo> our
193 ~fintud-macrep:dojo> our
158−
194+ :: produces
159 ~fintud-macrep
195 ~fintud-macrep
160
196
161#### `eny`
197#### `eny`
@@ -165,43 +201,63 @@ The current urbit plot. Read-only.
165**Example:**
201**Example:**
166
202
167 ~fintud-macrep:dojo> eny
203 ~fintud-macrep:dojo> eny
168−
204+ :: produces
169 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
205 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
170
206
171−# Generators
207+### Generators
208+
209+**`+cat`** - Similar to Unix `cat`. Accepts a path.
210+
211+ ~fintud-macrep:dojo> +cat %/web/md
212+ ~fintud-macrep:dojo> +cat /~talsur-todres/home/2/web/notes/md
213+
214+**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
215+
216+ ~fintud-macrep:dojo> +curl "http://nyt.com"
217+
218+**`+hello`** - Just prints the argument. Accepts a `@ta`.
219+
220+ ~fintud-macrep:dojo> +hello 'mars'
221+
222+**`+ls`** - Similar to Unix `ls`. Accepts a path.
223+
224+ ~fintud-macrep:dojo> +ls %/web
225+ ~fintud-macrep:dojo> +ls /~talsur-todres/home/2/web/notes
172
226
173−#### `+cat`
227+**`+moon`** - Generate a random moon from a planet. No arguments.
174
228
175−#### `+curl` / `+curl-hiss`
229+**`+solid`** - Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments.
230+
231+ ~fintud-macrep:dojo> .urbit/pill +solid
176
232
177−#### `+hello`
233+**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`).
178
234
179−#### `+ls`
235+ ~fintud-macrep:dojo> +ticket ~talsur-todres-fintud-macrep
180
236
181−#### `+moon`
237+**`+tree`** - Generate a recursive directory listing. Takes a path.
182
238
183−#### `+pope`
239+ ~fintud-macrep:dojo> +tree %/web
184
240
185−#### `+solid`
241+### Hood
186
242
187−#### `+ticket`
243+The hood is the system daemon. See `gen/hood` and `app/hood`.
188
244
189−#### `+tree`
245+**`|hi`** - Sends a direct message. Sort of like `finger`. Accepts an urbit name (`@p`) and a string (`cord`).
190
246
191−# Hood
247+ ~fintud-macrep:dojo> |hi ~doznec 'you there?'
192
248
193−`|hi`
249+**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an Urbit name and an app name.
194
250
195−`|ask`
251+ ~fintud-macrep:dojo> |link ~talsur-todres %octo
196
252
197−`|begin`
253+**`|mass`** - Prints the current memory usage of all the kernel modules. No arguments.
198
254
199−`|link` / `|unlink`
255+**`|reload`** - Reloads a kernel module (vane) from source. Accepts any number of vane names.
200
256
201−`|mass`
257+ ~fintud-macrep:dojo> |reload %clay %eyre
202
258
203−`|reload`
259+**`|reset`** - Reloads `hoon.hoon`. No arguments.
204
260
205−`|reset`
261+**`|start`** - Starts an app. Accepts an app name.
206
262
207−`|start`
263+ ~fintud-macrep:dojo> |start %curl