git.iko.soy/urbit.org
on master help sign in
Merge branch 'master' of github.com:urbit/docs
3e85a20Galen Wolfe-Pauly
docs/arvo/basic.md+2−2
compare with master
unifiedsplit
@@ -23,8 +23,8 @@ To run this code, you'll need an urbit, and will have to copy the
23[examples repo](https://github.com/urbit/examples) into it.
23[examples repo](https://github.com/urbit/examples) into it.
24
24
25If you haven't installed urbit yet, check out the [installation
25If you haven't installed urbit yet, check out the [installation
26−instructions](/docs/user/install). Once urbit is installed, take a look
26+instructions](/docs/using/install). Once urbit is installed, take a look
27−at the [basic operation](/docs/user/basic) of your urbit.
27+at the [basic operation](/docs/using/admin) of your urbit.
28
28
29If you haven't copied in the examples repo, running the following
29If you haven't copied in the examples repo, running the following
30commands from your urbit directory should do the trick:
30commands from your urbit directory should do the trick:
docs/arvo/generators.md+1−1
@@ -15,7 +15,7 @@ the "plumbing" way to interact with apps. Generators are the
15`|merge`, there are no marks in sight.
15`|merge`, there are no marks in sight.
16
16
17We've used generators before, back in [Basic
17We've used generators before, back in [Basic
18−Operation](/docs/user/basic). At that point, we just used the generators
18+Operation](/docs/using/admin). At that point, we just used the generators
19to produce values -- we didn't pipe their results into apps. In
19to produce values -- we didn't pipe their results into apps. In
20the dojo cast, the role of a generator is to take a list of
20the dojo cast, the role of a generator is to take a list of
21arguments and produce a value, which is often, though not always,
21arguments and produce a value, which is often, though not always,
docs/using/layout.md+1−1
@@ -1,6 +1,6 @@
1---
1---
2navhome: /docs
2navhome: /docs
3−sort: 8
3+sort: 9
4title: Source layout
4title: Source layout
5---
5---
6
6
docs/using/urb.mdnew file+356
@@ -0,0 +1,356 @@
1+---
2+navhome: /docs
3+sort: 8
4+title: From Unix
5+---
6+
7+<div class="row">
8+<div class="col-md-8">
9+
10+# Using Urbit from Unix
11+
12+With `urb` at your Unix command line, you can execute hoon, run
13+dojo commands, and more. Additionally, with `fuse`, you can
14+inspect the urbit namespace.
15+
16+</div>
17+</div>
18+
19+## Installation
20+
21+These commands are in the a [separate
22+repo](https://github.com/urbit/urb). Clone this repo to get the
23+commands.
24+
25+You'll also need the `requests` and `fuse` libraries for python.
26+If you have `pip`, you can just run:
27+
28+```
29+pip install requests fuse-python
30+```
31+
32+Otherwise, on Ubuntu, run:
33+
34+```
35+apt-get install python-requests python-fuse
36+```
37+
38+Then you can either run the python commands from the git repo, or
39+put them somewhere in your path.
40+
41+## `urb`
42+
43+`urb` transfers data from a source to a sink. Examples of data
44+sources include literal data, a file, a URL, or some
45+tranformation of another source. Examples of data sinks are
46+stdout, output file, POST request, or dojo command.
47+
48+Here are some examples. This takes the literal data "hello
49+world" and sends it to stdout (the default sink).
50+
51+ urb --data 'hello world'
52+
53+Let's run some hoon code at the dojo.
54+
55+ urb --dojo '(add 2 2)'
56+
57+Let's convert a markdown file to html.
58+
59+ urb --data @@file.md -m md -m html
60+
61+Mount the `%home` desk. This syncs the `home` desk into the pier
62+directory.
63+
64+ urb --dojo '+hood/mount /=home=' --app hood
65+
66+### Sources
67+
68+Sources can be any of the following:
69+
70+- `-d, --dojo command` runs a dojo command. This is commonly
71+ naked hoon code, but it can also be a generator, or any of the
72+ other ways the dojo gets data.
73+
74+- `-D, --data text` is literal text data, as a cord.
75+
76+- `-c, --clay path` pulls data from Urbit's filesystem.
77+
78+- `-u, --url url` pulls data from a URL.
79+
80+- `-m, --mark mark source` converts the output from another source to
81+ a new 'mark' (datatype).
82+
83+- `-H, --hoon code source` transforms the output of another
84+ source by running it through some hoon code.
85+
86+- `[source-0 source-1 ...]`. Sources can be combined into tuples
87+ of different sources.
88+
89+Any of the arguments to a source (except in the "compound
90+sources" `--mark` and `--hoon`) can be replaced by `-` to
91+represent stdin or `@@filename` to pull data in from a Unix file.
92+Thus, `urb [-D @@file1 -D - -D @@file2]` is equivalent to Unix's
93+`cat file1 - file2`.
94+
95+Additionally, if no source is specified, `--data -` (stdin as
96+literal text data) is assumed.
97+
98+### Sinks
99+
100+- `-s, --stdout` outputs to stdout. This is the default.
101+
102+- `-f, --output-file path` writes to a unix file.
103+
104+- `-C, --output-clay path` writes to Urbit's filesystem.
105+
106+- `-U, --output-url url` sends a POST request with the data to
107+ the URL.
108+
109+- `-p, --app app` sends the data to an urbit app.
110+
111+- `-x, --command` outputs to a literal dojo command.
112+
113+## `fuse`
114+
115+Urbit's namespace is accessible through the `fuse` command.
116+`fuse` takes all the normal FUSE arguments, which you can see
117+with `fuse -h`. Generally, you just run `fuse MOUNT-POINT`.
118+
119+When accessing the namespace through `fuse`, everything is
120+read-only. If you want to write to Clay, mount a desk, as
121+described above.
122+
123+Let's look first in the Clay portion of the Urbit namespace.
124+Assume we've mounted to `./pt`.
125+
126+ $ ls ./pt/c/=/=/=
127+ app arvo gen lib mar ren sec sur web
128+ $ ls ./pt/c/=/=/=/arvo
129+ ames behn clay dill eyre ford gall hoon zuse
130+
131+Those `=`s aren't decorative. The first `=` means "current
132+ship", the second "current desk", and the third "current
133+revision". Let's try something a little more exciting.
134+
135+This runs the Unix `diff` command on the first and current
136+versions of the `app/gh/hoon` file, showing all the changes we've
137+made to the file.
138+
139+```
140+$ diff pt/c/=/=/{1,=}/app/gh/hoon
141+73c73,75
142+< (malt (turn issues |=(issue:gh [(rsh 3 2 (scot %ui number)) ~])))
143+---
144+> %- malt ^- (list {@ta $~})
145+> :- [%gh-list-issues ~]
146+> (turn issues |=(issue:gh [(rsh 3 2 (scot %ui number)) ~]))
147+92c94,101
148+< read-y=(read-get /issues)
149+---
150+> read-y=(read-static %gh-list-issues ~)
151+> sigh-x=sigh-list-issues-x
152+> sigh-y=sigh-list-issues-y
153+> ==
154+> ^- place :: /issues/mine/<mark>
155+> :* guard={$issues $mine @t $~}
156+> read-x=read-null
157+> read-y=|=(pax/path [ost %diff %arch `0vsen.tinel ~])
158+126c135
159+< ^- place :: /issues/by-repo/<user>/<repo>
160+---
161+> ^- place :: /issues/by-repo/<user>/<repo>/<number>
162+131c140,146
163+< read-y=(read-static ~)
164+---
165+> ^= read-y
166+> |= pax/path
167+> %. pax
168+> ?: ((sane %tas) -.+>+>.pax)
169+> (read-static ~)
170+> (read-static %gh-issue ~)
171+> ::
172+137a153,159
173+> sigh-y=sigh-strange
174+> ==
175+> ^- place :: /issues/by-repo/<u>/<r>/<n>/<mark>
176+> :* guard={$issues $by-repo @t @t @t @t $~}
177+> read-x=read-null
178+> read-y=|=(pax/path [ost %diff %arch `0vsen.tinel ~])
179+> sigh-x=sigh-strange
180+```
181+
182+Urbit's namespace is not just revisioned, but global. Here's a
183+diff of our version of `arvo/gall/hoon` compared to the one on
184+the `~bud` urbit.
185+
186+```
187+$ diff pt/c/{~bud,=}/=/=/arvo/gall/hoon
188+2d1
189+<
190+640a640,644
191+> =+ ?. ?=($x ren)
192+> [mar=%$ tyl=tyl]
193+> =+ `path`(flop tyl)
194+> ?> ?=(^ -)
195+> [mar=i tyl=(flop t)]
196+643c647
197+< ((slog leaf+"peek find fail" >tyl< ~) [~ ~])
198+---
199+> ((slog leaf+"peek find fail" >tyl< >mar< ~) [~ ~])
200+654a659,660
201+> ?. =(mar p.q.caz)
202+> [~ ~]
203+1308a1315,1316
204+> ?. ?=(^ tyl)
205+> ~
206+```
207+
208+Besides Clay, the namespace contains Gall apps. One common usage
209+of the app namespace is to expose APIs. For example, if you
210+start the `%gh` app (`|start %gh`), you can do things like `cat`
211+an issue from a repository.
212+
213+```
214+$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/7/txt
215+title: big news! (#7)
216+state: open
217+creator: philipcmonktest
218+created-at: 2016-03-24T22:27:33Z
219+assignee: philipcmonktest
220+labels: invalid, wontfix, help wanted
221+comments: 0
222+url: https://api.github.com/repos/philipcmonktest/testing/issues/7
223+
224+Yup, that's it. i mean, maybe it's a bit longer than that.
225+
226+But you get the point, right?
227+
228+Code `is` cool!
229+```
230+
231+Or all open issues for a repository.
232+
233+```
234+$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/txt
235+title: i found a bug! (#11)
236+state: open
237+creator: philipcmonktest
238+created-at: 2016-04-14T23:14:49Z
239+assignee: none
240+labels:
241+comments: 1
242+url: https://api.github.com/repos/philipcmonktest/testing/issues/11
243+
244+
245+----------------------------------------
246+title: more newz (#8)
247+state: open
248+creator: philipcmonktest
249+created-at: 2016-03-24T22:29:16Z
250+assignee: none
251+labels:
252+comments: 4
253+url: https://api.github.com/repos/philipcmonktest/testing/issues/8
254+
255+Yup, that's it. i mean, maybe it's a bit longer than that.
256+
257+But you get the point, right?
258+
259+Code `is` cool!
260+----------------------------------------
261+title: big news! (#7)
262+state: open
263+creator: philipcmonktest
264+created-at: 2016-03-24T22:27:33Z
265+assignee: philipcmonktest
266+labels: invalid, wontfix, help wanted
267+comments: 0
268+url: https://api.github.com/repos/philipcmonktest/testing/issues/7
269+
270+Yup, that's it. i mean, maybe it's a bit longer than that.
271+
272+But you get the point, right?
273+
274+Code `is` cool!
275+----------------------------------------
276+title: something different (#4)
277+state: open
278+creator: philipcmonktest
279+created-at: 2016-01-26T21:45:08Z
280+assignee: philipcmonktest
281+labels: duplicate, help wanted, question, bug
282+comments: 1
283+url: https://api.github.com/repos/philipcmonktest/testing/issues/4
284+```
285+
286+Don't like the textual format? How about we get the raw JSON
287+(and prettyprint it).
288+
289+```
290+$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/7/json | python -m json.tool
291+{
292+ "assignee": {
293+ "avatar_url": "https://avatars.githubusercontent.com/u/16787461?v=3",
294+ "events_url": "https://api.github.com/users/philipcmonktest/events{/privacy}",
295+ "followers_url": "https://api.github.com/users/philipcmonktest/followers",
296+ "following_url": "https://api.github.com/users/philipcmonktest/following{/other_user}",
297+ "gists_url": "https://api.github.com/users/philipcmonktest/gists{/gist_id}",
298+ "gravatar_id": "",
299+ "html_url": "https://github.com/philipcmonktest",
300+ "id": 16787461,
301+ "login": "philipcmonktest",
302+ "organizations_url": "https://api.github.com/users/philipcmonktest/orgs",
303+ "received_events_url": "https://api.github.com/users/philipcmonktest/received_events",
304+ "repos_url": "https://api.github.com/users/philipcmonktest/repos",
305+ "site_admin": false,
306+ "starred_url": "https://api.github.com/users/philipcmonktest/starred{/owner}{/repo}",
307+ "subscriptions_url": "https://api.github.com/users/philipcmonktest/subscriptions",
308+ "type": "User",
309+ "url": "https://api.github.com/users/philipcmonktest"
310+ },
311+ "body": "Yup, that's it. i mean, maybe it's a bit longer than that.\r\n\r\nBut you get the point, right?\r\n\r\nCode `is` cool!",
312+ "closed_at": null,
313+ "closed_by": null,
314+ "comments": 0,
315+ "comments_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/comments",
316+ "created_at": "2016-03-24T22:27:33Z",
317+ "events_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/events",
318+ "html_url": "https://github.com/philipcmonktest/testing/issues/7",
319+ "id": 143377108,
320+ "labels": [
321+ {
322+ "color": "ffffff",
323+ "name": "wontfix",
324+ "url": "https://api.github.com/repos/philipcmonktest/testing/labels/wontfix"
325+ }
326+ ],
327+ "labels_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/labels{/name}",
328+ "locked": false,
329+ "milestone": null,
330+ "number": 7,
331+ "repository_url": "https://api.github.com/repos/philipcmonktest/testing",
332+ "state": "open",
333+ "title": "big news!",
334+ "updated_at": "2016-03-24T22:27:33Z",
335+ "url": "https://api.github.com/repos/philipcmonktest/testing/issues/7",
336+ "user": {
337+ "avatar_url": "https://avatars.githubusercontent.com/u/16787461?v=3",
338+ "events_url": "https://api.github.com/users/philipcmonktest/events{/privacy}",
339+ "followers_url": "https://api.github.com/users/philipcmonktest/followers",
340+ "following_url": "https://api.github.com/users/philipcmonktest/following{/other_user}",
341+ "gists_url": "https://api.github.com/users/philipcmonktest/gists{/gist_id}",
342+ "gravatar_id": "",
343+ "html_url": "https://github.com/philipcmonktest",
344+ "id": 16787461,
345+ "login": "philipcmonktest",
346+ "organizations_url": "https://api.github.com/users/philipcmonktest/orgs",
347+ "received_events_url": "https://api.github.com/users/philipcmonktest/received_events",
348+ "repos_url": "https://api.github.com/users/philipcmonktest/repos",
349+ "site_admin": false,
350+ "starred_url": "https://api.github.com/users/philipcmonktest/starred{/owner}{/repo}",
351+ "subscriptions_url": "https://api.github.com/users/philipcmonktest/subscriptions",
352+ "type": "User",
353+ "url": "https://api.github.com/users/philipcmonktest"
354+ }
355+}
356+```