@@ -0,0 +1,257 @@
1++++
2+title = "Imports / ('fas')"
3+weight = 15
4+template = "doc.html"
5++++
6+
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
11+runes".
12+
13+Ford runes are used at the top of a hoon file, and they typically specify
14+imports.
15+
16+## `/-` "fashep"
17+
18+Import structure libraries from `/sur`.
19+
20+#### Syntax
21+
22+```hoon
23+/- foo, bar, baz
24+```
25+
26+Note there is only a single space between each item.
27+
28+#### Semantics
29+
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
33+`/sur/foo/abc.hoon`.
34+
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`.
37+
38+---
39+
40+## `/+` "faslus"
41+
42+Import libraries from `/lib`.
43+
44+#### Syntax
45+
46+```hoon
47+/+ foo, bar, baz
48+```
49+
50+Note there is only a single space between each item.
51+
52+#### Semantics
53+
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
57+`/lib/foo/abc.hoon`.
58+
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`.
61+
62+---
63+
64+## `/=` "fastis"
65+
66+Build and import a hoon file at the specified path.
67+
68+#### Syntax
69+
70+Two arguments.
71+
72+```hoon
73+/= some-face /path/to/file
74+```
75+
76+#### Semantics
77+
78+This lets you build and import a hoon file from anywhere in the desk.
79+
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.
83+
84+#### Examples
85+
86+To build and import `/foo/bar.hoon` you would do:
87+
88+```hoon
89+/= foobar /foo/bar
90+```
91+
92+---
93+
94+## `/*` "fastar"
95+
96+Import the file at the specified path as the specified mark.
97+
98+#### Syntax
99+
100+Three arguments.
101+
102+```hoon
103+/* some-face %as-mark /path/to/file
104+```
105+
106+#### Semantics
107+
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.
111+
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.
115+
116+#### Examples
117+
118+To import `/foo/bar.hoon` you would do:
119+
120+```hoon
121+/* foobar %hoon /foo/bar/hoon
122+```
123+
124+`foobar` would then be an `@t` of the contents of that file.
125+
126+---
127+
128+## `/$` "fasbuc"
129+
130+Import mark conversion gate.
131+
132+#### Syntax
133+
134+Three arguments.
135+
136+```hoon
137+/$ some-face %from-mark %to-mark
138+```
139+
140+#### Semantics
141+
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_.
144+
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,
147+respectively.
148+
149+The mark conversion gate will be built from marks in `/mar` on the same desk as
150+this file.
151+
152+#### Examples
153+
154+To build a mark conversion gate from `%txt` to `%mime`, you would do:
155+
156+```hoon
157+/$ txt-to-mime %txt %mime
158+```
159+
160+`txt-to-mime` would be a gate of `$-(wain mime)`. You could then call the gate
161+like:
162+
163+```
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]]
166+```
167+
168+---
169+
170+## `/~` "fassig"
171+
172+Import, build, evaluate and pin the results of many hoon files in a directory.
173+
174+#### Syntax
175+
176+Three arguments.
177+
178+```hoon
179+/~ some-face some-type /some/directory
180+```
181+
182+#### Semantics
183+
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.
187+
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`).
194+
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.
198+
199+The type of the map will be `(map knot some-type)`.
200+
201+#### Examples
202+
203+If the `/foo/bar` directory contains three files:
204+
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])`
208+
209+Then the following `/~` expression:
210+
211+```hoon
212+/~ foo (set @ud) /foo/bar
213+```
214+
215+...will pin a `(map knot (set @ud))` with a face of `foo` which contains:
216+
217+```
218+{[p=~.y q={100 99}] [p=~.z q={22 33 44}] [p=~.x q={5 1 2 3 4}]}
219+```
220+
221+---
222+
223+## `/%` "fascen"
224+
225+Build and import a mark core.
226+
227+#### Syntax
228+
229+Two arguments.
230+
231+```hoon
232+/% some-face %some-mark
233+```
234+
235+#### Semantics
236+
237+The first argument is a face to pin the mark core with. The second argument is a
238+mark.
239+
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
242+face.
243+
244+#### Examples
245+
246+To build the mark core for the `%txt` mark:
247+
248+```hoon
249+/% foo %txt
250+```
251+
252+Its arms can then be accessed like:
253+
254+```
255+> form:foo
256+%txt-diff
257+```