@@ -1,13 +1,10 @@
11---
2−navhome: /docs/
2+navhome: '/docs/'
33---
44
5+# Reference
56
6−Reference
7−=========
8−
9−Data Models
10−-----------
7+## Data Models
118
129### `++axle`, formal state
1310
@@ -16,13 +13,13 @@ Data Models
1613 pol=(map ship baby) ::
1714 == ::
1815
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.
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.
2320
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.
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.
2623
2724### `++baby`, state by ship
2825
@@ -34,19 +31,18 @@ state. There is no shared ford state -- every ship is entirely separate.
3431
3532This is the state specific to each ship.
3633
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.
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.
4239
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.
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.
5046
5147### `++task`, problem in progress
5248
@@ -56,12 +52,12 @@ is reloaded.
5652 kig=[p=@ud q=(map ,@ud beam)] :: blocks
5753 == ::
5854
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.
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.
6258
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`.
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`.
6561
6662### `++silk`, problem
6763
@@ -83,13 +79,12 @@ stored by index in `q.kig`, and the next available index is `p.kig`.
8379 [%vale p=mark q=ship r=*] :: validate [our his]
8480 == ::
8581
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.
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.
8984
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.
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.
9388
9489### `++calx`, cache line
9590
@@ -99,20 +94,19 @@ discussion of the public interface to ford below.
9994 [%slam p=calm q=[p=vase q=vase] r=vase] :: compute
10095 == ::
10196
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.
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.
10499
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.
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.
108103
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.
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.
112107
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.
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.
116110
117111### `++calm`, cache line metadata
118112
@@ -121,9 +115,9 @@ them.
121115 dep=(set beam) :: dependencies
122116 == ::
123117
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.
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.
127121
128122### `++hood`, assembly components
129123
@@ -137,46 +131,43 @@ what are the dependencies of this line.
137131
138132When assembling a hook file, we split it into several sections.
139133
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.
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.
144138
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 `=>`.
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 `=>`.
150143
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 `=>`.
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 `=>`.
156148
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 `=~`.
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 `=~`.
160152
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 `=~`.
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 `=~`.
164156
165157### `++hoot`
166158
167159 ++ hoot (pair bean hoof) :: structure gate/core
168160
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`.
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`.
172164
173165### `++hoof`
174166
175167 ++ hoof (pair term (unit (pair case ship))) :: resource reference
176168
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.
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.
180171
181172### `++horn`
182173
@@ -202,44 +193,42 @@ discussion of their use from a user's perspective is documented in the [runes
202193documentation](https://urbit.org/docs/arvo/internals/runes), so we will here
203194only give a description of the data structure itself.
204195
205−A `%ape` horn is simply a twig that gets evaluated and placed in the
206−subject.
196+A `%ape` horn is simply a twig that gets evaluated and placed in the subject.
207197
208−A `%arg` is a gate that gets evaluated with a sample of our location and
209−our heel.
198+A `%arg` is a gate that gets evaluated with a sample of our location and our
199+heel.
210200
211−A `%day` is a horn that applies to each of a list of `@dr`-named files
212−in the directory.
201+A `%day` is a horn that applies to each of a list of `@dr`-named files in the
202+directory.
213203
214−A `%dub` is a term and horn, where the result of a horn is given the
215−face of the term.
204+A `%dub` is a term and horn, where the result of a horn is given the face of the
205+term.
216206
217207A `%fan` is a list of horns, all at the current directory level.
218208
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.
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.
222211
223−A `%hub` is a horn that applies to each of a list of `@ud`-named files
224−in the directory.
212+A `%hub` is a horn that applies to each of a list of `@ud`-named files in the
213+directory.
225214
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.
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.
228217
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.
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.
231220
232−A `%now` is a horn that applies to each of a list of `@da`-named files
233−in the directory.
221+A `%now` is a horn that applies to each of a list of `@da`-named files in the
222+directory.
234223
235−A `%saw` is a twig and a horn, where the twig operates on the result of
236−the horn.
224+A `%saw` is a twig and a horn, where the twig operates on the result of the
225+horn.
237226
238−A `%see` is a beam and a horn, where the horn is evaluated at a location
239−of the given beam.
227+A `%see` is a beam and a horn, where the horn is evaluated at a location of the
228+given beam.
240229
241−A `%sic` is a tile and a horn, where the horn is evaluated and cast to
242−the type associated with the tile.
230+A `%sic` is a tile and a horn, where the horn is evaluated and cast to the type
231+associated with the tile.
243232
244233A `%toy` is simply a mark to be baked.
245234
@@ -250,9 +239,9 @@ A `%toy` is simply a mark to be baked.
250239 [%| p=beam] :: resource location
251240 == ::
252241
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.
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.
256245
257246### `++bolt`, monadic edge
258247
@@ -266,28 +255,27 @@ file. The second is specified with a `//` rune.
266255 == ::
267256 == ::
268257
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.
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.
274263
275−At every step, we have a cache, so we store that in `p`. In `q` we store
276−the data.
264+At every step, we have a cache, so we store that in `p`. In `q` we store the
265+data.
277266
278−In the case of `%0`, we have the result in `q` and the set of
279−dependencies in `p`.
267+In the case of `%0`, we have the result in `q` and the set of dependencies in
268+`p`.
280269
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.
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.
287275
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.
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.
291279
292280### `++burg`, monadic rule
293281
@@ -296,53 +284,49 @@ of what went wrong, often including a stack trace.
296284 $+([c=cafe d=a] (bolt b)) ::
297285 :: ::
298286
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.
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.
305292
306−If you understand monads, this is probably fairly obvious. Otherwise,
307−see the discussion on `++cope` (link).
293+If you understand monads, this is probably fairly obvious. Otherwise, see the
294+discussion on `++cope` (link).
308295
309−Public Interface
310−----------------
296+## Public Interface
311297
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.
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.
319304
320305 ++ kiss :: in request ->$
321306 $% [%exec p=@p q=(unit silk)] :: make / kill
322307 == ::
323308
324309The `%exec` gift requests ford to perform a computation on behalf of a
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.
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.
330314
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`.
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`.
334318
335319 ++ gift :: out result <-$
336320 $% [%made p=(each bead (list tank))] :: computed result
337321 == ::
338322
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.
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.
341325
342326 ++ bead ,[p=(set beam) q=cage] :: computed result
343327
344−This is a set of dependencies required to compute this value and a cage
345−of the result with its associated mark.
328+This is a set of dependencies required to compute this value and a cage of the
329+result with its associated mark.
346330
347331There are twelve possible computations defined in `++silk`.
348332
@@ -362,83 +346,77 @@ There are twelve possible computations defined in `++silk`.
362346 [%vale p=mark q=ship r=*] :: validate [our his]
363347 == ::
364348
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.
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.
368352
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.
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.
372355
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`.
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`.
377360
378361`%call` slams the result of one silk against the result of another.
379362
380−`%cast` translates the given silk to the given mark, if possible. This
381−is one of the critical and fundamental operations of ford.
363+`%cast` translates the given silk to the given mark, if possible. This is one of
364+the critical and fundamental operations of ford.
382365
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.
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.
387369
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.
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.
391373
392−`%dude` computes the given silk with the given tank as part of the stack
393−trace if there is an error.
374+`%dude` computes the given silk with the given tank as part of the stack trace
375+if there is an error.
394376
395−`%dune` produces an error if the cage is empty. Otherwise, it produces
396−the value in the unit.
377+`%dune` produces an error if the cage is empty. Otherwise, it produces the value
378+in the unit.
397379
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.
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.
400382
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.
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.
404386
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.
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.
408390
409−`%reef` produces a core containing the entirety of zuse and hoon,
410−suitable for running arbitrary code against. The mark is `%noun`.
391+`%reef` produces a core containing the entirety of zuse and hoon, suitable for
392+running arbitrary code against. The mark is `%noun`.
411393
412−`%ride` slaps a twig against a subject silk. The mark of the result is
413−`%noun`.
394+`%ride` slaps a twig against a subject silk. The mark of the result is `%noun`.
414395
415−`%vale` validates untyped data from a ship against a given mark. This is
416−an extremely useful function.
396+`%vale` validates untyped data from a ship against a given mark. This is an
397+extremely useful function.
417398
418−Commentary
419−==========
399+# Commentary
420400
421−Parsing Hook Files
422−------------------
401+## Parsing Hook Files
423402
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.
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.
428407
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.
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.
433411
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.
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.
437415
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.
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.
442420
443421We kick off with `++hood:fair`.
444422
@@ -464,24 +442,23 @@ We kick off with `++hood:fair`.
464442 (most gap hoop)
465443 ==
466444
467−There are five sections to a hood: system version, structures,
468−libraries, resources, and body.
445+There are five sections to a hood: system version, structures, libraries,
446+resources, and body.
469447
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.
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.
473450
474−Second, we may have zero or more `/-` runes followed by a parsing of a
475−`++hoot`, which represents a shared structure.
451+Second, we may have zero or more `/-` runes followed by a parsing of a `++hoot`,
452+which represents a shared structure.
476453
477−Third, we may have zero or more `/+` runes followed by a parsing of a
478−`++hoof`, which represents a shared library.
454+Third, we may have zero or more `/+` runes followed by a parsing of a `++hoof`,
455+which represents a shared library.
479456
480−Fourth, we may have zero or more other `/` runes (as described in
481−`++horn`), which represent program-specific resources to be loaded.
457+Fourth, we may have zero or more other `/` runes (as described in `++horn`),
458+which represent program-specific resources to be loaded.
482459
483−Fifth and finally, we must have one or more body statements (hoops),
484−which are either direct twigs or `//` runes.
460+Fifth and finally, we must have one or more body statements (hoops), which are
461+either direct twigs or `//` runes.
485462
486463 ++ hoot
487464 ;~ pose
@@ -489,9 +466,9 @@ which are either direct twigs or `//` runes.
489466 (stag %& hoof)
490467 ==
491468
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 `*`.
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 `*`.
495472
496473 ++ hoof
497474 %+ cook |=(a=^hoof a)
@@ -504,11 +481,11 @@ requireing core references to be prefixed by a `*`.
504481 ==
505482 ==
506483
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`.
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`.
512489
513490 ++ case
514491 %- sear
@@ -517,11 +494,11 @@ ship name to denote the requested source of the resource. For example,
517494 ?. ?=([%$ ?(%da %ud %tas) *] a) ~
518495 [~ u=(^case a)]
519496
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.
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.
522499
523−This leaves only horns and hoops to parse. Hoops are much simple to
524−parse, so we'll discuss those first.
500+This leaves only horns and hoops to parse. Hoops are much simple to parse, so
501+we'll discuss those first.
525502
526503 ++ hoop
527504 ;~ pose
@@ -529,20 +506,20 @@ parse, so we'll discuss those first.
529506 (stag %& tall:vez)
530507 ==
531508
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.
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.
534511
535−References to external twigs are marked with a `//` rune followed by a
536−beam, which is parsed with `++have`.
512+References to external twigs are marked with a `//` rune followed by a beam,
513+which is parsed with `++have`.
537514
538515 ++ hath (sear plex:voz (stag %clsg poor:voz)) :: hood path
539516 ++ have (sear tome ;~(pfix fas hath)) :: hood beam
540517
541−`++have` parses a path with `++hath`, and then it converts the path into
542−a beam with `++tome`.
518+`++have` parses a path with `++hath`, and then it converts the path into a beam
519+with `++tome`.
543520
544−`++hath` parses a `/`-separated list with `++poor:vast`, then converts
545−it to an actual path with `++plex:vast`.
521+`++hath` parses a `/`-separated list with `++poor:vast`, then converts it to an
522+actual path with `++plex:vast`.
546523
547524This leaves only horns to parse.
548525
@@ -571,18 +548,17 @@ This leaves only horns to parse.
571548 ==
572549 ==
573550
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`.
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`.
578555
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/`.
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/`.
583559
584−We'll examine each of the horn parsing arms right after we discuss
585−`++rail`, which is used in each one.
560+We'll examine each of the horn parsing arms right after we discuss `++rail`,
561+which is used in each one.
586562
587563 ++ rail
588564 |* [wid=_rule tal=_rule]
@@ -590,8 +566,8 @@ We'll examine each of the horn parsing arms right after we discuss
590566 ;~(pose wid tal)
591567
592568This takes a wide-form and a tall-form parsing rule. If tall form is
593−permissible, then it allows either rule to match; else, it allows only
594−the wide form rule.
569+permissible, then it allows either rule to match; else, it allows only the wide
570+form rule.
595571
596572 ++ read
597573 |% ++ ape
@@ -599,49 +575,47 @@ the wide form rule.
599575 (ifix [sel ser] (stag %cltr (most ace wide:vez)))
600576 ;~(pfix gap tall:vez)
601577
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`
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`
606582
607583 ++ day
608584 %+ rail
609585 apex(tol |)
610586 ;~(pfix gap apex)
611587
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.
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.
616591
617592 ++ dub
618593 %+ rail
619594 ;~(plug sym ;~(pfix tis apex(tol |)))
620595 ;~(pfix gap ;~(plug sym ;~(pfix gap apex)))
621596
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.
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.
627601
628602 ++ fan
629603 %+ rail fail
630604 ;~(sfix (star ;~(pfix gap apex)) ;~(plug gap duz))
631605
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.
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.
635609
636610 ++ for
637611 %+ rail
638612 ;~(plug (ifix [sel ser] hath) apex(tol |))
639613 ;~(pfix gap ;~(plug hath ;~(pfix gap apex)))
640614
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.
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.
645619
646620 ++ man
647621 %+ rail fail
@@ -654,31 +628,31 @@ a path, another gap, and, recursively, the entire horn parser.
654628 ?. ?=(%dub -.i.fan) ~
655629 $(fan t.fan, naf [[p.i.fan q.i.fan] naf])
656630
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.
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.
662636
663637 ++ saw
664638 %+ rail
665639 ;~(plug ;~(sfix wide:vez sem) apex(tol |))
666640 ;~(pfix gap ;~(plug tall:vez ;~(pfix gap apex)))
667641
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.
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.
672646
673647 ++ see
674648 %+ rail
675649 ;~(plug ;~(sfix have col) apex(tol |))
676650 ;~(pfix gap ;~(plug have ;~(pfix gap apex)))
677651
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.
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.
682656
683657 ++ sic
684658 %+ rail
@@ -686,18 +660,17 @@ beam, another gap, and, recursively, the entire horn parser.
686660 ;~(pfix gap ;~(plug howl:vez ;~(pfix gap apex)))
687661 --
688662
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.
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.
694668
695−Assembling Hook Files
696−---------------------
669+## Assembling Hook Files
697670
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.
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.
701674
702675 ++ meow :: assemble
703676 |= [how=beam arg=heel]
@@ -711,47 +684,45 @@ assembling is handled entirely within the `++meow:zo:za` core.
711684 ==
712685 |%
713686
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.
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.
717690
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.
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.
721694
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.
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.
726699
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.
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.
730703
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.
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.
737709
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.
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.
742714
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.
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.
745717
746−In `hol`, we decide if we're allowed to contain horns. Libraries and
747−structures are not allowed to contain horns.
718+In `hol`, we decide if we're allowed to contain horns. Libraries and structures
719+are not allowed to contain horns.
748720
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.
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.
755726
756727 ++ cope :: bolt along
757728 |* [hoc=(bolt) fun=(burg)]
@@ -767,40 +738,36 @@ here.
767738 %0 [%0 p=(grom `_p.q.nuf`p.q.hoc p.q.nuf) q=q.q.nuf]
768739 == ==
769740
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`.
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`.
804771
805772 ++ abut :: generate
806773 |= [cof=cafe hyd=hood]
@@ -816,18 +783,17 @@ interesting uses of it. For now, this is sufficient to move on with
816783 |= [cof=cafe fin=vase]
817784 (fine cof fin)
818785
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.
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.
822789
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.
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.
831797
832798 ++ apex :: build to body
833799 |= [cof=cafe hyd=hood]
@@ -852,9 +818,9 @@ Otherwise, we produce and error with `++flaw`.
852818
853819This produces a `%2` error bolt from a list of tanks. Fairly trivial.
854820
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`.
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`.
858824
859825 ++ body :: produce functions
860826 |= [cof=cafe src=(list hoop)]
@@ -864,19 +830,19 @@ the libraries with `++neck`, and the structures with `++head`.
864830 |= [cof=cafe sel=_..body]
865831 ^$(cof cof, src t.src, ..body sel)
866832
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`.
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`.
869835
870836 ++ fine |* [a=cafe b=*] :: bolt from data
871837 [p=`cafe`a q=[%0 p=*(set beam) q=b]] ::
872838
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.
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.
877843
878−If there are more hoops in `++body`, we call `++wilt` to process an
879−individual hoop and recurse.
844+If there are more hoops in `++body`, we call `++wilt` to process an individual
845+hoop and recurse.
880846
881847 ++ wilt :: process body entry
882848 |= [cof=cafe hop=hoop]
@@ -916,24 +882,22 @@ individual hoop and recurse.
916882 (fine cof sel(boy [[%brcn mav] boy]))
917883 ==
918884
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.
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.
922887
923−First, we push onto the stack trace a message indicating which file
924−exactly we're compiling at the moment with `++cool`.
888+First, we push onto the stack trace a message indicating which file exactly
889+we're compiling at the moment with `++cool`.
925890
926891 ++ cool :: error caption
927892 |* [cyt=trap hoc=(bolt)]
928893 ?. ?=(%2 -.q.hoc) hoc
929894 [p.hoc [%2 *cyt p.q.hoc]]
930895
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.
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.
934898
935−Next in `++wilt`, we load the information about the filesystem node
936−referenced by the hoop with `++lend`.
899+Next in `++wilt`, we load the information about the filesystem node referenced
900+by the hoop with `++lend`.
937901
938902 ++ lend :: load arch
939903 |= [cof=cafe bem=beam]
@@ -942,28 +906,27 @@ referenced by the hoop with `++lend`.
942906 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
943907 (fine cof ((hard arch) (need u.von)))
944908
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.
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.
948912
949913Continuing in `++wilt`, we examine the produced arch. If the referenced
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`.
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`.
954918
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.
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.
960923
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.
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.
963926
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`.
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`.
967930
968931 ++ lark :: filter arch names
969932 |= [wox=$+(span (unit ,@)) arc=arch]
@@ -976,43 +939,39 @@ whose names are terms with `++lark`.
976939 =+ gib=(wox p.n.r.arc)
977940 ?~(gib rac [[u.gib p.n.r.arc] rac])
978941
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.
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.
985947
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`.
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`.
991952
992−If there are no more children, then we are done, so we produce our
993−current context.
953+If there are no more children, then we are done, so we produce our current
954+context.
994955
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.
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.
1001962
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.
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.
1005966
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`.
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`.
1009969
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.
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.
1013972
1014−This concludes our discussion of `++wilt` and `++body`. Thus, it remains
1015−in `++apex` to discuss `++neck` and `++head`.
973+This concludes our discussion of `++wilt` and `++body`. Thus, it remains in
974+`++apex` to discuss `++neck` and `++head`.
1016975
1017976 ++ neck :: consume libraries
1018977 |= [cof=cafe bir=(list hoof)]
@@ -1040,26 +999,24 @@ in `++apex` to discuss `++neck` and `++head`.
1040999 ==
10411000 ^^$(cof cof, bir t.bir)
10421001
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.
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.
10461004
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.
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.
10501008
10511009Otherwise, we let `gez` be `zeg` plus the current library so that while
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`.
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`.
10631020
10641021 ++ hone :: plant hoof
10651022 |= [for=@tas way=@tas huf=hoof]
@@ -1068,28 +1025,27 @@ that. First, we get the location of the library with `++hone`.
10681025 how(s ~[for p.huf way])
10691026 [[q.u.q.huf %main p.u.q.huf] ~[for p.huf way]]
10701027
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.
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.
10931049
10941050Finally, we recurse, processing the next library in our list.
10951051
@@ -1128,38 +1084,36 @@ To complete our disucssion of `++apex`, we must process our structures.
11281084 ==
11291085 ^^$(cof cof, bir t.bir)
11301086
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.
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.
11631117
11641118Finally, we recurse, processing the next structure in our list.
11651119
@@ -1179,9 +1133,9 @@ This concludes our discussion of `++apex`.
11791133 |= [cof=cafe fin=vase]
11801134 (fine cof fin)
11811135
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`.
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`.
11851139
11861140 ++ able :: assemble preamble
11871141 ^- twig
@@ -1189,10 +1143,10 @@ against zuse. First, we construct our preamble in `++able`.
11891143 ?:(=(~ rop) [%$ 1] [%brcn (~(run by rop) |=([* a=twig] [%ash a]))])
11901144 [%tssg (turn (flop lot) |=(a=term q:(need (~(get by bil) a))))]
11911145
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.
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.
11961150
11971151We slap the preamble against zuse with `++maim`.
11981152
@@ -1209,49 +1163,47 @@ We slap the preamble against zuse with `++maim`.
12091163 `vase`[p.p.puz val]
12101164 ==
12111165
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.
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.
12161170
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.
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.
12201174
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.
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.
12261179
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.
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.
12331186
1234−We haven't yet discussed either `++clef` or `++coup`. We'll start with
1235−`++coup` to finish the discussion of the computation.
1187+We haven't yet discussed either `++clef` or `++coup`. We'll start with `++coup`
1188+to finish the discussion of the computation.
12361189
12371190\``++ 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 == ==`
12381191
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.
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.
12441196
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.
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.
12521204
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.
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.
12551207
12561208We will now discuss `++clef`. This is where the cache magic happens.
12571209
@@ -1286,29 +1238,28 @@ Otherwise, we look up the request in the cache with `++calk`.
12861238 ?~ d [~ a] ::
12871239 [d a(p (~(put in p.a) u.d))] ::
12881240
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.
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.
12931245
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`.
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`.
12991251
13001252 ++ came ::
13011253 |= [a=cafe b=calx] :: cache install
13021254 ^- cafe ::
13031255 a(q (~(put by q.a) [-.b q.b] b)) ::
13041256
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.
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.
13081260
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`.
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`.
13121263
13131264 ++ calf :: reduce calx
13141265 |* sem=* :: a typesystem hack
@@ -1319,23 +1270,22 @@ value at that cache line. We convert the cache line into a value with
13191270 %slam ?>(?=(%slam -.cax) r.cax)
13201271 ==
13211272
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.
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.
13281279
13291280This concludes our discussion of `++clef` and `++maim`.
13301281
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.
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.
13361286
1337−`++chap` is broken up into a different case for each horn. We'll go
1338−through them one by one.
1287+`++chap` is broken up into a different case for each horn. We'll go through them
1288+one by one.
13391289
13401290 ++ chap :: produce resources
13411291 |= [cof=cafe bax=vase hon=horn]
@@ -1350,9 +1300,9 @@ This is `/~`. We slap the twig against our context.
13501300 |= [cof=cafe gat=vase]
13511301 (maul cof gat !>([how arg]))
13521302
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).
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).
13561306
13571307`++maul` is similar to `++maim`, but it slams instead of slaps.
13581308
@@ -1369,20 +1319,19 @@ which is our location and the heel (virtual path extension).
13691319 `vase`[p.top val]
13701320 ==
13711321
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.
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.
13751324
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`.
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`.
13791328
13801329Back to `++chap`.
13811330
13821331 %day (chad cof bax %dr p.hon)
13831332
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.
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.
13861335
13871336 ++ chad :: atomic list
13881337 |= [cof=cafe bax=vase doe=term hon=horn]
@@ -1406,8 +1355,8 @@ dates and process the next horn against each of the discovered paths.
14061355 ?~ yal [[%cube 0 [%atom %n]] 0]
14071356 (slop (slop [[%atom doe] p.i.yal] q.i.yal) $(yal t.yal))
14081357
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.
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.
14111360
14121361 ++ lash :: atomic sequence
14131362 |= wox=$+(span (unit ,@))
@@ -1417,26 +1366,22 @@ pick out those ones that are of the requested format.
14171366 |= [cof=cafe arc=arch]
14181367 (fine cof (lark wox arc))
14191368
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.
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.
14231371
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.
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.
14271374
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.
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.
14311377
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.
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.
14351381
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.
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.
14401385
14411386Back in `++chap`, we continue parsing resources.
14421387
@@ -1445,8 +1390,8 @@ Back in `++chap`, we continue parsing resources.
14451390 |= [cof=cafe vax=vase]
14461391 (fine cof [[%face p.hon p.vax] q.vax])
14471392
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.
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.
14501395
14511396 %fan
14521397 %+ cope
@@ -1463,21 +1408,21 @@ face on the vase so that it may be referred to later by name.
14631408 ?~ tev [[%cube 0 [%atom %n]] 0]
14641409 (slop i.tev $(tev t.tev))
14651410
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.
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.
14691414
14701415 %for $(hon q.hon, s.how (weld (flop p.hon) s.how))
14711416
1472−This is `/,`. We simply recurse on the horn with the given path welded
1473−onto our current beam.
1417+This is `/,`. We simply recurse on the horn with the given path welded onto our
1418+current beam.
14741419
14751420 %hub (chad cof bax %ud p.hon)
14761421
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.
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.
14811426
14821427 %man
14831428 |- ^- (bolt vase)
@@ -1493,21 +1438,20 @@ and produce a list of pairs of absolute dates and values.
14931438 (slop [[%atom %tas] p.n.p.hon] vax)
14941439 (slop lef rig)
14951440
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.
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.
14991444
15001445 %now (chad cof bax %da p.hon)
15011446
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.
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.
15061451
15071452 %nap (chai cof bax p.hon)
15081453
1509−This is `/%`. Here, we process the horn at each of our children with
1510−`++chai`.
1454+This is `/%`. Here, we process the horn at each of our children with `++chai`.
15111455
15121456 ++ chai :: atomic map
15131457 |= [cof=cafe bax=vase hon=horn]
@@ -1532,10 +1476,10 @@ This is `/%`. Here, we process the horn at each of our children with
15321476 (slop [[%atom %a] p.n.doy] q.n.doy)
15331477 (slop $(doy l.doy) $(doy r.doy))
15341478
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`.
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`.
15391483
15401484 %see $(hon q.hon, how p.hon)
15411485
@@ -1548,9 +1492,9 @@ This is `/:`. We process the given horn at the given beam.
15481492 |= [cof=cafe gat=vase]
15491493 (maul cof gat sam)
15501494
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.
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.
15541498
15551499 %sic
15561500 %+ cope $(hon q.hon)
@@ -1561,27 +1505,26 @@ the vase we got from processing the horn against the gate.
15611505 (flaw cof [%leaf "type error: {<p.hon>} {<q.hon>}"]~)
15621506 (fine cof [p.tug q.vax])
15631507
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.
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.
15701513
15711514 %toy (cope (make cof %bake p.hon how ~) feel)
15721515 ==
15731516
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.
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.
15771520
15781521 ++ feel |=([a=cafe b=cage] (fine a q.b)) :: cage to vase
15791522
15801523This is trivial.
15811524
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.
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.
15851528
15861529This concludes our discussion of `++chap`.
15871530
@@ -1601,26 +1544,24 @@ We return once more to `++abut`.
16011544 |= [cof=cafe fin=vase]
16021545 (fine cof fin)
16031546
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.
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.
16091552
16101553The hook file has been assembled. And there was great rejoicing.
16111554
1612−Lifecycle of a Kiss
1613−-------------------
1555+## Lifecycle of a Kiss
16141556
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.
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.
16191560
16201561First, though, we'll describe the common handling to all kisses.
16211562
1622−The silk in a `%exec` kiss to ford ends up in `++apex`, so we'll enter
1623−the narrative here.
1563+The silk in a `%exec` kiss to ford ends up in `++apex`, so we'll enter the
1564+narrative here.
16241565
16251566 ++ apex :: call
16261567 |= kus=(unit silk)
@@ -1639,13 +1580,13 @@ the narrative here.
16391580 ==
16401581 ~(exec zo [num `task`[hen u.kus 0 ~]])
16411582
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.
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.
16491590
16501591 ++ camo :: stop requests
16511592 ^+ .
@@ -1661,9 +1602,9 @@ requests, and call `++amok:zo` to remove the task from our task lists.
16611602 [%warp [our p.q.i.kiz] q.q.i.kiz ~]
16621603 ==
16631604
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.
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.
16671608
16681609 ++ amok
16691610 %_ ..zo
@@ -1671,12 +1612,12 @@ need only to send `%warp` kisses with a null instead of a rave.
16711612 dym.bay (~(del by dym.bay) nah)
16721613 ==
16731614
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.
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.
16761617
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.
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.
16801621
16811622 ++ exec :: execute app
16821623 ^+ ..zo
@@ -1697,9 +1638,9 @@ the task to our maps, increment the next task number, and call
16971638
16981639If we're still blocked on something in `q.kig`, we don't do anything.
16991640
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.
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.
17031644
17041645We put the new cache in our state with `++dash`.
17051646
@@ -1708,13 +1649,12 @@ We put the new cache in our state with `++dash`.
17081649 ^+ +>
17091650 %_(+> jav.bay q.cof)
17101651
1711−The cache is put in the baby so that it gets stored across calls to
1712−ford.
1652+The cache is put in the baby so that it gets stored across calls to ford.
17131653
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`.
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`.
17181658
17191659 ++ expo :: return gift
17201660 |= gef=gift
@@ -1722,11 +1662,11 @@ gift, and we remove ourselves from the task list with `++amok`.
17221662
17231663We simply push the gift onto our list of moves.
17241664
1725−In `++exec`, if we produced a `%2` error bolt, we produce a `%made` gift
1726−with the stack trace.
1665+In `++exec`, if we produced a `%2` error bolt, we produce a `%made` gift with
1666+the stack trace.
17271667
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.
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.
17301670
17311671 ++ camp :: request a file
17321672 |= [ren=care bem=beam]
@@ -1740,16 +1680,13 @@ and call `++camp` to produce a clay request for the resource.
17401680 [%warp [our p.bem] q.bem [~ %& %x r.bem s.bem]]
17411681 ==
17421682
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]'.
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\]'.
17471686
1748−We'll now describe how each of the individual silks are processed in
1749−`++make`.
1687+We'll now describe how each of the individual silks are processed in `++make`.
17501688
1751−Lifecycle of a Cell
1752−-------------------
1689+## Lifecycle of a Cell
17531690
17541691 ^
17551692 %. [cof p.kas q.kas]
@@ -1763,10 +1700,10 @@ Lifecycle of a Cell
17631700 [p=cof q=[%0 ~ [%$ (slop q.bor q.heg)]]]
17641701 ==
17651702
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.
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.
17701707
17711708 ++ coax :: bolt across
17721709 |* [hoc=(bolt) fun=(burg)]
@@ -1790,23 +1727,19 @@ which means we know no more mark information than that it is a noun.
17901727 %2 hoc
17911728 ==
17921729
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.
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.
17971733
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.
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.
18021737
18031738If the first bolt is already an error, we just pass that through.
18041739
1805−Note that `++coax` (and, indeed, `++cope`) is reasonable to use with
1806−`;~`.
1740+Note that `++coax` (and, indeed, `++cope`) is reasonable to use with `;~`.
18071741
1808−Lifecycle of a `%bake`
1809−----------------------
1742+## Lifecycle of a `%bake`
18101743
18111744 %bake
18121745 %+ cool |.(leaf/"ford: bake {<p.kas>} {<(tope q.kas)>}")
@@ -1816,12 +1749,11 @@ Lifecycle of a `%bake`
18161749 (flaw cof (smyt (tope q.kas)) ~)
18171750 (fine cof [p.kas u.vux])
18181751
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.
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.
18251757
18261758 ++ lima :: load at depth
18271759 |= [cof=cafe for=mark bem=beam arg=heel]
@@ -1843,19 +1775,19 @@ give it the correct mark.
18431775 |= [cof=cafe vax=vase]
18441776 (fine cof ~ vax)
18451777
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`.
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`.
18491781
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.
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.
18561788
1857−We'll first discuss the direct case of when one of our children is of
1858−the correct mark.
1789+We'll first discuss the direct case of when one of our children is of the
1790+correct mark.
18591791
18601792 ++ lace :: load and check
18611793 |= [cof=cafe for=mark bem=beam arg=heel]
@@ -1871,11 +1803,10 @@ the correct mark.
18711803 (cope (cope (abut:(meow bem arg) cof hyd) (lake for bek)) fest)
18721804 (fine cof ~)
18731805
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`.
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`.
18791810
18801811Otherwise, there is no way to translate this, so we produce null.
18811812
@@ -1886,9 +1817,8 @@ Otherwise, there is no way to translate this, so we produce null.
18861817This is just `++some` for bolts.
18871818
18881819We've delayed the discussion of `++fade` far too many times. It's not
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.
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.
18921822
18931823 ++ fade :: compile to hood
18941824 |= [cof=cafe for=mark bem=beam]
@@ -1907,18 +1837,17 @@ with ease.
19071837 (flaw cof [%leaf "syntax error: {<p.p.vex>} {<q.p.vex>}"] ~)
19081838 (fine cof p.u.q.vex)
19091839
1910−We first push a line onto a stack trace to say that we're parsing into a
1911−hood file.
1840+We first push a line onto a stack trace to say that we're parsing into a hood
1841+file.
19121842
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.
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.
19171846
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.
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.
19221851
19231852 ++ liar :: load vase
19241853 |= [cof=cafe bem=beam]
@@ -1930,15 +1859,14 @@ line and column number. Otherwise, we produce the value.
19301859 (flaw cof (smyt (tope bem)) ~)
19311860 (fine cof ?^(u.u.von [%cell %noun %noun] [%atom %$]) u.u.von)
19321861
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.
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.
19391868
1940−Back in `++lima`, recall that we call `++lion` to find a translation
1941−path.
1869+Back in `++lima`, recall that we call `++lion` to find a translation path.
19421870
19431871 ++ lion :: translation search
19441872 |= [cof=cafe too=@tas bek=beak fro=(list ,@tas)]
@@ -1973,41 +1901,38 @@ path.
19731901 (fine cof ?~(ked ~ [~ for u.ked]))
19741902 --
19751903
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.
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.
19851912
1986−We kick off our search in `++apex`, starting with the given initial list
1987−of marks that we know how to get to.
1913+We kick off our search in `++apex`, starting with the given initial list of
1914+marks that we know how to get to.
19881915
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.
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.
19931920
19941921Otherwise, we process this next mark with `++apse`, which will produce a
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.
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.
19991925
2000−If it doesn't produce null, then we have successfully found a
2001−translation path, so we produce it.
1926+If it doesn't produce null, then we have successfully found a translation path,
1927+so we produce it.
20021928
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.
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.
20081934
2009−We call `++lily` to get the list of marks we can translate this one
2010−into.
1935+We call `++lily` to get the list of marks we can translate this one into.
20111936
20121937 ++ lily :: translation targets
20131938 |= [cof=cafe for=mark bek=beak]
@@ -2026,29 +1951,27 @@ into.
20261951 =+ gow=(slap vax [%cnzy %grow])
20271952 (sloe p.gow)
20281953
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.
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.
20321957
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.
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.
20371962
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`.
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`.
20421966
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.
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.
20471970
20481971This concludes our discussion of `++lion`.
20491972
2050−The final piece of `++lima` is `++lope`, which performs the actual
2051−translation along the path we just computed.
1973+The final piece of `++lima` is `++lope`, which performs the actual translation
1974+along the path we just computed.
20521975
20531976 ++ lope :: translation pipe
20541977 |= [cof=cafe for=mark yaw=(list mark) bek=beak vax=vase]
@@ -2058,14 +1981,12 @@ translation along the path we just computed.
20581981 |= [cof=cafe yed=vase]
20591982 ^$(cof cof, for i.yaw, yaw t.yaw, vax yed)
20601983
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.
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.
20661988
2067−Lifecycle of a `%boil`
2068−----------------------
1989+## Lifecycle of a `%boil`
20691990
20701991 %boil
20711992 %+ cool |.(leaf/"ford: boil {<p.kas>} {<(tope q.kas)>} {<r.kas>}")
@@ -2075,13 +1996,13 @@ Lifecycle of a `%boil`
20751996 |= [cof=cafe vax=vase]
20761997 (fine cof `cage`[p.kas vax])
20771998
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.
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.
20812002
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.
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.
20852006
20862007 ++ lamp :: normalize version
20872008 |= [cof=cafe bem=beam]
@@ -2090,11 +2011,10 @@ ephemeral like a particular time.
20902011 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
20912012 (fine cof bem(r [%ud ((hard ,@) (need u.von))]))
20922013
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.
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.
20982018
20992019Next for `%boil` we call `++lime` to try to load the beam.
21002020
@@ -2109,14 +2029,13 @@ Next for `%boil` we call `++lime` to try to load the beam.
21092029 (flaw cof (smyt (tope bem)) ~)
21102030 ^$(s.mob t.s.mob, mer [i.s.mob mer])
21112031
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.
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.
21172037
2118−Lifecycle of a `%call`
2119−----------------------
2038+## Lifecycle of a `%call`
21202039
21212040 %call
21222041 %+ cool |.(leaf/"ford: call {<`@p`(mug kas)>}")
@@ -2134,15 +2053,13 @@ Lifecycle of a `%call`
21342053 (fine cof %noun vax)
21352054 ==
21362055
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.
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.
21412059
21422060`++coax` is documented under Lifecycle of a Cell.
21432061
2144−Lifecycle of a `%cast`
2145−----------------------
2062+## Lifecycle of a `%cast`
21462063
21472064 %cast
21482065 %+ cool |.(leaf/"ford: cast {<p.kas>}")
@@ -2152,11 +2069,11 @@ Lifecycle of a `%cast`
21522069 |= [cof=cafe vax=vase]
21532070 (fine cof [p.kas vax])
21542071
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.
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.
21602077
21612078 ++ link :: translate
21622079 |= [cof=cafe too=mark for=mark bek=beak vax=vase]
@@ -2181,29 +2098,28 @@ the `++grow` of the given mark or the `++grab` of the target mark.
21812098 (flaw cof [%leaf "ford: no link: {<[for too]>}"]~)
21822099 (maul cof u.zat vax)
21832100
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.
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.
21882105
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.
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.
21932110
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.
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.
21992116
22002117If you're confused as to why the handling of `++grow` and `++grab` look
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.
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.
22042121
2205−Lifecycle of a `%diff`
2206−----------------------
2122+## Lifecycle of a `%diff`
22072123
22082124 %diff
22092125 %+ cool |.(leaf/"ford: diff {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
@@ -2228,8 +2144,7 @@ First, we process the two given silks to get our arguments.
22282144 %+ flaw cof :_ ~
22292145 leaf/"diff on data of different marks: {(trip p.cay)} {(trip p.coy)}"
22302146
2231−If the two cages have different marks, then we can't diff them, so we
2232−complain.
2147+If the two cages have different marks, then we can't diff them, so we complain.
22332148
22342149 %+ cope (fang cof p.cay [our %main %da now])
22352150 |= [cof=cafe pro=vase]
@@ -2247,12 +2162,11 @@ We pull in the relevant mark's definition.
22472162 (flaw cof leaf/"bad ++sted:grad" ~)
22482163 (make cof %diff [%cast u.for kas] [%cast u.for kos])
22492164
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.
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.
22562170
22572171 ?. (slab %diff p.gar)
22582172 (flaw cof leaf/"no ++diff:grad" ~)
@@ -2262,8 +2176,7 @@ Otherwise, we expect a `++diff:grad`.
22622176 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
22632177 |= [cof=cafe pox=vase]
22642178
2265−We put the first cage's data into the sample of the given mark's
2266−definition.
2179+We put the first cage's data into the sample of the given mark's definition.
22672180
22682181 %+ cope
22692182 %^ maul cof
@@ -2279,46 +2192,41 @@ We run `++diff:grad` with a sample of the second cage's data.
22792192 (fine cof u.for dif)
22802193 ==
22812194
2282−We check that `++form:grad` exists, and we tag the result with it to
2283−give the final cage.
2195+We check that `++form:grad` exists, and we tag the result with it to give the
2196+final cage.
22842197
2285−Lifecycle of a `%done`
2286−----------------------
2198+## Lifecycle of a `%done`
22872199
22882200 %done [cof %0 p.kas q.kas]
22892201
22902202This is trivial. We simply produce the given cage with the given set of
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.
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.
22952206
2296−Lifecycle of a `%dude`
2297−----------------------
2207+## Lifecycle of a `%dude`
22982208
22992209 %dude (cool |.(p.kas) $(kas q.kas))
23002210
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`.
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`.
23032213
2304−Lifecycle of a `%dune`
2305−----------------------
2214+## Lifecycle of a `%dune`
23062215
23072216 %dune
23082217 ?~ q.kas [cof [%2 [%leaf "no data"]~]]
23092218 $(kas [%done p.kas u.q.kas])
23102219
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.
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.
23132222
2314−Lifcycle of a `%mute`
2315−---------------------
2223+## Lifcycle of a `%mute`
23162224
23172225 %mute (kale cof p.kas q.kas)
23182226
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.
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.
23222230
23232231 ++ kale :: mutate
23242232 |= [cof=cafe kas=silk muy=(list (pair wing silk))]
@@ -2338,10 +2246,10 @@ in a mark definition.
23382246 |= [cof=cafe vax=vase]
23392247 (fine cof p.cay vax)
23402248
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.
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.
23452253
23462254 ++ keel :: apply mutations
23472255 |= [cof=cafe suh=vase yom=(list (pair wing vase))]
@@ -2359,19 +2267,16 @@ of the main silk, so we mark the produced vase with the original mark.
23592267 :- [p.i.yom [%$ (peg axe 2)]]
23602268 $(yom t.yom, axe (peg axe 3))
23612269
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.
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.
23682275
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.
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.
23722278
2373−Lifecycle of a `%pact`
2374−----------------------
2279+## Lifecycle of a `%pact`
23752280
23762281 %pact
23772282 %+ cool |.(leaf/"ford: pact {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
@@ -2408,12 +2313,12 @@ We pull in the relevant mark's definition.
24082313 (flaw cof leaf/"bad ++sted:grad" ~)
24092314 (make cof %cast p.cay %pact [%cast u.for kas] kos)
24102315
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.
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.
24172322
24182323 =+ for=((soft ,@tas) q:(slap gar [%cnzy %form]))
24192324 ?~ for
@@ -2423,8 +2328,8 @@ to patch. Afterward, we cast the result back to the original mark.
24232328 =< leaf/"pact on data with wrong form: {-} {+<} {+>}"
24242329 [(trip p.cay) (trip u.for) (trip p.coy)]
24252330
2426−If `++form:grad` isn't a term, or else our second argument isn't of that
2427−mark, we complain.
2331+If `++form:grad` isn't a term, or else our second argument isn't of that mark,
2332+we complain.
24282333
24292334 ?. (slab %pact p.gar)
24302335 (flaw cof leaf/"no ++pact:grad" ~)
@@ -2434,8 +2339,7 @@ If we don't have a `++pact:grad`, we complain.
24342339 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
24352340 |= [cof=cafe pox=vase]
24362341
2437−We put the first cage's data into the sample of the given mark's
2438−definition.
2342+We put the first cage's data into the sample of the given mark's definition.
24392343
24402344 %+ cope
24412345 %^ maul cof
@@ -2443,36 +2347,32 @@ definition.
24432347 q.coy
24442348 |= [cof=cafe pat=vase]
24452349
2446−We run `++pact:grad` with a sample of the second cage's data, which is
2447−the diff.
2350+We run `++pact:grad` with a sample of the second cage's data, which is the diff.
24482351
24492352 (fine cof p.cay pat)
24502353 ==
24512354
24522355We tag the result with the mark of our first argument.
24532356
2454−Lifecycle of a `%plan`
2455−----------------------
2357+## Lifecycle of a `%plan`
24562358
24572359 %plan
24582360 %+ cope (abut:(meow p.kas q.kas) cof r.kas)
24592361 |= [cof=cafe vax=vase]
24602362 (fine cof %noun vax)
24612363
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`.
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`.
24652367
2466−Lifecycle of a `%reef`
2467−----------------------
2368+## Lifecycle of a `%reef`
24682369
24692370 %reef (fine cof %noun pit)
24702371
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`.
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`.
24732374
2474−Lifcycle of a `%ride`
2475−---------------------
2375+## Lifcycle of a `%ride`
24762376
24772377 %ride
24782378 %+ cool |.(leaf/"ford: ride {<`@p`(mug kas)>}")
@@ -2482,12 +2382,11 @@ Lifcycle of a `%ride`
24822382 |= [cof=cafe vax=vase]
24832383 (fine cof %noun vax)
24842384
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`.
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`.
24882388
2489−Lifecycle of a `%vale`
2490−----------------------
2389+## Lifecycle of a `%vale`
24912390
24922391 %vale
24932392 %+ cool |.(leaf/"ford: vale {<p.kas>} {<q.kas>} {<`@p`(mug r.kas)>}")
@@ -2495,20 +2394,20 @@ Lifecycle of a `%vale`
24952394 |= [cof=cafe vax=vase]
24962395 (fine cof `cage`[p.kas vax])
24972396
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.
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.
25002399
2501−We call `++lave` to perform the check, producing a vase. We produce this
2502−vase tagged with the given mark.
2400+We call `++lave` to perform the check, producing a vase. We produce this vase
2401+tagged with the given mark.
25032402
25042403 ++ lave :: validate
25052404 |= [cof=cafe for=mark his=ship som=*]
25062405 ^- (bolt vase)
25072406 ((lake for [our %main [%da now]]) cof [%noun som])
25082407
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.
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.
25122411
25132412At any rate, `++lake` coerces a noun into the correct type for a mark.
25142413
@@ -2536,27 +2435,24 @@ At any rate, `++lake` coerces a noun into the correct type for a mark.
25362435 (fine cof (slot 6 pro))
25372436 (flaw cof [%leaf "ford: invalid content: {<[for bek]>}"]~)
25382437
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.
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.
25442442
2545−Otherwise, we get the mark definition from our `/=main=/mar` directory
2546−with `++fang`, which we'll describe below.
2443+Otherwise, we get the mark definition from our `/=main=/mar` directory with
2444+`++fang`, which we'll describe below.
25472445
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.
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.
25512448
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.
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.
25552451
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.
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.
25602456
25612457 ++ fang :: protocol door
25622458 |= [cof=cafe for=mark bek=beak]
@@ -2571,6 +2467,6 @@ sample of the door. Otherwise, we fail.
25712467 (cope (fade cof %hook bem) abut:(meow bem ~))
25722468
25732469A mark's definition is generally in
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.
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.