@@ -0,0 +1,257 @@
2+title = "Imports / ('fas')"
7+Fas (`/`) runes are not technically hoon runes, but instead are instructions to
8+Arvo's build system. In the past, the build system was its own vane called
9+[Ford](/docs/arvo/ford/ford). Ford has since been merged into the filesystem
10+vane [Clay](/docs/arvo/clay/clay), but these are still referred to as "Ford
13+Ford runes are used at the top of a hoon file, and they typically specify
18+Import structure libraries from `/sur`.
26+Note there is only a single space between each item.
30+Names correspond to files in the `/sur` directory of the same desk as this file, e.g.
31+`/sur/foo.hoon` for `foo`. Names containing hyphens, e.g. `foo-abc`, will first
32+resolve to `/sur/foo-abc.hoon`, and if that doesn't exist, it will try
35+Imports may be given a different face by doing `xyz=foo`. Imports may have their
36+face stripped (so you can directly reference their wings) with `*foo`.
42+Import libraries from `/lib`.
50+Note there is only a single space between each item.
54+Names correspond to files in the `/lib` directory of the same desk as this file,
55+e.g. `/lib/foo.hoon` for `foo`. Names containing hyphens, e.g. `foo-abc`, will
56+first resolve to `/lib/foo-abc.hoon`, and if that doesn't exist, it will try
59+Imports may be given a different face by doing `xyz=foo`. Imports may have their
60+face stripped (so you can directly reference their wings) with `*foo`.
66+Build and import a hoon file at the specified path.
73+/= some-face /path/to/file
78+This lets you build and import a hoon file from anywhere in the desk.
80+The first argument is the face to pin it as. The second argument is the path to
81+the file in the same desk as this file. The file must be a `%hoon` file, and the
82+trailing mark (`hoon`) must be omitted from the path.
86+To build and import `/foo/bar.hoon` you would do:
96+Import the file at the specified path as the specified mark.
103+/* some-face %as-mark /path/to/file
108+The first argument is the face to pin it as. The second argument is the mark it
109+should be converted to. The third argument is the path to the file in the same
110+desk as this file, with the trailing mark included.
112+The mark specified may be different to the mark of the file, as long as
113+conversion is possible. Note that a `%hoon` file will not be built like with
114+`/=`: the type of a `%hoon` file is a `@t` so that is what will be pinned.
118+To import `/foo/bar.hoon` you would do:
121+/* foobar %hoon /foo/bar/hoon
124+`foobar` would then be an `@t` of the contents of that file.
130+Import mark conversion gate.
137+/$ some-face %from-mark %to-mark
142+The first argument is the face to pin it as. The second argument is the mark to
143+convert _from_. The third argument is the mark to convert _to_.
145+The result will be a gate of `$-(type-1 type-2)`, pinned with the specified
146+face. The types are the data types of the _from_ mark and _to_ mark,
149+The mark conversion gate will be built from marks in `/mar` on the same desk as
154+To build a mark conversion gate from `%txt` to `%mime`, you would do:
157+/$ txt-to-mime %txt %mime
160+`txt-to-mime` would be a gate of `$-(wain mime)`. You could then call the gate
164+> (txt-to-mime ~['first line' 'second line'])
165+[p=/text/plain q=[p=22 q=37.949.953.370.267.411.298.483.129.707.945.775.026.849.432.323.909.990]]
172+Import, build, evaluate and pin the results of many hoon files in a directory.
179+/~ some-face some-type /some/directory
184+The first argument is the face to pin the results with. The second argument is
185+the type each hoon file produces when evaluated. The third argument is the path
186+to a directory in the same desk as this file, containing `%hoon` files.
188+Each hoon file in the specified directory will be built and evalutated. The
189+result of evaluating each file will be added to a
190+[`++map`](/docs/hoon/reference/stdlib/2o#map) and pinned with the specified face
191+(`some-face`). The keys of the map will be the name of each file, and the values
192+of the map will be the result of evaluating each file and casting its result to
193+the type specified (`some-type`).
195+All of the hoon files in the specified directory, when evaluated, must produce
196+data of a type that nests under the type specified (`some-type`). File with a
197+mark other than `%hoon` will be ignored.
199+The type of the map will be `(map knot some-type)`.
203+If the `/foo/bar` directory contains three files:
205+- `x.hoon` containing `(silt ~[1 2 3 4 5])`
206+- `y.hoon` containing `(silt ~[99 100])`
207+- `z.hoon` containing `(silt ~[22 33 44])`
209+Then the following `/~` expression:
212+/~ foo (set @ud) /foo/bar
215+...will pin a `(map knot (set @ud))` with a face of `foo` which contains:
218+{[p=~.y q={100 99}] [p=~.z q={22 33 44}] [p=~.x q={5 1 2 3 4}]}
225+Build and import a mark core.
232+/% some-face %some-mark
237+The first argument is a face to pin the mark core with. The second argument is a
240+The static mark core (a `nave:clay`) for the specified mark (which resides in
241+the same desk as the file) is built and pinned to the subject with the specified
246+To build the mark core for the `%txt` mark:
252+Its arms can then be accessed like: