git.iko.soy/urbit.org
on master help sign in
Merge pull request #41 from asgardiator/master
7440e08Galen Wolfe-Pauly
docs/about/contributing.mdnew file+38
compare with master
unifiedsplit
@@ -0,0 +1,38 @@
1+---
2+navhome: '/docs'
3+next: True
4+sort: 4
5+title: Contributing to Urbit
6+---
7+
8+# Contributing to Urbit
9+
10+It's always a good day for pull requests! We gladly accept submissions
11+for improving our [code](https://github.com/urbit/urbit/) and
12+[documentation](https://github.com/urbit/docs/) alike.
13+
14+## Code guidelines
15+
16+Our official guide to contributing can be found
17+[here](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md),
18+which is most useful for large and low-level changes. For simpler
19+revisions, refer to [Hoon Syntax](/hoon/syntax) for an in-depth guide to
20+good Hoon. Alternatively, [browse the
21+source](https://github.com/urbit/arvo/blob/master/arvo/hoon.hoon).
22+
23+## Docs guidelines
24+
25+For documentation pull requests, acquire [pandoc](http://pandoc.org) and
26+format your edited files with the following flags:
27+
28+ $ pandoc --standalone \
29+ --from=markdown+yaml_metadata_block \
30+ --atx-headers \
31+ -o output.md \
32+ input.md
33+
34+**Note:** Pandoc will convert the terminating `---` in YAML metadata to
35+`...`, which is grounds for termination. Run the following one-liner to
36+atone.
37+
38+ $ sed '1,/^$/ s/^\.\.\./---/g' input.md > output.md
docs/arvo/basic.md+8−6
@@ -157,13 +157,13 @@ Instead of:
157
157
158You can write:
158You can write:
159
159
160− if(=(1 2) 'this is true' 'this is false')
160+ :if(=(1 2) 'this is true' 'this is false')
161 'this is false'
161 'this is false'
162
162
163### Lines 12-34
163### Lines 12-34
164
164
165Now let's quickly walk through this code line-by-line. Lines 12-34 are
165Now let's quickly walk through this code line-by-line. Lines 12-34 are
166−wrapped in a `|%` ('barcen'), which produces a core. Cores are a
166+wrapped in a `|%` ('[barcen](/hoon/twig/bar-core/cen-core/)'), which produces a core. Cores are a
167fundamental datatype in Hoon, similar to a struct, class, or object. A
167fundamental datatype in Hoon, similar to a struct, class, or object. A
168core is just a map of names to any kind of code, whether it be functions
168core is just a map of names to any kind of code, whether it be functions
169or data. Each element in this map begins with a `++` followed by the
169or data. Each element in this map begins with a `++` followed by the
@@ -182,7 +182,7 @@ Let's step into each of the three arms within our core.
182 (add (five a) (three a))
182 (add (five a) (three a))
183 --
183 --
184
184
185−`|=` ('bartis') produces a function, much like a lambda in lisp. It
185+`|=` ('[bartis](/hoon/twig/bar-core/tis-gate/)') produces a function, much like a lambda in lisp. It
186takes two children:
186takes two children:
187
187
1881. A set of argument(s). In this case our argument set only contains
1881. A set of argument(s). In this case our argument set only contains
@@ -207,7 +207,7 @@ takes two children:
207As above, `++three` takes an integer argument, `a`, and then executes
207As above, `++three` takes an integer argument, `a`, and then executes
208the remainder of the code with `a` set to the actual arguments.
208the remainder of the code with `a` set to the actual arguments.
209
209
210−Similarly, `=|` ('tisbar') pushes its first child, `b` into our context
210+Similarly, `=|` ('[tisbar](/hoon/twig/tis-flow/bar-new/)') pushes its first child, `b` into our context
211(in other words, it declares a variable `b`) and executes the remainder
211(in other words, it declares a variable `b`) and executes the remainder
212of the code. However, `b` is not an argument; `=|` sets `b` to the
212of the code. However, `b` is not an argument; `=|` sets `b` to the
213default value of whatever type it is declared as. Since the default
213default value of whatever type it is declared as. Since the default
@@ -225,10 +225,10 @@ value of an atom is `0`, b is set to `0`.
225So now we have two variables: `a` is set to our input, and `b` is
225So now we have two variables: `a` is set to our input, and `b` is
226initialized to `0`.
226initialized to `0`.
227
227
228−One way to think about `|-` ('barhep') is that it lays down a recursion
228+One way to think about `|-` ('[barhep](/hoon/twig/bar-core/hep-loop/)') is that it lays down a recursion
229point. More on this later.
229point. More on this later.
230
230
231−`^-` ('kethep') is just a cast that sets the result of the remainder of
231+`^-` ('[kethep](/hoon/core/ket-cast/hep-cast/)') is just a cast that sets the result of the remainder of
232the code to an unsigned integer, `@u`.
232the code to an unsigned integer, `@u`.
233
233
234In pseudocode, the last three lines read like this: if `a` is less than
234In pseudocode, the last three lines read like this: if `a` is less than
@@ -272,6 +272,8 @@ our cheatsheat at the bottom.
272 =(a b) test equality
272 =(a b) test equality
273 (function args ...) call function with args
273 (function args ...) call function with args
274
274
275+Lookup each of these expressions (and all others!) in the [Twig Expressions](/hoon/twig/) definition.
276+
275### New material
277### New material
276
278
2771. There are two syntaxes for writing Hoon: tallform and wideform.
2791. There are two syntaxes for writing Hoon: tallform and wideform.
docs/arvo/marks.md+5−3
@@ -5,6 +5,8 @@ sort: 6
5title: Marks
5title: Marks
6---
6---
7
7
8+# Marks
9+
8We've used predefined marks already, but we haven't yet created
10We've used predefined marks already, but we haven't yet created
9our own marks. Let's write a sample mark of our own, then chain
11our own marks. Let's write a sample mark of our own, then chain
10it together with some preexisting ones to have fun with type
12it together with some preexisting ones to have fun with type
@@ -28,14 +30,14 @@ text, but there's no predefined mark for it. Let's put the following code in:
28--
30--
29```
31```
30
32
31−Let's go through this line by line. `/? 314` is the required
33+`/? 314` is the required
32version number, just like in apps. After that everything's in a
34version number, just like in apps. After that everything's in a
33`|_`, which is a `|%` core, but with input arguments. In our
35`|_`, which is a `|%` core, but with input arguments. In our
34case, the argument is the marked data.
36case, the argument is the marked data.
35
37
36There are three possible top-level arms in the `|_` core,
38There are three possible top-level arms in the `|_` core,
37−`++grab`, `++grow`, and `++grad`. `++grad` is used for revision
39+`++grab`, `++grow`, and `++grad` (which is used for revision
38−controlv (it contains diff/patch logic), and is covered elsewhere. `++grab` specifies
40+control, covered elsewhere). `++grab` specifies
39functions to convert from another mark to the current mark.
41functions to convert from another mark to the current mark.
40`++grow` specifies how to convert from the current mark to
42`++grow` specifies how to convert from the current mark to
41another one.
43another one.
docs/arvo/web-apps.md+13−17
@@ -72,18 +72,16 @@ asserting the parsing succeeded with `need`, and asserting the
72result was 'click' with `?>`, which asserts that its first child
72result was 'click' with `?>`, which asserts that its first child
73is true.
73is true.
74
74
75−<blockquote class="blockquote">
76−Note the argument to `++json`is `jon/^json`. Why `^json`?
75+> Note the argument to `++json`is `jon/^json`. Why `^json`?
77−`++json` shadows the type definition, so if we want to refer to
76+> `++json` shadows the type definition, so if we want to refer to
78−the type, we have to prepend a `^`. This extends to multiple
77+> the type, we have to prepend a `^`. This extends to multiple
79−levels: `^^^foo` means the fourth most innermost instance of `foo`.
78+> levels: `^^^foo` means the fourth most innermost instance of `foo`.
80−
79+
81−`++jo` in `zuse` is a useful library for parsing complex json
80+> `++jo` in `zuse` is a useful library for parsing complex json
82−into hoon structures. In this case, the `:` between `so` and
81+> into hoon structures. In this case, the `:` between `so` and
83−`jo` means 'inside of', because `so` is an arm contained within
82+> `jo` means 'inside of', because `so` is an arm contained within
84−the core `jo`. Our case is actually simple enough that the
83+> the core `jo`. Our case is actually simple enough that the
85−`?>` line could have been `?> =([%s 'click'] jon)`.
84+> `?>` line could have been `?> =([%s 'click'] jon)`.
86−</blockquote>
87
85
88We can test this mark from the command line (don't forget to start your app with `|start %click`)
86We can test this mark from the command line (don't forget to start your app with `|start %click`)
89
87
@@ -115,11 +113,9 @@ And `/mar/clicks.hoon`:
115`clicks` is just an atom. We convert to json by creating an
113`clicks` is just an atom. We convert to json by creating an
116object with a single field "clicks" with our value.
114object with a single field "clicks" with our value.
117
115
118−<blockquote class="blockquote">
119−Be sure to checkout section 3bD, JSON and XML, in zuse.hoon
116+> Be sure to checkout section 3bD, JSON and XML, in zuse.hoon
120−`++joba` is just a function that takes a key-value pair and
117+> `++joba` is just a function that takes a key-value pair and
121−produces a JSON object with one element.
118+> produces a JSON object with one element.
122−</blockquote>
123
119
124```
120```
125~fintud-macrep:dojo> &json &clicks 6
121~fintud-macrep:dojo> &json &clicks 6
docs/hoon/twig/buc-mold/hep-lamb.md+1−1
@@ -4,7 +4,7 @@ sort: 8
4
4
5---
5---
6
6
7−# `:lamb $-, "buchep"`
7+# `:lamb $- "buchep"`
8
8
9`{$lamb p/moss q/moss}`: mold which normalizes to an example gate.
9`{$lamb p/moss q/moss}`: mold which normalizes to an example gate.
10
10