@@ -1,566 +1,9 @@
11+++
2−title = "Ford"
2+title = "Ford Fusion"
33weight = 7
44template = "doc.html"
55aliases = ["/docs/learn/arvo/ford/"]
66+++
7−Our typed and marked computation engine.
87
9−A variety of different services are provided by `%ford`, but they mostly
10−involve compiling hook files, slapping/slamming code with marked data,
11−and converting data between marks, including validating data to a mark.
12−Throughout every computation, `%ford` keeps track of which resources are
13−dependencies so that the client may be aware when one or more
14−dependencies are updated.
15−
16−`%ford` neither accepts unix events nor produces effects. It exists
17−entirely for the benefit of applications and other vanes, in particular
18−`%gall`. `%eyre` exposes the functional publishing aspects of `%ford`
19−while `%gall` uses `%ford` to control the execution of applications.
20−`%clay` is intended to use `%ford` to managed marked data, but this is
21−not yet reality.
22−
23−## Cards
24−
25−`%ford` accepts just one card, `%exec`. This is misleading, however,
26−since there are fourteen different `silk`s that may be used with it. In
27−every case, the expected response to a `%exec` card is a `%made` gift
28−with either an error or the produced result along with its set of
29−dependencies.
30−
31−Silks may autocons, so that the product of a cell of silks is a cell of
32−the product of the two silks.
33−
34−### `%bake`
35−
36−Tries to functionally produce the file at a given beam with the given
37−mark and heel. It fails if there is no way to translate at this level.
38−
39−### `%boil`
40−
41−Functionally produces the file at a given beam with the given mark and
42−heel. If there is no way to translate at this beam, we pop levels off
43−the stack and attempt to bake there until we find a level we can bake.
44−This should almost always be called instead of `%bake`.
45−
46−### `%call`
47−
48−Slams the result of one silk against the result of another.
49−
50−### `%cast`
51−
52−Translates the given silk to the given mark, if possible. This is one of
53−the critical and fundamental operations of ford.
54−
55−### `%diff`
56−
57−Diffs the two given silks (which must be of the same mark), producing a
58−cage of the mark specified in `++mark` in `++grad` for the mark of the
59−two silks.
60−
61−### `%done`
62−
63−Produces exactly its input. This is rarely used on its own, but many
64−silks are recursively defined in terms of other silks, so we often need
65−a silk that simply produces its input. A monadic return, if you will.
66−
67−### `%dude`
68−
69−Computes the given silk with the given tank as part of the stack trace
70−if there is an error.
71−
72−### `%dune`
73−
74−Produces an error if the cage is empty. Otherwise, it produces the value
75−in the unit.
76−
77−### `%mute`
78−
79−Takes a silk and a list of changes to make to the silk. At each wing in
80−the list we put the value of the associated silk.
81−
82−### `%pact`
83−
84−Applies the second silk as a patch to the first silk. The second silk
85−must be of the mark specified in `++mark` in `++grad` for the mark of
86−the first silk.
87−
88−### `%plan`
89−
90−Performs a structured assembly directly. This is not generally directly
91−useful because several other silks perform supersets of this
92−functionality. We don't usually have naked hoods outside ford.
93−
94−### `%reef`
95−
96−Produces a [core](/docs/glossary/core/) containing the entirety of Zuse and Hoon, suitable for
97−running arbitrary code against. The mark is `%noun`.
98−
99−### `%ride`
100−
101−Slaps a hoon against a subject silk. The mark of the result is `%noun`.
102−
103−### `%vale`
104−
105−Validates untyped data from a ship against a given mark. This is an
106−extremely useful function.
107−
108−## Ford runes
109−
110−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.
111−
112−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 purview of a build system.
113−
114−### `/+` "faslus"
115−
116−The `/+` rune accepts a filename as an argument. It interprets that filename
117−as a hoon source file within the `lib` directory. This is how we import a shared
118−library in urbit.
119−
120−To run this example, put this code in your desk at `gen/faslus.hoon` and run
121−`+faslus` in your dojo. This example is a generator. For more information on
122−generators, see the [generator docs](@/docs/tutorials/hoon/generators.md).
123−
124−```hoon
125−/+ time-to-id
126−::
127−:- %say
128−|= {{now/@da * *} $~ $~}
129−:- %noun
130−(time-to-id now)
131−```
132−
133−produces: `"c.314d"` (or something similar depending on when you run it)
134−
135−You can import multiple libraries with a single `/+` rune by separating them
136−with commas.
137−
138−Replace the code in `gen/faslus.hoon` with the following:
139−
140−```hoon
141−/+ time-to-id, hep-to-cab
142−::
143−:- %say
144−|= {{now/@da * *} $~ $~}
145−:- %noun
146−=/ id (time-to-id now)
147−=/ str "my-id-is-{id}"
148−(hep-to-cab (crip str))
149−```
150−
151−This should print something like `my_id_is_c.3588`.
152−
153−Another feature of the
154−`/+` and `/-` runes is the ability to specify the ship and case from which to
155−load the library.
156−
157−Example:
158−
159−```
160−/+ time-to-id, hep-to-cab/4/~zod
161−```
162−
163−will load the `hep-to-cab` library from `~zod` at `%clay` revision `4`.
164−
165−### `/-` "fashep"
166−
167−The `/-` rune accepts a filename as an argument. It interprets that filename as
168−a hoon source file within the `sur` directory. The `sur` directory contains
169−shared structures that can be used by other parts of urbit. This is somewhat
170−similar to including a header file in C.
171−
172−Example:
173−
174−```hoon
175−/- talk
176−::
177−*serial:talk
178−```
179−
180−produces: `0v0`
181−
182−`/-` can also take multiple files as arguments, and the ship and case of those
183−arguments can be specified. See the `/+` docs for more details about the syntax
184−for those features.
185−
186−### `/~` "fassig"
187−
188−`/~ <twig>` produces a "horn" that evaluates a twig and places the product in
189−the subject. Arbitrary hoon can be in the twig. A
190−horn is a data
191−structure representing a `%ford` static resource.
192−
193−Example:
194−
195−```hoon
196−/~ [a=0 b=1]
197−[a b]
198−```
199−
200−produces: `[0 1]`
201−
202−In wide-form, `/~` always takes a tuple (which may be a degenerate tuple of one element), and produces it.
203−
204−Example:
205−```hoon
206−/~[%something]
207−```
208−produces: `%something`
209−
210−```hoon
211−/~[%a %b]
212−```
213−produces: `[%a %b]`
214−
215−### `//` "fasfas"
216−
217−`// <rel-path>` parses `rel-path` as a hoon twig, and then adds the resulting
218−twig to the subject. Note that the result type of this rune is not a horn, but
219−just a hoon twig, so its result can't be used as an argument to other runes
220−that expect a horn. There is no wide-form for this rune.
221−
222−Example:
223−```hoon
224−// %/file-to-include
225−::
226−(frobnicate:file-to-include %.n)
227−
228−:: contents of file-to-include.hoon
229−|%
230−++ frobnicate
231− |= a/? ^+ a
232− !a
233−--
234−```
235−produces: `%.y`
236−
237−_Note: `%` means current directory, which in a hoon file will resolve to the
238−"directory" containing that file. Also, %clay doesn't have first-class
239−directories the way unix filesystems do. Whereas in unix, a directory is a
240−special kind of file, in %clay it's just a path prefix, and there is no file
241−stored at that path._
242−
243−### `/=` "fastis"
244−
245−`/=` runs a horn (usually produced by another ford rune), takes the result of
246−that horn, and wraps a face around it.
247−
248−Example:
249−```hoon
250−/= foo /~ [a=0 b=1]
251−::
252−[a.foo b.foo]
253−```
254−produces: `[0 1]`
255−
256−In wide-form, `/=` uses `=` as a delimiter: `/=foo=/~[a=0 b=1]`
257−
258−### `/:` "fascol"
259−
260−`/:` takes a path and a horn, and evaluates the horn with the current path set to the supplied path.
261−`/mar/` renders the mark 'mar' at the current path.
262−
263−Example:
264−```hoon
265−/= hoo-source /: /path/to/hoon-file /hoon/
266−::
267−`@t`hoo-source
268−```
269−
270−produces the text of the hoon file at "/path/to/hoon-file/hoon".
271−
272−`/hoon/` renders the current path using the `%hoon` mark, which in this case
273−passes the contents through unchanged. In general, rendering a file with a
274−mark will potentially run the contents through a series of conversion
275−operations. For details on marks, see the
276−[Gall docs](gall).
277−
278−Here's an example that includes a mark conversion:
279−```hoon
280−/= page /: /path/to/html/file /mime/
281−::
282−page
283−
284−:: contents of /path/to/html/file:
285−<html><head><title>My Fascinating Blog</title></head></html>
286−```
287−produces:
288−`[[%text %html ~] 60 '<html><head><title>My Fascinating Blog</title></head></html>']`
289−
290−This result includes the MIME type ('text/html'), the content length in bytes,
291−and the HTML itself.
292−
293−In wide-form, `/:` uses `:` as a delimiter: `/=page=/:/path/to/html/file:/mime/`
294−
295−### `/!mark/` "faszap"
296−
297−Example:
298−```hoon
299−/= mime /: /%/some-hoon-file /!mime/
300−::
301−mime
302−
303−:: contents of /%/some-hoon-file:
304−%produces-a-cord
305−```
306−produces: `[[%text %plain ~] 15 'produces-a-cord']`
307−
308−### `/&` "faspam"
309−
310−`/&` passes a horn through multiple marks, right-to-left. It has both a
311−wide-form and a tall-form syntax. In wide-form, it takes a series of mark
312−arguments followed by a horn. In tall-form, it takes a single mark followed by
313−a horn.
314−
315−```hoon
316−/= some-text /: /%/text-file /&mime&/txt/
317−::
318−some-text
319−```
320−produces: `[[%text %plain ~] p=17 q='Hi I\'m some text\0a']`
321−
322−This example shows two of the ways marks are used. The first way is what
323−happens with the `/txt/` mark: we use it to find a file in clay with that
324−extension, without performing any conversions. Since this file is stored with
325−the `%txt` mark in `%clay`, its type is a `wain`: a list of cords, where each
326−cord is a single line. Once we've read the file, the `%mime` mark converts the
327−`wain` to a triple that includes the MIME type ("text/plain"), the content
328−length in bytes, and the content itself as a cord.
329−
330−```hoon
331−/= page /&html&elem&/~[;div.foo;]
332−::
333−page
334−```
335−produces: `'<html><head></head><body><div class="foo"></div></body></html>'`
336−
337−This runs the sail expression `;div.foo;` through the `%elem` mark, then
338−through the `%html` mark. The `/~` rune produces an item of mark `noun`. The
339−`%elem` mark converts the mark of the expression from `noun` to `elem` by
340−checking that the type fits in `manx` (a hoon/sail type indicating an XML
341−element). The `%html` mark recognizes the `%elem` and converts it to an HTML
342−string with enclosing `<html>`, `<head>`, and `<body>` tags.
343−
344−It's possible to use wide-form `/&` with more than two marks, by using `&` as a
345−delimiter between marks and adding a `/` before the last mark, like:
346−`/&d&c&b&/a/`. The last argument here can actually be any arbitrary horn, not
347−just a mark: `/&c&b&/:path:/mark/`
348−
349−Tall-form `/&` takes only two arguments: a mark and a horn. The mark does not
350−need to be enclosed in `/`'s: `/& html /elem/`
351−
352−### `/|` "fasbar"
353−
354−`/|` takes a series of horns and produces the first one (left-to-right) that
355−succeeds. If none succeed, it produces stack traces from all of its arguments.
356−
357−Example:
358−```hoon
359−/= res /: /%/path/to/file
360−/|
361− /!elem/
362− /elem/
363−==
364−::
365−res
366−```
367−tries to parse the file at `/%/path/to/file` as a hoon expression and evaluate
368−it (`/!elem/`), and then if that fails, tries to convert the file to an HTML
369−element directly (`/elem/`). This is used in urbit's `tree` publishing system
370−to enable a user to place either a hoon file or a static file in a directory,
371−and have them both result in webpages, with preference given to treating the
372−file as hoon to be evaluated.
373−
374−Wide-form `/|` encloses its arguments in parentheses, with a single space as a delimiter:
375−`/|(/!elem/ /elem/)`
376−
377−### `/_` "fascab"
378−
379−`/_` can be used in two ways: filtered and unfiltered.
380−
381−Unfiltered `/_` takes a horn as an argument. It produces a new horn representing the
382−result of mapping the supplied horn over the list of files in the current
383−directory. The keys in the resulting map are the basenames of the files in the
384−directory, and each value is the result of running that horn on the contents of
385−the file.
386−
387−Example:
388−```hoon
389−/= kids /_ /hoon/
390−::
391−`(map term cord)`kids
392−```
393−
394−produces a value of type `(map term cord)`, where each key is the basename (the
395−filename without the prefix), and each value is the result of running the
396−contents of the file through the `%hoon` mark, which validates the
397−hoon code and returns it unmodified. So, the resulting map associates basenames
398−with file contents.
399−
400−Wide-form unfiltered `/_` doesn't need a delimiter: `/= kids /_/hoon/`
401−
402−### `/_` filtered: run a horn on each file in the directory matching an aura
403−
404−Filtered `/_` takes an aura and a horn, and filters the list of files in the
405−current directory by whether their filenames can be parsed to an [atom](/docs/glossary/atom/) of that
406−aura. It then produces a map where each key is the filename after parsing into
407−that atom type, and each value is the result of running the horn on the
408−contents of that file.
409−
410−Example:
411−```hoon
412−/= timed-posts /_ @da /md/
413−`(map @da @t)`timed-posts
414−```
415−produces a map from dates to cords. This product will only contain files whose
416−names are parsable into `@da` dates. The values are the file contents converted
417−to a cord of markdown-formatted text.
418−
419−Wide-form filtered `/_` uses `_` as a delimiter: `/= timed-posts /_@da_/md/`
420−
421−### `/;` "fasmic"
422−
423−`/;` takes a twig and a horn. The twig should evaluate to a [gate](/docs/glossary/gate/), which is then slammed
424−with the result of the horn as its sample.
425−
426−Example:
427−```hoon
428−/= goo
429− /; |=({a/@ b/@} +(b))
430− /~ [a=0 b=1]
431−::
432−goo
433−```
434−
435−produces: `2`
436−
437−Here's a slightly more complex example with runes that use the filesystem:
438−```hoon
439−/= file-length
440− /; |=(a/@t (lent (crip a)))
441− /: /%/path/to/hoon/file /hoon/
442−::
443−file-length
444−```
445−produces the number of bytes in the file "/%/path/to/hoon/file."
446−
447−### `/,` "fascom"
448−
449−`/,` is a switch statement, which picks a branch to evaluate based on
450−whether the current path matches the path in the switch statement.
451−Takes a sequence of pairs of (path, horn) terminated by a `==`. No wide-form.
452−
453−Example:
454−```hoon
455−/= just-right
456− /: /===/right-path :: set path to /%/right-path
457− /,
458− /wrong-path /~ ~
459− /another-wrong-path /~ ~
460− /right-path /~ %evaluate-me :: only evaluate this horn
461− ==
462−::
463−`@t`just-right
464−```
465−
466−produces: `'evaluate-me'`
467−
468−### `/.` "fasdot"
469−
470−Produce a null-terminated list from a sequence of horns, terminated by a `==`. No wide-form.
471−
472−Example:
473−```hoon
474−/= vanes
475− /.
476− /~ %ames
477− /~ %behn
478− /~ %clay
479− /~ %dill
480− /~ %eyre
481− /~ %ford
482− /~ %gall
483− ==
484−::
485−vanes
486−```
487−produces: `[%ames %behn %clay %dill %eyre %ford %gall ~]`.
488−
489−### `/^` "fasket"
490−
491−`/^` takes a mold and a horn, and casts the result of the horn to the mold.
492−
493−Example:
494−```hoon
495−/= liz /^ (list @) :: cast to real list
496− /~ ~[1 2 3] :: no 'i' or 't' faces
497−::
498−?< ?=($~ liz) :: prevent find-fork
499−i.liz
500−```
501−
502−produces: `1`
503−
504−Without the cast, we wouldn't be able to access the 'i' face of the list.
505−
506−Wide-form `/^` uses `^` as a delimiter: `/^(list @)^/~[1 2 3 ~]`
507−
508−### `/#` "fashax"
509−
510−`/#` takes a horn and produces a cell of the dependency
511−hash of the result of the horn, and the result itself.
512−
513−Example:
514−```hoon
515−/= inline /^ {dep/@uvH txt/@t} /# /: /%/my-script /js/
516−::
517−;= ;script: (trip txt.inline) :: set script contents
518− ;script@"/~/on/{<dep.inline>}.js"; :: set script src
519−==
520−```
521−produces two `<script>` tags. The first has its contents set to the contents
522−of the JavaScript file we loaded from clay. The second is an auto-update
523−script that polls the server to check whether the dependency hash has changed.
524−This pattern is used in urbit's `tree` web publishing system.
525−
526−Wide-form `/#` does not need a delimiter:
527−`/= inline /^ {dep/@uvH txt/@t} /#/:/%/my-script:/js/`
528−
529−### `/$` "fasbuc"
530−
531−`/$` will slam a gate on whatever extra arguments have been supplied to this build.
532−At the moment, only HTTP requests forwarded by `%eyre` contain any extra arguments,
533−and using this rune outside of that context will cause an error. Requests from `%eyre`
534−contain an argument representing the query string, which can be parsed using the
535−standard library gate `++fuel:html`.
536−
537−Example:
538−```hoon
539−/= gas /$ fuel:html
540−::
541−:*
542− %who {<(~(get ju aut.ced.gas) 0)>}
543− %where {(spud s.bem.gas)}
544− %case {(scow %ud p.r.bem.gas)}
545−==
546−```
547−produces: [%who '~zod' %where /ford/pages/web %case 60]
548−
549−Wide-form `/$` takes its arguments inside brackets, like `/~`:
550−`/=gas=/$[fuel:html]`
551−
552−### `/%` "fascen"
553−
554−`/%` will forward extra arguments (usually from `%eyre`) on to any enclosed `/renderer/`'s. Without this,
555−renderers that use `/$` to read the extra arguments will crash.
556−
557−Example:
558−```hoon
559−/= dat /% /tree-json/
560−::
561−dat
562−```
563−produces the results of running `ren/tree-json` on the current path. This renderer needs the query string,
564−which is one of the extra arguments passed in from `%eyre`.
565−
566−Wide-form `/%` has no delimiter: `/%/tree-json/`
8+> This document is out of date as of 2020.07.20. In the meantime, see the [blog
9+> post](https://urbit.org/blog/ford-fusion/) about Ford Fusion.