@@ -1,10 +1,13 @@
11---
2−navhome: '/docs/'
2+navhome: /docs/
33---
44
5−# Reference
65
7−## Data Models
6+Reference
7+=========
8+
9+Data Models
10+-----------
811
912### `++axle`, formal state
1013
@@ -13,13 +16,13 @@ navhome: '/docs/'
1316 pol=(map ship baby) ::
1417 == ::
1518
16−This is the formal state of our vane. Anything that must be remembered between
17−calls to ford must be stored here. The number `%1` is a version number for our
18−state that allows us to upgrade the structure of our state in the future if we
19−wish.
19+This is the formal state of our vane. Anything that must be remembered
20+between calls to ford must be stored here. The number `%1` is a version
21+number for our state that allows us to upgrade the structure of our
22+state in the future if we wish.
2023
21−`pol` is the a map from every ship on our pier to their individual ford state.
22−There is no shared ford state -- every ship is entirely separate.
24+`pol` is the a map from every ship on our pier to their individual ford
25+state. There is no shared ford state -- every ship is entirely separate.
2326
2427### `++baby`, state by ship
2528
@@ -31,18 +34,19 @@ There is no shared ford state -- every ship is entirely separate.
3134
3235This is the state specific to each ship.
3336
34−`tad` and `dym` keep track of the tasks we're currently working on. `dym` is a
35−map from ducts to task numbers, and `q.tad` is a map from task number to the
36−task itself. `p.tad` is the next available task number. Thus, the keys of
37−`q.tad` are a subset of the numbers less than `p.tad`, and ford has attempted
38−exactly `p.tad` tasks so far.
37+`tad` and `dym` keep track of the tasks we're currently working on.
38+`dym` is a map from ducts to task numbers, and `q.tad` is a map from
39+task number to the task itself. `p.tad` is the next available task
40+number. Thus, the keys of `q.tad` are a subset of the numbers less than
41+`p.tad`, and ford has attempted exactly `p.tad` tasks so far.
3942
40−`jav` is the cache of previously-solved problems. The keys are a pair of a term
41−(either `%hood`, `%slap`, or `%slam`) and a noun that represents the exact
42−problem solved. In the case of a `%hood`, then, the key is of the form
43−`[%hood beam cage]`. For `%slap`, there is `[%slap vase twig]`. For `%slam`,
44−there is `[%slam vase vase]`. The values are the result of solving the problem.
45−Note that this cache is wiped in `++stay` when ford is reloaded.
43+`jav` is the cache of previously-solved problems. The keys are a pair of
44+a term (either `%hood`, `%slap`, or `%slam`) and a noun that represents
45+the exact problem solved. In the case of a `%hood`, then, the key is of
46+the form `[%hood beam cage]`. For `%slap`, there is `[%slap vase twig]`.
47+For `%slam`, there is `[%slam vase vase]`. The values are the result of
48+solving the problem. Note that this cache is wiped in `++stay` when ford
49+is reloaded.
4650
4751### `++task`, problem in progress
4852
@@ -52,12 +56,12 @@ Note that this cache is wiped in `++stay` when ford is reloaded.
5256 kig=[p=@ud q=(map ,@ud beam)] :: blocks
5357 == ::
5458
55−This is all the state we keep regarding a particular task. `nah` is the duct
56−which asked us to solve the problem, and `kas` is the most recent statement of
57−the problem.
59+This is all the state we keep regarding a particular task. `nah` is the
60+duct which asked us to solve the problem, and `kas` is the most recent
61+statement of the problem.
5862
59−`kig` keeps track of which resources we are blocked on. Our blocks are stored by
60−index in `q.kig`, and the next available index is `p.kig`.
63+`kig` keeps track of which resources we are blocked on. Our blocks are
64+stored by index in `q.kig`, and the next available index is `p.kig`.
6165
6266### `++silk`, problem
6367
@@ -79,12 +83,13 @@ index in `q.kig`, and the next available index is `p.kig`.
7983 [%vale p=mark q=ship r=*] :: validate [our his]
8084 == ::
8185
82−This is the every type of problem we can solve. Every `%exec` kiss that requests
83−us to solve a problem must choose one of these problems to solve.
86+This is the every type of problem we can solve. Every `%exec` kiss that
87+requests us to solve a problem must choose one of these problems to
88+solve.
8489
85−Because this is both an internal structure used in ford and the public interface
86−to ford, we choose to document this structure in our discussion of the public
87−interface to ford below.
90+Because this is both an internal structure used in ford and the public
91+interface to ford, we choose to document this structure in our
92+discussion of the public interface to ford below.
8893
8994### `++calx`, cache line
9095
@@ -94,19 +99,20 @@ interface to ford below.
9499 [%slam p=calm q=[p=vase q=vase] r=vase] :: compute
95100 == ::
96101
97−There are three kinds of cache entries. Every entry includes some metadata in
98−`p` and is the combination of an input and its output.
102+There are three kinds of cache entries. Every entry includes some
103+metadata in `p` and is the combination of an input and its output.
99104
100−The input to a `%hood` is the location of the resource and a cage representing
101−the data at that location. The output is the hood found by compiling the given
102−cage at the given location.
105+The input to a `%hood` is the location of the resource and a cage
106+representing the data at that location. The output is the hood found by
107+compiling the given cage at the given location.
103108
104−The input to a `%slap` is the vase of the subject and the twig of the formula
105−against which we are slapping the subject. The output is the vase produced by
106−slapping them.
109+The input to a `%slap` is the vase of the subject and the twig of the
110+formula against which we are slapping the subject. The output is the
111+vase produced by slapping them.
107112
108−The input to a `%slam` is the vase of the subject and the vase of the gate which
109−we are slapping. The output is the vase produced by slamming them.
113+The input to a `%slam` is the vase of the subject and the vase of the
114+gate which we are slapping. The output is the vase produced by slamming
115+them.
110116
111117### `++calm`, cache line metadata
112118
@@ -115,9 +121,9 @@ we are slapping. The output is the vase produced by slamming them.
115121 dep=(set beam) :: dependencies
116122 == ::
117123
118−Every line in the cache needs to have two pieces of metadata. We must know the
119−last time this line in the cache was accessed, and we must know what are the
120−dependencies of this line.
124+Every line in the cache needs to have two pieces of metadata. We must
125+know the last time this line in the cache was accessed, and we must know
126+what are the dependencies of this line.
121127
122128### `++hood`, assembly components
123129
@@ -131,43 +137,46 @@ dependencies of this line.
131137
132138When assembling a hook file, we split it into several sections.
133139
134−`zus` is the kelvin version of the required zuse. In general, we assume that any
135−newer (lower-numbered) zuse will retain backward compatibility, so any newer
136−zuse is also permissible. This number is set with a `/?` at the beginning of the
137−file.
140+`zus` is the kelvin version of the required zuse. In general, we assume
141+that any newer (lower-numbered) zuse will retain backward compatibility,
142+so any newer zuse is also permissible. This number is set with a `/?` at
143+the beginning of the file.
138144
139−`sur` is the set of structures included. These are included with the `/-` rune.
140−When a structure is included, we look in `/=main=/sur` for the given structure
141−and we load the gate there. When compiling, all the included structures are
142−collected into a single core placed in the subject of the body with a `=>`.
145+`sur` is the set of structures included. These are included with the
146+`/-` rune. When a structure is included, we look in `/=main=/sur` for
147+the given structure and we load the gate there. When compiling, all the
148+included structures are collected into a single core placed in the
149+subject of the body with a `=>`.
143150
144−`lib` is the set of librarires included. These are included with the `/+` rune.
145−When a library is included, we look in `/=main=/lib` for the given library and
146−we load the library there. As with structures, all the included libraries are
147−collected into a single core placed in the subject of the body with a `=>`.
151+`lib` is the set of librarires included. These are included with the
152+`/+` rune. When a library is included, we look in `/=main=/lib` for the
153+given library and we load the library there. As with structures, all the
154+included libraries are collected into a single core placed in the
155+subject of the body with a `=>`.
148156
149−`fan` is the set of resources included. These are loaded in many different ways
150−and may load resources from any location. These are placed in the subject of the
151−body with a `=~`.
157+`fan` is the set of resources included. These are loaded in many
158+different ways and may load resources from any location. These are
159+placed in the subject of the body with a `=~`.
152160
153−`src` is the set of twigs or references to twigs in the body of the program.
154−Generally, each of these will represent a core, but this is not required. When
155−compiling, these are strung together in a `=~`.
161+`src` is the set of twigs or references to twigs in the body of the
162+program. Generally, each of these will represent a core, but this is not
163+required. When compiling, these are strung together in a `=~`.
156164
157165### `++hoot`
158166
159167 ++ hoot (pair bean hoof) :: structure gate/core
160168
161−A structures may be either a direct gate or a core. These are syntactically
162−distinguished by adding a `*` to the beginning of the structure name for a core.
163−The structure itself is a `hoof`.
169+A structures may be either a direct gate or a core. These are
170+syntactically distinguished by adding a `*` to the beginning of the
171+structure name for a core. The structure itself is a `hoof`.
164172
165173### `++hoof`
166174
167175 ++ hoof (pair term (unit (pair case ship))) :: resource reference
168176
169−A hoof, which is either a structure or a library, has a name, and it may also
170−specify which version of the resource to use and which ship to retrieve it from.
177+A hoof, which is either a structure or a library, has a name, and it may
178+also specify which version of the resource to use and which ship to
179+retrieve it from.
171180
172181### `++horn`
173182
@@ -193,42 +202,44 @@ discussion of their use from a user's perspective is documented in the [runes
193202documentation](https://urbit.org/docs/arvo/internals/runes), so we will here
194203only give a description of the data structure itself.
195204
196−A `%ape` horn is simply a twig that gets evaluated and placed in the subject.
205+A `%ape` horn is simply a twig that gets evaluated and placed in the
206+subject.
197207
198−A `%arg` is a gate that gets evaluated with a sample of our location and our
199−heel.
208+A `%arg` is a gate that gets evaluated with a sample of our location and
209+our heel.
200210
201−A `%day` is a horn that applies to each of a list of `@dr`-named files in the
202−directory.
211+A `%day` is a horn that applies to each of a list of `@dr`-named files
212+in the directory.
203213
204−A `%dub` is a term and horn, where the result of a horn is given the face of the
205−term.
214+A `%dub` is a term and horn, where the result of a horn is given the
215+face of the term.
206216
207217A `%fan` is a list of horns, all at the current directory level.
208218
209−A `%for` is a path and a horn, where the horn is evaluated relative to the given
210−path, where the given path is relative to the current location.
219+A `%for` is a path and a horn, where the horn is evaluated relative to
220+the given path, where the given path is relative to the current
221+location.
211222
212−A `%hub` is a horn that applies to each of a list of `@ud`-named files in the
213−directory.
223+A `%hub` is a horn that applies to each of a list of `@ud`-named files
224+in the directory.
214225
215−A `%man` is a map of spans to horns where the result is a set of each horn
216−applied to the current directory given the associated face.
226+A `%man` is a map of spans to horns where the result is a set of each
227+horn applied to the current directory given the associated face.
217228
218−A `%nap` is a homogenous map where each entry in a directory is handled with the
219−same horn and is given a face according to its name.
229+A `%nap` is a homogenous map where each entry in a directory is handled
230+with the same horn and is given a face according to its name.
220231
221−A `%now` is a horn that applies to each of a list of `@da`-named files in the
222−directory.
232+A `%now` is a horn that applies to each of a list of `@da`-named files
233+in the directory.
223234
224−A `%saw` is a twig and a horn, where the twig operates on the result of the
225−horn.
235+A `%saw` is a twig and a horn, where the twig operates on the result of
236+the horn.
226237
227−A `%see` is a beam and a horn, where the horn is evaluated at a location of the
228−given beam.
238+A `%see` is a beam and a horn, where the horn is evaluated at a location
239+of the given beam.
229240
230−A `%sic` is a tile and a horn, where the horn is evaluated and cast to the type
231−associated with the tile.
241+A `%sic` is a tile and a horn, where the horn is evaluated and cast to
242+the type associated with the tile.
232243
233244A `%toy` is simply a mark to be baked.
234245
@@ -239,9 +250,9 @@ A `%toy` is simply a mark to be baked.
239250 [%| p=beam] :: resource location
240251 == ::
241252
242−This is an entry in the body of the hook file. The hoop can either be defined
243−directly in the given file or it can be a reference to another file. The second
244−is specified with a `//` rune.
253+This is an entry in the body of the hook file. The hoop can either be
254+defined directly in the given file or it can be a reference to another
255+file. The second is specified with a `//` rune.
245256
246257### `++bolt`, monadic edge
247258
@@ -255,27 +266,28 @@ is specified with a `//` rune.
255266 == ::
256267 == ::
257268
258−Throughout our computation, we let our result flow through with the set of
259−dependencies of the value. At various times, we may wish to either throw an
260−error or declare that the actual result cannot be found until a particular
261−resource is retrieved. This is a perfect case for a monad, so here we define a
262−data structure for it.
269+Throughout our computation, we let our result flow through with the set
270+of dependencies of the value. At various times, we may wish to either
271+throw an error or declare that the actual result cannot be found until a
272+particular resource is retrieved. This is a perfect case for a monad, so
273+here we define a data structure for it.
263274
264−At every step, we have a cache, so we store that in `p`. In `q` we store the
265−data.
275+At every step, we have a cache, so we store that in `p`. In `q` we store
276+the data.
266277
267−In the case of `%0`, we have the result in `q` and the set of dependencies in
268−`p`.
278+In the case of `%0`, we have the result in `q` and the set of
279+dependencies in `p`.
269280
270−In the case of `%1`, we have a set of dependencies on which we are blocking.
271−When this happens, we make a call to clay to get the dependencies, and we
272−proceed with the computation when we receive them. Technically, we restart the
273−computation, but since every expensive step is cached, there is no significant
274−performance penalty to doing this. Referential transparency has its uses.
281+In the case of `%1`, we have a set of dependencies on which we are
282+blocking. When this happens, we make a call to clay to get the
283+dependencies, and we proceed with the computation when we receive them.
284+Technically, we restart the computation, but since every expensive step
285+is cached, there is no significant performance penalty to doing this.
286+Referential transparency has its uses.
275287
276−In the case of `%2`, we have a hit an error. This gets passed all the way
277−through to the calling duct. The list of tanks is some description of what went
278−wrong, often including a stack trace.
288+In the case of `%2`, we have a hit an error. This gets passed all the
289+way through to the calling duct. The list of tanks is some description
290+of what went wrong, often including a stack trace.
279291
280292### `++burg`, monadic rule
281293
@@ -284,49 +296,53 @@ wrong, often including a stack trace.
284296 $+([c=cafe d=a] (bolt b)) ::
285297 :: ::
286298
287−To operate on bolts, we use `++cope` as our bind operator, and the functions it
288−works on are of type `burg`. Our functions that operate on bolts should have a
289−sample of the cache and a value. Their output should be a bolt of the output
290−value. Then, `++cope` will only call the function when necessary (in the `%0`
291−case), and it will do so without the wrapping of a bolt.
299+To operate on bolts, we use `++cope` as our bind operator, and the
300+functions it works on are of type `burg`. Our functions that operate on
301+bolts should have a sample of the cache and a value. Their output should
302+be a bolt of the output value. Then, `++cope` will only call the
303+function when necessary (in the `%0` case), and it will do so without
304+the wrapping of a bolt.
292305
293−If you understand monads, this is probably fairly obvious. Otherwise, see the
294−discussion on `++cope` (link).
306+If you understand monads, this is probably fairly obvious. Otherwise,
307+see the discussion on `++cope` (link).
295308
296−## Public Interface
309+Public Interface
310+----------------
297311
298−Ford does not export a scry interface, so the only way to interact with ford is
299−by sending kisses and receiving gifts. In fact, ford only sends accepts one kiss
300−and gives one gift. This is, of course, misleading because ford actually does
301−many different things. It does, however, only produce one type of thing -- a
302−result of a computation, which is either an error or the value produced along
303−with the set of dependencies referenced by it.
312+Ford does not export a scry interface, so the only way to interact with
313+ford is by sending kisses and receiving gifts. In fact, ford only sends
314+accepts one kiss and gives one gift. This is, of course, misleading
315+because ford actually does many different things. It does, however, only
316+produce one type of thing -- a result of a computation, which is either
317+an error or the value produced along with the set of dependencies
318+referenced by it.
304319
305320 ++ kiss :: in request ->$
306321 $% [%exec p=@p q=(unit silk)] :: make / kill
307322 == ::
308323
309324The `%exec` gift requests ford to perform a computation on behalf of a
310−particular ship. `p` is the ship, and `q` is the computation. If `q` is null,
311−then we are requesting that ford cancel the computation that it is currently
312−being run along this duct. Thus, if you wish to cancel a computation, you must
313−send the kiss along the same duct as the original request.
325+particular ship. `p` is the ship, and `q` is the computation. If `q` is
326+null, then we are requesting that ford cancel the computation that it is
327+currently being run along this duct. Thus, if you wish to cancel a
328+computation, you must send the kiss along the same duct as the original
329+request.
314330
315−Otherwise, we ask ford to perform a certain computation, as defined in `++silk`.
316−Since all computations produce the same type of result, we will discuss that
317−result before we jump into `++silk`.
331+Otherwise, we ask ford to perform a certain computation, as defined in
332+`++silk`. Since all computations produce the same type of result, we
333+will discuss that result before we jump into `++silk`.
318334
319335 ++ gift :: out result <-$
320336 $% [%made p=(each bead (list tank))] :: computed result
321337 == ::
322338
323−We give either a `bead`, which is a result, or a list of tanks, which is an
324−error messge, often including a stack trace.
339+We give either a `bead`, which is a result, or a list of tanks, which is
340+an error messge, often including a stack trace.
325341
326342 ++ bead ,[p=(set beam) q=cage] :: computed result
327343
328−This is a set of dependencies required to compute this value and a cage of the
329−result with its associated mark.
344+This is a set of dependencies required to compute this value and a cage
345+of the result with its associated mark.
330346
331347There are twelve possible computations defined in `++silk`.
332348
@@ -346,77 +362,83 @@ There are twelve possible computations defined in `++silk`.
346362 [%vale p=mark q=ship r=*] :: validate [our his]
347363 == ::
348364
349−First, we allow silks to autocons. A cell of silks is also a silk, and the
350−product vase is a cell of the two silks. This obviously extends to an arbitrary
351−number of silks.
365+First, we allow silks to autocons. A cell of silks is also a silk, and
366+the product vase is a cell of the two silks. This obviously extends to
367+an arbitrary number of silks.
352368
353−`%bake` tries to functionally produce the file at a given beam with the given
354−mark and heel. It fails if there is no way to translate at this level.
369+`%bake` tries to functionally produce the file at a given beam with the
370+given mark and heel. It fails if there is no way to translate at this
371+level.
355372
356−`%boil` functionally produces the file at a given beam with the given mark and
357−heel. If there is no way to translate at this beam, we pop levels off the stack
358−and attempt to bake there until we find a level we can bake. This should almost
359−always be called instead of `%bake`.
373+`%boil` functionally produces the file at a given beam with the given
374+mark and heel. If there is no way to translate at this beam, we pop
375+levels off the stack and attempt to bake there until we find a level we
376+can bake. This should almost always be called instead of `%bake`.
360377
361378`%call` slams the result of one silk against the result of another.
362379
363−`%cast` translates the given silk to the given mark, if possible. This is one of
364−the critical and fundamental operations of ford.
380+`%cast` translates the given silk to the given mark, if possible. This
381+is one of the critical and fundamental operations of ford.
365382
366−`%done` produces exactly its input. This is rarely used on its own, but many
367−silks are recursively defined in terms of other silks, so we often need a silk
368−that simply produces its input. A monadic return, if you will.
383+`%done` produces exactly its input. This is rarely used on its own, but
384+many silks are recursively defined in terms of other silks, so we often
385+need a silk that simply produces its input. A monadic return, if you
386+will.
369387
370−`%diff` diffs the two given silks (which must be of the same mark), producing a
371−cage of the mark specified in `++mark` in `++grad` for the mark of the two
372−silks.
388+`%diff` diffs the two given silks (which must be of the same mark),
389+producing a cage of the mark specified in `++mark` in `++grad` for the
390+mark of the two silks.
373391
374−`%dude` computes the given silk with the given tank as part of the stack trace
375−if there is an error.
392+`%dude` computes the given silk with the given tank as part of the stack
393+trace if there is an error.
376394
377−`%dune` produces an error if the cage is empty. Otherwise, it produces the value
378−in the unit.
395+`%dune` produces an error if the cage is empty. Otherwise, it produces
396+the value in the unit.
379397
380−`%mute` takes a silk and a list of changes to make to the silk. At each wing in
381−the list we put the value of the associated silk.
398+`%mute` takes a silk and a list of changes to make to the silk. At each
399+wing in the list we put the value of the associated silk.
382400
383−`%pact` applies the second silk as a patch to the first silk. The second silk
384−must be of the mark specified in `++mark` in `++grad` for the mark of the first
385−silk.
401+`%pact` applies the second silk as a patch to the first silk. The second
402+silk must be of the mark specified in `++mark` in `++grad` for the mark
403+of the first silk.
386404
387−`%plan` performs a structured assembly directly. This is not generally directly
388−useful because several other silks perform supersets of this functionality. We
389−don't usually have naked hoods outside ford.
405+`%plan` performs a structured assembly directly. This is not generally
406+directly useful because several other silks perform supersets of this
407+functionality. We don't usually have naked hoods outside ford.
390408
391−`%reef` produces a core containing the entirety of zuse and hoon, suitable for
392−running arbitrary code against. The mark is `%noun`.
409+`%reef` produces a core containing the entirety of zuse and hoon,
410+suitable for running arbitrary code against. The mark is `%noun`.
393411
394−`%ride` slaps a twig against a subject silk. The mark of the result is `%noun`.
412+`%ride` slaps a twig against a subject silk. The mark of the result is
413+`%noun`.
395414
396−`%vale` validates untyped data from a ship against a given mark. This is an
397−extremely useful function.
415+`%vale` validates untyped data from a ship against a given mark. This is
416+an extremely useful function.
398417
399−# Commentary
418+Commentary
419+==========
400420
401−## Parsing Hook Files
421+Parsing Hook Files
422+------------------
402423
403−In the commentary on other vanes, we have traced through the lifecycle of
404−various external requests. This is generally a very reasonable order to examine
405−vanes since it will eventually cover the entire vane, and we are never left
406−wondering why we are doing something.
424+In the commentary on other vanes, we have traced through the lifecycle
425+of various external requests. This is generally a very reasonable order
426+to examine vanes since it will eventually cover the entire vane, and we
427+are never left wondering why we are doing something.
407428
408−For ford, however, it makes more sense to begin by discussing the parsing and
409−assembliing of hook files. Many of the possible requests require us to assemble
410−hook files, so we may as well examine this immediately.
429+For ford, however, it makes more sense to begin by discussing the
430+parsing and assembliing of hook files. Many of the possible requests
431+require us to assemble hook files, so we may as well examine this
432+immediately.
411433
412−First, we will examine the parsing. We parse a file at a beam to a hood in
413−`++fade:zo:za`. The top-level parsing rule is `++fair`, which takes a beam and
414−produces a rule to parse an entire hood file.
434+First, we will examine the parsing. We parse a file at a beam to a hood
435+in `++fade:zo:za`. The top-level parsing rule is `++fair`, which takes a
436+beam and produces a rule to parse an entire hood file.
415437
416−A note on the naming scheme: the parsing the combinators that parse into a
417−particular structure are conventionally given the same name as the structure.
418−Although this locally clobbers the type names, this pattern makes obvious the
419−intent of the parsing combinators.
438+A note on the naming scheme: the parsing the combinators that parse into
439+a particular structure are conventionally given the same name as the
440+structure. Although this locally clobbers the type names, this pattern
441+makes obvious the intent of the parsing combinators.
420442
421443We kick off with `++hood:fair`.
422444
@@ -442,23 +464,24 @@ We kick off with `++hood:fair`.
442464 (most gap hoop)
443465 ==
444466
445−There are five sections to a hood: system version, structures, libraries,
446−resources, and body.
467+There are five sections to a hood: system version, structures,
468+libraries, resources, and body.
447469
448−First, we parse the requested version number of the system. This is specified
449−with a unary `/?` rune. If not present, then we default to the current version.
470+First, we parse the requested version number of the system. This is
471+specified with a unary `/?` rune. If not present, then we default to the
472+current version.
450473
451−Second, we may have zero or more `/-` runes followed by a parsing of a `++hoot`,
452−which represents a shared structure.
474+Second, we may have zero or more `/-` runes followed by a parsing of a
475+`++hoot`, which represents a shared structure.
453476
454−Third, we may have zero or more `/+` runes followed by a parsing of a `++hoof`,
455−which represents a shared library.
477+Third, we may have zero or more `/+` runes followed by a parsing of a
478+`++hoof`, which represents a shared library.
456479
457−Fourth, we may have zero or more other `/` runes (as described in `++horn`),
458−which represent program-specific resources to be loaded.
480+Fourth, we may have zero or more other `/` runes (as described in
481+`++horn`), which represent program-specific resources to be loaded.
459482
460−Fifth and finally, we must have one or more body statements (hoops), which are
461−either direct twigs or `//` runes.
483+Fifth and finally, we must have one or more body statements (hoops),
484+which are either direct twigs or `//` runes.
462485
463486 ++ hoot
464487 ;~ pose
@@ -466,9 +489,9 @@ either direct twigs or `//` runes.
466489 (stag %& hoof)
467490 ==
468491
469−A structure can either be a direct gate, or it can be a simple core. Either one
470−is parsed with `++hoof`, so we distinguish the two cases by requireing core
471−references to be prefixed by a `*`.
492+A structure can either be a direct gate, or it can be a simple core.
493+Either one is parsed with `++hoof`, so we distinguish the two cases by
494+requireing core references to be prefixed by a `*`.
472495
473496 ++ hoof
474497 %+ cook |=(a=^hoof a)
@@ -481,11 +504,11 @@ references to be prefixed by a `*`.
481504 ==
482505 ==
483506
484−A hoof must have a name, which is a term. Optionally, we also include a case and
485−a ship. This is marked by appending a `/` followed by a case to denote the
486−requested version of the resource and a `/` followed by a ship name to denote
487−the requested source of the resource. For example, `resource/1/~zod` requests
488−the first version of `resource` on `~zod`.
507+A hoof must have a name, which is a term. Optionally, we also include a
508+case and a ship. This is marked by appending a `/` followed by a case to
509+denote the requested version of the resource and a `/` followed by a
510+ship name to denote the requested source of the resource. For example,
511+`resource/1/~zod` requests the first version of `resource` on `~zod`.
489512
490513 ++ case
491514 %- sear
@@ -494,11 +517,11 @@ the first version of `resource` on `~zod`.
494517 ?. ?=([%$ ?(%da %ud %tas) *] a) ~
495518 [~ u=(^case a)]
496519
497−Here, we parse a literal with `++nuck:so`, and we accept the input if it is
498−either an absolute date, an unsigned decimal, or a label.
520+Here, we parse a literal with `++nuck:so`, and we accept the input if it
521+is either an absolute date, an unsigned decimal, or a label.
499522
500−This leaves only horns and hoops to parse. Hoops are much simple to parse, so
501−we'll discuss those first.
523+This leaves only horns and hoops to parse. Hoops are much simple to
524+parse, so we'll discuss those first.
502525
503526 ++ hoop
504527 ;~ pose
@@ -506,20 +529,20 @@ we'll discuss those first.
506529 (stag %& tall:vez)
507530 ==
508531
509−There are two types of hoops. Direct twigs are parsed with `++tall:vast`, which
510−is the just the hoon parser for a tall-form twig.
532+There are two types of hoops. Direct twigs are parsed with
533+`++tall:vast`, which is the just the hoon parser for a tall-form twig.
511534
512−References to external twigs are marked with a `//` rune followed by a beam,
513−which is parsed with `++have`.
535+References to external twigs are marked with a `//` rune followed by a
536+beam, which is parsed with `++have`.
514537
515538 ++ hath (sear plex:voz (stag %clsg poor:voz)) :: hood path
516539 ++ have (sear tome ;~(pfix fas hath)) :: hood beam
517540
518−`++have` parses a path with `++hath`, and then it converts the path into a beam
519−with `++tome`.
541+`++have` parses a path with `++hath`, and then it converts the path into
542+a beam with `++tome`.
520543
521−`++hath` parses a `/`-separated list with `++poor:vast`, then converts it to an
522−actual path with `++plex:vast`.
544+`++hath` parses a `/`-separated list with `++poor:vast`, then converts
545+it to an actual path with `++plex:vast`.
523546
524547This leaves only horns to parse.
525548
@@ -548,17 +571,18 @@ This leaves only horns to parse.
548571 ==
549572 ==
550573
551−Horn parsing is slightly complex, so we create an internal core to organize our
552−code. Our core has a global variable of `tol`, which is true if tall form is
553−permissible and false if we're already in wide form. We kick off the parsing
554−with `++apex`.
574+Horn parsing is slightly complex, so we create an internal core to
575+organize our code. Our core has a global variable of `tol`, which is
576+true if tall form is permissible and false if we're already in wide
577+form. We kick off the parsing with `++apex`.
555578
556−`++apex` specifies how each rune is parsed. This allows us to offload the
557−different ways of parsing the arguments to these runes into separate arms. The
558−exception here is that the `%toy` horn is simply of the form `/mark/`.
579+`++apex` specifies how each rune is parsed. This allows us to offload
580+the different ways of parsing the arguments to these runes into separate
581+arms. The exception here is that the `%toy` horn is simply of the form
582+`/mark/`.
559583
560−We'll examine each of the horn parsing arms right after we discuss `++rail`,
561−which is used in each one.
584+We'll examine each of the horn parsing arms right after we discuss
585+`++rail`, which is used in each one.
562586
563587 ++ rail
564588 |* [wid=_rule tal=_rule]
@@ -566,8 +590,8 @@ which is used in each one.
566590 ;~(pose wid tal)
567591
568592This takes a wide-form and a tall-form parsing rule. If tall form is
569−permissible, then it allows either rule to match; else, it allows only the wide
570−form rule.
593+permissible, then it allows either rule to match; else, it allows only
594+the wide form rule.
571595
572596 ++ read
573597 |% ++ ape
@@ -575,47 +599,49 @@ form rule.
575599 (ifix [sel ser] (stag %cltr (most ace wide:vez)))
576600 ;~(pfix gap tall:vez)
577601
578−`++ape:read` parses for both the `/~` and the `/$` runes. It produces a twig.
579−The wide form is a tuple of one or more ace-separated wide-form twigs parsed
580−with `++wide:vast` and surrounded by `[` and `]`. The tall form is a single tall
581−form twig parsed by `++tall:vast`
602+`++ape:read` parses for both the `/~` and the `/$` runes. It produces a
603+twig. The wide form is a tuple of one or more ace-separated wide-form
604+twigs parsed with `++wide:vast` and surrounded by `[` and `]`. The tall
605+form is a single tall form twig parsed by `++tall:vast`
582606
583607 ++ day
584608 %+ rail
585609 apex(tol |)
586610 ;~(pfix gap apex)
587611
588−This parses for the `/|`, `/@`, `/%`, and `/&` runes. It produces a horn. The
589−wide form is, recursively, the entire horn parser with tall form disabled. The
590−tall form is a gap followed by, recursively, the entire horn parser.
612+This parses for the `/|`, `/@`, `/%`, and `/&` runes. It produces a
613+horn. The wide form is, recursively, the entire horn parser with tall
614+form disabled. The tall form is a gap followed by, recursively, the
615+entire horn parser.
591616
592617 ++ dub
593618 %+ rail
594619 ;~(plug sym ;~(pfix tis apex(tol |)))
595620 ;~(pfix gap ;~(plug sym ;~(pfix gap apex)))
596621
597−This parses for the `/=` rune. It produces a term followed by a horn. The wide
598−form is a symbol name followed by a `=` and, recursively, the entire horn parser
599−with tall form disabled. The tall form is a gap followed by a symbol name,
600−another gap, and, recursively, the entire horn parser.
622+This parses for the `/=` rune. It produces a term followed by a horn.
623+The wide form is a symbol name followed by a `=` and, recursively, the
624+entire horn parser with tall form disabled. The tall form is a gap
625+followed by a symbol name, another gap, and, recursively, the entire
626+horn parser.
601627
602628 ++ fan
603629 %+ rail fail
604630 ;~(sfix (star ;~(pfix gap apex)) ;~(plug gap duz))
605631
606−This parses for the `/.` rune. It produces a list of horns. There is no wide
607−form. The tall form is a stet-terminated series of gap-separated recursive calls
608−to the entire horn parser.
632+This parses for the `/.` rune. It produces a list of horns. There is no
633+wide form. The tall form is a stet-terminated series of gap-separated
634+recursive calls to the entire horn parser.
609635
610636 ++ for
611637 %+ rail
612638 ;~(plug (ifix [sel ser] hath) apex(tol |))
613639 ;~(pfix gap ;~(plug hath ;~(pfix gap apex)))
614640
615−This parses for the `/,` rune. It produces a path and a horn. The wide form is a
616−`[`-`]`-surrounded path followed by, recursively, the entire horn parser with
617−tall form disabled. The tall form is a gap followed by a path, another gap, and,
618−recursively, the entire horn parser.
641+This parses for the `/,` rune. It produces a path and a horn. The wide
642+form is a `[`-`]`-surrounded path followed by, recursively, the entire
643+horn parser with tall form disabled. The tall form is a gap followed by
644+a path, another gap, and, recursively, the entire horn parser.
619645
620646 ++ man
621647 %+ rail fail
@@ -628,31 +654,31 @@ recursively, the entire horn parser.
628654 ?. ?=(%dub -.i.fan) ~
629655 $(fan t.fan, naf [[p.i.fan q.i.fan] naf])
630656
631−This parses for the `/*` rune. It produces a map of spans to horns. There is no
632−wide form. The tall form is a stet-terminated series of gap-separated recursive
633−calls to the entire horn parser. All produced horns are expected to be from `/=`
634−runes. The term and horn in each `/=` horn is inserted into the produced map as
635−a key-value pair.
657+This parses for the `/*` rune. It produces a map of spans to horns.
658+There is no wide form. The tall form is a stet-terminated series of
659+gap-separated recursive calls to the entire horn parser. All produced
660+horns are expected to be from `/=` runes. The term and horn in each `/=`
661+horn is inserted into the produced map as a key-value pair.
636662
637663 ++ saw
638664 %+ rail
639665 ;~(plug ;~(sfix wide:vez sem) apex(tol |))
640666 ;~(pfix gap ;~(plug tall:vez ;~(pfix gap apex)))
641667
642−This parses for the `/;` rune. It produces a twig and a horn. The wide form is a
643−wide-form twig followed by a `;` and, recursively, the entire horn parser with
644−tall form disabled. The tall form is a gap followed by a tall-form twig, another
645−gap, and, recursively, the entire horn parser.
668+This parses for the `/;` rune. It produces a twig and a horn. The wide
669+form is a wide-form twig followed by a `;` and, recursively, the entire
670+horn parser with tall form disabled. The tall form is a gap followed by
671+a tall-form twig, another gap, and, recursively, the entire horn parser.
646672
647673 ++ see
648674 %+ rail
649675 ;~(plug ;~(sfix have col) apex(tol |))
650676 ;~(pfix gap ;~(plug have ;~(pfix gap apex)))
651677
652−This parses for the `/:` rune. It produces a beam and a horn. The wide form is a
653−beam followed by a `;` and, recursively, the entire horn parser with tall form
654−disabled. The tall form is a gap followed by a beam, another gap, and,
655−recursively, the entire horn parser.
678+This parses for the `/:` rune. It produces a beam and a horn. The wide
679+form is a beam followed by a `;` and, recursively, the entire horn
680+parser with tall form disabled. The tall form is a gap followed by a
681+beam, another gap, and, recursively, the entire horn parser.
656682
657683 ++ sic
658684 %+ rail
@@ -660,17 +686,18 @@ recursively, the entire horn parser.
660686 ;~(pfix gap ;~(plug howl:vez ;~(pfix gap apex)))
661687 --
662688
663−This parses for the `/^` rune. It produces a tile and a horn. The wide form is a
664−wide-form tile, parsed with `++toil:vast`, followed by a `^` and, recursively,
665−the entire horn parser with tall form disabled. The tall form is a gap followed
666−by a tall-form tile, parsed with `++howl:vast`, another gap, and, recursively,
667−the entire horn parser.
689+This parses for the `/^` rune. It produces a tile and a horn. The wide
690+form is a wide-form tile, parsed with `++toil:vast`, followed by a `^`
691+and, recursively, the entire horn parser with tall form disabled. The
692+tall form is a gap followed by a tall-form tile, parsed with
693+`++howl:vast`, another gap, and, recursively, the entire horn parser.
668694
669−## Assembling Hook Files
695+Assembling Hook Files
696+---------------------
670697
671−At this point, we've parsed a hook file into a hood. We will now describe
672−exactly how this hood is assembled into a vase. The problem of assembling is
673−handled entirely within the `++meow:zo:za` core.
698+At this point, we've parsed a hook file into a hood. We will now
699+describe exactly how this hood is assembled into a vase. The problem of
700+assembling is handled entirely within the `++meow:zo:za` core.
674701
675702 ++ meow :: assemble
676703 |= [how=beam arg=heel]
@@ -684,45 +711,47 @@ handled entirely within the `++meow:zo:za` core.
684711 ==
685712 |%
686713
687−We take two arguments and keep seven pieces of state. `how` is the location of
688−the hook file we're assembling, and `arg` is the heel, or virtual path
689−extension, of the file.
714+We take two arguments and keep seven pieces of state. `how` is the
715+location of the hook file we're assembling, and `arg` is the heel, or
716+virtual path extension, of the file.
690717
691−In `rop`, we maintain a map of terms to pairs of hooves and twigs to represent
692−the structures we've encountered that we will put together in a core at the top
693−of the file.
718+In `rop`, we maintain a map of terms to pairs of hooves and twigs to
719+represent the structures we've encountered that we will put together in
720+a core at the top of the file.
694721
695−In `zog`, we maintain the set of structures we're in the middle of loading. If
696−we try to load a structure already in our dependency ancestry, then we fail
697−because we do not allow circular dependencies. This enforces that our structure
698−dependency graph is a DAG.
722+In `zog`, we maintain the set of structures we're in the middle of
723+loading. If we try to load a structure already in our dependency
724+ancestry, then we fail because we do not allow circular dependencies.
725+This enforces that our structure dependency graph is a DAG.
699726
700−In `bil`, we maintain a map of terms to pairs of hooves and twigs to represent
701−the libraries we've encountered that we will put together in a series of cores
702−after the structure core.
727+In `bil`, we maintain a map of terms to pairs of hooves and twigs to
728+represent the libraries we've encountered that we will put together in a
729+series of cores after the structure core.
703730
704−In `lot`, we maintain a stack of library names as they are encountered during a
705−depth-first search. More precisely, we push a library onto the stack after we've
706−processed all its children. Thus, every library depends only on things deeper in
707−the list. The libraries must be loaded in the reverse of this order. Concisely,
708−this is a topological sort of the library dependency partial ordering.
731+In `lot`, we maintain a stack of library names as they are encountered
732+during a depth-first search. More precisely, we push a library onto the
733+stack after we've processed all its children. Thus, every library
734+depends only on things deeper in the list. The libraries must be loaded
735+in the reverse of this order. Concisely, this is a topological sort of
736+the library dependency partial ordering.
709737
710−In `zeg`, we maintain the set of libraries we're in the middle of loading. If we
711−try to load a library already in our dependency ancestry, then we fail because
712−we do not allow circular dependencies. This enforces that our library dependency
713−graph is a DAG.
738+In `zeg`, we maintain the set of libraries we're in the middle of
739+loading. If we try to load a library already in our dependency ancestry,
740+then we fail because we do not allow circular dependencies. This
741+enforces that our library dependency graph is a DAG.
714742
715−In `boy`, we maintain a stack of body twigs, which we'll put together in a
716−series of cores at the end of the file.
743+In `boy`, we maintain a stack of body twigs, which we'll put together in
744+a series of cores at the end of the file.
717745
718−In `hol`, we decide if we're allowed to contain horns. Libraries and structures
719−are not allowed to contain horns.
746+In `hol`, we decide if we're allowed to contain horns. Libraries and
747+structures are not allowed to contain horns.
720748
721−We in every case enter `++meow` through `++abut`. You'll notice that there are
722−four (count 'em, four!) calls to `++cope` in `++abut`. If you've glanced at the
723−ford code in general, you've probably seen cope over and over. It is called in
724−79 different places. We need to discuss the use of this critical function in
725−detail, so we may as well do it here.
749+We in every case enter `++meow` through `++abut`. You'll notice that
750+there are four (count 'em, four!) calls to `++cope` in `++abut`. If
751+you've glanced at the ford code in general, you've probably seen cope
752+over and over. It is called in 79 different places. We need to discuss
753+the use of this critical function in detail, so we may as well do it
754+here.
726755
727756 ++ cope :: bolt along
728757 |* [hoc=(bolt) fun=(burg)]
@@ -738,36 +767,40 @@ detail, so we may as well do it here.
738767 %0 [%0 p=(grom `_p.q.nuf`p.q.hoc p.q.nuf) q=q.q.nuf]
739768 == ==
740769
741−In monad-speak, this is the bind operator for the bolt monad. If monads aren't
742−your thing, don't worry, we're going to explain the use of cope without further
743−reference to them.
744−
745−Recall that there are three different types of bolt. A `%2` error bolt contains
746−a list of tanks describing the error, a `%1` block bolt contains a set of
747−resources we're blocked on, and a `%0` value bolt contains an actual value and
748−the set of its dependencies.
749−
750−We most commonly want to perform an operation on the value in a bolt if it is a
751−`%0` bolt. If it's not a `%0` bolt, we want to leave it alone. This requires us
752−to write a certain amount of boilerplate between each of our operations to see
753−if any of them produced a `%1` or a `%2` bolt. This gets tiresome, so we pull it
754−out into a separate arm and call it `++cope`.
755−
756−Intuitively, we're calling the function `fun` with the value in `hoc`, where
757−`fun` takes an argument of type whatever is the value in a `%0` case of `hoc`,
758−and it produces a bolt of some (possibly different) type. For brevity, we will
759−refer to the type of the of the value in the `%0` case of a bolt as the "type of
760−the bolt".
761−
762−If the `hoc` bolt we're given as input to `fun` is already a `%1` or a `%2`
763−bolt, then we simply produce that. We don't even try to run `fun` on it.
764−
765−Otherwise, we run `fun` with the arguments from the bolt and, if it produces a
766−`%1` or a `%2` bolt, we simply produce that. If it produces a `%0` bolt, then we
767−produce that with the old set of dependencies merged in with the new set.
768−
769−We'll see more about how the bolt monad works as we run into more interesting
770−uses of it. For now, this is sufficient to move on with `++abut`.
770+In monad-speak, this is the bind operator for the bolt monad. If monads
771+aren't your thing, don't worry, we're going to explain the use of cope
772+without further reference to them.
773+
774+Recall that there are three different types of bolt. A `%2` error bolt
775+contains a list of tanks describing the error, a `%1` block bolt
776+contains a set of resources we're blocked on, and a `%0` value bolt
777+contains an actual value and the set of its dependencies.
778+
779+We most commonly want to perform an operation on the value in a bolt if
780+it is a `%0` bolt. If it's not a `%0` bolt, we want to leave it alone.
781+This requires us to write a certain amount of boilerplate between each
782+of our operations to see if any of them produced a `%1` or a `%2` bolt.
783+This gets tiresome, so we pull it out into a separate arm and call it
784+`++cope`.
785+
786+Intuitively, we're calling the function `fun` with the value in `hoc`,
787+where `fun` takes an argument of type whatever is the value in a `%0`
788+case of `hoc`, and it produces a bolt of some (possibly different) type.
789+For brevity, we will refer to the type of the of the value in the `%0`
790+case of a bolt as the "type of the bolt".
791+
792+If the `hoc` bolt we're given as input to `fun` is already a `%1` or a
793+`%2` bolt, then we simply produce that. We don't even try to run `fun`
794+on it.
795+
796+Otherwise, we run `fun` with the arguments from the bolt and, if it
797+produces a `%1` or a `%2` bolt, we simply produce that. If it produces a
798+`%0` bolt, then we produce that with the old set of dependencies merged
799+in with the new set.
800+
801+We'll see more about how the bolt monad works as we run into more
802+interesting uses of it. For now, this is sufficient to move on with
803+`++abut`.
771804
772805 ++ abut :: generate
773806 |= [cof=cafe hyd=hood]
@@ -783,17 +816,18 @@ uses of it. For now, this is sufficient to move on with `++abut`.
783816 |= [cof=cafe fin=vase]
784817 (fine cof fin)
785818
786−Our job is simple: we must assemble a hood file into a vase. Hopefully, the
787−usage of `++cope` is fairly understandable. The correct way to read this is that
788−it does essentially five things.
819+Our job is simple: we must assemble a hood file into a vase. Hopefully,
820+the usage of `++cope` is fairly understandable. The correct way to read
821+this is that it does essentially five things.
789822
790−First, we call `++apex` to process the structures, libraries, and body. This
791−changes our state, so we set our context to the produced context. Second, we
792−call `++able` to assemble the strucutres and libraries into a twig, which we
793−slap against zuse with `++maim`. Third, we call `++chap` to process the
794−resources in the context of the already-loaded structures and libraries. Fourth,
795−we slap the body against the structures, libraries, and resources. Fifth and
796−finally, we produce the resultant vase.
823+First, we call `++apex` to process the structures, libraries, and body.
824+This changes our state, so we set our context to the produced context.
825+Second, we call `++able` to assemble the strucutres and libraries into a
826+twig, which we slap against zuse with `++maim`. Third, we call `++chap`
827+to process the resources in the context of the already-loaded structures
828+and libraries. Fourth, we slap the body against the structures,
829+libraries, and resources. Fifth and finally, we produce the resultant
830+vase.
797831
798832 ++ apex :: build to body
799833 |= [cof=cafe hyd=hood]
@@ -818,9 +852,9 @@ Otherwise, we produce and error with `++flaw`.
818852
819853This produces a `%2` error bolt from a list of tanks. Fairly trivial.
820854
821−We should be starting to get used to the cope syntax, so we can see that we
822−really only do three things here. We process the body with `++body`, the
823−libraries with `++neck`, and the structures with `++head`.
855+We should be starting to get used to the cope syntax, so we can see that
856+we really only do three things here. We process the body with `++body`,
857+the libraries with `++neck`, and the structures with `++head`.
824858
825859 ++ body :: produce functions
826860 |= [cof=cafe src=(list hoop)]
@@ -830,19 +864,19 @@ libraries with `++neck`, and the structures with `++head`.
830864 |= [cof=cafe sel=_..body]
831865 ^$(cof cof, src t.src, ..body sel)
832866
833−We must process a list of hoops that represent our body. If there are no more
834−hoops, we just produce our context in a `%0` bolt with `++fine`.
867+We must process a list of hoops that represent our body. If there are no
868+more hoops, we just produce our context in a `%0` bolt with `++fine`.
835869
836870 ++ fine |* [a=cafe b=*] :: bolt from data
837871 [p=`cafe`a q=[%0 p=*(set beam) q=b]] ::
838872
839−In monad-speak, this is the return operator. For us, this just means that we're
840−producing a `%0` bolt, which contains a path and a set of dependencies. We
841−assume there are no dependencies for the given data, or that they will be added
842−later.
873+In monad-speak, this is the return operator. For us, this just means
874+that we're producing a `%0` bolt, which contains a path and a set of
875+dependencies. We assume there are no dependencies for the given data, or
876+that they will be added later.
843877
844−If there are more hoops in `++body`, we call `++wilt` to process an individual
845−hoop and recurse.
878+If there are more hoops in `++body`, we call `++wilt` to process an
879+individual hoop and recurse.
846880
847881 ++ wilt :: process body entry
848882 |= [cof=cafe hop=hoop]
@@ -882,22 +916,24 @@ hoop and recurse.
882916 (fine cof sel(boy [[%brcn mav] boy]))
883917 ==
884918
885−In the case of a direct twig hoop, we just push it onto `boy` and we're done. In
886−the case of an indirect hoop, we must compile the referenced file.
919+In the case of a direct twig hoop, we just push it onto `boy` and we're
920+done. In the case of an indirect hoop, we must compile the referenced
921+file.
887922
888−First, we push onto the stack trace a message indicating which file exactly
889−we're compiling at the moment with `++cool`.
923+First, we push onto the stack trace a message indicating which file
924+exactly we're compiling at the moment with `++cool`.
890925
891926 ++ cool :: error caption
892927 |* [cyt=trap hoc=(bolt)]
893928 ?. ?=(%2 -.q.hoc) hoc
894929 [p.hoc [%2 *cyt p.q.hoc]]
895930
896−If an error occurred in computing `hoc`, we put the bunt of `cyt` onto the stack
897−trace. Thus, `cyt` is not evaluated at all unless an error occurred.
931+If an error occurred in computing `hoc`, we put the bunt of `cyt` onto
932+the stack trace. Thus, `cyt` is not evaluated at all unless an error
933+occurred.
898934
899−Next in `++wilt`, we load the information about the filesystem node referenced
900−by the hoop with `++lend`.
935+Next in `++wilt`, we load the information about the filesystem node
936+referenced by the hoop with `++lend`.
901937
902938 ++ lend :: load arch
903939 |= [cof=cafe bem=beam]
@@ -906,27 +942,28 @@ by the hoop with `++lend`.
906942 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
907943 (fine cof ((hard arch) (need u.von)))
908944
909−This is a simple call to the namespace. If the resource does not yet exist, we
910−block on it by producing a `%1` bolt. Otherwise, we cast it to an arch and
911−produce this.
945+This is a simple call to the namespace. If the resource does not yet
946+exist, we block on it by producing a `%1` bolt. Otherwise, we cast it to
947+an arch and produce this.
912948
913949Continuing in `++wilt`, we examine the produced arch. If the referenced
914−filesystem node has a `hoon` child node, then we've found the required source,
915−so we parse it with `++fade`. Recall that we referred earlier to `++fade`. The
916−salient point there is that it takes a beam, reads in the hook file there, and
917−parses it into a hood file with `++fair`.
950+filesystem node has a `hoon` child node, then we've found the required
951+source, so we parse it with `++fade`. Recall that we referred earlier to
952+`++fade`. The salient point there is that it takes a beam, reads in the
953+hook file there, and parses it into a hood file with `++fair`.
918954
919−Now, we simply recurse on `++apex` to compile the new hood. Note that, while we
920−do clear the `boy` list, we do not clear the other lists. Thus, we are
921−accumulating all the structures and libraries referenced in all the referenced
922−hook files in one group, which we will put at the top of the product.
955+Now, we simply recurse on `++apex` to compile the new hood. Note that,
956+while we do clear the `boy` list, we do not clear the other lists. Thus,
957+we are accumulating all the structures and libraries referenced in all
958+the referenced hook files in one group, which we will put at the top of
959+the product.
923960
924−After this, we put the new list of body twigs into a `=~`, push this onto our
925−old list of body twigs, and produce the result.
961+After this, we put the new list of body twigs into a `=~`, push this
962+onto our old list of body twigs, and produce the result.
926963
927−If there is no hoon file here, then we descend into each of our children until
928−we find a hoon file. First, we produce a list of all our children whose names
929−are terms with `++lark`.
964+If there is no hoon file here, then we descend into each of our children
965+until we find a hoon file. First, we produce a list of all our children
966+whose names are terms with `++lark`.
930967
931968 ++ lark :: filter arch names
932969 |= [wox=$+(span (unit ,@)) arc=arch]
@@ -939,39 +976,43 @@ are terms with `++lark`.
939976 =+ gib=(wox p.n.r.arc)
940977 ?~(gib rac [[u.gib p.n.r.arc] rac])
941978
942−We traverse the children map of `arc` to filter out those children whose names
943−aren't accepted by `wox` and produce a map from the product of `wox` to the
944−original name. `++lark` is used in many cases to parse names into other types,
945−like numbers or dates, ignoring those which do not fit the format. In `++wilt`,
946−though, we simply want to filter out those children whose names are not terms.
979+We traverse the children map of `arc` to filter out those children whose
980+names aren't accepted by `wox` and produce a map from the product of
981+`wox` to the original name. `++lark` is used in many cases to parse
982+names into other types, like numbers or dates, ignoring those which do
983+not fit the format. In `++wilt`, though, we simply want to filter out
984+those children whose names are not terms.
947985
948−Next, we will produce a map from terms to feet. Each of these feet will be
949−placed in a core named by the child name, and it will contain arms according to
950−its children. Thus, if the indirect hoop references `/path`, then to access the
951−twig defined in `/path/to/twig/hoon`, our body must refer to `twig:to`.
986+Next, we will produce a map from terms to feet. Each of these feet will
987+be placed in a core named by the child name, and it will contain arms
988+according to its children. Thus, if the indirect hoop references
989+`/path`, then to access the twig defined in `/path/to/twig/hoon`, our
990+body must refer to `twig:to`.
952991
953−If there are no more children, then we are done, so we produce our current
954−context.
992+If there are no more children, then we are done, so we produce our
993+current context.
955994
956−Else, we recurse into the left and right sides of our map. Finally, we process
957−our current entry in the map. We first recurse by calling `++wilt` one level
958−down. Thus, in the previous example, the first time we get to this point we are
959−processing `/path`, so we recurse on `++wilt` with path `/path/to`. We also
960−remove our current body from the recursion, so that we may add it back in later
961−the way we want to.
995+Else, we recurse into the left and right sides of our map. Finally, we
996+process our current entry in the map. We first recurse by calling
997+`++wilt` one level down. Thus, in the previous example, the first time
998+we get to this point we are processing `/path`, so we recurse on
999+`++wilt` with path `/path/to`. We also remove our current body from the
1000+recursion, so that we may add it back in later the way we want to.
9621001
963−After recursing, we push the new body onto our map, keyed by its name. We also
964−produce the new context so that all external structures, libraries, and
965−resources are collected into the same place.
1002+After recursing, we push the new body onto our map, keyed by its name.
1003+We also produce the new context so that all external structures,
1004+libraries, and resources are collected into the same place.
9661005
967−Finally, we have a map of names to feet. If this map is empty, then there were
968−no twigs at the requested path, so we give an error with `++flaw`.
1006+Finally, we have a map of names to feet. If this map is empty, then
1007+there were no twigs at the requested path, so we give an error with
1008+`++flaw`.
9691009
970−If the map is nonempty, then we finally produce our context with with one thing
971−pushed onto the front: a core made out of the map we just produced.
1010+If the map is nonempty, then we finally produce our context with with
1011+one thing pushed onto the front: a core made out of the map we just
1012+produced.
9721013
973−This concludes our discussion of `++wilt` and `++body`. Thus, it remains in
974−`++apex` to discuss `++neck` and `++head`.
1014+This concludes our discussion of `++wilt` and `++body`. Thus, it remains
1015+in `++apex` to discuss `++neck` and `++head`.
9751016
9761017 ++ neck :: consume libraries
9771018 |= [cof=cafe bir=(list hoof)]
@@ -999,24 +1040,26 @@ This concludes our discussion of `++wilt` and `++body`. Thus, it remains in
9991040 ==
10001041 ^^$(cof cof, bir t.bir)
10011042
1002−Here, we're going to consume the list of libraries and place them in `bil`. If
1003−there are no more libraries, we're done, so we just produce our current context.
1043+Here, we're going to consume the list of libraries and place them in
1044+`bil`. If there are no more libraries, we're done, so we just produce
1045+our current context.
10041046
1005−Otherwise, we check to see if the next library in the list is in `zeg`. If so,
1006−then this library is one of the libraries that we're already in the middle of
1007−compiling. There is a circular dependency, so we fail.
1047+Otherwise, we check to see if the next library in the list is in `zeg`.
1048+If so, then this library is one of the libraries that we're already in
1049+the middle of compiling. There is a circular dependency, so we fail.
10081050
10091051Otherwise, we let `gez` be `zeg` plus the current library so that while
1010−compiling the dependencies of this library we don't later create a circular
1011−dependency. We check next to see if this library is alredy in `bil`. If so, then
1012−we have already included this library earlier, so we check to see if this is the
1013−same version of the library as we included earlier. If so, we skip it. Else, we
1014−fail since we can't include two different versions of a library. We really
1015−should allow for newer versions of a library since in kelvin versioning we
1016−assume backwards compatibility, but for now we require an exact match.
1017−
1018−If we haven't already included this library, then we're going to do that. First,
1019−we get the location of the library with `++hone`.
1052+compiling the dependencies of this library we don't later create a
1053+circular dependency. We check next to see if this library is alredy in
1054+`bil`. If so, then we have already included this library earlier, so we
1055+check to see if this is the same version of the library as we included
1056+earlier. If so, we skip it. Else, we fail since we can't include two
1057+different versions of a library. We really should allow for newer
1058+versions of a library since in kelvin versioning we assume backwards
1059+compatibility, but for now we require an exact match.
1060+
1061+If we haven't already included this library, then we're going to do
1062+that. First, we get the location of the library with `++hone`.
10201063
10211064 ++ hone :: plant hoof
10221065 |= [for=@tas way=@tas huf=hoof]
@@ -1025,27 +1068,28 @@ we get the location of the library with `++hone`.
10251068 how(s ~[for p.huf way])
10261069 [[q.u.q.huf %main p.u.q.huf] ~[for p.huf way]]
10271070
1028−If we haven't specified the version of the library, we use the current ship,
1029−desk, and case. Otherwise, we use the given ship and case on desk `%main`. In
1030−either case, the path is `/way/p.huf/for`. In the case of `++neck`, this means
1031−`/lib/core/[library name]`.
1032−
1033−In `++neck`, we next compile the hook file at that location with `++fade`.
1034−Again, we will delay the discussion of `++fade`, noting only that it takes a
1035−beam and parses the hook file there into a hood.
1036−
1037−We recurse on this to compile the library. During the compilation, we let `zeg`
1038−be `gez` to avoid circular dependencies, we let `hol` be false since we don't
1039−allow horns in libraries, and we let `boy` be null so that we can isolate the
1040−new body twigs.
1041−
1042−Next, we reintegrate the new data into our context. We use the context created
1043−by the recursion with four changes. First, we reset `zeg` to our old `zeg`.
1044−Second, we reset `hol` to our old `hol`. Third, we put the name of our library
1045−onto the stack of libraries. This means all of a libraries dependencies will be
1046−earlier in `lot` than the library itself, making `lot` a topological ordering on
1047−the dependency graph. Fourth, we put in `bil` the library hoof and body (with
1048−all body twigs collected in a `=~`), keyed by the library name.
1071+If we haven't specified the version of the library, we use the current
1072+ship, desk, and case. Otherwise, we use the given ship and case on desk
1073+`%main`. In either case, the path is `/way/p.huf/for`. In the case of
1074+`++neck`, this means `/lib/core/[library name]`.
1075+
1076+In `++neck`, we next compile the hook file at that location with
1077+`++fade`. Again, we will delay the discussion of `++fade`, noting only
1078+that it takes a beam and parses the hook file there into a hood.
1079+
1080+We recurse on this to compile the library. During the compilation, we
1081+let `zeg` be `gez` to avoid circular dependencies, we let `hol` be false
1082+since we don't allow horns in libraries, and we let `boy` be null so
1083+that we can isolate the new body twigs.
1084+
1085+Next, we reintegrate the new data into our context. We use the context
1086+created by the recursion with four changes. First, we reset `zeg` to our
1087+old `zeg`. Second, we reset `hol` to our old `hol`. Third, we put the
1088+name of our library onto the stack of libraries. This means all of a
1089+libraries dependencies will be earlier in `lot` than the library itself,
1090+making `lot` a topological ordering on the dependency graph. Fourth, we
1091+put in `bil` the library hoof and body (with all body twigs collected in
1092+a `=~`), keyed by the library name.
10491093
10501094Finally, we recurse, processing the next library in our list.
10511095
@@ -1084,36 +1128,38 @@ To complete our disucssion of `++apex`, we must process our structures.
10841128 ==
10851129 ^^$(cof cof, bir t.bir)
10861130
1087−The processing of our structures is very similar to that of our libraries. For
1088−clarity, we'll use many of the same phrases in describing the parallel natures.
1089−First, we check to see if there are more structures to process. If not, we're
1090−done, so we produce our context.
1091−
1092−Otherwise, we let `goz` be `zog` plus the current structure so that while
1093−compiling the dependencies of this structure we don't later create a circular
1094−dependency. We check next to see if this structure is alredy in `rop`. If so,
1095−then we have already included this structure earlier, so we check to see if this
1096−is the same version of the structure as we included earlier. If so, we skip it.
1097−Else, we fail since we can't include two different versions of a structure.
1098−
1099−If we haven't loaded this structure, then we call `++hone` to get the beam where
1100−the file structure should be. If the loobean in the hoot is true, then we're
1101−looking for a gate; otherwise, we're looking for a core. We parse this file with
1102−`++fade`.
1103−
1104−Now, we recurse on this to compile the structure. During the recursion, there we
1105−have threee changes. Frist, we let `zog` be `goz` so that we don't create a
1106−circular dependency. Second, we let `hol` be false since we do not allow horns
1107−in structures. Third, we let `boy` be null so that we can isolate the new body
1108−twigs.
1109−
1110−Next, we reintegrate the new data into our context. We use the context cretaed
1111−by the recursion with four changes. First, if we're including a gate structure,
1112−then we reset the body to its original body. Else we put on the top of our list
1113−of body twigs what is essentially a `=+ structure-name` to take off the face of
1114−the structure. Second, we reset `zog` to our old `zog`. Third, we reset `hol` to
1115−our old `hol`. Finally, we put in `rop` the structure hoof and body (with all
1116−body twiggs collected in a `=~`), keyed by the structure name.
1131+The processing of our structures is very similar to that of our
1132+libraries. For clarity, we'll use many of the same phrases in describing
1133+the parallel natures. First, we check to see if there are more
1134+structures to process. If not, we're done, so we produce our context.
1135+
1136+Otherwise, we let `goz` be `zog` plus the current structure so that
1137+while compiling the dependencies of this structure we don't later create
1138+a circular dependency. We check next to see if this structure is alredy
1139+in `rop`. If so, then we have already included this structure earlier,
1140+so we check to see if this is the same version of the structure as we
1141+included earlier. If so, we skip it. Else, we fail since we can't
1142+include two different versions of a structure.
1143+
1144+If we haven't loaded this structure, then we call `++hone` to get the
1145+beam where the file structure should be. If the loobean in the hoot is
1146+true, then we're looking for a gate; otherwise, we're looking for a
1147+core. We parse this file with `++fade`.
1148+
1149+Now, we recurse on this to compile the structure. During the recursion,
1150+there we have threee changes. Frist, we let `zog` be `goz` so that we
1151+don't create a circular dependency. Second, we let `hol` be false since
1152+we do not allow horns in structures. Third, we let `boy` be null so that
1153+we can isolate the new body twigs.
1154+
1155+Next, we reintegrate the new data into our context. We use the context
1156+cretaed by the recursion with four changes. First, if we're including a
1157+gate structure, then we reset the body to its original body. Else we put
1158+on the top of our list of body twigs what is essentially a
1159+`=+ structure-name` to take off the face of the structure. Second, we
1160+reset `zog` to our old `zog`. Third, we reset `hol` to our old `hol`.
1161+Finally, we put in `rop` the structure hoof and body (with all body
1162+twiggs collected in a `=~`), keyed by the structure name.
11171163
11181164Finally, we recurse, processing the next structure in our list.
11191165
@@ -1133,9 +1179,9 @@ This concludes our discussion of `++apex`.
11331179 |= [cof=cafe fin=vase]
11341180 (fine cof fin)
11351181
1136−Returning to `++abut`, we have now processed the structures, libraries and body
1137−twigs. Next, we slap our preamble (structures and libraries) against zuse.
1138−First, we construct our preamble in `++able`.
1182+Returning to `++abut`, we have now processed the structures, libraries
1183+and body twigs. Next, we slap our preamble (structures and libraries)
1184+against zuse. First, we construct our preamble in `++able`.
11391185
11401186 ++ able :: assemble preamble
11411187 ^- twig
@@ -1143,10 +1189,10 @@ First, we construct our preamble in `++able`.
11431189 ?:(=(~ rop) [%$ 1] [%brcn (~(run by rop) |=([* a=twig] [%ash a]))])
11441190 [%tssg (turn (flop lot) |=(a=term q:(need (~(get by bil) a))))]
11451191
1146−We first put the structures in `rop` into a single `|%` at the top and `=>` it
1147−onto a `=~` of our libraries, in the reverse order that they appear in `lot`.
1148−Thus, the structures are in a single core while the libraries are in consecutive
1149−cores.
1192+We first put the structures in `rop` into a single `|%` at the top and
1193+`=>` it onto a `=~` of our libraries, in the reverse order that they
1194+appear in `lot`. Thus, the structures are in a single core while the
1195+libraries are in consecutive cores.
11501196
11511197We slap the preamble against zuse with `++maim`.
11521198
@@ -1163,47 +1209,49 @@ We slap the preamble against zuse with `++maim`.
11631209 `vase`[p.p.puz val]
11641210 ==
11651211
1166−Here we start to get into ford's caching system. We wrap our computation in a
1167−call to `++clef` so that we only actually compute it if the result is not
1168−already in our cache. First we'll discuss the computation, then we'll discuss
1169−the caching system.
1212+Here we start to get into ford's caching system. We wrap our computation
1213+in a call to `++clef` so that we only actually compute it if the result
1214+is not already in our cache. First we'll discuss the computation, then
1215+we'll discuss the caching system.
11701216
1171−We call `++mule` with a call to `++mint:ut` on the type of our subject vase
1172−against the given twig. In other words, we're compiling the twig with against
1173−the subject type in the given subject vase.
1217+We call `++mule` with a call to `++mint:ut` on the type of our subject
1218+vase against the given twig. In other words, we're compiling the twig
1219+with against the subject type in the given subject vase.
11741220
1175−If compilation fails, then we produce an error bolt with the produced stack
1176−trace. Otherwise, we run the produced nock with `++mock` and our sky function.
1177−We convert the produced toon to a bolt with `++coup` and use the type from `puz`
1178−combined with the value from `mock` to produce our vase.
1221+If compilation fails, then we produce an error bolt with the produced
1222+stack trace. Otherwise, we run the produced nock with `++mock` and our
1223+sky function. We convert the produced toon to a bolt with `++coup` and
1224+use the type from `puz` combined with the value from `mock` to produce
1225+our vase.
11791226
1180−If this process seems harder than just calling `++slap`, it's because it is. We
1181−have two requirements that `++slap` doesn't satisfy. First, we want the to use
1182−an explicit sky function for use with `.^`. With `++slap`, you get whatever sky
1183−function is available in the calling context, which in ford is none. Second, we
1184−want to explicitly handle the stack trace on failure. `++slap` would cause crash
1185−on failure.
1227+If this process seems harder than just calling `++slap`, it's because it
1228+is. We have two requirements that `++slap` doesn't satisfy. First, we
1229+want the to use an explicit sky function for use with `.^`. With
1230+`++slap`, you get whatever sky function is available in the calling
1231+context, which in ford is none. Second, we want to explicitly handle the
1232+stack trace on failure. `++slap` would cause crash on failure.
11861233
1187−We haven't yet discussed either `++clef` or `++coup`. We'll start with `++coup`
1188−to finish the discussion of the computation.
1234+We haven't yet discussed either `++clef` or `++coup`. We'll start with
1235+`++coup` to finish the discussion of the computation.
11891236
11901237\``++ coup :: toon to bolt |= cof=cafe |* [ton=toon fun=$+(* *)] :- p=cof ^= q ?- -.ton %2 [%2 p=p.ton] %0 [%0 p=*(set beam) q=(fun p.ton)] %1 ~& [%coup-need ((list path) p.ton)] =- ?- -.faw & [%1 p=(sa (turn p.faw |=(a=beam [a *(list tank)])))] | [%2 p=p.faw] == ^= faw |- ^- (each (list beam) (list tank)) ?~ p.ton [%& ~] =+ nex=$(p.ton t.p.ton) =+ pax=(path i.p.ton) ?~ pax [%| (smyt pax) ?:(?=(& -.nex) ~ p.nex)] =+ zis=(tome t.pax) ?~ zis [%| (smyt pax) ?:(?=(& -.nex) ~ p.nex)] ?- -.nex & [%& u.zis p.nex] | nex == ==`
11911238
1192−Recall that a toon is either a `%0` value, a `%1` block, or a `%2` failure.
1193−Converting a `%2` toon failure into a `%2` bolt failure is trivial. Converting a
1194−`%0` toon value into a `%0` bolt value is easy since we assume there were no
1195−dependencies. Converting the blocks is rather more difficult.
1239+Recall that a toon is either a `%0` value, a `%1` block, or a `%2`
1240+failure. Converting a `%2` toon failure into a `%2` bolt failure is
1241+trivial. Converting a `%0` toon value into a `%0` bolt value is easy
1242+since we assume there were no dependencies. Converting the blocks is
1243+rather more difficult.
11961244
1197−To compute `faw`, we recurse through the list of paths in the `%1` toon. At each
1198−one, we make sure with `++tome` that it is, in fact, a beam. If so, then we
1199−check to see if the later paths succeed as well. If so, we append the current
1200−path to the list of other paths. If not, we produce the error message we got
1201−from processing the rest of the paths. If this path is not a beam, then we fail,
1202−producing a list of tanks including this path and, if later paths fail too,
1203−those paths as well.
1245+To compute `faw`, we recurse through the list of paths in the `%1` toon.
1246+At each one, we make sure with `++tome` that it is, in fact, a beam. If
1247+so, then we check to see if the later paths succeed as well. If so, we
1248+append the current path to the list of other paths. If not, we produce
1249+the error message we got from processing the rest of the paths. If this
1250+path is not a beam, then we fail, producing a list of tanks including
1251+this path and, if later paths fail too, those paths as well.
12041252
1205−If some paths were not beams, then we produce a `%2` error bolt. If all paths
1206−were correct, then we produce a `%1` blocking bolt.
1253+If some paths were not beams, then we produce a `%2` error bolt. If all
1254+paths were correct, then we produce a `%1` blocking bolt.
12071255
12081256We will now discuss `++clef`. This is where the cache magic happens.
12091257
@@ -1238,28 +1286,29 @@ Otherwise, we look up the request in the cache with `++calk`.
12381286 ?~ d [~ a] ::
12391287 [d a(p (~(put in p.a) u.d))] ::
12401288
1241−When looking up something in the cache, we mark it if we find it. This way, we
1242−have in our cache the set of all cache entries that have been referenced. While
1243−we do not at present do anything with this data, it should be used to clear out
1244−old and unused entries in the cache.
1289+When looking up something in the cache, we mark it if we find it. This
1290+way, we have in our cache the set of all cache entries that have been
1291+referenced. While we do not at present do anything with this data, it
1292+should be used to clear out old and unused entries in the cache.
12451293
1246−Moving on in `++clef`, we check to see if we actually found anything. If we
1247−didn't find a cache entry, then we run the computation in `fun`, and examine its
1248−result. If it produced a `%2` error or `%1` block bolt, we just pass that
1249−through. Otherwise, we produce both the value and an updated cache with this new
1250−entry. We add the entry with `++came`.
1294+Moving on in `++clef`, we check to see if we actually found anything. If
1295+we didn't find a cache entry, then we run the computation in `fun`, and
1296+examine its result. If it produced a `%2` error or `%1` block bolt, we
1297+just pass that through. Otherwise, we produce both the value and an
1298+updated cache with this new entry. We add the entry with `++came`.
12511299
12521300 ++ came ::
12531301 |= [a=cafe b=calx] :: cache install
12541302 ^- cafe ::
12551303 a(q (~(put by q.a) [-.b q.b] b)) ::
12561304
1257−We key cache entries by the type of computation (`-:calx`) and the inputs to the
1258−computation (`q:calc`). This just puts the cache line in the cache at the
1259−correct key.
1305+We key cache entries by the type of computation (`-:calx`) and the
1306+inputs to the computation (`q:calc`). This just puts the cache line in
1307+the cache at the correct key.
12601308
1261−Back in `++clef`, if we did find a cache entry, then we just produce the value
1262−at that cache line. We convert the cache line into a value with `++calf`.
1309+Back in `++clef`, if we did find a cache entry, then we just produce the
1310+value at that cache line. We convert the cache line into a value with
1311+`++calf`.
12631312
12641313 ++ calf :: reduce calx
12651314 |* sem=* :: a typesystem hack
@@ -1270,22 +1319,23 @@ at that cache line. We convert the cache line into a value with `++calf`.
12701319 %slam ?>(?=(%slam -.cax) r.cax)
12711320 ==
12721321
1273−This is simply a typesystem hack. Because the `sem` is passed in through a wet
1274−gate, we know at type time which of the three cases will be chosen. Thus, the
1275−correct type of the value in the cache line gets passed through to the caller.
1276−This also depends on the fact that `++clef` is wet. The type stuff here is
1277−mathematically interesting, but the action is simple: we get the value from the
1278−cache line.
1322+This is simply a typesystem hack. Because the `sem` is passed in through
1323+a wet gate, we know at type time which of the three cases will be
1324+chosen. Thus, the correct type of the value in the cache line gets
1325+passed through to the caller. This also depends on the fact that
1326+`++clef` is wet. The type stuff here is mathematically interesting, but
1327+the action is simple: we get the value from the cache line.
12791328
12801329This concludes our discussion of `++clef` and `++maim`.
12811330
1282−Back in `++abut`, recall that we processed the structures, libraries, and body
1283−with `++apex`. Then, we slapped our preamble (structures and libraries) against
1284−zuse with `++maim`. Next, we process our resources with `++chap`. Note that we
1285−pass in the preamble so that we may refer to anything in there in our resources.
1331+Back in `++abut`, recall that we processed the structures, libraries,
1332+and body with `++apex`. Then, we slapped our preamble (structures and
1333+libraries) against zuse with `++maim`. Next, we process our resources
1334+with `++chap`. Note that we pass in the preamble so that we may refer to
1335+anything in there in our resources.
12861336
1287−`++chap` is broken up into a different case for each horn. We'll go through them
1288−one by one.
1337+`++chap` is broken up into a different case for each horn. We'll go
1338+through them one by one.
12891339
12901340 ++ chap :: produce resources
12911341 |= [cof=cafe bax=vase hon=horn]
@@ -1300,9 +1350,9 @@ This is `/~`. We slap the twig against our context.
13001350 |= [cof=cafe gat=vase]
13011351 (maul cof gat !>([how arg]))
13021352
1303−This is `/$`. We slap the twig against our context, which we expect to produce a
1304−gate. We slam this gate with a sample of `how` and `arg`, which is our location
1305−and the heel (virtual path extension).
1353+This is `/$`. We slap the twig against our context, which we expect to
1354+produce a gate. We slam this gate with a sample of `how` and `arg`,
1355+which is our location and the heel (virtual path extension).
13061356
13071357`++maul` is similar to `++maim`, but it slams instead of slaps.
13081358
@@ -1319,19 +1369,20 @@ and the heel (virtual path extension).
13191369 `vase`[p.top val]
13201370 ==
13211371
1322−We cache slams exactly as we cache slaps. We use `++slit` to find the type of
1323−the product of the slam given the types of the gate and the sample.
1372+We cache slams exactly as we cache slaps. We use `++slit` to find the
1373+type of the product of the slam given the types of the gate and the
1374+sample.
13241375
1325−If this type fails, we produce the given stack trace as a `%2` error bolt.
1326−Otherwise, we produce the top produced above combined with the value we get from
1327−slamming the values in the vases with `++mong`.
1376+If this type fails, we produce the given stack trace as a `%2` error
1377+bolt. Otherwise, we produce the top produced above combined with the
1378+value we get from slamming the values in the vases with `++mong`.
13281379
13291380Back to `++chap`.
13301381
13311382 %day (chad cof bax %dr p.hon)
13321383
1333−This is `/|`. We call `++chad` to convert textual names to relative dates and
1334−process the next horn against each of the discovered paths.
1384+This is `/|`. We call `++chad` to convert textual names to relative
1385+dates and process the next horn against each of the discovered paths.
13351386
13361387 ++ chad :: atomic list
13371388 |= [cof=cafe bax=vase doe=term hon=horn]
@@ -1355,8 +1406,8 @@ process the next horn against each of the discovered paths.
13551406 ?~ yal [[%cube 0 [%atom %n]] 0]
13561407 (slop (slop [[%atom doe] p.i.yal] q.i.yal) $(yal t.yal))
13571408
1358−First, we call `++lash` to parse the children of the current beam and pick out
1359−those ones that are of the requested format.
1409+First, we call `++lash` to parse the children of the current beam and
1410+pick out those ones that are of the requested format.
13601411
13611412 ++ lash :: atomic sequence
13621413 |= wox=$+(span (unit ,@))
@@ -1366,22 +1417,26 @@ those ones that are of the requested format.
13661417 |= [cof=cafe arc=arch]
13671418 (fine cof (lark wox arc))
13681419
1369−First, we get the arch with `++lend`, as described above. We filter and parse
1370−the child names with `++lark` according to the given parser function.
1420+First, we get the arch with `++lend`, as described above. We filter and
1421+parse the child names with `++lark` according to the given parser
1422+function.
13711423
1372−In `++chad`, this parser function is `(slat doe)`, which will parse a cord into
1373−an atom of the requested odor. For `%day` the odor is for relative dates.
1424+In `++chad`, this parser function is `(slat doe)`, which will parse a
1425+cord into an atom of the requested odor. For `%day` the odor is for
1426+relative dates.
13741427
1375−Thus, we now have a map from atoms of the given odor to the actual child names.
1376−We next turn this map into a list and sort it in increasing order by the atom.
1428+Thus, we now have a map from atoms of the given odor to the actual child
1429+names. We next turn this map into a list and sort it in increasing order
1430+by the atom.
13771431
1378−We next convert this list of pairs of atoms and spans to a list of pairs of
1379−atoms and vases. We process the given horn once at every child beam, producing
1380−the resource at that location.
1432+We next convert this list of pairs of atoms and spans to a list of pairs
1433+of atoms and vases. We process the given horn once at every child beam,
1434+producing the resource at that location.
13811435
1382−Finally, we convert this list of pairs of atoms and vases to a vase of a list of
1383−pairs of atoms to (well-typed) values. Each entry in the list is of type atom
1384−with the given odor combined with the type of the produced vase.
1436+Finally, we convert this list of pairs of atoms and vases to a vase of a
1437+list of pairs of atoms to (well-typed) values. Each entry in the list is
1438+of type atom with the given odor combined with the type of the produced
1439+vase.
13851440
13861441Back in `++chap`, we continue parsing resources.
13871442
@@ -1390,8 +1445,8 @@ Back in `++chap`, we continue parsing resources.
13901445 |= [cof=cafe vax=vase]
13911446 (fine cof [[%face p.hon p.vax] q.vax])
13921447
1393−This is `/=`. We process the given horn, giving us a vase. We put as a face on
1394−the vase so that it may be referred to later by name.
1448+This is `/=`. We process the given horn, giving us a vase. We put as a
1449+face on the vase so that it may be referred to later by name.
13951450
13961451 %fan
13971452 %+ cope
@@ -1408,21 +1463,21 @@ the vase so that it may be referred to later by name.
14081463 ?~ tev [[%cube 0 [%atom %n]] 0]
14091464 (slop i.tev $(tev t.tev))
14101465
1411−This is `/.`. We first process each of the child horns, producing a list of
1412−vases. This is done by just recursing on `++chap`. Then, we simply fold over
1413−this list to create a vase of the list of values.
1466+This is `/.`. We first process each of the child horns, producing a list
1467+of vases. This is done by just recursing on `++chap`. Then, we simply
1468+fold over this list to create a vase of the list of values.
14141469
14151470 %for $(hon q.hon, s.how (weld (flop p.hon) s.how))
14161471
1417−This is `/,`. We simply recurse on the horn with the given path welded onto our
1418−current beam.
1472+This is `/,`. We simply recurse on the horn with the given path welded
1473+onto our current beam.
14191474
14201475 %hub (chad cof bax %ud p.hon)
14211476
1422−This is `/@`. This is exactly like the processing of `%day` except we expect the
1423−children to be named as unsigned integers rather than relative dates. We process
1424−the horn at each of the children's locations and produce a list of pairs of
1425−absolute dates and values.
1477+This is `/@`. This is exactly like the processing of `%day` except we
1478+expect the children to be named as unsigned integers rather than
1479+relative dates. We process the horn at each of the children's locations
1480+and produce a list of pairs of absolute dates and values.
14261481
14271482 %man
14281483 |- ^- (bolt vase)
@@ -1438,20 +1493,21 @@ absolute dates and values.
14381493 (slop [[%atom %tas] p.n.p.hon] vax)
14391494 (slop lef rig)
14401495
1441−This is `/*`. We process each of the horns in the given map by recursion through
1442−`++chap`. Once we have these vases, we create a vase of a map from the given
1443−textual names to the produced values.
1496+This is `/*`. We process each of the horns in the given map by recursion
1497+through `++chap`. Once we have these vases, we create a vase of a map
1498+from the given textual names to the produced values.
14441499
14451500 %now (chad cof bax %da p.hon)
14461501
1447−This is `/&`. This is exactly like the processing of `%now` except we expect the
1448−children to be names as absolute dates rather than relative dates. We process
1449−the horn at each of the children's locations and produce a list of pairs of
1450−absolute dates and values.
1502+This is `/&`. This is exactly like the processing of `%now` except we
1503+expect the children to be names as absolute dates rather than relative
1504+dates. We process the horn at each of the children's locations and
1505+produce a list of pairs of absolute dates and values.
14511506
14521507 %nap (chai cof bax p.hon)
14531508
1454−This is `/%`. Here, we process the horn at each of our children with `++chai`.
1509+This is `/%`. Here, we process the horn at each of our children with
1510+`++chai`.
14551511
14561512 ++ chai :: atomic map
14571513 |= [cof=cafe bax=vase hon=horn]
@@ -1476,10 +1532,10 @@ This is `/%`. Here, we process the horn at each of our children with `++chai`.
14761532 (slop [[%atom %a] p.n.doy] q.n.doy)
14771533 (slop $(doy l.doy) $(doy r.doy))
14781534
1479−We get the arch at our current beam with `++lend`. Then, we process the horn at
1480−each of our children to give us a map of atoms to vases. Finally, we convert
1481−that into a vase of a map of these atoms to the values. This is very similar to
1482−`++chad` and the handling of `%man`.
1535+We get the arch at our current beam with `++lend`. Then, we process the
1536+horn at each of our children to give us a map of atoms to vases.
1537+Finally, we convert that into a vase of a map of these atoms to the
1538+values. This is very similar to `++chad` and the handling of `%man`.
14831539
14841540 %see $(hon q.hon, how p.hon)
14851541
@@ -1492,9 +1548,9 @@ This is `/:`. We process the given horn at the given beam.
14921548 |= [cof=cafe gat=vase]
14931549 (maul cof gat sam)
14941550
1495−This is `/;`. First, we process the given horn. Then, we slap the given twig
1496−against our context to produce (hopefully) a gate. Finally, we slam the vase we
1497−got from processing the horn against the gate.
1551+This is `/;`. First, we process the given horn. Then, we slap the given
1552+twig against our context to produce (hopefully) a gate. Finally, we slam
1553+the vase we got from processing the horn against the gate.
14981554
14991555 %sic
15001556 %+ cope $(hon q.hon)
@@ -1505,26 +1561,27 @@ got from processing the horn against the gate.
15051561 (flaw cof [%leaf "type error: {<p.hon>} {<q.hon>}"]~)
15061562 (fine cof [p.tug q.vax])
15071563
1508−This is `/^`. First, we process the given horn. Then, we slap the the bunt of
1509−the given tile against our context. This will produce a vase with the correct
1510−type. We test to see if this type nests within the type of the vase we got from
1511−processing the horn. If so, we produce the value from the horn along with the
1512−type from the tile. Otherwise, we produce a `%2` error bolt.
1564+This is `/^`. First, we process the given horn. Then, we slap the the
1565+bunt of the given tile against our context. This will produce a vase
1566+with the correct type. We test to see if this type nests within the type
1567+of the vase we got from processing the horn. If so, we produce the value
1568+from the horn along with the type from the tile. Otherwise, we produce a
1569+`%2` error bolt.
15131570
15141571 %toy (cope (make cof %bake p.hon how ~) feel)
15151572 ==
15161573
1517−This is `/mark/`. Here, we simply run the `%bake` silk on the given mark,
1518−producing a cage. We convert this cage into a vase with `++feel`, which is
1519−exactly as simple as it sounds like it should be.
1574+This is `/mark/`. Here, we simply run the `%bake` silk on the given
1575+mark, producing a cage. We convert this cage into a vase with `++feel`,
1576+which is exactly as simple as it sounds like it should be.
15201577
15211578 ++ feel |=([a=cafe b=cage] (fine a q.b)) :: cage to vase
15221579
15231580This is trivial.
15241581
1525−We will discuss later `++make` and how `%bake` is processed. Suffice it to say
1526−that baking a resource with a given mark gets the resource and converts it, if
1527−necessary, to the requested mark.
1582+We will discuss later `++make` and how `%bake` is processed. Suffice it
1583+to say that baking a resource with a given mark gets the resource and
1584+converts it, if necessary, to the requested mark.
15281585
15291586This concludes our discussion of `++chap`.
15301587
@@ -1544,24 +1601,26 @@ We return once more to `++abut`.
15441601 |= [cof=cafe fin=vase]
15451602 (fine cof fin)
15461603
1547−Recall that we processed our structures, libraries and body with `++apex`. We
1548−slapped our structures and libraries against zuse with `++maim`. We processed
1549−our resources with `++chap`. Now, all our body twigs are collected in a `=~` and
1550−slapped against our structures, libraries, and resources. This produces our
1551−final result.
1604+Recall that we processed our structures, libraries and body with
1605+`++apex`. We slapped our structures and libraries against zuse with
1606+`++maim`. We processed our resources with `++chap`. Now, all our body
1607+twigs are collected in a `=~` and slapped against our structures,
1608+libraries, and resources. This produces our final result.
15521609
15531610The hook file has been assembled. And there was great rejoicing.
15541611
1555−## Lifecycle of a Kiss
1612+Lifecycle of a Kiss
1613+-------------------
15561614
1557−We're now going to go through a series of lifecycle descriptions. When a user of
1558−ford sends a kiss, it is one of a dozen different types of silk. We'll go
1559−through each one, tracing through the flow of control of each of these.
1615+We're now going to go through a series of lifecycle descriptions. When a
1616+user of ford sends a kiss, it is one of a dozen different types of silk.
1617+We'll go through each one, tracing through the flow of control of each
1618+of these.
15601619
15611620First, though, we'll describe the common handling to all kisses.
15621621
1563−The silk in a `%exec` kiss to ford ends up in `++apex`, so we'll enter the
1564−narrative here.
1622+The silk in a `%exec` kiss to ford ends up in `++apex`, so we'll enter
1623+the narrative here.
15651624
15661625 ++ apex :: call
15671626 |= kus=(unit silk)
@@ -1580,13 +1639,13 @@ narrative here.
15801639 ==
15811640 ~(exec zo [num `task`[hen u.kus 0 ~]])
15821641
1583−Recall that a `%exec` kiss actually sends a unit silk. If it's null, we're
1584−trying to cancel the request. We first look up the task number keyed by duct. If
1585−we don't find it, then we're trying to cancel a request that either was never
1586−started or has already completed. We print out `%ford-mystery` and do nothing.
1587−If we do find the task number, then we look up the task from it, call
1588−`++camo:zo` to cancel pending requests, and call `++amok:zo` to remove the task
1589−from our task lists.
1642+Recall that a `%exec` kiss actually sends a unit silk. If it's null,
1643+we're trying to cancel the request. We first look up the task number
1644+keyed by duct. If we don't find it, then we're trying to cancel a
1645+request that either was never started or has already completed. We print
1646+out `%ford-mystery` and do nothing. If we do find the task number, then
1647+we look up the task from it, call `++camo:zo` to cancel pending
1648+requests, and call `++amok:zo` to remove the task from our task lists.
15901649
15911650 ++ camo :: stop requests
15921651 ^+ .
@@ -1602,9 +1661,9 @@ from our task lists.
16021661 [%warp [our p.q.i.kiz] q.q.i.kiz ~]
16031662 ==
16041663
1605−Our list of blocks is in `q.kig`, so we iterate over it, cancelling our pending
1606−requests for each block. Our requests are all to clay, so we need only to send
1607−`%warp` kisses with a null instead of a rave.
1664+Our list of blocks is in `q.kig`, so we iterate over it, cancelling our
1665+pending requests for each block. Our requests are all to clay, so we
1666+need only to send `%warp` kisses with a null instead of a rave.
16081667
16091668 ++ amok
16101669 %_ ..zo
@@ -1612,12 +1671,12 @@ requests for each block. Our requests are all to clay, so we need only to send
16121671 dym.bay (~(del by dym.bay) nah)
16131672 ==
16141673
1615−We remove the task number from the map of numbers to tasks and the duct from the
1616−map of ducts to task numbers.
1674+We remove the task number from the map of numbers to tasks and the duct
1675+from the map of ducts to task numbers.
16171676
1618−Back in `++apex`, if we were given a silk, we need to process it. We add the
1619−task to our maps, increment the next task number, and call `++exec:zo` on the
1620−new task.
1677+Back in `++apex`, if we were given a silk, we need to process it. We add
1678+the task to our maps, increment the next task number, and call
1679+`++exec:zo` on the new task.
16211680
16221681 ++ exec :: execute app
16231682 ^+ ..zo
@@ -1638,9 +1697,9 @@ new task.
16381697
16391698If we're still blocked on something in `q.kig`, we don't do anything.
16401699
1641−Otherwise, we try to process the silk with `++make`. `++make` handles each
1642−individual request and will be the entire focus of the remainder of this doc
1643−after this section. It produces a bolt of a cage.
1700+Otherwise, we try to process the silk with `++make`. `++make` handles
1701+each individual request and will be the entire focus of the remainder of
1702+this doc after this section. It produces a bolt of a cage.
16441703
16451704We put the new cache in our state with `++dash`.
16461705
@@ -1649,12 +1708,13 @@ We put the new cache in our state with `++dash`.
16491708 ^+ +>
16501709 %_(+> jav.bay q.cof)
16511710
1652−The cache is put in the baby so that it gets stored across calls to ford.
1711+The cache is put in the baby so that it gets stored across calls to
1712+ford.
16531713
1654−In `++exec`, we process the bolt in three different ways according to the type
1655−of bolt produced. If we produced a `%0` value bolt, we use `++expo` to give the
1656−produced value and set of dependencies as a `%made` gift, and we remove
1657−ourselves from the task list with `++amok`.
1714+In `++exec`, we process the bolt in three different ways according to
1715+the type of bolt produced. If we produced a `%0` value bolt, we use
1716+`++expo` to give the produced value and set of dependencies as a `%made`
1717+gift, and we remove ourselves from the task list with `++amok`.
16581718
16591719 ++ expo :: return gift
16601720 |= gef=gift
@@ -1662,11 +1722,11 @@ ourselves from the task list with `++amok`.
16621722
16631723We simply push the gift onto our list of moves.
16641724
1665−In `++exec`, if we produced a `%2` error bolt, we produce a `%made` gift with
1666−the stack trace.
1725+In `++exec`, if we produced a `%2` error bolt, we produce a `%made` gift
1726+with the stack trace.
16671727
1668−If we produced a `%1` block bolt, we iterate through each of the blocks and call
1669−`++camp` to produce a clay request for the resource.
1728+If we produced a `%1` block bolt, we iterate through each of the blocks
1729+and call `++camp` to produce a clay request for the resource.
16701730
16711731 ++ camp :: request a file
16721732 |= [ren=care bem=beam]
@@ -1680,13 +1740,16 @@ If we produced a `%1` block bolt, we iterate through each of the blocks and call
16801740 [%warp [our p.bem] q.bem [~ %& %x r.bem s.bem]]
16811741 ==
16821742
1683−We put the resource in our block list in `q.kig` so that we save the fact that
1684−we're blocked. We then produce the `%warp` request to clay for the resource. Our
1685−request path has the format \`/\[our-ship\]/\[task-number\]/\[block-number\]'.
1743+We put the resource in our block list in `q.kig` so that we save the
1744+fact that we're blocked. We then produce the `%warp` request to clay for
1745+the resource. Our request path has the format
1746+\`/[our-ship]/[task-number]/[block-number]'.
16861747
1687−We'll now describe how each of the individual silks are processed in `++make`.
1748+We'll now describe how each of the individual silks are processed in
1749+`++make`.
16881750
1689−## Lifecycle of a Cell
1751+Lifecycle of a Cell
1752+-------------------
16901753
16911754 ^
16921755 %. [cof p.kas q.kas]
@@ -1700,10 +1763,10 @@ We'll now describe how each of the individual silks are processed in `++make`.
17001763 [p=cof q=[%0 ~ [%$ (slop q.bor q.heg)]]]
17011764 ==
17021765
1703−Silks autocons. The product of a cell of silks is a cell of the products of the
1704−silks, so we evaluate the two silks in parallel with `++coax` and slop together
1705−the results in a cell vase. We mark the product with `%$`, which means we know
1706−no more mark information than that it is a noun.
1766+Silks autocons. The product of a cell of silks is a cell of the products
1767+of the silks, so we evaluate the two silks in parallel with `++coax` and
1768+slop together the results in a cell vase. We mark the product with `%$`,
1769+which means we know no more mark information than that it is a noun.
17071770
17081771 ++ coax :: bolt across
17091772 |* [hoc=(bolt) fun=(burg)]
@@ -1727,19 +1790,23 @@ no more mark information than that it is a noun.
17271790 %2 hoc
17281791 ==
17291792
1730−If the first bolt is a value, we evaluate the burg to get the next bolt. If that
1731−also produces a value, we merge the dependency sets and produce a cell of the
1732−two values. Otherwise, we produce the block or error of the second bolt.
1793+If the first bolt is a value, we evaluate the burg to get the next bolt.
1794+If that also produces a value, we merge the dependency sets and produce
1795+a cell of the two values. Otherwise, we produce the block or error of
1796+the second bolt.
17331797
1734−If the first bolt is a block, we evaluate the burg to get the next bolt. If that
1735−produces a value, we just produce the block. If it produces a block, we merge
1736−the two block sets. If it produces an error, we produce that error.
1798+If the first bolt is a block, we evaluate the burg to get the next bolt.
1799+If that produces a value, we just produce the block. If it produces a
1800+block, we merge the two block sets. If it produces an error, we produce
1801+that error.
17371802
17381803If the first bolt is already an error, we just pass that through.
17391804
1740−Note that `++coax` (and, indeed, `++cope`) is reasonable to use with `;~`.
1805+Note that `++coax` (and, indeed, `++cope`) is reasonable to use with
1806+`;~`.
17411807
1742−## Lifecycle of a `%bake`
1808+Lifecycle of a `%bake`
1809+----------------------
17431810
17441811 %bake
17451812 %+ cool |.(leaf/"ford: bake {<p.kas>} {<(tope q.kas)>}")
@@ -1749,11 +1816,12 @@ Note that `++coax` (and, indeed, `++cope`) is reasonable to use with `;~`.
17491816 (flaw cof (smyt (tope q.kas)) ~)
17501817 (fine cof [p.kas u.vux])
17511818
1752−This is one of the most critical silks. We are going to functionally produce the
1753−hook file at the given beam with the given heel. The result will be of the
1754−correct mark, even if we need to run conversion functions. The functionality is
1755−encapsulated in `++lime`. If it produces null, then we produce an error.
1756−Otherwise, we take the vase produced and give it the correct mark.
1819+This is one of the most critical silks. We are going to functionally
1820+produce the hook file at the given beam with the given heel. The result
1821+will be of the correct mark, even if we need to run conversion
1822+functions. The functionality is encapsulated in `++lime`. If it produces
1823+null, then we produce an error. Otherwise, we take the vase produced and
1824+give it the correct mark.
17571825
17581826 ++ lima :: load at depth
17591827 |= [cof=cafe for=mark bem=beam arg=heel]
@@ -1775,19 +1843,19 @@ Otherwise, we take the vase produced and give it the correct mark.
17751843 |= [cof=cafe vax=vase]
17761844 (fine cof ~ vax)
17771845
1778−First, we load the arch at the given beam with `++lend`. If we have a child
1779−named the mark, our job is straightforward, so we go ahead and load that with
1780−`++lace`.
1846+First, we load the arch at the given beam with `++lend`. If we have a
1847+child named the mark, our job is straightforward, so we go ahead and
1848+load that with `++lace`.
17811849
1782−Otherwise, we iterate through our children. If we have no children, we produce
1783−null, signifying that we didn't find any way to convert to the requested mark.
1784−Otherwise, we call `++lion` to find a translation path from one of the available
1785−marks into the target mark. We recursively bake the child that has a path to the
1786−target mark, and then we call `++lope` to translate this mark into the target
1787−mark.
1850+Otherwise, we iterate through our children. If we have no children, we
1851+produce null, signifying that we didn't find any way to convert to the
1852+requested mark. Otherwise, we call `++lion` to find a translation path
1853+from one of the available marks into the target mark. We recursively
1854+bake the child that has a path to the target mark, and then we call
1855+`++lope` to translate this mark into the target mark.
17881856
1789−We'll first discuss the direct case of when one of our children is of the
1790−correct mark.
1857+We'll first discuss the direct case of when one of our children is of
1858+the correct mark.
17911859
17921860 ++ lace :: load and check
17931861 |= [cof=cafe for=mark bem=beam arg=heel]
@@ -1803,10 +1871,11 @@ correct mark.
18031871 (cope (cope (abut:(meow bem arg) cof hyd) (lake for bek)) fest)
18041872 (fine cof ~)
18051873
1806−First, we get the arch at the given beam with `++lend`. If this is a file, we
1807−load the file with `++liar` and coerce the type with `++lake`. Otherwise, we
1808−check to see if we have a hook file here. If so, we parse it with `++fade`,
1809−compile it with `++abut:meow`, and coerce the type with `++lake`.
1874+First, we get the arch at the given beam with `++lend`. If this is a
1875+file, we load the file with `++liar` and coerce the type with `++lake`.
1876+Otherwise, we check to see if we have a hook file here. If so, we parse
1877+it with `++fade`, compile it with `++abut:meow`, and coerce the type
1878+with `++lake`.
18101879
18111880Otherwise, there is no way to translate this, so we produce null.
18121881
@@ -1817,8 +1886,9 @@ Otherwise, there is no way to translate this, so we produce null.
18171886This is just `++some` for bolts.
18181887
18191888We've delayed the discussion of `++fade` far too many times. It's not
1820−complicated, we just wanted to spare a premature discussion of `++make` and the
1821−`%bake` silk. We 're now able to discuss everything in `++fade` with ease.
1889+complicated, we just wanted to spare a premature discussion of `++make`
1890+and the `%bake` silk. We 're now able to discuss everything in `++fade`
1891+with ease.
18221892
18231893 ++ fade :: compile to hood
18241894 |= [cof=cafe for=mark bem=beam]
@@ -1837,17 +1907,18 @@ complicated, we just wanted to spare a premature discussion of `++make` and the
18371907 (flaw cof [%leaf "syntax error: {<p.p.vex>} {<q.p.vex>}"] ~)
18381908 (fine cof p.u.q.vex)
18391909
1840−We first push a line onto a stack trace to say that we're parsing into a hood
1841−file.
1910+We first push a line onto a stack trace to say that we're parsing into a
1911+hood file.
18421912
1843−We bake the given beam with the given mark and no heel. Recall that baking gate,
1844−core, door, hoon, and hook files produces simply an atom of the text. We check
1845−to make sure that our value is an atom, failing otherwise.
1913+We bake the given beam with the given mark and no heel. Recall that
1914+baking gate, core, door, hoon, and hook files produces simply an atom of
1915+the text. We check to make sure that our value is an atom, failing
1916+otherwise.
18461917
1847−The parsing step is run within `++clef` so that the result is cached. We call
1848−`++fair` with the current beam to generate the parsing rule, and we parse the
1849−file. If parsing fails, we fail giving a syntax error with the line and column
1850−number. Otherwise, we produce the value.
1918+The parsing step is run within `++clef` so that the result is cached. We
1919+call `++fair` with the current beam to generate the parsing rule, and we
1920+parse the file. If parsing fails, we fail giving a syntax error with the
1921+line and column number. Otherwise, we produce the value.
18511922
18521923 ++ liar :: load vase
18531924 |= [cof=cafe bem=beam]
@@ -1859,14 +1930,15 @@ number. Otherwise, we produce the value.
18591930 (flaw cof (smyt (tope bem)) ~)
18601931 (fine cof ?^(u.u.von [%cell %noun %noun] [%atom %$]) u.u.von)
18611932
1862−This takes a beam and loads the file at that location. If our sky function
1863−produces null, that means the resource is currently unavailable, so we block on
1864−it. If it produces `[~ ~]`, that means our resource is permanently unavailable,
1865−so we produce an error. Otherwise, we produce the value there with a type of
1866−either a cell of two nouns or an atom, depending on whether the value is a cell
1867−or not.
1933+This takes a beam and loads the file at that location. If our sky
1934+function produces null, that means the resource is currently
1935+unavailable, so we block on it. If it produces `[~ ~]`, that means our
1936+resource is permanently unavailable, so we produce an error. Otherwise,
1937+we produce the value there with a type of either a cell of two nouns or
1938+an atom, depending on whether the value is a cell or not.
18681939
1869−Back in `++lima`, recall that we call `++lion` to find a translation path.
1940+Back in `++lima`, recall that we call `++lion` to find a translation
1941+path.
18701942
18711943 ++ lion :: translation search
18721944 |= [cof=cafe too=@tas bek=beak fro=(list ,@tas)]
@@ -1901,38 +1973,41 @@ Back in `++lima`, recall that we call `++lion` to find a translation path.
19011973 (fine cof ?~(ked ~ [~ for u.ked]))
19021974 --
19031975
1904−At a high level, we have `++apex` and `++apse`. `++apex` takes a list of marks
1905−to try in succession until we find one that can be translated into the target
1906−mark. On each one, it calls `++apse`, which takes a single mark and tries to
1907−find a translation path from this mark to the target. To do this, it sees which
1908−marks we know how to directly translate to, and calls `++apex` on this list. The
1909−result of this mututal recursion is a depth-first search of the translation
1910−graph to find the target mark. Since the translation graph is not necessarily
1911−acyclic, we maintain a set of marks that we've already tried.
1976+At a high level, we have `++apex` and `++apse`. `++apex` takes a list of
1977+marks to try in succession until we find one that can be translated into
1978+the target mark. On each one, it calls `++apse`, which takes a single
1979+mark and tries to find a translation path from this mark to the target.
1980+To do this, it sees which marks we know how to directly translate to,
1981+and calls `++apex` on this list. The result of this mututal recursion is
1982+a depth-first search of the translation graph to find the target mark.
1983+Since the translation graph is not necessarily acyclic, we maintain a
1984+set of marks that we've already tried.
19121985
1913−We kick off our search in `++apex`, starting with the given initial list of
1914−marks that we know how to get to.
1986+We kick off our search in `++apex`, starting with the given initial list
1987+of marks that we know how to get to.
19151988
1916−If `++apex` is called with a bolt other than a `%0` value bolt, we simply
1917−produce it. Otherwise, we check to see if the list of available marks to
1918−investigate is null. If so, then we're done, so we produce a `%0` bolt with a
1919−null list of accessible marks.
1989+If `++apex` is called with a bolt other than a `%0` value bolt, we
1990+simply produce it. Otherwise, we check to see if the list of available
1991+marks to investigate is null. If so, then we're done, so we produce a
1992+`%0` bolt with a null list of accessible marks.
19201993
19211994Otherwise, we process this next mark with `++apse`, which will produce a
1922−possible list of marks from this one to the target mark. If it fails to produce
1923−a `%0` bolt, we just produce that. Otherwise, if it produces null, we can't get
1924−to our target through this mark, so we move on to the next one.
1995+possible list of marks from this one to the target mark. If it fails to
1996+produce a `%0` bolt, we just produce that. Otherwise, if it produces
1997+null, we can't get to our target through this mark, so we move on to the
1998+next one.
19251999
1926−If it doesn't produce null, then we have successfully found a translation path,
1927−so we produce it.
2000+If it doesn't produce null, then we have successfully found a
2001+translation path, so we produce it.
19282002
1929−In `++apse`, we first test to see if we've arrived at the target path. If so,
1930−we're done, so we produce a list including just ourself. Otherwise, we check to
1931−see if we've already tried this mark. If so, we know we can't succeed here, so
1932−we produce null. Otherwise, we put ourselves in the set of already-tried marks,
1933−and we move on.
2003+In `++apse`, we first test to see if we've arrived at the target path.
2004+If so, we're done, so we produce a list including just ourself.
2005+Otherwise, we check to see if we've already tried this mark. If so, we
2006+know we can't succeed here, so we produce null. Otherwise, we put
2007+ourselves in the set of already-tried marks, and we move on.
19342008
1935−We call `++lily` to get the list of marks we can translate this one into.
2009+We call `++lily` to get the list of marks we can translate this one
2010+into.
19362011
19372012 ++ lily :: translation targets
19382013 |= [cof=cafe for=mark bek=beak]
@@ -1951,27 +2026,29 @@ We call `++lily` to get the list of marks we can translate this one into.
19512026 =+ gow=(slap vax [%cnzy %grow])
19522027 (sloe p.gow)
19532028
1954−We call `++fang` to get the mark definition door. This is documented under
1955−`%vale`. If getting the mark fails, we produce null because we can't translate a
1956−non-existent mark into anything.
2029+We call `++fang` to get the mark definition door. This is documented
2030+under `%vale`. If getting the mark fails, we produce null because we
2031+can't translate a non-existent mark into anything.
19572032
1958−Otherwise, we examine the door. The door may have a `++garb`, which is simply a
1959−list of marks which know how to translate from the current one. There must be a
1960−corresponding `++grab` in the definition of the other mark, though we don't
1961−check that here.
2033+Otherwise, we examine the door. The door may have a `++garb`, which is
2034+simply a list of marks which know how to translate from the current one.
2035+There must be a corresponding `++grab` in the definition of the other
2036+mark, though we don't check that here.
19622037
1963−The door may also have a `++grow`, which defines how to translate this mark into
1964−another one. Each arm in `++grow` is the name of a mark we can translate into.
1965−The call to `++sloe` simply produces a list of arm names in `++grow`.
2038+The door may also have a `++grow`, which defines how to translate this
2039+mark into another one. Each arm in `++grow` is the name of a mark we can
2040+translate into. The call to `++sloe` simply produces a list of arm names
2041+in `++grow`.
19662042
1967−Back in `++apse:lion`, we take the list of translation targets we just found and
1968−call `++apex` on it. If we got back a null, we produce a null; otherwise, we
1969−produce the list of marks we got back plus the current mark.
2043+Back in `++apse:lion`, we take the list of translation targets we just
2044+found and call `++apex` on it. If we got back a null, we produce a null;
2045+otherwise, we produce the list of marks we got back plus the current
2046+mark.
19702047
19712048This concludes our discussion of `++lion`.
19722049
1973−The final piece of `++lima` is `++lope`, which performs the actual translation
1974−along the path we just computed.
2050+The final piece of `++lima` is `++lope`, which performs the actual
2051+translation along the path we just computed.
19752052
19762053 ++ lope :: translation pipe
19772054 |= [cof=cafe for=mark yaw=(list mark) bek=beak vax=vase]
@@ -1981,12 +2058,14 @@ along the path we just computed.
19812058 |= [cof=cafe yed=vase]
19822059 ^$(cof cof, for i.yaw, yaw t.yaw, vax yed)
19832060
1984−We iterate through our list, calling `++link` on every adjacent pair of marks,
1985−translating from one mark to the next until we finish the list of marks. A call
1986−to `++link` is equivalent to a `%cast` silk, so we document it there. After
1987−we've called performed every step in the translation pipeline, we're done.
2061+We iterate through our list, calling `++link` on every adjacent pair of
2062+marks, translating from one mark to the next until we finish the list of
2063+marks. A call to `++link` is equivalent to a `%cast` silk, so we
2064+document it there. After we've called performed every step in the
2065+translation pipeline, we're done.
19882066
1989−## Lifecycle of a `%boil`
2067+Lifecycle of a `%boil`
2068+----------------------
19902069
19912070 %boil
19922071 %+ cool |.(leaf/"ford: boil {<p.kas>} {<(tope q.kas)>} {<r.kas>}")
@@ -1996,13 +2075,13 @@ we've called performed every step in the translation pipeline, we're done.
19962075 |= [cof=cafe vax=vase]
19972076 (fine cof `cage`[p.kas vax])
19982077
1999−At a high level, we try to bake at the given beam, and if it fails, we go up a
2000−level and try again. This is the usual semantics of ford, and this should nearly
2001−always be preferred over directly baking.
2078+At a high level, we try to bake at the given beam, and if it fails, we
2079+go up a level and try again. This is the usual semantics of ford, and
2080+this should nearly always be preferred over directly baking.
20022081
2003−First, we normalize the version case to a number with `++lamp`. This allows
2004−caching to be based on revision number rather than something more ephemeral like
2005−a particular time.
2082+First, we normalize the version case to a number with `++lamp`. This
2083+allows caching to be based on revision number rather than something more
2084+ephemeral like a particular time.
20062085
20072086 ++ lamp :: normalize version
20082087 |= [cof=cafe bem=beam]
@@ -2011,10 +2090,11 @@ a particular time.
20112090 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
20122091 (fine cof bem(r [%ud ((hard ,@) (need u.von))]))
20132092
2014−We call the sky function with `%cw`, asking clay for the revision number at this
2015−case. If the case refers to a revision that isn't there yet, we produce a `%1`
2016−blocking bolt. Otherwise, we require that the value exist and that it's a
2017−number, both of which are guaranteed by clay. We produce this number.
2093+We call the sky function with `%cw`, asking clay for the revision number
2094+at this case. If the case refers to a revision that isn't there yet, we
2095+produce a `%1` blocking bolt. Otherwise, we require that the value exist
2096+and that it's a number, both of which are guaranteed by clay. We produce
2097+this number.
20182098
20192099Next for `%boil` we call `++lime` to try to load the beam.
20202100
@@ -2029,13 +2109,14 @@ Next for `%boil` we call `++lime` to try to load the beam.
20292109 (flaw cof (smyt (tope bem)) ~)
20302110 ^$(s.mob t.s.mob, mer [i.s.mob mer])
20312111
2032−We start at the given beam and try to bake it. If it succeeds, we're good.
2033−Otherwise, we pop off the top level of the path and put it in our heel (virtual
2034−path extension). We do this recursively until either we find something we can
2035−bake or we've gone all the way up to the root path of the desk, in which case we
2036−fail.
2112+We start at the given beam and try to bake it. If it succeeds, we're
2113+good. Otherwise, we pop off the top level of the path and put it in our
2114+heel (virtual path extension). We do this recursively until either we
2115+find something we can bake or we've gone all the way up to the root path
2116+of the desk, in which case we fail.
20372117
2038−## Lifecycle of a `%call`
2118+Lifecycle of a `%call`
2119+----------------------
20392120
20402121 %call
20412122 %+ cool |.(leaf/"ford: call {<`@p`(mug kas)>}")
@@ -2053,13 +2134,15 @@ fail.
20532134 (fine cof %noun vax)
20542135 ==
20552136
2056−This is slam for silks. We process both of the given silks in parallel with
2057−`++coax`. We then slam the two produced vases together with `++maul` and mark
2058−the produced vase with `%noun` since we don't know any more specific mark.
2137+This is slam for silks. We process both of the given silks in parallel
2138+with `++coax`. We then slam the two produced vases together with
2139+`++maul` and mark the produced vase with `%noun` since we don't know any
2140+more specific mark.
20592141
20602142`++coax` is documented under Lifecycle of a Cell.
20612143
2062−## Lifecycle of a `%cast`
2144+Lifecycle of a `%cast`
2145+----------------------
20632146
20642147 %cast
20652148 %+ cool |.(leaf/"ford: cast {<p.kas>}")
@@ -2069,11 +2152,11 @@ the produced vase with `%noun` since we don't know any more specific mark.
20692152 |= [cof=cafe vax=vase]
20702153 (fine cof [p.kas vax])
20712154
2072−This is a request to convert data of one mark to another mark directly. We
2073−evaluate the given silk and pass the result into `++link`, which performs the
2074−actual translation. Note that this will not search for indirect conversion
2075−paths, so the conversion must be defined either in the `++grow` of the given
2076−mark or the `++grab` of the target mark.
2155+This is a request to convert data of one mark to another mark directly.
2156+We evaluate the given silk and pass the result into `++link`, which
2157+performs the actual translation. Note that this will not search for
2158+indirect conversion paths, so the conversion must be defined either in
2159+the `++grow` of the given mark or the `++grab` of the target mark.
20772160
20782161 ++ link :: translate
20792162 |= [cof=cafe too=mark for=mark bek=beak vax=vase]
@@ -2098,28 +2181,29 @@ mark or the `++grab` of the target mark.
20982181 (flaw cof [%leaf "ford: no link: {<[for too]>}"]~)
20992182 (maul cof u.zat vax)
21002183
2101−This performs one step in the translation pipeline. If the given and target
2102−marks are the same, we're done. If we're translating from a noun or the empty
2103−mark, we coerce with `++lake` (documented in `%vale`). Otherwise, we're
2104−translating from a user-defined mark.
2184+This performs one step in the translation pipeline. If the given and
2185+target marks are the same, we're done. If we're translating from a noun
2186+or the empty mark, we coerce with `++lake` (documented in `%vale`).
2187+Otherwise, we're translating from a user-defined mark.
21052188
2106−We load the definition of the given mark with `++fang`, and we check to see if
2107−it has an arm in `++grow` named the target mark. If so, we place our data in the
2108−sample of the door with `++keel` and slap the arm. `++keel` is equivalent to a
2109−`%mute` silk, so we document it there.
2189+We load the definition of the given mark with `++fang`, and we check to
2190+see if it has an arm in `++grow` named the target mark. If so, we place
2191+our data in the sample of the door with `++keel` and slap the arm.
2192+`++keel` is equivalent to a `%mute` silk, so we document it there.
21102193
2111−If there is no arm in `++grow` of the given mark named the target mark, we
2112−suppose there must be an arm in `++grab` of the target mark named the given
2113−mark. We get the definition of the target mark and check to see if it has the
2114−required arm, failing if it doesn't. Finally, we slam the data against the
2115−correct arm, producing the translated data.
2194+If there is no arm in `++grow` of the given mark named the target mark,
2195+we suppose there must be an arm in `++grab` of the target mark named the
2196+given mark. We get the definition of the target mark and check to see if
2197+it has the required arm, failing if it doesn't. Finally, we slam the
2198+data against the correct arm, producing the translated data.
21162199
21172200If you're confused as to why the handling of `++grow` and `++grab` look
2118−superficially so different, remember that the correct arm in `++grow` does not
2119−have a sample while the one in `++grab` does. This means they must be called
2120−rather differently.
2201+superficially so different, remember that the correct arm in `++grow`
2202+does not have a sample while the one in `++grab` does. This means they
2203+must be called rather differently.
21212204
2122−## Lifecycle of a `%diff`
2205+Lifecycle of a `%diff`
2206+----------------------
21232207
21242208 %diff
21252209 %+ cool |.(leaf/"ford: diff {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
@@ -2144,7 +2228,8 @@ First, we process the two given silks to get our arguments.
21442228 %+ flaw cof :_ ~
21452229 leaf/"diff on data of different marks: {(trip p.cay)} {(trip p.coy)}"
21462230
2147−If the two cages have different marks, then we can't diff them, so we complain.
2231+If the two cages have different marks, then we can't diff them, so we
2232+complain.
21482233
21492234 %+ cope (fang cof p.cay [our %main %da now])
21502235 |= [cof=cafe pro=vase]
@@ -2162,11 +2247,12 @@ We pull in the relevant mark's definition.
21622247 (flaw cof leaf/"bad ++sted:grad" ~)
21632248 (make cof %diff [%cast u.for kas] [%cast u.for kos])
21642249
2165−If there's no `++grad`, we complain. If there's no `++form:grad`, then we look
2166−for a `++sted:grad`. If we can't find either, or if `++sted:grad` isn't a term,
2167−then we complain. If `++sted:grad` exists and is a term, then it represents the
2168−mark we should use as a proxy to get our diff. So, we cast both our given cages
2169−to the new mark and start the dance again.
2250+If there's no `++grad`, we complain. If there's no `++form:grad`, then
2251+we look for a `++sted:grad`. If we can't find either, or if
2252+`++sted:grad` isn't a term, then we complain. If `++sted:grad` exists
2253+and is a term, then it represents the mark we should use as a proxy to
2254+get our diff. So, we cast both our given cages to the new mark and start
2255+the dance again.
21702256
21712257 ?. (slab %diff p.gar)
21722258 (flaw cof leaf/"no ++diff:grad" ~)
@@ -2176,7 +2262,8 @@ Otherwise, we expect a `++diff:grad`.
21762262 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
21772263 |= [cof=cafe pox=vase]
21782264
2179−We put the first cage's data into the sample of the given mark's definition.
2265+We put the first cage's data into the sample of the given mark's
2266+definition.
21802267
21812268 %+ cope
21822269 %^ maul cof
@@ -2192,41 +2279,46 @@ We run `++diff:grad` with a sample of the second cage's data.
21922279 (fine cof u.for dif)
21932280 ==
21942281
2195−We check that `++form:grad` exists, and we tag the result with it to give the
2196−final cage.
2282+We check that `++form:grad` exists, and we tag the result with it to
2283+give the final cage.
21972284
2198−## Lifecycle of a `%done`
2285+Lifecycle of a `%done`
2286+----------------------
21992287
22002288 %done [cof %0 p.kas q.kas]
22012289
22022290This is trivial. We simply produce the given cage with the given set of
2203−dependencies. This is used when we already have a cage that we want to insert
2204−into another silk that requires a silk argument. It's analogous to the return
2205−operator in a monad -- which makes it sound way more complicated than it is.
2291+dependencies. This is used when we already have a cage that we want to
2292+insert into another silk that requires a silk argument. It's analogous
2293+to the return operator in a monad -- which makes it sound way more
2294+complicated than it is.
22062295
2207−## Lifecycle of a `%dude`
2296+Lifecycle of a `%dude`
2297+----------------------
22082298
22092299 %dude (cool |.(p.kas) $(kas q.kas))
22102300
2211−This simply puts a given tank on the stack trace if the given silk produces an
2212−error. This is implemented as a simple call to `++cool`.
2301+This simply puts a given tank on the stack trace if the given silk
2302+produces an error. This is implemented as a simple call to `++cool`.
22132303
2214−## Lifecycle of a `%dune`
2304+Lifecycle of a `%dune`
2305+----------------------
22152306
22162307 %dune
22172308 ?~ q.kas [cof [%2 [%leaf "no data"]~]]
22182309 $(kas [%done p.kas u.q.kas])
22192310
2220−This is a sort of a `++need` for silks. If there is no data in the unit cage, we
2221−produce an error. Else, we simply produce the data in the cage.
2311+This is a sort of a `++need` for silks. If there is no data in the unit
2312+cage, we produce an error. Else, we simply produce the data in the cage.
22222313
2223−## Lifcycle of a `%mute`
2314+Lifcycle of a `%mute`
2315+---------------------
22242316
22252317 %mute (kale cof p.kas q.kas)
22262318
2227−This mutates a silk by putting the values of other silks at particular axes.
2228−This is useful in, for example, replacing the sample of the door in a mark
2229−definition.
2319+This mutates a silk by putting the values of other silks at particular
2320+axes. This is useful in, for example, replacing the sample of the door
2321+in a mark definition.
22302322
22312323 ++ kale :: mutate
22322324 |= [cof=cafe kas=silk muy=(list (pair wing silk))]
@@ -2246,10 +2338,10 @@ definition.
22462338 |= [cof=cafe vax=vase]
22472339 (fine cof p.cay vax)
22482340
2249−First, we process each of the silks by calling `++make` on them. We pass the
2250−resultant vase and list of pairs of wings and silks to `++keel` to do the actual
2251−mutation. We assume the mutation doesn't change the mark of the main silk, so we
2252−mark the produced vase with the original mark.
2341+First, we process each of the silks by calling `++make` on them. We pass
2342+the resultant vase and list of pairs of wings and silks to `++keel` to
2343+do the actual mutation. We assume the mutation doesn't change the mark
2344+of the main silk, so we mark the produced vase with the original mark.
22532345
22542346 ++ keel :: apply mutations
22552347 |= [cof=cafe suh=vase yom=(list (pair wing vase))]
@@ -2267,16 +2359,19 @@ mark the produced vase with the original mark.
22672359 :- [p.i.yom [%$ (peg axe 2)]]
22682360 $(yom t.yom, axe (peg axe 3))
22692361
2270−We first put the vases together in one big tuple starting with the subject and
2271−going through the mutations. We slap against this tuple a `%_` twig we directly
2272−construct. Since a `%_` twig takes a list of pairs of wings and twigs, we simply
2273−have to generate twigs referring to the correct axes in the subject. This is
2274−very easy since we just recur on axis 3 of whatever axis we were already at.
2362+We first put the vases together in one big tuple starting with the
2363+subject and going through the mutations. We slap against this tuple a
2364+`%_` twig we directly construct. Since a `%_` twig takes a list of pairs
2365+of wings and twigs, we simply have to generate twigs referring to the
2366+correct axes in the subject. This is very easy since we just recur on
2367+axis 3 of whatever axis we were already at.
22752368
2276−Note the use of `%_` instead of `%=` enforces that our mutations don't change
2277−the type of the subject, which justifies our use of the original mark.
2369+Note the use of `%_` instead of `%=` enforces that our mutations don't
2370+change the type of the subject, which justifies our use of the original
2371+mark.
22782372
2279−## Lifecycle of a `%pact`
2373+Lifecycle of a `%pact`
2374+----------------------
22802375
22812376 %pact
22822377 %+ cool |.(leaf/"ford: pact {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
@@ -2313,12 +2408,12 @@ We pull in the relevant mark's definition.
23132408 (flaw cof leaf/"bad ++sted:grad" ~)
23142409 (make cof %cast p.cay %pact [%cast u.for kas] kos)
23152410
2316−If there's no `++grad`, we complain. If there's no `++form:grad`, then we look
2317−for a `++sted:grad`. If we can't find either, or if `++sted:grad` isn't a term,
2318−then we complain. If `++sted:grad` exists and is a term, then it represents the
2319−mark we should use as a proxy to get our diff. So, we cast the first argument to
2320−the new mark, then try to patch. Afterward, we cast the result back to the
2321−original mark.
2411+If there's no `++grad`, we complain. If there's no `++form:grad`, then
2412+we look for a `++sted:grad`. If we can't find either, or if
2413+`++sted:grad` isn't a term, then we complain. If `++sted:grad` exists
2414+and is a term, then it represents the mark we should use as a proxy to
2415+get our diff. So, we cast the first argument to the new mark, then try
2416+to patch. Afterward, we cast the result back to the original mark.
23222417
23232418 =+ for=((soft ,@tas) q:(slap gar [%cnzy %form]))
23242419 ?~ for
@@ -2328,8 +2423,8 @@ original mark.
23282423 =< leaf/"pact on data with wrong form: {-} {+<} {+>}"
23292424 [(trip p.cay) (trip u.for) (trip p.coy)]
23302425
2331−If `++form:grad` isn't a term, or else our second argument isn't of that mark,
2332−we complain.
2426+If `++form:grad` isn't a term, or else our second argument isn't of that
2427+mark, we complain.
23332428
23342429 ?. (slab %pact p.gar)
23352430 (flaw cof leaf/"no ++pact:grad" ~)
@@ -2339,7 +2434,8 @@ If we don't have a `++pact:grad`, we complain.
23392434 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
23402435 |= [cof=cafe pox=vase]
23412436
2342−We put the first cage's data into the sample of the given mark's definition.
2437+We put the first cage's data into the sample of the given mark's
2438+definition.
23432439
23442440 %+ cope
23452441 %^ maul cof
@@ -2347,32 +2443,36 @@ We put the first cage's data into the sample of the given mark's definition.
23472443 q.coy
23482444 |= [cof=cafe pat=vase]
23492445
2350−We run `++pact:grad` with a sample of the second cage's data, which is the diff.
2446+We run `++pact:grad` with a sample of the second cage's data, which is
2447+the diff.
23512448
23522449 (fine cof p.cay pat)
23532450 ==
23542451
23552452We tag the result with the mark of our first argument.
23562453
2357−## Lifecycle of a `%plan`
2454+Lifecycle of a `%plan`
2455+----------------------
23582456
23592457 %plan
23602458 %+ cope (abut:(meow p.kas q.kas) cof r.kas)
23612459 |= [cof=cafe vax=vase]
23622460 (fine cof %noun vax)
23632461
2364−This is a direct request to compile a hood at a given beam with a heel of the
2365−given path. We comply by calling `++abut` with the given arguments and producing
2366−the vase with a mark of `%noun`.
2462+This is a direct request to compile a hood at a given beam with a heel
2463+of the given path. We comply by calling `++abut` with the given
2464+arguments and producing the vase with a mark of `%noun`.
23672465
2368−## Lifecycle of a `%reef`
2466+Lifecycle of a `%reef`
2467+----------------------
23692468
23702469 %reef (fine cof %noun pit)
23712470
2372−This is one of the simplest silks. We simply produce our context, which is zuse
2373−compiled against hoon. The mark is a `%noun`.
2471+This is one of the simplest silks. We simply produce our context, which
2472+is zuse compiled against hoon. The mark is a `%noun`.
23742473
2375−## Lifcycle of a `%ride`
2474+Lifcycle of a `%ride`
2475+---------------------
23762476
23772477 %ride
23782478 %+ cool |.(leaf/"ford: ride {<`@p`(mug kas)>}")
@@ -2382,11 +2482,12 @@ compiled against hoon. The mark is a `%noun`.
23822482 |= [cof=cafe vax=vase]
23832483 (fine cof %noun vax)
23842484
2385−This slaps evaluates the given silk, then it slaps the result against the given
2386−twig. Since we don't know what of what mark (if any) is the result, we give it a
2387−mark of `%noun`.
2485+This slaps evaluates the given silk, then it slaps the result against
2486+the given twig. Since we don't know what of what mark (if any) is the
2487+result, we give it a mark of `%noun`.
23882488
2389−## Lifecycle of a `%vale`
2489+Lifecycle of a `%vale`
2490+----------------------
23902491
23912492 %vale
23922493 %+ cool |.(leaf/"ford: vale {<p.kas>} {<q.kas>} {<`@p`(mug r.kas)>}")
@@ -2394,20 +2495,20 @@ mark of `%noun`.
23942495 |= [cof=cafe vax=vase]
23952496 (fine cof `cage`[p.kas vax])
23962497
2397−This checks whether given data is of the given mark. If we don't have the
2398−definition of the mark, we check the given ship for it.
2498+This checks whether given data is of the given mark. If we don't have
2499+the definition of the mark, we check the given ship for it.
23992500
2400−We call `++lave` to perform the check, producing a vase. We produce this vase
2401−tagged with the given mark.
2501+We call `++lave` to perform the check, producing a vase. We produce this
2502+vase tagged with the given mark.
24022503
24032504 ++ lave :: validate
24042505 |= [cof=cafe for=mark his=ship som=*]
24052506 ^- (bolt vase)
24062507 ((lake for [our %main [%da now]]) cof [%noun som])
24072508
2408−This is a thinly-veiled wrapper over `++lake`. Note that, contrary to documented
2409−opinion, we do not in fact check the other ship's definition of a mark. This is
2410−likely a bug.
2509+This is a thinly-veiled wrapper over `++lake`. Note that, contrary to
2510+documented opinion, we do not in fact check the other ship's definition
2511+of a mark. This is likely a bug.
24112512
24122513At any rate, `++lake` coerces a noun into the correct type for a mark.
24132514
@@ -2435,24 +2536,27 @@ At any rate, `++lake` coerces a noun into the correct type for a mark.
24352536 (fine cof (slot 6 pro))
24362537 (flaw cof [%leaf "ford: invalid content: {<[for bek]>}"]~)
24372538
2438−This is going to coerce the sample into the correct type for the mark. First, we
2439−push a line onto the stack trace saying that we're checking the type. If the
2440−requested mark is a gate, core, door, hoon, or hook, then we don't do any more
2441−type information than just saying it's a noun, so we're done.
2539+This is going to coerce the sample into the correct type for the mark.
2540+First, we push a line onto the stack trace saying that we're checking
2541+the type. If the requested mark is a gate, core, door, hoon, or hook,
2542+then we don't do any more type information than just saying it's a noun,
2543+so we're done.
24422544
2443−Otherwise, we get the mark definition from our `/=main=/mar` directory with
2444−`++fang`, which we'll describe below.
2545+Otherwise, we get the mark definition from our `/=main=/mar` directory
2546+with `++fang`, which we'll describe below.
24452547
2446−We check to see if our sample type nests within the type of the sample to the
2447−door. If so, then we're already of the correct type, so we're done.
2548+We check to see if our sample type nests within the type of the sample
2549+to the door. If so, then we're already of the correct type, so we're
2550+done.
24482551
2449−Otherwise, we check to see if there's a `++grab` in the door, and a `++noun` in
2450−the `++grab`. If not, there's no way we can translate to this mark, so we fail.
2552+Otherwise, we check to see if there's a `++grab` in the door, and a
2553+`++noun` in the `++grab`. If not, there's no way we can translate to
2554+this mark, so we fail.
24512555
2452−If we have everything we need, we slam our sample (typed as a noun) against the
2453−`++noun` in `++grab`. If the sample of the door is the same as our sample, then
2454−the check succeeded, so we produce the well-typed sample of the door. Otherwise,
2455−we fail.
2556+If we have everything we need, we slam our sample (typed as a noun)
2557+against the `++noun` in `++grab`. If the sample of the door is the same
2558+as our sample, then the check succeeded, so we produce the well-typed
2559+sample of the door. Otherwise, we fail.
24562560
24572561 ++ fang :: protocol door
24582562 |= [cof=cafe for=mark bek=beak]
@@ -2467,6 +2571,6 @@ we fail.
24672571 (cope (fade cof %hook bem) abut:(meow bem ~))
24682572
24692573A mark's definition is generally in
2470−`/=main=/mar/[mark-name]/door/hook'. If we don't find it there, we look in`/\[given-beak\]/mar/\[mark-name\]/door/hook'.
2471−We parse the mark definition with `++fade` and assemble it with `++abut:meow`.
2472−`++fade` is defined under the `%bake` silk.
2574+`/=main=/mar/[mark-name]/door/hook'. If we don't find it there, we look in`/[given-beak]/mar/[mark-name]/door/hook'.
2575+We parse the mark definition with `++fade` and assemble it with
2576+`++abut:meow`. `++fade` is defined under the `%bake` silk.