@@ -0,0 +1,83 @@
1+# `%ford` user manual
2+
3+## ford runes
4+
5+One of the most common ways to use ford is through ford's runes, all of which begin with `/` ("fas"). A ford rune runs a step of a ford build and places the result in the subject. There are various kinds of build steps, some of which take other build steps as parameters. The most common pattern is to have a sequence of ford runes at the top of a hoon source file that import the results of evaluating other hoon files. This is how we "import a library" in urbit: we add the result of compiling another hoon file into the current subject, possibly renaming it by wrapping a face around it.
6+
7+Another common use case is assembling and rendering markdown templates into a single HTML file, to be sent as an HTTP response in urbit's web server `%eyre`. It's important to keep in mind that %ford is quite flexible and generic, and is used in other parts of urbit -- such as the dojo -- that would not traditionally fall under the auspices of a build system.
8+
9+### `/~` twig by hand
10+
11+`/~ <twig>` produces a horn that evaluates a twig and places the product
12+in the subject. Arbitrary hoon can be in the twig.
13+
14+Example:
15+```
16+/~ [a=0 b=1]
17+[a b]
18+```
19+produces:
20+`[0 1]`
21+
22+### `//` include a file by relative path
23+
24+`// <rel-path>` parses `rel-path` as a hoon twig, and then adds the resulting
25+twig to the subject. It's similar to `#include` in C. Note that the result type
26+of this rune is not a horn, but just a hoon twig, so its result can't be used
27+as an argument to other runes that expect a horn.
28+
29+Example:
30+```
31+// %/file-to-include
32+::
33+(frobnicate:file-to-include |)
34+
35+:: contents of file-to-include.hoon
36+|%
37+++ frobnicate
38+ |= a/? ^+ a
39+ !a
40+--
41+```
42+produces: `%.y`
43+
44+_Note: `%` means current directory, which in a hoon file will resolve to the
45+"directory" containing that file. Also, %clay doesn't have first-class
46+directories the way unix filesystems do. Whereas in unix, a directory is a
47+special kind of file, in %clay it's just a path prefix, and there is no file
48+stored at that path. The meaning of `%` is also contextual: some ford runes can
49+also modify the value of `%` inside their arguments (see the docs for `/_` for
50+an example)._
51+
52+### `/=` wrap a face around an included horn
53+
54+`/=` runs a horn (usually produced by another ford rune), takes the result of
55+that horn, and wraps a face around it.
56+
57+Example:
58+```
59+/= foo /~ [a=0 b=1]
60+[a.foo b.foo]
61+```
62+produces: `[0 1]`
63+
64+### `/_` run a horn on each file in the current directory
65+
66+`/_` takes a horn as an argument. It produces a new horn
67+representing the result of mapping the supplied horn over
68+the list of files in the current directory.
69+
70+Example:
71+```
72+/= kids /_ /~ %
73+`(map term path)`kids
74+```
75+
76+produces a value of type `(map term path)`, where each key is the basename (the
77+filename without the prefix), and each value is the prefix: the path of the
78+"directory" containing that file.
79+
80+_Note that `%` is contextual: it takes on different values based on the
81+"current directory", which can be set by `/_` and other ford runes. For each
82+file in the directory through which `/_` is iterating, `%` becomes the path of
83+that file during that iteration._