@@ -1,10 +1,13 @@
2−navhome: '/docs/'
2+navhome: /docs/
7−## Data Models
6+Reference
9### `++axle`, formal state
12### `++axle`, formal state
@@ -13,13 +16,13 @@ navhome: '/docs/'
13 pol=(map ship baby) ::
16 pol=(map ship baby) ::
16−This is the formal state of our vane. Anything that must be remembered between
19+This is the formal state of our vane. Anything that must be remembered
17−calls to ford must be stored here. The number `%1` is a version number for our
20+between calls to ford must be stored here. The number `%1` is a version
18−state that allows us to upgrade the structure of our state in the future if we
21+number for our state that allows us to upgrade the structure of our
19−wish.
22+state in the future if we wish.
21−`pol` is the a map from every ship on our pier to their individual ford state.
24+`pol` is the a map from every ship on our pier to their individual ford
22−There is no shared ford state -- every ship is entirely separate.
25+state. There is no shared ford state -- every ship is entirely separate.
24### `++baby`, state by ship
27### `++baby`, state by ship
@@ -31,18 +34,19 @@ There is no shared ford state -- every ship is entirely separate.
32This is the state specific to each ship.
35This is the state specific to each ship.
34−`tad` and `dym` keep track of the tasks we're currently working on. `dym` is a
37+`tad` and `dym` keep track of the tasks we're currently working on.
35−map from ducts to task numbers, and `q.tad` is a map from task number to the
38+`dym` is a map from ducts to task numbers, and `q.tad` is a map from
36−task itself. `p.tad` is the next available task number. Thus, the keys of
39+task number to the task itself. `p.tad` is the next available task
37−`q.tad` are a subset of the numbers less than `p.tad`, and ford has attempted
40+number. Thus, the keys of `q.tad` are a subset of the numbers less than
38−exactly `p.tad` tasks so far.
41+`p.tad`, and ford has attempted exactly `p.tad` tasks so far.
40−`jav` is the cache of previously-solved problems. The keys are a pair of a term
43+`jav` is the cache of previously-solved problems. The keys are a pair of
41−(either `%hood`, `%slap`, or `%slam`) and a noun that represents the exact
44+a term (either `%hood`, `%slap`, or `%slam`) and a noun that represents
42−problem solved. In the case of a `%hood`, then, the key is of the form
45+the exact problem solved. In the case of a `%hood`, then, the key is of
43−`[%hood beam cage]`. For `%slap`, there is `[%slap vase twig]`. For `%slam`,
46+the form `[%hood beam cage]`. For `%slap`, there is `[%slap vase twig]`.
44−there is `[%slam vase vase]`. The values are the result of solving the problem.
47+For `%slam`, there is `[%slam vase vase]`. The values are the result of
45−Note that this cache is wiped in `++stay` when ford is reloaded.
48+solving the problem. Note that this cache is wiped in `++stay` when ford
47### `++task`, problem in progress
51### `++task`, problem in progress
@@ -52,12 +56,12 @@ Note that this cache is wiped in `++stay` when ford is reloaded.
52 kig=[p=@ud q=(map ,@ud beam)] :: blocks
56 kig=[p=@ud q=(map ,@ud beam)] :: blocks
55−This is all the state we keep regarding a particular task. `nah` is the duct
59+This is all the state we keep regarding a particular task. `nah` is the
56−which asked us to solve the problem, and `kas` is the most recent statement of
60+duct which asked us to solve the problem, and `kas` is the most recent
57−the problem.
61+statement of the problem.
59−`kig` keeps track of which resources we are blocked on. Our blocks are stored by
63+`kig` keeps track of which resources we are blocked on. Our blocks are
60−index in `q.kig`, and the next available index is `p.kig`.
64+stored by index in `q.kig`, and the next available index is `p.kig`.
62### `++silk`, problem
66### `++silk`, problem
@@ -79,12 +83,13 @@ index in `q.kig`, and the next available index is `p.kig`.
79 [%vale p=mark q=ship r=*] :: validate [our his]
83 [%vale p=mark q=ship r=*] :: validate [our his]
82−This is the every type of problem we can solve. Every `%exec` kiss that requests
86+This is the every type of problem we can solve. Every `%exec` kiss that
83−us to solve a problem must choose one of these problems to solve.
87+requests us to solve a problem must choose one of these problems to
85−Because this is both an internal structure used in ford and the public interface
90+Because this is both an internal structure used in ford and the public
86−to ford, we choose to document this structure in our discussion of the public
91+interface to ford, we choose to document this structure in our
87−interface to ford below.
92+discussion of the public interface to ford below.
89### `++calx`, cache line
94### `++calx`, cache line
@@ -94,19 +99,20 @@ interface to ford below.
94 [%slam p=calm q=[p=vase q=vase] r=vase] :: compute
99 [%slam p=calm q=[p=vase q=vase] r=vase] :: compute
97−There are three kinds of cache entries. Every entry includes some metadata in
102+There are three kinds of cache entries. Every entry includes some
98−`p` and is the combination of an input and its output.
103+metadata in `p` and is the combination of an input and its output.
100−The input to a `%hood` is the location of the resource and a cage representing
105+The input to a `%hood` is the location of the resource and a cage
101−the data at that location. The output is the hood found by compiling the given
106+representing the data at that location. The output is the hood found by
102−cage at the given location.
107+compiling the given cage at the given location.
104−The input to a `%slap` is the vase of the subject and the twig of the formula
109+The input to a `%slap` is the vase of the subject and the twig of the
105−against which we are slapping the subject. The output is the vase produced by
110+formula against which we are slapping the subject. The output is the
106−slapping them.
111+vase produced by slapping them.
108−The input to a `%slam` is the vase of the subject and the vase of the gate which
113+The input to a `%slam` is the vase of the subject and the vase of the
109−we are slapping. The output is the vase produced by slamming them.
114+gate which we are slapping. The output is the vase produced by slamming
111### `++calm`, cache line metadata
117### `++calm`, cache line metadata
@@ -115,9 +121,9 @@ we are slapping. The output is the vase produced by slamming them.
115 dep=(set beam) :: dependencies
121 dep=(set beam) :: dependencies
118−Every line in the cache needs to have two pieces of metadata. We must know the
124+Every line in the cache needs to have two pieces of metadata. We must
119−last time this line in the cache was accessed, and we must know what are the
125+know the last time this line in the cache was accessed, and we must know
120−dependencies of this line.
126+what are the dependencies of this line.
122### `++hood`, assembly components
128### `++hood`, assembly components
@@ -131,43 +137,46 @@ dependencies of this line.
132When assembling a hook file, we split it into several sections.
138When assembling a hook file, we split it into several sections.
134−`zus` is the kelvin version of the required zuse. In general, we assume that any
140+`zus` is the kelvin version of the required zuse. In general, we assume
135−newer (lower-numbered) zuse will retain backward compatibility, so any newer
141+that any newer (lower-numbered) zuse will retain backward compatibility,
136−zuse is also permissible. This number is set with a `/?` at the beginning of the
142+so any newer zuse is also permissible. This number is set with a `/?` at
137−file.
143+the beginning of the file.
139−`sur` is the set of structures included. These are included with the `/-` rune.
145+`sur` is the set of structures included. These are included with the
140−When a structure is included, we look in `/=main=/sur` for the given structure
146+`/-` rune. When a structure is included, we look in `/=main=/sur` for
141−and we load the gate there. When compiling, all the included structures are
147+the given structure and we load the gate there. When compiling, all the
142−collected into a single core placed in the subject of the body with a `=>`.
148+included structures are collected into a single core placed in the
149+subject of the body with a `=>`.
144−`lib` is the set of librarires included. These are included with the `/+` rune.
151+`lib` is the set of librarires included. These are included with the
145−When a library is included, we look in `/=main=/lib` for the given library and
152+`/+` rune. When a library is included, we look in `/=main=/lib` for the
146−we load the library there. As with structures, all the included libraries are
153+given library and we load the library there. As with structures, all the
147−collected into a single core placed in the subject of the body with a `=>`.
154+included libraries are collected into a single core placed in the
155+subject of the body with a `=>`.
149−`fan` is the set of resources included. These are loaded in many different ways
157+`fan` is the set of resources included. These are loaded in many
150−and may load resources from any location. These are placed in the subject of the
158+different ways and may load resources from any location. These are
151−body with a `=~`.
159+placed in the subject of the body with a `=~`.
153−`src` is the set of twigs or references to twigs in the body of the program.
161+`src` is the set of twigs or references to twigs in the body of the
154−Generally, each of these will represent a core, but this is not required. When
162+program. Generally, each of these will represent a core, but this is not
155−compiling, these are strung together in a `=~`.
163+required. When compiling, these are strung together in a `=~`.
157### `++hoot`
165### `++hoot`
159 ++ hoot (pair bean hoof) :: structure gate/core
167 ++ hoot (pair bean hoof) :: structure gate/core
161−A structures may be either a direct gate or a core. These are syntactically
169+A structures may be either a direct gate or a core. These are
162−distinguished by adding a `*` to the beginning of the structure name for a core.
170+syntactically distinguished by adding a `*` to the beginning of the
163−The structure itself is a `hoof`.
171+structure name for a core. The structure itself is a `hoof`.
165### `++hoof`
173### `++hoof`
167 ++ hoof (pair term (unit (pair case ship))) :: resource reference
175 ++ hoof (pair term (unit (pair case ship))) :: resource reference
169−A hoof, which is either a structure or a library, has a name, and it may also
177+A hoof, which is either a structure or a library, has a name, and it may
170−specify which version of the resource to use and which ship to retrieve it from.
178+also specify which version of the resource to use and which ship to
172### `++horn`
181### `++horn`
@@ -193,42 +202,44 @@ discussion of their use from a user's perspective is documented in the [runes
193documentation](https://urbit.org/docs/arvo/internals/runes), so we will here
202documentation](https://urbit.org/docs/arvo/internals/runes), so we will here
194only give a description of the data structure itself.
203only give a description of the data structure itself.
196−A `%ape` horn is simply a twig that gets evaluated and placed in the subject.
205+A `%ape` horn is simply a twig that gets evaluated and placed in the
198−A `%arg` is a gate that gets evaluated with a sample of our location and our
208+A `%arg` is a gate that gets evaluated with a sample of our location and
201−A `%day` is a horn that applies to each of a list of `@dr`-named files in the
211+A `%day` is a horn that applies to each of a list of `@dr`-named files
202−directory.
212+in the directory.
204−A `%dub` is a term and horn, where the result of a horn is given the face of the
214+A `%dub` is a term and horn, where the result of a horn is given the
205−term.
215+face of the term.
207A `%fan` is a list of horns, all at the current directory level.
217A `%fan` is a list of horns, all at the current directory level.
209−A `%for` is a path and a horn, where the horn is evaluated relative to the given
219+A `%for` is a path and a horn, where the horn is evaluated relative to
210−path, where the given path is relative to the current location.
220+the given path, where the given path is relative to the current
212−A `%hub` is a horn that applies to each of a list of `@ud`-named files in the
223+A `%hub` is a horn that applies to each of a list of `@ud`-named files
213−directory.
224+in the directory.
215−A `%man` is a map of spans to horns where the result is a set of each horn
226+A `%man` is a map of spans to horns where the result is a set of each
216−applied to the current directory given the associated face.
227+horn applied to the current directory given the associated face.
218−A `%nap` is a homogenous map where each entry in a directory is handled with the
229+A `%nap` is a homogenous map where each entry in a directory is handled
219−same horn and is given a face according to its name.
230+with the same horn and is given a face according to its name.
221−A `%now` is a horn that applies to each of a list of `@da`-named files in the
232+A `%now` is a horn that applies to each of a list of `@da`-named files
222−directory.
233+in the directory.
224−A `%saw` is a twig and a horn, where the twig operates on the result of the
235+A `%saw` is a twig and a horn, where the twig operates on the result of
227−A `%see` is a beam and a horn, where the horn is evaluated at a location of the
238+A `%see` is a beam and a horn, where the horn is evaluated at a location
228−given beam.
239+of the given beam.
230−A `%sic` is a tile and a horn, where the horn is evaluated and cast to the type
241+A `%sic` is a tile and a horn, where the horn is evaluated and cast to
231−associated with the tile.
242+the type associated with the tile.
233A `%toy` is simply a mark to be baked.
244A `%toy` is simply a mark to be baked.
@@ -239,9 +250,9 @@ A `%toy` is simply a mark to be baked.
239 [%| p=beam] :: resource location
250 [%| p=beam] :: resource location
242−This is an entry in the body of the hook file. The hoop can either be defined
253+This is an entry in the body of the hook file. The hoop can either be
243−directly in the given file or it can be a reference to another file. The second
254+defined directly in the given file or it can be a reference to another
244−is specified with a `//` rune.
255+file. The second is specified with a `//` rune.
246### `++bolt`, monadic edge
257### `++bolt`, monadic edge
@@ -255,27 +266,28 @@ is specified with a `//` rune.
258−Throughout our computation, we let our result flow through with the set of
269+Throughout our computation, we let our result flow through with the set
259−dependencies of the value. At various times, we may wish to either throw an
270+of dependencies of the value. At various times, we may wish to either
260−error or declare that the actual result cannot be found until a particular
271+throw an error or declare that the actual result cannot be found until a
261−resource is retrieved. This is a perfect case for a monad, so here we define a
272+particular resource is retrieved. This is a perfect case for a monad, so
262−data structure for it.
273+here we define a data structure for it.
264−At every step, we have a cache, so we store that in `p`. In `q` we store the
275+At every step, we have a cache, so we store that in `p`. In `q` we store
267−In the case of `%0`, we have the result in `q` and the set of dependencies in
278+In the case of `%0`, we have the result in `q` and the set of
268−`p`.
279+dependencies in `p`.
270−In the case of `%1`, we have a set of dependencies on which we are blocking.
281+In the case of `%1`, we have a set of dependencies on which we are
271−When this happens, we make a call to clay to get the dependencies, and we
282+blocking. When this happens, we make a call to clay to get the
272−proceed with the computation when we receive them. Technically, we restart the
283+dependencies, and we proceed with the computation when we receive them.
273−computation, but since every expensive step is cached, there is no significant
284+Technically, we restart the computation, but since every expensive step
274−performance penalty to doing this. Referential transparency has its uses.
285+is cached, there is no significant performance penalty to doing this.
286+Referential transparency has its uses.
276−In the case of `%2`, we have a hit an error. This gets passed all the way
288+In the case of `%2`, we have a hit an error. This gets passed all the
277−through to the calling duct. The list of tanks is some description of what went
289+way through to the calling duct. The list of tanks is some description
278−wrong, often including a stack trace.
290+of what went wrong, often including a stack trace.
280### `++burg`, monadic rule
292### `++burg`, monadic rule
@@ -284,49 +296,53 @@ wrong, often including a stack trace.
284 $+([c=cafe d=a] (bolt b)) ::
296 $+([c=cafe d=a] (bolt b)) ::
287−To operate on bolts, we use `++cope` as our bind operator, and the functions it
299+To operate on bolts, we use `++cope` as our bind operator, and the
288−works on are of type `burg`. Our functions that operate on bolts should have a
300+functions it works on are of type `burg`. Our functions that operate on
289−sample of the cache and a value. Their output should be a bolt of the output
301+bolts should have a sample of the cache and a value. Their output should
290−value. Then, `++cope` will only call the function when necessary (in the `%0`
302+be a bolt of the output value. Then, `++cope` will only call the
291−case), and it will do so without the wrapping of a bolt.
303+function when necessary (in the `%0` case), and it will do so without
304+the wrapping of a bolt.
293−If you understand monads, this is probably fairly obvious. Otherwise, see the
306+If you understand monads, this is probably fairly obvious. Otherwise,
294−discussion on `++cope` (link).
307+see the discussion on `++cope` (link).
296−## Public Interface
309+Public Interface
298−Ford does not export a scry interface, so the only way to interact with ford is
312+Ford does not export a scry interface, so the only way to interact with
299−by sending kisses and receiving gifts. In fact, ford only sends accepts one kiss
313+ford is by sending kisses and receiving gifts. In fact, ford only sends
300−and gives one gift. This is, of course, misleading because ford actually does
314+accepts one kiss and gives one gift. This is, of course, misleading
301−many different things. It does, however, only produce one type of thing -- a
315+because ford actually does many different things. It does, however, only
302−result of a computation, which is either an error or the value produced along
316+produce one type of thing -- a result of a computation, which is either
303−with the set of dependencies referenced by it.
317+an error or the value produced along with the set of dependencies
305 ++ kiss :: in request ->$
320 ++ kiss :: in request ->$
306 $% [%exec p=@p q=(unit silk)] :: make / kill
321 $% [%exec p=@p q=(unit silk)] :: make / kill
309The `%exec` gift requests ford to perform a computation on behalf of a
324The `%exec` gift requests ford to perform a computation on behalf of a
310−particular ship. `p` is the ship, and `q` is the computation. If `q` is null,
325+particular ship. `p` is the ship, and `q` is the computation. If `q` is
311−then we are requesting that ford cancel the computation that it is currently
326+null, then we are requesting that ford cancel the computation that it is
312−being run along this duct. Thus, if you wish to cancel a computation, you must
327+currently being run along this duct. Thus, if you wish to cancel a
313−send the kiss along the same duct as the original request.
328+computation, you must send the kiss along the same duct as the original
315−Otherwise, we ask ford to perform a certain computation, as defined in `++silk`.
331+Otherwise, we ask ford to perform a certain computation, as defined in
316−Since all computations produce the same type of result, we will discuss that
332+`++silk`. Since all computations produce the same type of result, we
317−result before we jump into `++silk`.
333+will discuss that result before we jump into `++silk`.
319 ++ gift :: out result <-$
335 ++ gift :: out result <-$
320 $% [%made p=(each bead (list tank))] :: computed result
336 $% [%made p=(each bead (list tank))] :: computed result
323−We give either a `bead`, which is a result, or a list of tanks, which is an
339+We give either a `bead`, which is a result, or a list of tanks, which is
324−error messge, often including a stack trace.
340+an error messge, often including a stack trace.
326 ++ bead ,[p=(set beam) q=cage] :: computed result
342 ++ bead ,[p=(set beam) q=cage] :: computed result
328−This is a set of dependencies required to compute this value and a cage of the
344+This is a set of dependencies required to compute this value and a cage
329−result with its associated mark.
345+of the result with its associated mark.
331There are twelve possible computations defined in `++silk`.
347There are twelve possible computations defined in `++silk`.
@@ -346,77 +362,83 @@ There are twelve possible computations defined in `++silk`.
346 [%vale p=mark q=ship r=*] :: validate [our his]
362 [%vale p=mark q=ship r=*] :: validate [our his]
349−First, we allow silks to autocons. A cell of silks is also a silk, and the
365+First, we allow silks to autocons. A cell of silks is also a silk, and
350−product vase is a cell of the two silks. This obviously extends to an arbitrary
366+the product vase is a cell of the two silks. This obviously extends to
351−number of silks.
367+an arbitrary number of silks.
353−`%bake` tries to functionally produce the file at a given beam with the given
369+`%bake` tries to functionally produce the file at a given beam with the
354−mark and heel. It fails if there is no way to translate at this level.
370+given mark and heel. It fails if there is no way to translate at this
356−`%boil` functionally produces the file at a given beam with the given mark and
373+`%boil` functionally produces the file at a given beam with the given
357−heel. If there is no way to translate at this beam, we pop levels off the stack
374+mark and heel. If there is no way to translate at this beam, we pop
358−and attempt to bake there until we find a level we can bake. This should almost
375+levels off the stack and attempt to bake there until we find a level we
359−always be called instead of `%bake`.
376+can bake. This should almost always be called instead of `%bake`.
361`%call` slams the result of one silk against the result of another.
378`%call` slams the result of one silk against the result of another.
363−`%cast` translates the given silk to the given mark, if possible. This is one of
380+`%cast` translates the given silk to the given mark, if possible. This
364−the critical and fundamental operations of ford.
381+is one of the critical and fundamental operations of ford.
366−`%done` produces exactly its input. This is rarely used on its own, but many
383+`%done` produces exactly its input. This is rarely used on its own, but
367−silks are recursively defined in terms of other silks, so we often need a silk
384+many silks are recursively defined in terms of other silks, so we often
368−that simply produces its input. A monadic return, if you will.
385+need a silk that simply produces its input. A monadic return, if you
370−`%diff` diffs the two given silks (which must be of the same mark), producing a
388+`%diff` diffs the two given silks (which must be of the same mark),
371−cage of the mark specified in `++mark` in `++grad` for the mark of the two
389+producing a cage of the mark specified in `++mark` in `++grad` for the
372−silks.
390+mark of the two silks.
374−`%dude` computes the given silk with the given tank as part of the stack trace
392+`%dude` computes the given silk with the given tank as part of the stack
375−if there is an error.
393+trace if there is an error.
377−`%dune` produces an error if the cage is empty. Otherwise, it produces the value
395+`%dune` produces an error if the cage is empty. Otherwise, it produces
378−in the unit.
396+the value in the unit.
380−`%mute` takes a silk and a list of changes to make to the silk. At each wing in
398+`%mute` takes a silk and a list of changes to make to the silk. At each
381−the list we put the value of the associated silk.
399+wing in the list we put the value of the associated silk.
383−`%pact` applies the second silk as a patch to the first silk. The second silk
401+`%pact` applies the second silk as a patch to the first silk. The second
384−must be of the mark specified in `++mark` in `++grad` for the mark of the first
402+silk must be of the mark specified in `++mark` in `++grad` for the mark
385−silk.
403+of the first silk.
387−`%plan` performs a structured assembly directly. This is not generally directly
405+`%plan` performs a structured assembly directly. This is not generally
388−useful because several other silks perform supersets of this functionality. We
406+directly useful because several other silks perform supersets of this
389−don't usually have naked hoods outside ford.
407+functionality. We don't usually have naked hoods outside ford.
391−`%reef` produces a core containing the entirety of zuse and hoon, suitable for
409+`%reef` produces a core containing the entirety of zuse and hoon,
392−running arbitrary code against. The mark is `%noun`.
410+suitable for running arbitrary code against. The mark is `%noun`.
394−`%ride` slaps a twig against a subject silk. The mark of the result is `%noun`.
412+`%ride` slaps a twig against a subject silk. The mark of the result is
396−`%vale` validates untyped data from a ship against a given mark. This is an
415+`%vale` validates untyped data from a ship against a given mark. This is
397−extremely useful function.
416+an extremely useful function.
399−# Commentary
418+Commentary
401−## Parsing Hook Files
421+Parsing Hook Files
403−In the commentary on other vanes, we have traced through the lifecycle of
424+In the commentary on other vanes, we have traced through the lifecycle
404−various external requests. This is generally a very reasonable order to examine
425+of various external requests. This is generally a very reasonable order
405−vanes since it will eventually cover the entire vane, and we are never left
426+to examine vanes since it will eventually cover the entire vane, and we
406−wondering why we are doing something.
427+are never left wondering why we are doing something.
408−For ford, however, it makes more sense to begin by discussing the parsing and
429+For ford, however, it makes more sense to begin by discussing the
409−assembliing of hook files. Many of the possible requests require us to assemble
430+parsing and assembliing of hook files. Many of the possible requests
410−hook files, so we may as well examine this immediately.
431+require us to assemble hook files, so we may as well examine this
412−First, we will examine the parsing. We parse a file at a beam to a hood in
434+First, we will examine the parsing. We parse a file at a beam to a hood
413−`++fade:zo:za`. The top-level parsing rule is `++fair`, which takes a beam and
435+in `++fade:zo:za`. The top-level parsing rule is `++fair`, which takes a
414−produces a rule to parse an entire hood file.
436+beam and produces a rule to parse an entire hood file.
416−A note on the naming scheme: the parsing the combinators that parse into a
438+A note on the naming scheme: the parsing the combinators that parse into
417−particular structure are conventionally given the same name as the structure.
439+a particular structure are conventionally given the same name as the
418−Although this locally clobbers the type names, this pattern makes obvious the
440+structure. Although this locally clobbers the type names, this pattern
419−intent of the parsing combinators.
441+makes obvious the intent of the parsing combinators.
421We kick off with `++hood:fair`.
443We kick off with `++hood:fair`.
@@ -442,23 +464,24 @@ We kick off with `++hood:fair`.
442 (most gap hoop)
464 (most gap hoop)
445−There are five sections to a hood: system version, structures, libraries,
467+There are five sections to a hood: system version, structures,
446−resources, and body.
468+libraries, resources, and body.
448−First, we parse the requested version number of the system. This is specified
470+First, we parse the requested version number of the system. This is
449−with a unary `/?` rune. If not present, then we default to the current version.
471+specified with a unary `/?` rune. If not present, then we default to the
451−Second, we may have zero or more `/-` runes followed by a parsing of a `++hoot`,
474+Second, we may have zero or more `/-` runes followed by a parsing of a
452−which represents a shared structure.
475+`++hoot`, which represents a shared structure.
454−Third, we may have zero or more `/+` runes followed by a parsing of a `++hoof`,
477+Third, we may have zero or more `/+` runes followed by a parsing of a
455−which represents a shared library.
478+`++hoof`, which represents a shared library.
457−Fourth, we may have zero or more other `/` runes (as described in `++horn`),
480+Fourth, we may have zero or more other `/` runes (as described in
458−which represent program-specific resources to be loaded.
481+`++horn`), which represent program-specific resources to be loaded.
460−Fifth and finally, we must have one or more body statements (hoops), which are
483+Fifth and finally, we must have one or more body statements (hoops),
461−either direct twigs or `//` runes.
484+which are either direct twigs or `//` runes.
@@ -466,9 +489,9 @@ either direct twigs or `//` runes.
466 (stag %& hoof)
489 (stag %& hoof)
469−A structure can either be a direct gate, or it can be a simple core. Either one
492+A structure can either be a direct gate, or it can be a simple core.
470−is parsed with `++hoof`, so we distinguish the two cases by requireing core
493+Either one is parsed with `++hoof`, so we distinguish the two cases by
471−references to be prefixed by a `*`.
494+requireing core references to be prefixed by a `*`.
474 %+ cook |=(a=^hoof a)
497 %+ cook |=(a=^hoof a)
@@ -481,11 +504,11 @@ references to be prefixed by a `*`.
484−A hoof must have a name, which is a term. Optionally, we also include a case and
507+A hoof must have a name, which is a term. Optionally, we also include a
485−a ship. This is marked by appending a `/` followed by a case to denote the
508+case and a ship. This is marked by appending a `/` followed by a case to
486−requested version of the resource and a `/` followed by a ship name to denote
509+denote the requested version of the resource and a `/` followed by a
487−the requested source of the resource. For example, `resource/1/~zod` requests
510+ship name to denote the requested source of the resource. For example,
488−the first version of `resource` on `~zod`.
511+`resource/1/~zod` requests the first version of `resource` on `~zod`.
@@ -494,11 +517,11 @@ the first version of `resource` on `~zod`.
494 ?. ?=([%$ ?(%da %ud %tas) *] a) ~
517 ?. ?=([%$ ?(%da %ud %tas) *] a) ~
495 [~ u=(^case a)]
518 [~ u=(^case a)]
497−Here, we parse a literal with `++nuck:so`, and we accept the input if it is
520+Here, we parse a literal with `++nuck:so`, and we accept the input if it
498−either an absolute date, an unsigned decimal, or a label.
521+is either an absolute date, an unsigned decimal, or a label.
500−This leaves only horns and hoops to parse. Hoops are much simple to parse, so
523+This leaves only horns and hoops to parse. Hoops are much simple to
501−we'll discuss those first.
524+parse, so we'll discuss those first.
@@ -506,20 +529,20 @@ we'll discuss those first.
506 (stag %& tall:vez)
529 (stag %& tall:vez)
509−There are two types of hoops. Direct twigs are parsed with `++tall:vast`, which
532+There are two types of hoops. Direct twigs are parsed with
510−is the just the hoon parser for a tall-form twig.
533+`++tall:vast`, which is the just the hoon parser for a tall-form twig.
512−References to external twigs are marked with a `//` rune followed by a beam,
535+References to external twigs are marked with a `//` rune followed by a
513−which is parsed with `++have`.
536+beam, which is parsed with `++have`.
515 ++ hath (sear plex:voz (stag %clsg poor:voz)) :: hood path
538 ++ hath (sear plex:voz (stag %clsg poor:voz)) :: hood path
516 ++ have (sear tome ;~(pfix fas hath)) :: hood beam
539 ++ have (sear tome ;~(pfix fas hath)) :: hood beam
518−`++have` parses a path with `++hath`, and then it converts the path into a beam
541+`++have` parses a path with `++hath`, and then it converts the path into
519−with `++tome`.
542+a beam with `++tome`.
521−`++hath` parses a `/`-separated list with `++poor:vast`, then converts it to an
544+`++hath` parses a `/`-separated list with `++poor:vast`, then converts
522−actual path with `++plex:vast`.
545+it to an actual path with `++plex:vast`.
524This leaves only horns to parse.
547This leaves only horns to parse.
@@ -548,17 +571,18 @@ This leaves only horns to parse.
551−Horn parsing is slightly complex, so we create an internal core to organize our
574+Horn parsing is slightly complex, so we create an internal core to
552−code. Our core has a global variable of `tol`, which is true if tall form is
575+organize our code. Our core has a global variable of `tol`, which is
553−permissible and false if we're already in wide form. We kick off the parsing
576+true if tall form is permissible and false if we're already in wide
554−with `++apex`.
577+form. We kick off the parsing with `++apex`.
556−`++apex` specifies how each rune is parsed. This allows us to offload the
579+`++apex` specifies how each rune is parsed. This allows us to offload
557−different ways of parsing the arguments to these runes into separate arms. The
580+the different ways of parsing the arguments to these runes into separate
558−exception here is that the `%toy` horn is simply of the form `/mark/`.
581+arms. The exception here is that the `%toy` horn is simply of the form
560−We'll examine each of the horn parsing arms right after we discuss `++rail`,
584+We'll examine each of the horn parsing arms right after we discuss
561−which is used in each one.
585+`++rail`, which is used in each one.
564 |* [wid=_rule tal=_rule]
588 |* [wid=_rule tal=_rule]
@@ -566,8 +590,8 @@ which is used in each one.
566 ;~(pose wid tal)
590 ;~(pose wid tal)
568This takes a wide-form and a tall-form parsing rule. If tall form is
592This takes a wide-form and a tall-form parsing rule. If tall form is
569−permissible, then it allows either rule to match; else, it allows only the wide
593+permissible, then it allows either rule to match; else, it allows only
570−form rule.
594+the wide form rule.
573 |% ++ ape
597 |% ++ ape
@@ -575,47 +599,49 @@ form rule.
575 (ifix [sel ser] (stag %cltr (most ace wide:vez)))
599 (ifix [sel ser] (stag %cltr (most ace wide:vez)))
576 ;~(pfix gap tall:vez)
600 ;~(pfix gap tall:vez)
578−`++ape:read` parses for both the `/~` and the `/$` runes. It produces a twig.
602+`++ape:read` parses for both the `/~` and the `/$` runes. It produces a
579−The wide form is a tuple of one or more ace-separated wide-form twigs parsed
603+twig. The wide form is a tuple of one or more ace-separated wide-form
580−with `++wide:vast` and surrounded by `[` and `]`. The tall form is a single tall
604+twigs parsed with `++wide:vast` and surrounded by `[` and `]`. The tall
581−form twig parsed by `++tall:vast`
605+form is a single tall form twig parsed by `++tall:vast`
585 apex(tol |)
609 apex(tol |)
586 ;~(pfix gap apex)
610 ;~(pfix gap apex)
588−This parses for the `/|`, `/@`, `/%`, and `/&` runes. It produces a horn. The
612+This parses for the `/|`, `/@`, `/%`, and `/&` runes. It produces a
589−wide form is, recursively, the entire horn parser with tall form disabled. The
613+horn. The wide form is, recursively, the entire horn parser with tall
590−tall form is a gap followed by, recursively, the entire horn parser.
614+form disabled. The tall form is a gap followed by, recursively, the
594 ;~(plug sym ;~(pfix tis apex(tol |)))
619 ;~(plug sym ;~(pfix tis apex(tol |)))
595 ;~(pfix gap ;~(plug sym ;~(pfix gap apex)))
620 ;~(pfix gap ;~(plug sym ;~(pfix gap apex)))
597−This parses for the `/=` rune. It produces a term followed by a horn. The wide
622+This parses for the `/=` rune. It produces a term followed by a horn.
598−form is a symbol name followed by a `=` and, recursively, the entire horn parser
623+The wide form is a symbol name followed by a `=` and, recursively, the
599−with tall form disabled. The tall form is a gap followed by a symbol name,
624+entire horn parser with tall form disabled. The tall form is a gap
600−another gap, and, recursively, the entire horn parser.
625+followed by a symbol name, another gap, and, recursively, the entire
603 %+ rail fail
629 %+ rail fail
604 ;~(sfix (star ;~(pfix gap apex)) ;~(plug gap duz))
630 ;~(sfix (star ;~(pfix gap apex)) ;~(plug gap duz))
606−This parses for the `/.` rune. It produces a list of horns. There is no wide
632+This parses for the `/.` rune. It produces a list of horns. There is no
607−form. The tall form is a stet-terminated series of gap-separated recursive calls
633+wide form. The tall form is a stet-terminated series of gap-separated
608−to the entire horn parser.
634+recursive calls to the entire horn parser.
612 ;~(plug (ifix [sel ser] hath) apex(tol |))
638 ;~(plug (ifix [sel ser] hath) apex(tol |))
613 ;~(pfix gap ;~(plug hath ;~(pfix gap apex)))
639 ;~(pfix gap ;~(plug hath ;~(pfix gap apex)))
615−This parses for the `/,` rune. It produces a path and a horn. The wide form is a
641+This parses for the `/,` rune. It produces a path and a horn. The wide
616−`[`-`]`-surrounded path followed by, recursively, the entire horn parser with
642+form is a `[`-`]`-surrounded path followed by, recursively, the entire
617−tall form disabled. The tall form is a gap followed by a path, another gap, and,
643+horn parser with tall form disabled. The tall form is a gap followed by
618−recursively, the entire horn parser.
644+a path, another gap, and, recursively, the entire horn parser.
621 %+ rail fail
647 %+ rail fail
@@ -628,31 +654,31 @@ recursively, the entire horn parser.
628 ?. ?=(%dub -.i.fan) ~
654 ?. ?=(%dub -.i.fan) ~
629 $(fan t.fan, naf [[p.i.fan q.i.fan] naf])
655 $(fan t.fan, naf [[p.i.fan q.i.fan] naf])
631−This parses for the `/*` rune. It produces a map of spans to horns. There is no
657+This parses for the `/*` rune. It produces a map of spans to horns.
632−wide form. The tall form is a stet-terminated series of gap-separated recursive
658+There is no wide form. The tall form is a stet-terminated series of
633−calls to the entire horn parser. All produced horns are expected to be from `/=`
659+gap-separated recursive calls to the entire horn parser. All produced
634−runes. The term and horn in each `/=` horn is inserted into the produced map as
660+horns are expected to be from `/=` runes. The term and horn in each `/=`
635−a key-value pair.
661+horn is inserted into the produced map as a key-value pair.
639 ;~(plug ;~(sfix wide:vez sem) apex(tol |))
665 ;~(plug ;~(sfix wide:vez sem) apex(tol |))
640 ;~(pfix gap ;~(plug tall:vez ;~(pfix gap apex)))
666 ;~(pfix gap ;~(plug tall:vez ;~(pfix gap apex)))
642−This parses for the `/;` rune. It produces a twig and a horn. The wide form is a
668+This parses for the `/;` rune. It produces a twig and a horn. The wide
643−wide-form twig followed by a `;` and, recursively, the entire horn parser with
669+form is a wide-form twig followed by a `;` and, recursively, the entire
644−tall form disabled. The tall form is a gap followed by a tall-form twig, another
670+horn parser with tall form disabled. The tall form is a gap followed by
645−gap, and, recursively, the entire horn parser.
671+a tall-form twig, another gap, and, recursively, the entire horn parser.
649 ;~(plug ;~(sfix have col) apex(tol |))
675 ;~(plug ;~(sfix have col) apex(tol |))
650 ;~(pfix gap ;~(plug have ;~(pfix gap apex)))
676 ;~(pfix gap ;~(plug have ;~(pfix gap apex)))
652−This parses for the `/:` rune. It produces a beam and a horn. The wide form is a
678+This parses for the `/:` rune. It produces a beam and a horn. The wide
653−beam followed by a `;` and, recursively, the entire horn parser with tall form
679+form is a beam followed by a `;` and, recursively, the entire horn
654−disabled. The tall form is a gap followed by a beam, another gap, and,
680+parser with tall form disabled. The tall form is a gap followed by a
655−recursively, the entire horn parser.
681+beam, another gap, and, recursively, the entire horn parser.
@@ -660,17 +686,18 @@ recursively, the entire horn parser.
660 ;~(pfix gap ;~(plug howl:vez ;~(pfix gap apex)))
686 ;~(pfix gap ;~(plug howl:vez ;~(pfix gap apex)))
663−This parses for the `/^` rune. It produces a tile and a horn. The wide form is a
689+This parses for the `/^` rune. It produces a tile and a horn. The wide
664−wide-form tile, parsed with `++toil:vast`, followed by a `^` and, recursively,
690+form is a wide-form tile, parsed with `++toil:vast`, followed by a `^`
665−the entire horn parser with tall form disabled. The tall form is a gap followed
691+and, recursively, the entire horn parser with tall form disabled. The
666−by a tall-form tile, parsed with `++howl:vast`, another gap, and, recursively,
692+tall form is a gap followed by a tall-form tile, parsed with
667−the entire horn parser.
693+`++howl:vast`, another gap, and, recursively, the entire horn parser.
669−## Assembling Hook Files
695+Assembling Hook Files
696+---------------------
671−At this point, we've parsed a hook file into a hood. We will now describe
698+At this point, we've parsed a hook file into a hood. We will now
672−exactly how this hood is assembled into a vase. The problem of assembling is
699+describe exactly how this hood is assembled into a vase. The problem of
673−handled entirely within the `++meow:zo:za` core.
700+assembling is handled entirely within the `++meow:zo:za` core.
675 ++ meow :: assemble
702 ++ meow :: assemble
676 |= [how=beam arg=heel]
703 |= [how=beam arg=heel]
@@ -684,45 +711,47 @@ handled entirely within the `++meow:zo:za` core.
687−We take two arguments and keep seven pieces of state. `how` is the location of
714+We take two arguments and keep seven pieces of state. `how` is the
688−the hook file we're assembling, and `arg` is the heel, or virtual path
715+location of the hook file we're assembling, and `arg` is the heel, or
689−extension, of the file.
716+virtual path extension, of the file.
691−In `rop`, we maintain a map of terms to pairs of hooves and twigs to represent
718+In `rop`, we maintain a map of terms to pairs of hooves and twigs to
692−the structures we've encountered that we will put together in a core at the top
719+represent the structures we've encountered that we will put together in
693−of the file.
720+a core at the top of the file.
695−In `zog`, we maintain the set of structures we're in the middle of loading. If
722+In `zog`, we maintain the set of structures we're in the middle of
696−we try to load a structure already in our dependency ancestry, then we fail
723+loading. If we try to load a structure already in our dependency
697−because we do not allow circular dependencies. This enforces that our structure
724+ancestry, then we fail because we do not allow circular dependencies.
698−dependency graph is a DAG.
725+This enforces that our structure dependency graph is a DAG.
700−In `bil`, we maintain a map of terms to pairs of hooves and twigs to represent
727+In `bil`, we maintain a map of terms to pairs of hooves and twigs to
701−the libraries we've encountered that we will put together in a series of cores
728+represent the libraries we've encountered that we will put together in a
702−after the structure core.
729+series of cores after the structure core.
704−In `lot`, we maintain a stack of library names as they are encountered during a
731+In `lot`, we maintain a stack of library names as they are encountered
705−depth-first search. More precisely, we push a library onto the stack after we've
732+during a depth-first search. More precisely, we push a library onto the
706−processed all its children. Thus, every library depends only on things deeper in
733+stack after we've processed all its children. Thus, every library
707−the list. The libraries must be loaded in the reverse of this order. Concisely,
734+depends only on things deeper in the list. The libraries must be loaded
708−this is a topological sort of the library dependency partial ordering.
735+in the reverse of this order. Concisely, this is a topological sort of
736+the library dependency partial ordering.
710−In `zeg`, we maintain the set of libraries we're in the middle of loading. If we
738+In `zeg`, we maintain the set of libraries we're in the middle of
711−try to load a library already in our dependency ancestry, then we fail because
739+loading. If we try to load a library already in our dependency ancestry,
712−we do not allow circular dependencies. This enforces that our library dependency
740+then we fail because we do not allow circular dependencies. This
713−graph is a DAG.
741+enforces that our library dependency graph is a DAG.
715−In `boy`, we maintain a stack of body twigs, which we'll put together in a
743+In `boy`, we maintain a stack of body twigs, which we'll put together in
716−series of cores at the end of the file.
744+a series of cores at the end of the file.
718−In `hol`, we decide if we're allowed to contain horns. Libraries and structures
746+In `hol`, we decide if we're allowed to contain horns. Libraries and
719−are not allowed to contain horns.
747+structures are not allowed to contain horns.
721−We in every case enter `++meow` through `++abut`. You'll notice that there are
749+We in every case enter `++meow` through `++abut`. You'll notice that
722−four (count 'em, four!) calls to `++cope` in `++abut`. If you've glanced at the
750+there are four (count 'em, four!) calls to `++cope` in `++abut`. If
723−ford code in general, you've probably seen cope over and over. It is called in
751+you've glanced at the ford code in general, you've probably seen cope
724−79 different places. We need to discuss the use of this critical function in
752+over and over. It is called in 79 different places. We need to discuss
725−detail, so we may as well do it here.
753+the use of this critical function in detail, so we may as well do it
727 ++ cope :: bolt along
756 ++ cope :: bolt along
728 |* [hoc=(bolt) fun=(burg)]
757 |* [hoc=(bolt) fun=(burg)]
@@ -738,36 +767,40 @@ detail, so we may as well do it here.
738 %0 [%0 p=(grom `_p.q.nuf`p.q.hoc p.q.nuf) q=q.q.nuf]
767 %0 [%0 p=(grom `_p.q.nuf`p.q.hoc p.q.nuf) q=q.q.nuf]
741−In monad-speak, this is the bind operator for the bolt monad. If monads aren't
770+In monad-speak, this is the bind operator for the bolt monad. If monads
742−your thing, don't worry, we're going to explain the use of cope without further
771+aren't your thing, don't worry, we're going to explain the use of cope
743−reference to them.
772+without further reference to them.
745−Recall that there are three different types of bolt. A `%2` error bolt contains
774+Recall that there are three different types of bolt. A `%2` error bolt
746−a list of tanks describing the error, a `%1` block bolt contains a set of
775+contains a list of tanks describing the error, a `%1` block bolt
747−resources we're blocked on, and a `%0` value bolt contains an actual value and
776+contains a set of resources we're blocked on, and a `%0` value bolt
748−the set of its dependencies.
777+contains an actual value and the set of its dependencies.
750−We most commonly want to perform an operation on the value in a bolt if it is a
779+We most commonly want to perform an operation on the value in a bolt if
751−`%0` bolt. If it's not a `%0` bolt, we want to leave it alone. This requires us
780+it is a `%0` bolt. If it's not a `%0` bolt, we want to leave it alone.
752−to write a certain amount of boilerplate between each of our operations to see
781+This requires us to write a certain amount of boilerplate between each
753−if any of them produced a `%1` or a `%2` bolt. This gets tiresome, so we pull it
782+of our operations to see if any of them produced a `%1` or a `%2` bolt.
754−out into a separate arm and call it `++cope`.
783+This gets tiresome, so we pull it out into a separate arm and call it
756−Intuitively, we're calling the function `fun` with the value in `hoc`, where
785+
757−`fun` takes an argument of type whatever is the value in a `%0` case of `hoc`,
786+Intuitively, we're calling the function `fun` with the value in `hoc`,
758−and it produces a bolt of some (possibly different) type. For brevity, we will
787+where `fun` takes an argument of type whatever is the value in a `%0`
759−refer to the type of the of the value in the `%0` case of a bolt as the "type of
788+case of `hoc`, and it produces a bolt of some (possibly different) type.
760−the bolt".
789+For brevity, we will refer to the type of the of the value in the `%0`
761−
790+case of a bolt as the "type of the bolt".
762−If the `hoc` bolt we're given as input to `fun` is already a `%1` or a `%2`
791+
763−bolt, then we simply produce that. We don't even try to run `fun` on it.
792+If the `hoc` bolt we're given as input to `fun` is already a `%1` or a
764−
793+`%2` bolt, then we simply produce that. We don't even try to run `fun`
765−Otherwise, we run `fun` with the arguments from the bolt and, if it produces a
794+on it.
766−`%1` or a `%2` bolt, we simply produce that. If it produces a `%0` bolt, then we
795+
767−produce that with the old set of dependencies merged in with the new set.
796+Otherwise, we run `fun` with the arguments from the bolt and, if it
768−
797+produces a `%1` or a `%2` bolt, we simply produce that. If it produces a
769−We'll see more about how the bolt monad works as we run into more interesting
798+`%0` bolt, then we produce that with the old set of dependencies merged
770−uses of it. For now, this is sufficient to move on with `++abut`.
799+in with the new set.
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
772 ++ abut :: generate
805 ++ abut :: generate
773 |= [cof=cafe hyd=hood]
806 |= [cof=cafe hyd=hood]
@@ -783,17 +816,18 @@ uses of it. For now, this is sufficient to move on with `++abut`.
783 |= [cof=cafe fin=vase]
816 |= [cof=cafe fin=vase]
784 (fine cof fin)
817 (fine cof fin)
786−Our job is simple: we must assemble a hood file into a vase. Hopefully, the
819+Our job is simple: we must assemble a hood file into a vase. Hopefully,
787−usage of `++cope` is fairly understandable. The correct way to read this is that
820+the usage of `++cope` is fairly understandable. The correct way to read
788−it does essentially five things.
821+this is that it does essentially five things.
790−First, we call `++apex` to process the structures, libraries, and body. This
823+First, we call `++apex` to process the structures, libraries, and body.
791−changes our state, so we set our context to the produced context. Second, we
824+This changes our state, so we set our context to the produced context.
792−call `++able` to assemble the strucutres and libraries into a twig, which we
825+Second, we call `++able` to assemble the strucutres and libraries into a
793−slap against zuse with `++maim`. Third, we call `++chap` to process the
826+twig, which we slap against zuse with `++maim`. Third, we call `++chap`
794−resources in the context of the already-loaded structures and libraries. Fourth,
827+to process the resources in the context of the already-loaded structures
795−we slap the body against the structures, libraries, and resources. Fifth and
828+and libraries. Fourth, we slap the body against the structures,
796−finally, we produce the resultant vase.
829+libraries, and resources. Fifth and finally, we produce the resultant
798 ++ apex :: build to body
832 ++ apex :: build to body
799 |= [cof=cafe hyd=hood]
833 |= [cof=cafe hyd=hood]
@@ -818,9 +852,9 @@ Otherwise, we produce and error with `++flaw`.
819This produces a `%2` error bolt from a list of tanks. Fairly trivial.
853This produces a `%2` error bolt from a list of tanks. Fairly trivial.
821−We should be starting to get used to the cope syntax, so we can see that we
855+We should be starting to get used to the cope syntax, so we can see that
822−really only do three things here. We process the body with `++body`, the
856+we really only do three things here. We process the body with `++body`,
823−libraries with `++neck`, and the structures with `++head`.
857+the libraries with `++neck`, and the structures with `++head`.
825 ++ body :: produce functions
859 ++ body :: produce functions
826 |= [cof=cafe src=(list hoop)]
860 |= [cof=cafe src=(list hoop)]
@@ -830,19 +864,19 @@ libraries with `++neck`, and the structures with `++head`.
830 |= [cof=cafe sel=_..body]
864 |= [cof=cafe sel=_..body]
831 ^$(cof cof, src t.src, ..body sel)
865 ^$(cof cof, src t.src, ..body sel)
833−We must process a list of hoops that represent our body. If there are no more
867+We must process a list of hoops that represent our body. If there are no
834−hoops, we just produce our context in a `%0` bolt with `++fine`.
868+more hoops, we just produce our context in a `%0` bolt with `++fine`.
836 ++ fine |* [a=cafe b=*] :: bolt from data
870 ++ fine |* [a=cafe b=*] :: bolt from data
837 [p=`cafe`a q=[%0 p=*(set beam) q=b]] ::
871 [p=`cafe`a q=[%0 p=*(set beam) q=b]] ::
839−In monad-speak, this is the return operator. For us, this just means that we're
873+In monad-speak, this is the return operator. For us, this just means
840−producing a `%0` bolt, which contains a path and a set of dependencies. We
874+that we're producing a `%0` bolt, which contains a path and a set of
841−assume there are no dependencies for the given data, or that they will be added
875+dependencies. We assume there are no dependencies for the given data, or
842−later.
876+that they will be added later.
844−If there are more hoops in `++body`, we call `++wilt` to process an individual
878+If there are more hoops in `++body`, we call `++wilt` to process an
845−hoop and recurse.
879+individual hoop and recurse.
847 ++ wilt :: process body entry
881 ++ wilt :: process body entry
848 |= [cof=cafe hop=hoop]
882 |= [cof=cafe hop=hoop]
@@ -882,22 +916,24 @@ hoop and recurse.
882 (fine cof sel(boy [[%brcn mav] boy]))
916 (fine cof sel(boy [[%brcn mav] boy]))
885−In the case of a direct twig hoop, we just push it onto `boy` and we're done. In
919+In the case of a direct twig hoop, we just push it onto `boy` and we're
886−the case of an indirect hoop, we must compile the referenced file.
920+done. In the case of an indirect hoop, we must compile the referenced
888−First, we push onto the stack trace a message indicating which file exactly
923+First, we push onto the stack trace a message indicating which file
889−we're compiling at the moment with `++cool`.
924+exactly we're compiling at the moment with `++cool`.
891 ++ cool :: error caption
926 ++ cool :: error caption
892 |* [cyt=trap hoc=(bolt)]
927 |* [cyt=trap hoc=(bolt)]
893 ?. ?=(%2 -.q.hoc) hoc
928 ?. ?=(%2 -.q.hoc) hoc
894 [p.hoc [%2 *cyt p.q.hoc]]
929 [p.hoc [%2 *cyt p.q.hoc]]
896−If an error occurred in computing `hoc`, we put the bunt of `cyt` onto the stack
931+If an error occurred in computing `hoc`, we put the bunt of `cyt` onto
897−trace. Thus, `cyt` is not evaluated at all unless an error occurred.
932+the stack trace. Thus, `cyt` is not evaluated at all unless an error
899−Next in `++wilt`, we load the information about the filesystem node referenced
935+Next in `++wilt`, we load the information about the filesystem node
900−by the hoop with `++lend`.
936+referenced by the hoop with `++lend`.
902 ++ lend :: load arch
938 ++ lend :: load arch
903 |= [cof=cafe bem=beam]
939 |= [cof=cafe bem=beam]
@@ -906,27 +942,28 @@ by the hoop with `++lend`.
906 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
942 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
907 (fine cof ((hard arch) (need u.von)))
943 (fine cof ((hard arch) (need u.von)))
909−This is a simple call to the namespace. If the resource does not yet exist, we
945+This is a simple call to the namespace. If the resource does not yet
910−block on it by producing a `%1` bolt. Otherwise, we cast it to an arch and
946+exist, we block on it by producing a `%1` bolt. Otherwise, we cast it to
911−produce this.
947+an arch and produce this.
913Continuing in `++wilt`, we examine the produced arch. If the referenced
949Continuing in `++wilt`, we examine the produced arch. If the referenced
914−filesystem node has a `hoon` child node, then we've found the required source,
950+filesystem node has a `hoon` child node, then we've found the required
915−so we parse it with `++fade`. Recall that we referred earlier to `++fade`. The
951+source, so we parse it with `++fade`. Recall that we referred earlier to
916−salient point there is that it takes a beam, reads in the hook file there, and
952+`++fade`. The salient point there is that it takes a beam, reads in the
917−parses it into a hood file with `++fair`.
953+hook file there, and parses it into a hood file with `++fair`.
919−Now, we simply recurse on `++apex` to compile the new hood. Note that, while we
955+Now, we simply recurse on `++apex` to compile the new hood. Note that,
920−do clear the `boy` list, we do not clear the other lists. Thus, we are
956+while we do clear the `boy` list, we do not clear the other lists. Thus,
921−accumulating all the structures and libraries referenced in all the referenced
957+we are accumulating all the structures and libraries referenced in all
922−hook files in one group, which we will put at the top of the product.
958+the referenced hook files in one group, which we will put at the top of
924−After this, we put the new list of body twigs into a `=~`, push this onto our
961+After this, we put the new list of body twigs into a `=~`, push this
925−old list of body twigs, and produce the result.
962+onto our old list of body twigs, and produce the result.
927−If there is no hoon file here, then we descend into each of our children until
964+If there is no hoon file here, then we descend into each of our children
928−we find a hoon file. First, we produce a list of all our children whose names
965+until we find a hoon file. First, we produce a list of all our children
929−are terms with `++lark`.
966+whose names are terms with `++lark`.
931 ++ lark :: filter arch names
968 ++ lark :: filter arch names
932 |= [wox=$+(span (unit ,@)) arc=arch]
969 |= [wox=$+(span (unit ,@)) arc=arch]
@@ -939,39 +976,43 @@ are terms with `++lark`.
939 =+ gib=(wox p.n.r.arc)
976 =+ gib=(wox p.n.r.arc)
940 ?~(gib rac [[u.gib p.n.r.arc] rac])
977 ?~(gib rac [[u.gib p.n.r.arc] rac])
942−We traverse the children map of `arc` to filter out those children whose names
979+We traverse the children map of `arc` to filter out those children whose
943−aren't accepted by `wox` and produce a map from the product of `wox` to the
980+names aren't accepted by `wox` and produce a map from the product of
944−original name. `++lark` is used in many cases to parse names into other types,
981+`wox` to the original name. `++lark` is used in many cases to parse
945−like numbers or dates, ignoring those which do not fit the format. In `++wilt`,
982+names into other types, like numbers or dates, ignoring those which do
946−though, we simply want to filter out those children whose names are not terms.
983+not fit the format. In `++wilt`, though, we simply want to filter out
984+those children whose names are not terms.
948−Next, we will produce a map from terms to feet. Each of these feet will be
986+Next, we will produce a map from terms to feet. Each of these feet will
949−placed in a core named by the child name, and it will contain arms according to
987+be placed in a core named by the child name, and it will contain arms
950−its children. Thus, if the indirect hoop references `/path`, then to access the
988+according to its children. Thus, if the indirect hoop references
951−twig defined in `/path/to/twig/hoon`, our body must refer to `twig:to`.
989+`/path`, then to access the twig defined in `/path/to/twig/hoon`, our
990+body must refer to `twig:to`.
953−If there are no more children, then we are done, so we produce our current
992+If there are no more children, then we are done, so we produce our
954−context.
993+current context.
956−Else, we recurse into the left and right sides of our map. Finally, we process
995+Else, we recurse into the left and right sides of our map. Finally, we
957−our current entry in the map. We first recurse by calling `++wilt` one level
996+process our current entry in the map. We first recurse by calling
958−down. Thus, in the previous example, the first time we get to this point we are
997+`++wilt` one level down. Thus, in the previous example, the first time
959−processing `/path`, so we recurse on `++wilt` with path `/path/to`. We also
998+we get to this point we are processing `/path`, so we recurse on
960−remove our current body from the recursion, so that we may add it back in later
999+`++wilt` with path `/path/to`. We also remove our current body from the
961−the way we want to.
1000+recursion, so that we may add it back in later the way we want to.
963−After recursing, we push the new body onto our map, keyed by its name. We also
1002+After recursing, we push the new body onto our map, keyed by its name.
964−produce the new context so that all external structures, libraries, and
1003+We also produce the new context so that all external structures,
965−resources are collected into the same place.
1004+libraries, and resources are collected into the same place.
967−Finally, we have a map of names to feet. If this map is empty, then there were
1006+Finally, we have a map of names to feet. If this map is empty, then
968−no twigs at the requested path, so we give an error with `++flaw`.
1007+there were no twigs at the requested path, so we give an error with
970−If the map is nonempty, then we finally produce our context with with one thing
1010+If the map is nonempty, then we finally produce our context with with
971−pushed onto the front: a core made out of the map we just produced.
1011+one thing pushed onto the front: a core made out of the map we just
973−This concludes our discussion of `++wilt` and `++body`. Thus, it remains in
1014+This concludes our discussion of `++wilt` and `++body`. Thus, it remains
974−`++apex` to discuss `++neck` and `++head`.
1015+in `++apex` to discuss `++neck` and `++head`.
976 ++ neck :: consume libraries
1017 ++ neck :: consume libraries
977 |= [cof=cafe bir=(list hoof)]
1018 |= [cof=cafe bir=(list hoof)]
@@ -999,24 +1040,26 @@ This concludes our discussion of `++wilt` and `++body`. Thus, it remains in
1000 ^^$(cof cof, bir t.bir)
1041 ^^$(cof cof, bir t.bir)
1002−Here, we're going to consume the list of libraries and place them in `bil`. If
1043+Here, we're going to consume the list of libraries and place them in
1003−there are no more libraries, we're done, so we just produce our current context.
1044+`bil`. If there are no more libraries, we're done, so we just produce
1045+our current context.
1005−Otherwise, we check to see if the next library in the list is in `zeg`. If so,
1047+Otherwise, we check to see if the next library in the list is in `zeg`.
1006−then this library is one of the libraries that we're already in the middle of
1048+If so, then this library is one of the libraries that we're already in
1007−compiling. There is a circular dependency, so we fail.
1049+the middle of compiling. There is a circular dependency, so we fail.
1009Otherwise, we let `gez` be `zeg` plus the current library so that while
1051Otherwise, we let `gez` be `zeg` plus the current library so that while
1010−compiling the dependencies of this library we don't later create a circular
1052+compiling the dependencies of this library we don't later create a
1011−dependency. We check next to see if this library is alredy in `bil`. If so, then
1053+circular dependency. We check next to see if this library is alredy in
1012−we have already included this library earlier, so we check to see if this is the
1054+`bil`. If so, then we have already included this library earlier, so we
1013−same version of the library as we included earlier. If so, we skip it. Else, we
1055+check to see if this is the same version of the library as we included
1014−fail since we can't include two different versions of a library. We really
1056+earlier. If so, we skip it. Else, we fail since we can't include two
1015−should allow for newer versions of a library since in kelvin versioning we
1057+different versions of a library. We really should allow for newer
1016−assume backwards compatibility, but for now we require an exact match.
1058+versions of a library since in kelvin versioning we assume backwards
1017−
1059+compatibility, but for now we require an exact match.
1018−If we haven't already included this library, then we're going to do that. First,
1060+
1019−we get the location of the library with `++hone`.
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`.
1021 ++ hone :: plant hoof
1064 ++ hone :: plant hoof
1022 |= [for=@tas way=@tas huf=hoof]
1065 |= [for=@tas way=@tas huf=hoof]
@@ -1025,27 +1068,28 @@ we get the location of the library with `++hone`.
1025 how(s ~[for p.huf way])
1068 how(s ~[for p.huf way])
1026 [[q.u.q.huf %main p.u.q.huf] ~[for p.huf way]]
1069 [[q.u.q.huf %main p.u.q.huf] ~[for p.huf way]]
1028−If we haven't specified the version of the library, we use the current ship,
1071+If we haven't specified the version of the library, we use the current
1029−desk, and case. Otherwise, we use the given ship and case on desk `%main`. In
1072+ship, desk, and case. Otherwise, we use the given ship and case on desk
1030−either case, the path is `/way/p.huf/for`. In the case of `++neck`, this means
1073+`%main`. In either case, the path is `/way/p.huf/for`. In the case of
1031−`/lib/core/[library name]`.
1074+`++neck`, this means `/lib/core/[library name]`.
1033−In `++neck`, we next compile the hook file at that location with `++fade`.
1076+In `++neck`, we next compile the hook file at that location with
1034−Again, we will delay the discussion of `++fade`, noting only that it takes a
1077+`++fade`. Again, we will delay the discussion of `++fade`, noting only
1035−beam and parses the hook file there into a hood.
1078+that it takes a beam and parses the hook file there into a hood.
1037−We recurse on this to compile the library. During the compilation, we let `zeg`
1080+We recurse on this to compile the library. During the compilation, we
1038−be `gez` to avoid circular dependencies, we let `hol` be false since we don't
1081+let `zeg` be `gez` to avoid circular dependencies, we let `hol` be false
1039−allow horns in libraries, and we let `boy` be null so that we can isolate the
1082+since we don't allow horns in libraries, and we let `boy` be null so
1040−new body twigs.
1083+that we can isolate the new body twigs.
1042−Next, we reintegrate the new data into our context. We use the context created
1085+Next, we reintegrate the new data into our context. We use the context
1043−by the recursion with four changes. First, we reset `zeg` to our old `zeg`.
1086+created by the recursion with four changes. First, we reset `zeg` to our
1044−Second, we reset `hol` to our old `hol`. Third, we put the name of our library
1087+old `zeg`. Second, we reset `hol` to our old `hol`. Third, we put the
1045−onto the stack of libraries. This means all of a libraries dependencies will be
1088+name of our library onto the stack of libraries. This means all of a
1046−earlier in `lot` than the library itself, making `lot` a topological ordering on
1089+libraries dependencies will be earlier in `lot` than the library itself,
1047−the dependency graph. Fourth, we put in `bil` the library hoof and body (with
1090+making `lot` a topological ordering on the dependency graph. Fourth, we
1048−all body twigs collected in a `=~`), keyed by the library name.
1091+put in `bil` the library hoof and body (with all body twigs collected in
1092+a `=~`), keyed by the library name.
1050Finally, we recurse, processing the next library in our list.
1094Finally, we recurse, processing the next library in our list.
@@ -1084,36 +1128,38 @@ To complete our disucssion of `++apex`, we must process our structures.
1085 ^^$(cof cof, bir t.bir)
1129 ^^$(cof cof, bir t.bir)
1087−The processing of our structures is very similar to that of our libraries. For
1131+The processing of our structures is very similar to that of our
1088−clarity, we'll use many of the same phrases in describing the parallel natures.
1132+libraries. For clarity, we'll use many of the same phrases in describing
1089−First, we check to see if there are more structures to process. If not, we're
1133+the parallel natures. First, we check to see if there are more
1090−done, so we produce our context.
1134+structures to process. If not, we're done, so we produce our context.
1092−Otherwise, we let `goz` be `zog` plus the current structure so that while
1136+Otherwise, we let `goz` be `zog` plus the current structure so that
1093−compiling the dependencies of this structure we don't later create a circular
1137+while compiling the dependencies of this structure we don't later create
1094−dependency. We check next to see if this structure is alredy in `rop`. If so,
1138+a circular dependency. We check next to see if this structure is alredy
1095−then we have already included this structure earlier, so we check to see if this
1139+in `rop`. If so, then we have already included this structure earlier,
1096−is the same version of the structure as we included earlier. If so, we skip it.
1140+so we check to see if this is the same version of the structure as we
1097−Else, we fail since we can't include two different versions of a structure.
1141+included earlier. If so, we skip it. Else, we fail since we can't
1098−
1142+include two different versions of a structure.
1099−If we haven't loaded this structure, then we call `++hone` to get the beam where
1143+
1100−the file structure should be. If the loobean in the hoot is true, then we're
1144+If we haven't loaded this structure, then we call `++hone` to get the
1101−looking for a gate; otherwise, we're looking for a core. We parse this file with
1145+beam where the file structure should be. If the loobean in the hoot is
1102−`++fade`.
1146+true, then we're looking for a gate; otherwise, we're looking for a
1103−
1147+core. We parse this file with `++fade`.
1104−Now, we recurse on this to compile the structure. During the recursion, there we
1148+
1105−have threee changes. Frist, we let `zog` be `goz` so that we don't create a
1149+Now, we recurse on this to compile the structure. During the recursion,
1106−circular dependency. Second, we let `hol` be false since we do not allow horns
1150+there we have threee changes. Frist, we let `zog` be `goz` so that we
1107−in structures. Third, we let `boy` be null so that we can isolate the new body
1151+don't create a circular dependency. Second, we let `hol` be false since
1108−twigs.
1152+we do not allow horns in structures. Third, we let `boy` be null so that
1109−
1153+we can isolate the new body twigs.
1110−Next, we reintegrate the new data into our context. We use the context cretaed
1154+
1111−by the recursion with four changes. First, if we're including a gate structure,
1155+Next, we reintegrate the new data into our context. We use the context
1112−then we reset the body to its original body. Else we put on the top of our list
1156+cretaed by the recursion with four changes. First, if we're including a
1113−of body twigs what is essentially a `=+ structure-name` to take off the face of
1157+gate structure, then we reset the body to its original body. Else we put
1114−the structure. Second, we reset `zog` to our old `zog`. Third, we reset `hol` to
1158+on the top of our list of body twigs what is essentially a
1115−our old `hol`. Finally, we put in `rop` the structure hoof and body (with all
1159+`=+ structure-name` to take off the face of the structure. Second, we
1116−body twiggs collected in a `=~`), keyed by the structure name.
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.
1118Finally, we recurse, processing the next structure in our list.
1164Finally, we recurse, processing the next structure in our list.
@@ -1133,9 +1179,9 @@ This concludes our discussion of `++apex`.
1133 |= [cof=cafe fin=vase]
1179 |= [cof=cafe fin=vase]
1134 (fine cof fin)
1180 (fine cof fin)
1136−Returning to `++abut`, we have now processed the structures, libraries and body
1182+Returning to `++abut`, we have now processed the structures, libraries
1137−twigs. Next, we slap our preamble (structures and libraries) against zuse.
1183+and body twigs. Next, we slap our preamble (structures and libraries)
1138−First, we construct our preamble in `++able`.
1184+against zuse. First, we construct our preamble in `++able`.
1140 ++ able :: assemble preamble
1186 ++ able :: assemble preamble
@@ -1143,10 +1189,10 @@ First, we construct our preamble in `++able`.
1143 ?:(=(~ rop) [%$ 1] [%brcn (~(run by rop) |=([* a=twig] [%ash a]))])
1189 ?:(=(~ rop) [%$ 1] [%brcn (~(run by rop) |=([* a=twig] [%ash a]))])
1144 [%tssg (turn (flop lot) |=(a=term q:(need (~(get by bil) a))))]
1190 [%tssg (turn (flop lot) |=(a=term q:(need (~(get by bil) a))))]
1146−We first put the structures in `rop` into a single `|%` at the top and `=>` it
1192+We first put the structures in `rop` into a single `|%` at the top and
1147−onto a `=~` of our libraries, in the reverse order that they appear in `lot`.
1193+`=>` it onto a `=~` of our libraries, in the reverse order that they
1148−Thus, the structures are in a single core while the libraries are in consecutive
1194+appear in `lot`. Thus, the structures are in a single core while the
1149−cores.
1195+libraries are in consecutive cores.
1151We slap the preamble against zuse with `++maim`.
1197We slap the preamble against zuse with `++maim`.
@@ -1163,47 +1209,49 @@ We slap the preamble against zuse with `++maim`.
1163 `vase`[p.p.puz val]
1209 `vase`[p.p.puz val]
1166−Here we start to get into ford's caching system. We wrap our computation in a
1212+Here we start to get into ford's caching system. We wrap our computation
1167−call to `++clef` so that we only actually compute it if the result is not
1213+in a call to `++clef` so that we only actually compute it if the result
1168−already in our cache. First we'll discuss the computation, then we'll discuss
1214+is not already in our cache. First we'll discuss the computation, then
1169−the caching system.
1215+we'll discuss the caching system.
1171−We call `++mule` with a call to `++mint:ut` on the type of our subject vase
1217+We call `++mule` with a call to `++mint:ut` on the type of our subject
1172−against the given twig. In other words, we're compiling the twig with against
1218+vase against the given twig. In other words, we're compiling the twig
1173−the subject type in the given subject vase.
1219+with against the subject type in the given subject vase.
1175−If compilation fails, then we produce an error bolt with the produced stack
1221+If compilation fails, then we produce an error bolt with the produced
1176−trace. Otherwise, we run the produced nock with `++mock` and our sky function.
1222+stack trace. Otherwise, we run the produced nock with `++mock` and our
1177−We convert the produced toon to a bolt with `++coup` and use the type from `puz`
1223+sky function. We convert the produced toon to a bolt with `++coup` and
1178−combined with the value from `mock` to produce our vase.
1224+use the type from `puz` combined with the value from `mock` to produce
1180−If this process seems harder than just calling `++slap`, it's because it is. We
1227+If this process seems harder than just calling `++slap`, it's because it
1181−have two requirements that `++slap` doesn't satisfy. First, we want the to use
1228+is. We have two requirements that `++slap` doesn't satisfy. First, we
1182−an explicit sky function for use with `.^`. With `++slap`, you get whatever sky
1229+want the to use an explicit sky function for use with `.^`. With
1183−function is available in the calling context, which in ford is none. Second, we
1230+`++slap`, you get whatever sky function is available in the calling
1184−want to explicitly handle the stack trace on failure. `++slap` would cause crash
1231+context, which in ford is none. Second, we want to explicitly handle the
1185−on failure.
1232+stack trace on failure. `++slap` would cause crash on failure.
1187−We haven't yet discussed either `++clef` or `++coup`. We'll start with `++coup`
1234+We haven't yet discussed either `++clef` or `++coup`. We'll start with
1188−to finish the discussion of the computation.
1235+`++coup` to finish the discussion of the computation.
1190\``++ 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 == ==`
1237\``++ 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 == ==`
1192−Recall that a toon is either a `%0` value, a `%1` block, or a `%2` failure.
1239+Recall that a toon is either a `%0` value, a `%1` block, or a `%2`
1193−Converting a `%2` toon failure into a `%2` bolt failure is trivial. Converting a
1240+failure. Converting a `%2` toon failure into a `%2` bolt failure is
1194−`%0` toon value into a `%0` bolt value is easy since we assume there were no
1241+trivial. Converting a `%0` toon value into a `%0` bolt value is easy
1195−dependencies. Converting the blocks is rather more difficult.
1242+since we assume there were no dependencies. Converting the blocks is
1243+rather more difficult.
1197−To compute `faw`, we recurse through the list of paths in the `%1` toon. At each
1245+To compute `faw`, we recurse through the list of paths in the `%1` toon.
1198−one, we make sure with `++tome` that it is, in fact, a beam. If so, then we
1246+At each one, we make sure with `++tome` that it is, in fact, a beam. If
1199−check to see if the later paths succeed as well. If so, we append the current
1247+so, then we check to see if the later paths succeed as well. If so, we
1200−path to the list of other paths. If not, we produce the error message we got
1248+append the current path to the list of other paths. If not, we produce
1201−from processing the rest of the paths. If this path is not a beam, then we fail,
1249+the error message we got from processing the rest of the paths. If this
1202−producing a list of tanks including this path and, if later paths fail too,
1250+path is not a beam, then we fail, producing a list of tanks including
1203−those paths as well.
1251+this path and, if later paths fail too, those paths as well.
1205−If some paths were not beams, then we produce a `%2` error bolt. If all paths
1253+If some paths were not beams, then we produce a `%2` error bolt. If all
1206−were correct, then we produce a `%1` blocking bolt.
1254+paths were correct, then we produce a `%1` blocking bolt.
1208We will now discuss `++clef`. This is where the cache magic happens.
1256We will now discuss `++clef`. This is where the cache magic happens.
@@ -1238,28 +1286,29 @@ Otherwise, we look up the request in the cache with `++calk`.
1238 ?~ d [~ a] ::
1286 ?~ d [~ a] ::
1239 [d a(p (~(put in p.a) u.d))] ::
1287 [d a(p (~(put in p.a) u.d))] ::
1241−When looking up something in the cache, we mark it if we find it. This way, we
1289+When looking up something in the cache, we mark it if we find it. This
1242−have in our cache the set of all cache entries that have been referenced. While
1290+way, we have in our cache the set of all cache entries that have been
1243−we do not at present do anything with this data, it should be used to clear out
1291+referenced. While we do not at present do anything with this data, it
1244−old and unused entries in the cache.
1292+should be used to clear out old and unused entries in the cache.
1246−Moving on in `++clef`, we check to see if we actually found anything. If we
1294+Moving on in `++clef`, we check to see if we actually found anything. If
1247−didn't find a cache entry, then we run the computation in `fun`, and examine its
1295+we didn't find a cache entry, then we run the computation in `fun`, and
1248−result. If it produced a `%2` error or `%1` block bolt, we just pass that
1296+examine its result. If it produced a `%2` error or `%1` block bolt, we
1249−through. Otherwise, we produce both the value and an updated cache with this new
1297+just pass that through. Otherwise, we produce both the value and an
1250−entry. We add the entry with `++came`.
1298+updated cache with this new entry. We add the entry with `++came`.
1252 ++ came ::
1300 ++ came ::
1253 |= [a=cafe b=calx] :: cache install
1301 |= [a=cafe b=calx] :: cache install
1254 ^- cafe ::
1302 ^- cafe ::
1255 a(q (~(put by q.a) [-.b q.b] b)) ::
1303 a(q (~(put by q.a) [-.b q.b] b)) ::
1257−We key cache entries by the type of computation (`-:calx`) and the inputs to the
1305+We key cache entries by the type of computation (`-:calx`) and the
1258−computation (`q:calc`). This just puts the cache line in the cache at the
1306+inputs to the computation (`q:calc`). This just puts the cache line in
1259−correct key.
1307+the cache at the correct key.
1261−Back in `++clef`, if we did find a cache entry, then we just produce the value
1309+Back in `++clef`, if we did find a cache entry, then we just produce the
1262−at that cache line. We convert the cache line into a value with `++calf`.
1310+value at that cache line. We convert the cache line into a value with
1264 ++ calf :: reduce calx
1313 ++ calf :: reduce calx
1265 |* sem=* :: a typesystem hack
1314 |* sem=* :: a typesystem hack
@@ -1270,22 +1319,23 @@ at that cache line. We convert the cache line into a value with `++calf`.
1270 %slam ?>(?=(%slam -.cax) r.cax)
1319 %slam ?>(?=(%slam -.cax) r.cax)
1273−This is simply a typesystem hack. Because the `sem` is passed in through a wet
1322+This is simply a typesystem hack. Because the `sem` is passed in through
1274−gate, we know at type time which of the three cases will be chosen. Thus, the
1323+a wet gate, we know at type time which of the three cases will be
1275−correct type of the value in the cache line gets passed through to the caller.
1324+chosen. Thus, the correct type of the value in the cache line gets
1276−This also depends on the fact that `++clef` is wet. The type stuff here is
1325+passed through to the caller. This also depends on the fact that
1277−mathematically interesting, but the action is simple: we get the value from the
1326+`++clef` is wet. The type stuff here is mathematically interesting, but
1278−cache line.
1327+the action is simple: we get the value from the cache line.
1280This concludes our discussion of `++clef` and `++maim`.
1329This concludes our discussion of `++clef` and `++maim`.
1282−Back in `++abut`, recall that we processed the structures, libraries, and body
1331+Back in `++abut`, recall that we processed the structures, libraries,
1283−with `++apex`. Then, we slapped our preamble (structures and libraries) against
1332+and body with `++apex`. Then, we slapped our preamble (structures and
1284−zuse with `++maim`. Next, we process our resources with `++chap`. Note that we
1333+libraries) against zuse with `++maim`. Next, we process our resources
1285−pass in the preamble so that we may refer to anything in there in 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.
1287−`++chap` is broken up into a different case for each horn. We'll go through them
1337+`++chap` is broken up into a different case for each horn. We'll go
1288−one by one.
1338+through them one by one.
1290 ++ chap :: produce resources
1340 ++ chap :: produce resources
1291 |= [cof=cafe bax=vase hon=horn]
1341 |= [cof=cafe bax=vase hon=horn]
@@ -1300,9 +1350,9 @@ This is `/~`. We slap the twig against our context.
1300 |= [cof=cafe gat=vase]
1350 |= [cof=cafe gat=vase]
1301 (maul cof gat !>([how arg]))
1351 (maul cof gat !>([how arg]))
1303−This is `/$`. We slap the twig against our context, which we expect to produce a
1353+This is `/$`. We slap the twig against our context, which we expect to
1304−gate. We slam this gate with a sample of `how` and `arg`, which is our location
1354+produce a gate. We slam this gate with a sample of `how` and `arg`,
1305−and the heel (virtual path extension).
1355+which is our location and the heel (virtual path extension).
1307`++maul` is similar to `++maim`, but it slams instead of slaps.
1357`++maul` is similar to `++maim`, but it slams instead of slaps.
@@ -1319,19 +1369,20 @@ and the heel (virtual path extension).
1319 `vase`[p.top val]
1369 `vase`[p.top val]
1322−We cache slams exactly as we cache slaps. We use `++slit` to find the type of
1372+We cache slams exactly as we cache slaps. We use `++slit` to find the
1323−the product of the slam given the types of the gate and the sample.
1373+type of the product of the slam given the types of the gate and the
1325−If this type fails, we produce the given stack trace as a `%2` error bolt.
1376+If this type fails, we produce the given stack trace as a `%2` error
1326−Otherwise, we produce the top produced above combined with the value we get from
1377+bolt. Otherwise, we produce the top produced above combined with the
1327−slamming the values in the vases with `++mong`.
1378+value we get from slamming the values in the vases with `++mong`.
1329Back to `++chap`.
1380Back to `++chap`.
1331 %day (chad cof bax %dr p.hon)
1382 %day (chad cof bax %dr p.hon)
1333−This is `/|`. We call `++chad` to convert textual names to relative dates and
1384+This is `/|`. We call `++chad` to convert textual names to relative
1334−process the next horn against each of the discovered paths.
1385+dates and process the next horn against each of the discovered paths.
1336 ++ chad :: atomic list
1387 ++ chad :: atomic list
1337 |= [cof=cafe bax=vase doe=term hon=horn]
1388 |= [cof=cafe bax=vase doe=term hon=horn]
@@ -1355,8 +1406,8 @@ process the next horn against each of the discovered paths.
1355 ?~ yal [[%cube 0 [%atom %n]] 0]
1406 ?~ yal [[%cube 0 [%atom %n]] 0]
1356 (slop (slop [[%atom doe] p.i.yal] q.i.yal) $(yal t.yal))
1407 (slop (slop [[%atom doe] p.i.yal] q.i.yal) $(yal t.yal))
1358−First, we call `++lash` to parse the children of the current beam and pick out
1409+First, we call `++lash` to parse the children of the current beam and
1359−those ones that are of the requested format.
1410+pick out those ones that are of the requested format.
1361 ++ lash :: atomic sequence
1412 ++ lash :: atomic sequence
1362 |= wox=$+(span (unit ,@))
1413 |= wox=$+(span (unit ,@))
@@ -1366,22 +1417,26 @@ those ones that are of the requested format.
1366 |= [cof=cafe arc=arch]
1417 |= [cof=cafe arc=arch]
1367 (fine cof (lark wox arc))
1418 (fine cof (lark wox arc))
1369−First, we get the arch with `++lend`, as described above. We filter and parse
1420+First, we get the arch with `++lend`, as described above. We filter and
1370−the child names with `++lark` according to the given parser function.
1421+parse the child names with `++lark` according to the given parser
1372−In `++chad`, this parser function is `(slat doe)`, which will parse a cord into
1424+In `++chad`, this parser function is `(slat doe)`, which will parse a
1373−an atom of the requested odor. For `%day` the odor is for relative dates.
1425+cord into an atom of the requested odor. For `%day` the odor is for
1375−Thus, we now have a map from atoms of the given odor to the actual child names.
1428+Thus, we now have a map from atoms of the given odor to the actual child
1376−We next turn this map into a list and sort it in increasing order by the atom.
1429+names. We next turn this map into a list and sort it in increasing order
1378−We next convert this list of pairs of atoms and spans to a list of pairs of
1432+We next convert this list of pairs of atoms and spans to a list of pairs
1379−atoms and vases. We process the given horn once at every child beam, producing
1433+of atoms and vases. We process the given horn once at every child beam,
1380−the resource at that location.
1434+producing the resource at that location.
1382−Finally, we convert this list of pairs of atoms and vases to a vase of a list of
1436+Finally, we convert this list of pairs of atoms and vases to a vase of a
1383−pairs of atoms to (well-typed) values. Each entry in the list is of type atom
1437+list of pairs of atoms to (well-typed) values. Each entry in the list is
1384−with the given odor combined with the type of the produced vase.
1438+of type atom with the given odor combined with the type of the produced
1386Back in `++chap`, we continue parsing resources.
1441Back in `++chap`, we continue parsing resources.
@@ -1390,8 +1445,8 @@ Back in `++chap`, we continue parsing resources.
1390 |= [cof=cafe vax=vase]
1445 |= [cof=cafe vax=vase]
1391 (fine cof [[%face p.hon p.vax] q.vax])
1446 (fine cof [[%face p.hon p.vax] q.vax])
1393−This is `/=`. We process the given horn, giving us a vase. We put as a face on
1448+This is `/=`. We process the given horn, giving us a vase. We put as a
1394−the vase so that it may be referred to later by name.
1449+face on the vase so that it may be referred to later by name.
@@ -1408,21 +1463,21 @@ the vase so that it may be referred to later by name.
1408 ?~ tev [[%cube 0 [%atom %n]] 0]
1463 ?~ tev [[%cube 0 [%atom %n]] 0]
1409 (slop i.tev $(tev t.tev))
1464 (slop i.tev $(tev t.tev))
1411−This is `/.`. We first process each of the child horns, producing a list of
1466+This is `/.`. We first process each of the child horns, producing a list
1412−vases. This is done by just recursing on `++chap`. Then, we simply fold over
1467+of vases. This is done by just recursing on `++chap`. Then, we simply
1413−this list to create a vase of the list of values.
1468+fold over this list to create a vase of the list of values.
1415 %for $(hon q.hon, s.how (weld (flop p.hon) s.how))
1470 %for $(hon q.hon, s.how (weld (flop p.hon) s.how))
1417−This is `/,`. We simply recurse on the horn with the given path welded onto our
1472+This is `/,`. We simply recurse on the horn with the given path welded
1418−current beam.
1473+onto our current beam.
1420 %hub (chad cof bax %ud p.hon)
1475 %hub (chad cof bax %ud p.hon)
1422−This is `/@`. This is exactly like the processing of `%day` except we expect the
1477+This is `/@`. This is exactly like the processing of `%day` except we
1423−children to be named as unsigned integers rather than relative dates. We process
1478+expect the children to be named as unsigned integers rather than
1424−the horn at each of the children's locations and produce a list of pairs of
1479+relative dates. We process the horn at each of the children's locations
1425−absolute dates and values.
1480+and produce a list of pairs of absolute dates and values.
1428 |- ^- (bolt vase)
1483 |- ^- (bolt vase)
@@ -1438,20 +1493,21 @@ absolute dates and values.
1438 (slop [[%atom %tas] p.n.p.hon] vax)
1493 (slop [[%atom %tas] p.n.p.hon] vax)
1439 (slop lef rig)
1494 (slop lef rig)
1441−This is `/*`. We process each of the horns in the given map by recursion through
1496+This is `/*`. We process each of the horns in the given map by recursion
1442−`++chap`. Once we have these vases, we create a vase of a map from the given
1497+through `++chap`. Once we have these vases, we create a vase of a map
1443−textual names to the produced values.
1498+from the given textual names to the produced values.
1445 %now (chad cof bax %da p.hon)
1500 %now (chad cof bax %da p.hon)
1447−This is `/&`. This is exactly like the processing of `%now` except we expect the
1502+This is `/&`. This is exactly like the processing of `%now` except we
1448−children to be names as absolute dates rather than relative dates. We process
1503+expect the children to be names as absolute dates rather than relative
1449−the horn at each of the children's locations and produce a list of pairs of
1504+dates. We process the horn at each of the children's locations and
1450−absolute dates and values.
1505+produce a list of pairs of absolute dates and values.
1452 %nap (chai cof bax p.hon)
1507 %nap (chai cof bax p.hon)
1454−This is `/%`. Here, we process the horn at each of our children with `++chai`.
1509+This is `/%`. Here, we process the horn at each of our children with
1456 ++ chai :: atomic map
1512 ++ chai :: atomic map
1457 |= [cof=cafe bax=vase hon=horn]
1513 |= [cof=cafe bax=vase hon=horn]
@@ -1476,10 +1532,10 @@ This is `/%`. Here, we process the horn at each of our children with `++chai`.
1476 (slop [[%atom %a] p.n.doy] q.n.doy)
1532 (slop [[%atom %a] p.n.doy] q.n.doy)
1477 (slop $(doy l.doy) $(doy r.doy))
1533 (slop $(doy l.doy) $(doy r.doy))
1479−We get the arch at our current beam with `++lend`. Then, we process the horn at
1535+We get the arch at our current beam with `++lend`. Then, we process the
1480−each of our children to give us a map of atoms to vases. Finally, we convert
1536+horn at each of our children to give us a map of atoms to vases.
1481−that into a vase of a map of these atoms to the values. This is very similar to
1537+Finally, we convert that into a vase of a map of these atoms to the
1482−`++chad` and the handling of `%man`.
1538+values. This is very similar to `++chad` and the handling of `%man`.
1484 %see $(hon q.hon, how p.hon)
1540 %see $(hon q.hon, how p.hon)
@@ -1492,9 +1548,9 @@ This is `/:`. We process the given horn at the given beam.
1492 |= [cof=cafe gat=vase]
1548 |= [cof=cafe gat=vase]
1493 (maul cof gat sam)
1549 (maul cof gat sam)
1495−This is `/;`. First, we process the given horn. Then, we slap the given twig
1551+This is `/;`. First, we process the given horn. Then, we slap the given
1496−against our context to produce (hopefully) a gate. Finally, we slam the vase we
1552+twig against our context to produce (hopefully) a gate. Finally, we slam
1497−got from processing the horn against the gate.
1553+the vase we got from processing the horn against the gate.
1500 %+ cope $(hon q.hon)
1556 %+ cope $(hon q.hon)
@@ -1505,26 +1561,27 @@ got from processing the horn against the gate.
1505 (flaw cof [%leaf "type error: {<p.hon>} {<q.hon>}"]~)
1561 (flaw cof [%leaf "type error: {<p.hon>} {<q.hon>}"]~)
1506 (fine cof [p.tug q.vax])
1562 (fine cof [p.tug q.vax])
1508−This is `/^`. First, we process the given horn. Then, we slap the the bunt of
1564+This is `/^`. First, we process the given horn. Then, we slap the the
1509−the given tile against our context. This will produce a vase with the correct
1565+bunt of the given tile against our context. This will produce a vase
1510−type. We test to see if this type nests within the type of the vase we got from
1566+with the correct type. We test to see if this type nests within the type
1511−processing the horn. If so, we produce the value from the horn along with the
1567+of the vase we got from processing the horn. If so, we produce the value
1512−type from the tile. Otherwise, we produce a `%2` error bolt.
1568+from the horn along with the type from the tile. Otherwise, we produce a
1514 %toy (cope (make cof %bake p.hon how ~) feel)
1571 %toy (cope (make cof %bake p.hon how ~) feel)
1517−This is `/mark/`. Here, we simply run the `%bake` silk on the given mark,
1574+This is `/mark/`. Here, we simply run the `%bake` silk on the given
1518−producing a cage. We convert this cage into a vase with `++feel`, which is
1575+mark, producing a cage. We convert this cage into a vase with `++feel`,
1519−exactly as simple as it sounds like it should be.
1576+which is exactly as simple as it sounds like it should be.
1521 ++ feel |=([a=cafe b=cage] (fine a q.b)) :: cage to vase
1578 ++ feel |=([a=cafe b=cage] (fine a q.b)) :: cage to vase
1523This is trivial.
1580This is trivial.
1525−We will discuss later `++make` and how `%bake` is processed. Suffice it to say
1582+We will discuss later `++make` and how `%bake` is processed. Suffice it
1526−that baking a resource with a given mark gets the resource and converts it, if
1583+to say that baking a resource with a given mark gets the resource and
1527−necessary, to the requested mark.
1584+converts it, if necessary, to the requested mark.
1529This concludes our discussion of `++chap`.
1586This concludes our discussion of `++chap`.
@@ -1544,24 +1601,26 @@ We return once more to `++abut`.
1544 |= [cof=cafe fin=vase]
1601 |= [cof=cafe fin=vase]
1545 (fine cof fin)
1602 (fine cof fin)
1547−Recall that we processed our structures, libraries and body with `++apex`. We
1604+Recall that we processed our structures, libraries and body with
1548−slapped our structures and libraries against zuse with `++maim`. We processed
1605+`++apex`. We slapped our structures and libraries against zuse with
1549−our resources with `++chap`. Now, all our body twigs are collected in a `=~` and
1606+`++maim`. We processed our resources with `++chap`. Now, all our body
1550−slapped against our structures, libraries, and resources. This produces our
1607+twigs are collected in a `=~` and slapped against our structures,
1551−final result.
1608+libraries, and resources. This produces our final result.
1553The hook file has been assembled. And there was great rejoicing.
1610The hook file has been assembled. And there was great rejoicing.
1555−## Lifecycle of a Kiss
1612+Lifecycle of a Kiss
1557−We're now going to go through a series of lifecycle descriptions. When a user of
1615+We're now going to go through a series of lifecycle descriptions. When a
1558−ford sends a kiss, it is one of a dozen different types of silk. We'll go
1616+user of ford sends a kiss, it is one of a dozen different types of silk.
1559−through each one, tracing through the flow of control of each of these.
1617+We'll go through each one, tracing through the flow of control of each
1561First, though, we'll describe the common handling to all kisses.
1620First, though, we'll describe the common handling to all kisses.
1563−The silk in a `%exec` kiss to ford ends up in `++apex`, so we'll enter the
1622+The silk in a `%exec` kiss to ford ends up in `++apex`, so we'll enter
1564−narrative here.
1623+the narrative here.
1566 ++ apex :: call
1625 ++ apex :: call
1567 |= kus=(unit silk)
1626 |= kus=(unit silk)
@@ -1580,13 +1639,13 @@ narrative here.
1581 ~(exec zo [num `task`[hen u.kus 0 ~]])
1640 ~(exec zo [num `task`[hen u.kus 0 ~]])
1583−Recall that a `%exec` kiss actually sends a unit silk. If it's null, we're
1642+Recall that a `%exec` kiss actually sends a unit silk. If it's null,
1584−trying to cancel the request. We first look up the task number keyed by duct. If
1643+we're trying to cancel the request. We first look up the task number
1585−we don't find it, then we're trying to cancel a request that either was never
1644+keyed by duct. If we don't find it, then we're trying to cancel a
1586−started or has already completed. We print out `%ford-mystery` and do nothing.
1645+request that either was never started or has already completed. We print
1587−If we do find the task number, then we look up the task from it, call
1646+out `%ford-mystery` and do nothing. If we do find the task number, then
1588−`++camo:zo` to cancel pending requests, and call `++amok:zo` to remove the task
1647+we look up the task from it, call `++camo:zo` to cancel pending
1589−from our task lists.
1648+requests, and call `++amok:zo` to remove the task from our task lists.
1591 ++ camo :: stop requests
1650 ++ camo :: stop requests
@@ -1602,9 +1661,9 @@ from our task lists.
1602 [%warp [our p.q.i.kiz] q.q.i.kiz ~]
1661 [%warp [our p.q.i.kiz] q.q.i.kiz ~]
1605−Our list of blocks is in `q.kig`, so we iterate over it, cancelling our pending
1664+Our list of blocks is in `q.kig`, so we iterate over it, cancelling our
1606−requests for each block. Our requests are all to clay, so we need only to send
1665+pending requests for each block. Our requests are all to clay, so we
1607−`%warp` kisses with a null instead of a rave.
1666+need only to send `%warp` kisses with a null instead of a rave.
1609 ++ amok
1668 ++ amok
1610 %_ ..zo
1669 %_ ..zo
@@ -1612,12 +1671,12 @@ requests for each block. Our requests are all to clay, so we need only to send
1612 dym.bay (~(del by dym.bay) nah)
1671 dym.bay (~(del by dym.bay) nah)
1615−We remove the task number from the map of numbers to tasks and the duct from the
1674+We remove the task number from the map of numbers to tasks and the duct
1616−map of ducts to task numbers.
1675+from the map of ducts to task numbers.
1618−Back in `++apex`, if we were given a silk, we need to process it. We add the
1677+Back in `++apex`, if we were given a silk, we need to process it. We add
1619−task to our maps, increment the next task number, and call `++exec:zo` on the
1678+the task to our maps, increment the next task number, and call
1620−new task.
1679+`++exec:zo` on the new task.
1622 ++ exec :: execute app
1681 ++ exec :: execute app
@@ -1638,9 +1697,9 @@ new task.
1639If we're still blocked on something in `q.kig`, we don't do anything.
1698If we're still blocked on something in `q.kig`, we don't do anything.
1641−Otherwise, we try to process the silk with `++make`. `++make` handles each
1700+Otherwise, we try to process the silk with `++make`. `++make` handles
1642−individual request and will be the entire focus of the remainder of this doc
1701+each individual request and will be the entire focus of the remainder of
1643−after this section. It produces a bolt of a cage.
1702+this doc after this section. It produces a bolt of a cage.
1645We put the new cache in our state with `++dash`.
1704We put the new cache in our state with `++dash`.
@@ -1649,12 +1708,13 @@ We put the new cache in our state with `++dash`.
1650 %_(+> jav.bay q.cof)
1709 %_(+> jav.bay q.cof)
1652−The cache is put in the baby so that it gets stored across calls to ford.
1711+The cache is put in the baby so that it gets stored across calls to
1654−In `++exec`, we process the bolt in three different ways according to the type
1714+In `++exec`, we process the bolt in three different ways according to
1655−of bolt produced. If we produced a `%0` value bolt, we use `++expo` to give the
1715+the type of bolt produced. If we produced a `%0` value bolt, we use
1656−produced value and set of dependencies as a `%made` gift, and we remove
1716+`++expo` to give the produced value and set of dependencies as a `%made`
1657−ourselves from the task list with `++amok`.
1717+gift, and we remove ourselves from the task list with `++amok`.
1659 ++ expo :: return gift
1719 ++ expo :: return gift
1660 |= gef=gift
1720 |= gef=gift
@@ -1662,11 +1722,11 @@ ourselves from the task list with `++amok`.
1663We simply push the gift onto our list of moves.
1723We simply push the gift onto our list of moves.
1665−In `++exec`, if we produced a `%2` error bolt, we produce a `%made` gift with
1725+In `++exec`, if we produced a `%2` error bolt, we produce a `%made` gift
1666−the stack trace.
1726+with the stack trace.
1668−If we produced a `%1` block bolt, we iterate through each of the blocks and call
1728+If we produced a `%1` block bolt, we iterate through each of the blocks
1669−`++camp` to produce a clay request for the resource.
1729+and call `++camp` to produce a clay request for the resource.
1671 ++ camp :: request a file
1731 ++ camp :: request a file
1672 |= [ren=care bem=beam]
1732 |= [ren=care bem=beam]
@@ -1680,13 +1740,16 @@ If we produced a `%1` block bolt, we iterate through each of the blocks and call
1680 [%warp [our p.bem] q.bem [~ %& %x r.bem s.bem]]
1740 [%warp [our p.bem] q.bem [~ %& %x r.bem s.bem]]
1683−We put the resource in our block list in `q.kig` so that we save the fact that
1743+We put the resource in our block list in `q.kig` so that we save the
1684−we're blocked. We then produce the `%warp` request to clay for the resource. Our
1744+fact that we're blocked. We then produce the `%warp` request to clay for
1685−request path has the format \`/\[our-ship\]/\[task-number\]/\[block-number\]'.
1745+the resource. Our request path has the format
1746+\`/[our-ship]/[task-number]/[block-number]'.
1687−We'll now describe how each of the individual silks are processed in `++make`.
1748+We'll now describe how each of the individual silks are processed in
1689−## Lifecycle of a Cell
1751+Lifecycle of a Cell
1692 %. [cof p.kas q.kas]
1755 %. [cof p.kas q.kas]
@@ -1700,10 +1763,10 @@ We'll now describe how each of the individual silks are processed in `++make`.
1700 [p=cof q=[%0 ~ [%$ (slop q.bor q.heg)]]]
1763 [p=cof q=[%0 ~ [%$ (slop q.bor q.heg)]]]
1703−Silks autocons. The product of a cell of silks is a cell of the products of the
1766+Silks autocons. The product of a cell of silks is a cell of the products
1704−silks, so we evaluate the two silks in parallel with `++coax` and slop together
1767+of the silks, so we evaluate the two silks in parallel with `++coax` and
1705−the results in a cell vase. We mark the product with `%$`, which means we know
1768+slop together the results in a cell vase. We mark the product with `%$`,
1706−no more mark information than that it is a noun.
1769+which means we know no more mark information than that it is a noun.
1708 ++ coax :: bolt across
1771 ++ coax :: bolt across
1709 |* [hoc=(bolt) fun=(burg)]
1772 |* [hoc=(bolt) fun=(burg)]
@@ -1727,19 +1790,23 @@ no more mark information than that it is a noun.
1730−If the first bolt is a value, we evaluate the burg to get the next bolt. If that
1793+If the first bolt is a value, we evaluate the burg to get the next bolt.
1731−also produces a value, we merge the dependency sets and produce a cell of the
1794+If that also produces a value, we merge the dependency sets and produce
1732−two values. Otherwise, we produce the block or error of the second bolt.
1795+a cell of the two values. Otherwise, we produce the block or error of
1734−If the first bolt is a block, we evaluate the burg to get the next bolt. If that
1798+If the first bolt is a block, we evaluate the burg to get the next bolt.
1735−produces a value, we just produce the block. If it produces a block, we merge
1799+If that produces a value, we just produce the block. If it produces a
1736−the two block sets. If it produces an error, we produce that error.
1800+block, we merge the two block sets. If it produces an error, we produce
1738If the first bolt is already an error, we just pass that through.
1803If the first bolt is already an error, we just pass that through.
1740−Note that `++coax` (and, indeed, `++cope`) is reasonable to use with `;~`.
1805+Note that `++coax` (and, indeed, `++cope`) is reasonable to use with
1742−## Lifecycle of a `%bake`
1808+Lifecycle of a `%bake`
1809+----------------------
1745 %+ cool |.(leaf/"ford: bake {<p.kas>} {<(tope q.kas)>}")
1812 %+ cool |.(leaf/"ford: bake {<p.kas>} {<(tope q.kas)>}")
@@ -1749,11 +1816,12 @@ Note that `++coax` (and, indeed, `++cope`) is reasonable to use with `;~`.
1749 (flaw cof (smyt (tope q.kas)) ~)
1816 (flaw cof (smyt (tope q.kas)) ~)
1750 (fine cof [p.kas u.vux])
1817 (fine cof [p.kas u.vux])
1752−This is one of the most critical silks. We are going to functionally produce the
1819+This is one of the most critical silks. We are going to functionally
1753−hook file at the given beam with the given heel. The result will be of the
1820+produce the hook file at the given beam with the given heel. The result
1754−correct mark, even if we need to run conversion functions. The functionality is
1821+will be of the correct mark, even if we need to run conversion
1755−encapsulated in `++lime`. If it produces null, then we produce an error.
1822+functions. The functionality is encapsulated in `++lime`. If it produces
1756−Otherwise, we take the vase produced and give it the correct mark.
1823+null, then we produce an error. Otherwise, we take the vase produced and
1824+give it the correct mark.
1758 ++ lima :: load at depth
1826 ++ lima :: load at depth
1759 |= [cof=cafe for=mark bem=beam arg=heel]
1827 |= [cof=cafe for=mark bem=beam arg=heel]
@@ -1775,19 +1843,19 @@ Otherwise, we take the vase produced and give it the correct mark.
1775 |= [cof=cafe vax=vase]
1843 |= [cof=cafe vax=vase]
1776 (fine cof ~ vax)
1844 (fine cof ~ vax)
1778−First, we load the arch at the given beam with `++lend`. If we have a child
1846+First, we load the arch at the given beam with `++lend`. If we have a
1779−named the mark, our job is straightforward, so we go ahead and load that with
1847+child named the mark, our job is straightforward, so we go ahead and
1780−`++lace`.
1848+load that with `++lace`.
1782−Otherwise, we iterate through our children. If we have no children, we produce
1850+Otherwise, we iterate through our children. If we have no children, we
1783−null, signifying that we didn't find any way to convert to the requested mark.
1851+produce null, signifying that we didn't find any way to convert to the
1784−Otherwise, we call `++lion` to find a translation path from one of the available
1852+requested mark. Otherwise, we call `++lion` to find a translation path
1785−marks into the target mark. We recursively bake the child that has a path to the
1853+from one of the available marks into the target mark. We recursively
1786−target mark, and then we call `++lope` to translate this mark into the target
1854+bake the child that has a path to the target mark, and then we call
1787−mark.
1855+`++lope` to translate this mark into the target mark.
1789−We'll first discuss the direct case of when one of our children is of the
1857+We'll first discuss the direct case of when one of our children is of
1790−correct mark.
1858+the correct mark.
1792 ++ lace :: load and check
1860 ++ lace :: load and check
1793 |= [cof=cafe for=mark bem=beam arg=heel]
1861 |= [cof=cafe for=mark bem=beam arg=heel]
@@ -1803,10 +1871,11 @@ correct mark.
1803 (cope (cope (abut:(meow bem arg) cof hyd) (lake for bek)) fest)
1871 (cope (cope (abut:(meow bem arg) cof hyd) (lake for bek)) fest)
1804 (fine cof ~)
1872 (fine cof ~)
1806−First, we get the arch at the given beam with `++lend`. If this is a file, we
1874+First, we get the arch at the given beam with `++lend`. If this is a
1807−load the file with `++liar` and coerce the type with `++lake`. Otherwise, we
1875+file, we load the file with `++liar` and coerce the type with `++lake`.
1808−check to see if we have a hook file here. If so, we parse it with `++fade`,
1876+Otherwise, we check to see if we have a hook file here. If so, we parse
1809−compile it with `++abut:meow`, and coerce the type with `++lake`.
1877+it with `++fade`, compile it with `++abut:meow`, and coerce the type
1811Otherwise, there is no way to translate this, so we produce null.
1880Otherwise, there is no way to translate this, so we produce null.
@@ -1817,8 +1886,9 @@ Otherwise, there is no way to translate this, so we produce null.
1817This is just `++some` for bolts.
1886This is just `++some` for bolts.
1819We've delayed the discussion of `++fade` far too many times. It's not
1888We've delayed the discussion of `++fade` far too many times. It's not
1820−complicated, we just wanted to spare a premature discussion of `++make` and the
1889+complicated, we just wanted to spare a premature discussion of `++make`
1821−`%bake` silk. We 're now able to discuss everything in `++fade` with ease.
1890+and the `%bake` silk. We 're now able to discuss everything in `++fade`
1823 ++ fade :: compile to hood
1893 ++ fade :: compile to hood
1824 |= [cof=cafe for=mark bem=beam]
1894 |= [cof=cafe for=mark bem=beam]
@@ -1837,17 +1907,18 @@ complicated, we just wanted to spare a premature discussion of `++make` and the
1837 (flaw cof [%leaf "syntax error: {<p.p.vex>} {<q.p.vex>}"] ~)
1907 (flaw cof [%leaf "syntax error: {<p.p.vex>} {<q.p.vex>}"] ~)
1838 (fine cof p.u.q.vex)
1908 (fine cof p.u.q.vex)
1840−We first push a line onto a stack trace to say that we're parsing into a hood
1910+We first push a line onto a stack trace to say that we're parsing into a
1841−file.
1911+hood file.
1843−We bake the given beam with the given mark and no heel. Recall that baking gate,
1913+We bake the given beam with the given mark and no heel. Recall that
1844−core, door, hoon, and hook files produces simply an atom of the text. We check
1914+baking gate, core, door, hoon, and hook files produces simply an atom of
1845−to make sure that our value is an atom, failing otherwise.
1915+the text. We check to make sure that our value is an atom, failing
1847−The parsing step is run within `++clef` so that the result is cached. We call
1918+The parsing step is run within `++clef` so that the result is cached. We
1848−`++fair` with the current beam to generate the parsing rule, and we parse the
1919+call `++fair` with the current beam to generate the parsing rule, and we
1849−file. If parsing fails, we fail giving a syntax error with the line and column
1920+parse the file. If parsing fails, we fail giving a syntax error with the
1850−number. Otherwise, we produce the value.
1921+line and column number. Otherwise, we produce the value.
1852 ++ liar :: load vase
1923 ++ liar :: load vase
1853 |= [cof=cafe bem=beam]
1924 |= [cof=cafe bem=beam]
@@ -1859,14 +1930,15 @@ number. Otherwise, we produce the value.
1859 (flaw cof (smyt (tope bem)) ~)
1930 (flaw cof (smyt (tope bem)) ~)
1860 (fine cof ?^(u.u.von [%cell %noun %noun] [%atom %$]) u.u.von)
1931 (fine cof ?^(u.u.von [%cell %noun %noun] [%atom %$]) u.u.von)
1862−This takes a beam and loads the file at that location. If our sky function
1933+This takes a beam and loads the file at that location. If our sky
1863−produces null, that means the resource is currently unavailable, so we block on
1934+function produces null, that means the resource is currently
1864−it. If it produces `[~ ~]`, that means our resource is permanently unavailable,
1935+unavailable, so we block on it. If it produces `[~ ~]`, that means our
1865−so we produce an error. Otherwise, we produce the value there with a type of
1936+resource is permanently unavailable, so we produce an error. Otherwise,
1866−either a cell of two nouns or an atom, depending on whether the value is a cell
1937+we produce the value there with a type of either a cell of two nouns or
1867−or not.
1938+an atom, depending on whether the value is a cell or not.
1869−Back in `++lima`, recall that we call `++lion` to find a translation path.
1940+Back in `++lima`, recall that we call `++lion` to find a translation
1871 ++ lion :: translation search
1943 ++ lion :: translation search
1872 |= [cof=cafe too=@tas bek=beak fro=(list ,@tas)]
1944 |= [cof=cafe too=@tas bek=beak fro=(list ,@tas)]
@@ -1901,38 +1973,41 @@ Back in `++lima`, recall that we call `++lion` to find a translation path.
1901 (fine cof ?~(ked ~ [~ for u.ked]))
1973 (fine cof ?~(ked ~ [~ for u.ked]))
1904−At a high level, we have `++apex` and `++apse`. `++apex` takes a list of marks
1976+At a high level, we have `++apex` and `++apse`. `++apex` takes a list of
1905−to try in succession until we find one that can be translated into the target
1977+marks to try in succession until we find one that can be translated into
1906−mark. On each one, it calls `++apse`, which takes a single mark and tries to
1978+the target mark. On each one, it calls `++apse`, which takes a single
1907−find a translation path from this mark to the target. To do this, it sees which
1979+mark and tries to find a translation path from this mark to the target.
1908−marks we know how to directly translate to, and calls `++apex` on this list. The
1980+To do this, it sees which marks we know how to directly translate to,
1909−result of this mututal recursion is a depth-first search of the translation
1981+and calls `++apex` on this list. The result of this mututal recursion is
1910−graph to find the target mark. Since the translation graph is not necessarily
1982+a depth-first search of the translation graph to find the target mark.
1911−acyclic, we maintain a set of marks that we've already tried.
1983+Since the translation graph is not necessarily acyclic, we maintain a
1984+set of marks that we've already tried.
1913−We kick off our search in `++apex`, starting with the given initial list of
1986+We kick off our search in `++apex`, starting with the given initial list
1914−marks that we know how to get to.
1987+of marks that we know how to get to.
1916−If `++apex` is called with a bolt other than a `%0` value bolt, we simply
1989+If `++apex` is called with a bolt other than a `%0` value bolt, we
1917−produce it. Otherwise, we check to see if the list of available marks to
1990+simply produce it. Otherwise, we check to see if the list of available
1918−investigate is null. If so, then we're done, so we produce a `%0` bolt with a
1991+marks to investigate is null. If so, then we're done, so we produce a
1919−null list of accessible marks.
1992+`%0` bolt with a null list of accessible marks.
1921Otherwise, we process this next mark with `++apse`, which will produce a
1994Otherwise, we process this next mark with `++apse`, which will produce a
1922−possible list of marks from this one to the target mark. If it fails to produce
1995+possible list of marks from this one to the target mark. If it fails to
1923−a `%0` bolt, we just produce that. Otherwise, if it produces null, we can't get
1996+produce a `%0` bolt, we just produce that. Otherwise, if it produces
1924−to our target through this mark, so we move on to the next one.
1997+null, we can't get to our target through this mark, so we move on to the
1926−If it doesn't produce null, then we have successfully found a translation path,
2000+If it doesn't produce null, then we have successfully found a
1927−so we produce it.
2001+translation path, so we produce it.
1929−In `++apse`, we first test to see if we've arrived at the target path. If so,
2003+In `++apse`, we first test to see if we've arrived at the target path.
1930−we're done, so we produce a list including just ourself. Otherwise, we check to
2004+If so, we're done, so we produce a list including just ourself.
1931−see if we've already tried this mark. If so, we know we can't succeed here, so
2005+Otherwise, we check to see if we've already tried this mark. If so, we
1932−we produce null. Otherwise, we put ourselves in the set of already-tried marks,
2006+know we can't succeed here, so we produce null. Otherwise, we put
1933−and we move on.
2007+ourselves in the set of already-tried marks, and we move on.
1935−We call `++lily` to get the list of marks we can translate this one into.
2009+We call `++lily` to get the list of marks we can translate this one
1937 ++ lily :: translation targets
2012 ++ lily :: translation targets
1938 |= [cof=cafe for=mark bek=beak]
2013 |= [cof=cafe for=mark bek=beak]
@@ -1951,27 +2026,29 @@ We call `++lily` to get the list of marks we can translate this one into.
1951 =+ gow=(slap vax [%cnzy %grow])
2026 =+ gow=(slap vax [%cnzy %grow])
1952 (sloe p.gow)
2027 (sloe p.gow)
1954−We call `++fang` to get the mark definition door. This is documented under
2029+We call `++fang` to get the mark definition door. This is documented
1955−`%vale`. If getting the mark fails, we produce null because we can't translate a
2030+under `%vale`. If getting the mark fails, we produce null because we
1956−non-existent mark into anything.
2031+can't translate a non-existent mark into anything.
1958−Otherwise, we examine the door. The door may have a `++garb`, which is simply a
2033+Otherwise, we examine the door. The door may have a `++garb`, which is
1959−list of marks which know how to translate from the current one. There must be a
2034+simply a list of marks which know how to translate from the current one.
1960−corresponding `++grab` in the definition of the other mark, though we don't
2035+There must be a corresponding `++grab` in the definition of the other
1961−check that here.
2036+mark, though we don't check that here.
1963−The door may also have a `++grow`, which defines how to translate this mark into
2038+The door may also have a `++grow`, which defines how to translate this
1964−another one. Each arm in `++grow` is the name of a mark we can translate into.
2039+mark into another one. Each arm in `++grow` is the name of a mark we can
1965−The call to `++sloe` simply produces a list of arm names in `++grow`.
2040+translate into. The call to `++sloe` simply produces a list of arm names
1967−Back in `++apse:lion`, we take the list of translation targets we just found and
2043+Back in `++apse:lion`, we take the list of translation targets we just
1968−call `++apex` on it. If we got back a null, we produce a null; otherwise, we
2044+found and call `++apex` on it. If we got back a null, we produce a null;
1969−produce the list of marks we got back plus the current mark.
2045+otherwise, we produce the list of marks we got back plus the current
1971This concludes our discussion of `++lion`.
2048This concludes our discussion of `++lion`.
1973−The final piece of `++lima` is `++lope`, which performs the actual translation
2050+The final piece of `++lima` is `++lope`, which performs the actual
1974−along the path we just computed.
2051+translation along the path we just computed.
1976 ++ lope :: translation pipe
2053 ++ lope :: translation pipe
1977 |= [cof=cafe for=mark yaw=(list mark) bek=beak vax=vase]
2054 |= [cof=cafe for=mark yaw=(list mark) bek=beak vax=vase]
@@ -1981,12 +2058,14 @@ along the path we just computed.
1981 |= [cof=cafe yed=vase]
2058 |= [cof=cafe yed=vase]
1982 ^$(cof cof, for i.yaw, yaw t.yaw, vax yed)
2059 ^$(cof cof, for i.yaw, yaw t.yaw, vax yed)
1984−We iterate through our list, calling `++link` on every adjacent pair of marks,
2061+We iterate through our list, calling `++link` on every adjacent pair of
1985−translating from one mark to the next until we finish the list of marks. A call
2062+marks, translating from one mark to the next until we finish the list of
1986−to `++link` is equivalent to a `%cast` silk, so we document it there. After
2063+marks. A call to `++link` is equivalent to a `%cast` silk, so we
1987−we've called performed every step in the translation pipeline, we're done.
2064+document it there. After we've called performed every step in the
2065+translation pipeline, we're done.
1989−## Lifecycle of a `%boil`
2067+Lifecycle of a `%boil`
2068+----------------------
1992 %+ cool |.(leaf/"ford: boil {<p.kas>} {<(tope q.kas)>} {<r.kas>}")
2071 %+ cool |.(leaf/"ford: boil {<p.kas>} {<(tope q.kas)>} {<r.kas>}")
@@ -1996,13 +2075,13 @@ we've called performed every step in the translation pipeline, we're done.
1996 |= [cof=cafe vax=vase]
2075 |= [cof=cafe vax=vase]
1997 (fine cof `cage`[p.kas vax])
2076 (fine cof `cage`[p.kas vax])
1999−At a high level, we try to bake at the given beam, and if it fails, we go up a
2078+At a high level, we try to bake at the given beam, and if it fails, we
2000−level and try again. This is the usual semantics of ford, and this should nearly
2079+go up a level and try again. This is the usual semantics of ford, and
2001−always be preferred over directly baking.
2080+this should nearly always be preferred over directly baking.
2003−First, we normalize the version case to a number with `++lamp`. This allows
2082+First, we normalize the version case to a number with `++lamp`. This
2004−caching to be based on revision number rather than something more ephemeral like
2083+allows caching to be based on revision number rather than something more
2005−a particular time.
2084+ephemeral like a particular time.
2007 ++ lamp :: normalize version
2086 ++ lamp :: normalize version
2008 |= [cof=cafe bem=beam]
2087 |= [cof=cafe bem=beam]
@@ -2011,10 +2090,11 @@ a particular time.
2011 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
2090 ?~ von [p=cof q=[%1 [bem ~] ~ ~]]
2012 (fine cof bem(r [%ud ((hard ,@) (need u.von))]))
2091 (fine cof bem(r [%ud ((hard ,@) (need u.von))]))
2014−We call the sky function with `%cw`, asking clay for the revision number at this
2093+We call the sky function with `%cw`, asking clay for the revision number
2015−case. If the case refers to a revision that isn't there yet, we produce a `%1`
2094+at this case. If the case refers to a revision that isn't there yet, we
2016−blocking bolt. Otherwise, we require that the value exist and that it's a
2095+produce a `%1` blocking bolt. Otherwise, we require that the value exist
2017−number, both of which are guaranteed by clay. We produce this number.
2096+and that it's a number, both of which are guaranteed by clay. We produce
2019Next for `%boil` we call `++lime` to try to load the beam.
2099Next for `%boil` we call `++lime` to try to load the beam.
@@ -2029,13 +2109,14 @@ Next for `%boil` we call `++lime` to try to load the beam.
2029 (flaw cof (smyt (tope bem)) ~)
2109 (flaw cof (smyt (tope bem)) ~)
2030 ^$(s.mob t.s.mob, mer [i.s.mob mer])
2110 ^$(s.mob t.s.mob, mer [i.s.mob mer])
2032−We start at the given beam and try to bake it. If it succeeds, we're good.
2112+We start at the given beam and try to bake it. If it succeeds, we're
2033−Otherwise, we pop off the top level of the path and put it in our heel (virtual
2113+good. Otherwise, we pop off the top level of the path and put it in our
2034−path extension). We do this recursively until either we find something we can
2114+heel (virtual path extension). We do this recursively until either we
2035−bake or we've gone all the way up to the root path of the desk, in which case we
2115+find something we can bake or we've gone all the way up to the root path
2036−fail.
2116+of the desk, in which case we fail.
2038−## Lifecycle of a `%call`
2118+Lifecycle of a `%call`
2119+----------------------
2041 %+ cool |.(leaf/"ford: call {<`@p`(mug kas)>}")
2122 %+ cool |.(leaf/"ford: call {<`@p`(mug kas)>}")
@@ -2053,13 +2134,15 @@ fail.
2053 (fine cof %noun vax)
2134 (fine cof %noun vax)
2056−This is slam for silks. We process both of the given silks in parallel with
2137+This is slam for silks. We process both of the given silks in parallel
2057−`++coax`. We then slam the two produced vases together with `++maul` and mark
2138+with `++coax`. We then slam the two produced vases together with
2058−the produced vase with `%noun` since we don't know any more specific mark.
2139+`++maul` and mark the produced vase with `%noun` since we don't know any
2060`++coax` is documented under Lifecycle of a Cell.
2142`++coax` is documented under Lifecycle of a Cell.
2062−## Lifecycle of a `%cast`
2144+Lifecycle of a `%cast`
2145+----------------------
2065 %+ cool |.(leaf/"ford: cast {<p.kas>}")
2148 %+ cool |.(leaf/"ford: cast {<p.kas>}")
@@ -2069,11 +2152,11 @@ the produced vase with `%noun` since we don't know any more specific mark.
2069 |= [cof=cafe vax=vase]
2152 |= [cof=cafe vax=vase]
2070 (fine cof [p.kas vax])
2153 (fine cof [p.kas vax])
2072−This is a request to convert data of one mark to another mark directly. We
2155+This is a request to convert data of one mark to another mark directly.
2073−evaluate the given silk and pass the result into `++link`, which performs the
2156+We evaluate the given silk and pass the result into `++link`, which
2074−actual translation. Note that this will not search for indirect conversion
2157+performs the actual translation. Note that this will not search for
2075−paths, so the conversion must be defined either in the `++grow` of the given
2158+indirect conversion paths, so the conversion must be defined either in
2076−mark or the `++grab` of the target mark.
2159+the `++grow` of the given mark or the `++grab` of the target mark.
2078 ++ link :: translate
2161 ++ link :: translate
2079 |= [cof=cafe too=mark for=mark bek=beak vax=vase]
2162 |= [cof=cafe too=mark for=mark bek=beak vax=vase]
@@ -2098,28 +2181,29 @@ mark or the `++grab` of the target mark.
2098 (flaw cof [%leaf "ford: no link: {<[for too]>}"]~)
2181 (flaw cof [%leaf "ford: no link: {<[for too]>}"]~)
2099 (maul cof u.zat vax)
2182 (maul cof u.zat vax)
2101−This performs one step in the translation pipeline. If the given and target
2184+This performs one step in the translation pipeline. If the given and
2102−marks are the same, we're done. If we're translating from a noun or the empty
2185+target marks are the same, we're done. If we're translating from a noun
2103−mark, we coerce with `++lake` (documented in `%vale`). Otherwise, we're
2186+or the empty mark, we coerce with `++lake` (documented in `%vale`).
2104−translating from a user-defined mark.
2187+Otherwise, we're translating from a user-defined mark.
2106−We load the definition of the given mark with `++fang`, and we check to see if
2189+We load the definition of the given mark with `++fang`, and we check to
2107−it has an arm in `++grow` named the target mark. If so, we place our data in the
2190+see if it has an arm in `++grow` named the target mark. If so, we place
2108−sample of the door with `++keel` and slap the arm. `++keel` is equivalent to a
2191+our data in the sample of the door with `++keel` and slap the arm.
2109−`%mute` silk, so we document it there.
2192+`++keel` is equivalent to a `%mute` silk, so we document it there.
2111−If there is no arm in `++grow` of the given mark named the target mark, we
2194+If there is no arm in `++grow` of the given mark named the target mark,
2112−suppose there must be an arm in `++grab` of the target mark named the given
2195+we suppose there must be an arm in `++grab` of the target mark named the
2113−mark. We get the definition of the target mark and check to see if it has the
2196+given mark. We get the definition of the target mark and check to see if
2114−required arm, failing if it doesn't. Finally, we slam the data against the
2197+it has the required arm, failing if it doesn't. Finally, we slam the
2115−correct arm, producing the translated data.
2198+data against the correct arm, producing the translated data.
2117If you're confused as to why the handling of `++grow` and `++grab` look
2200If you're confused as to why the handling of `++grow` and `++grab` look
2118−superficially so different, remember that the correct arm in `++grow` does not
2201+superficially so different, remember that the correct arm in `++grow`
2119−have a sample while the one in `++grab` does. This means they must be called
2202+does not have a sample while the one in `++grab` does. This means they
2120−rather differently.
2203+must be called rather differently.
2122−## Lifecycle of a `%diff`
2205+Lifecycle of a `%diff`
2206+----------------------
2125 %+ cool |.(leaf/"ford: diff {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
2209 %+ cool |.(leaf/"ford: diff {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
@@ -2144,7 +2228,8 @@ First, we process the two given silks to get our arguments.
2144 %+ flaw cof :_ ~
2228 %+ flaw cof :_ ~
2145 leaf/"diff on data of different marks: {(trip p.cay)} {(trip p.coy)}"
2229 leaf/"diff on data of different marks: {(trip p.cay)} {(trip p.coy)}"
2147−If the two cages have different marks, then we can't diff them, so we complain.
2231+If the two cages have different marks, then we can't diff them, so we
2149 %+ cope (fang cof p.cay [our %main %da now])
2234 %+ cope (fang cof p.cay [our %main %da now])
2150 |= [cof=cafe pro=vase]
2235 |= [cof=cafe pro=vase]
@@ -2162,11 +2247,12 @@ We pull in the relevant mark's definition.
2162 (flaw cof leaf/"bad ++sted:grad" ~)
2247 (flaw cof leaf/"bad ++sted:grad" ~)
2163 (make cof %diff [%cast u.for kas] [%cast u.for kos])
2248 (make cof %diff [%cast u.for kas] [%cast u.for kos])
2165−If there's no `++grad`, we complain. If there's no `++form:grad`, then we look
2250+If there's no `++grad`, we complain. If there's no `++form:grad`, then
2166−for a `++sted:grad`. If we can't find either, or if `++sted:grad` isn't a term,
2251+we look for a `++sted:grad`. If we can't find either, or if
2167−then we complain. If `++sted:grad` exists and is a term, then it represents the
2252+`++sted:grad` isn't a term, then we complain. If `++sted:grad` exists
2168−mark we should use as a proxy to get our diff. So, we cast both our given cages
2253+and is a term, then it represents the mark we should use as a proxy to
2169−to the new mark and start the dance again.
2254+get our diff. So, we cast both our given cages to the new mark and start
2171 ?. (slab %diff p.gar)
2257 ?. (slab %diff p.gar)
2172 (flaw cof leaf/"no ++diff:grad" ~)
2258 (flaw cof leaf/"no ++diff:grad" ~)
@@ -2176,7 +2262,8 @@ Otherwise, we expect a `++diff:grad`.
2176 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
2262 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
2177 |= [cof=cafe pox=vase]
2263 |= [cof=cafe pox=vase]
2179−We put the first cage's data into the sample of the given mark's definition.
2265+We put the first cage's data into the sample of the given mark's
2182 %^ maul cof
2269 %^ maul cof
@@ -2192,41 +2279,46 @@ We run `++diff:grad` with a sample of the second cage's data.
2192 (fine cof u.for dif)
2279 (fine cof u.for dif)
2195−We check that `++form:grad` exists, and we tag the result with it to give the
2282+We check that `++form:grad` exists, and we tag the result with it to
2196−final cage.
2283+give the final cage.
2198−## Lifecycle of a `%done`
2285+Lifecycle of a `%done`
2286+----------------------
2200 %done [cof %0 p.kas q.kas]
2288 %done [cof %0 p.kas q.kas]
2202This is trivial. We simply produce the given cage with the given set of
2290This is trivial. We simply produce the given cage with the given set of
2203−dependencies. This is used when we already have a cage that we want to insert
2291+dependencies. This is used when we already have a cage that we want to
2204−into another silk that requires a silk argument. It's analogous to the return
2292+insert into another silk that requires a silk argument. It's analogous
2205−operator in a monad -- which makes it sound way more complicated than it is.
2293+to the return operator in a monad -- which makes it sound way more
2294+complicated than it is.
2207−## Lifecycle of a `%dude`
2296+Lifecycle of a `%dude`
2297+----------------------
2209 %dude (cool |.(p.kas) $(kas q.kas))
2299 %dude (cool |.(p.kas) $(kas q.kas))
2211−This simply puts a given tank on the stack trace if the given silk produces an
2301+This simply puts a given tank on the stack trace if the given silk
2212−error. This is implemented as a simple call to `++cool`.
2302+produces an error. This is implemented as a simple call to `++cool`.
2214−## Lifecycle of a `%dune`
2304+Lifecycle of a `%dune`
2305+----------------------
2217 ?~ q.kas [cof [%2 [%leaf "no data"]~]]
2308 ?~ q.kas [cof [%2 [%leaf "no data"]~]]
2218 $(kas [%done p.kas u.q.kas])
2309 $(kas [%done p.kas u.q.kas])
2220−This is a sort of a `++need` for silks. If there is no data in the unit cage, we
2311+This is a sort of a `++need` for silks. If there is no data in the unit
2221−produce an error. Else, we simply produce the data in the cage.
2312+cage, we produce an error. Else, we simply produce the data in the cage.
2223−## Lifcycle of a `%mute`
2314+Lifcycle of a `%mute`
2315+---------------------
2225 %mute (kale cof p.kas q.kas)
2317 %mute (kale cof p.kas q.kas)
2227−This mutates a silk by putting the values of other silks at particular axes.
2319+This mutates a silk by putting the values of other silks at particular
2228−This is useful in, for example, replacing the sample of the door in a mark
2320+axes. This is useful in, for example, replacing the sample of the door
2229−definition.
2321+in a mark definition.
2231 ++ kale :: mutate
2323 ++ kale :: mutate
2232 |= [cof=cafe kas=silk muy=(list (pair wing silk))]
2324 |= [cof=cafe kas=silk muy=(list (pair wing silk))]
@@ -2246,10 +2338,10 @@ definition.
2246 |= [cof=cafe vax=vase]
2338 |= [cof=cafe vax=vase]
2247 (fine cof p.cay vax)
2339 (fine cof p.cay vax)
2249−First, we process each of the silks by calling `++make` on them. We pass the
2341+First, we process each of the silks by calling `++make` on them. We pass
2250−resultant vase and list of pairs of wings and silks to `++keel` to do the actual
2342+the resultant vase and list of pairs of wings and silks to `++keel` to
2251−mutation. We assume the mutation doesn't change the mark of the main silk, so we
2343+do the actual mutation. We assume the mutation doesn't change the mark
2252−mark the produced vase with the original mark.
2344+of the main silk, so we mark the produced vase with the original mark.
2254 ++ keel :: apply mutations
2346 ++ keel :: apply mutations
2255 |= [cof=cafe suh=vase yom=(list (pair wing vase))]
2347 |= [cof=cafe suh=vase yom=(list (pair wing vase))]
@@ -2267,16 +2359,19 @@ mark the produced vase with the original mark.
2267 :- [p.i.yom [%$ (peg axe 2)]]
2359 :- [p.i.yom [%$ (peg axe 2)]]
2268 $(yom t.yom, axe (peg axe 3))
2360 $(yom t.yom, axe (peg axe 3))
2270−We first put the vases together in one big tuple starting with the subject and
2362+We first put the vases together in one big tuple starting with the
2271−going through the mutations. We slap against this tuple a `%_` twig we directly
2363+subject and going through the mutations. We slap against this tuple a
2272−construct. Since a `%_` twig takes a list of pairs of wings and twigs, we simply
2364+`%_` twig we directly construct. Since a `%_` twig takes a list of pairs
2273−have to generate twigs referring to the correct axes in the subject. This is
2365+of wings and twigs, we simply have to generate twigs referring to the
2274−very easy since we just recur on axis 3 of whatever axis we were already at.
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.
2276−Note the use of `%_` instead of `%=` enforces that our mutations don't change
2369+Note the use of `%_` instead of `%=` enforces that our mutations don't
2277−the type of the subject, which justifies our use of the original mark.
2370+change the type of the subject, which justifies our use of the original
2279−## Lifecycle of a `%pact`
2373+Lifecycle of a `%pact`
2374+----------------------
2282 %+ cool |.(leaf/"ford: pact {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
2377 %+ cool |.(leaf/"ford: pact {<`@p`(mug p.kas)>} {<`@p`(mug q.kas)>}")
@@ -2313,12 +2408,12 @@ We pull in the relevant mark's definition.
2313 (flaw cof leaf/"bad ++sted:grad" ~)
2408 (flaw cof leaf/"bad ++sted:grad" ~)
2314 (make cof %cast p.cay %pact [%cast u.for kas] kos)
2409 (make cof %cast p.cay %pact [%cast u.for kas] kos)
2316−If there's no `++grad`, we complain. If there's no `++form:grad`, then we look
2411+If there's no `++grad`, we complain. If there's no `++form:grad`, then
2317−for a `++sted:grad`. If we can't find either, or if `++sted:grad` isn't a term,
2412+we look for a `++sted:grad`. If we can't find either, or if
2318−then we complain. If `++sted:grad` exists and is a term, then it represents the
2413+`++sted:grad` isn't a term, then we complain. If `++sted:grad` exists
2319−mark we should use as a proxy to get our diff. So, we cast the first argument to
2414+and is a term, then it represents the mark we should use as a proxy to
2320−the new mark, then try to patch. Afterward, we cast the result back to the
2415+get our diff. So, we cast the first argument to the new mark, then try
2321−original mark.
2416+to patch. Afterward, we cast the result back to the original mark.
2323 =+ for=((soft ,@tas) q:(slap gar [%cnzy %form]))
2418 =+ for=((soft ,@tas) q:(slap gar [%cnzy %form]))
@@ -2328,8 +2423,8 @@ original mark.
2328 =< leaf/"pact on data with wrong form: {-} {+<} {+>}"
2423 =< leaf/"pact on data with wrong form: {-} {+<} {+>}"
2329 [(trip p.cay) (trip u.for) (trip p.coy)]
2424 [(trip p.cay) (trip u.for) (trip p.coy)]
2331−If `++form:grad` isn't a term, or else our second argument isn't of that mark,
2426+If `++form:grad` isn't a term, or else our second argument isn't of that
2332−we complain.
2427+mark, we complain.
2334 ?. (slab %pact p.gar)
2429 ?. (slab %pact p.gar)
2335 (flaw cof leaf/"no ++pact:grad" ~)
2430 (flaw cof leaf/"no ++pact:grad" ~)
@@ -2339,7 +2434,8 @@ If we don't have a `++pact:grad`, we complain.
2339 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
2434 %+ cope (keel cof pro [[%& 6]~ q.cay]~)
2340 |= [cof=cafe pox=vase]
2435 |= [cof=cafe pox=vase]
2342−We put the first cage's data into the sample of the given mark's definition.
2437+We put the first cage's data into the sample of the given mark's
2345 %^ maul cof
2441 %^ maul cof
@@ -2347,32 +2443,36 @@ We put the first cage's data into the sample of the given mark's definition.
2348 |= [cof=cafe pat=vase]
2444 |= [cof=cafe pat=vase]
2350−We run `++pact:grad` with a sample of the second cage's data, which is the diff.
2446+We run `++pact:grad` with a sample of the second cage's data, which is
2352 (fine cof p.cay pat)
2449 (fine cof p.cay pat)
2355We tag the result with the mark of our first argument.
2452We tag the result with the mark of our first argument.
2357−## Lifecycle of a `%plan`
2454+Lifecycle of a `%plan`
2455+----------------------
2360 %+ cope (abut:(meow p.kas q.kas) cof r.kas)
2458 %+ cope (abut:(meow p.kas q.kas) cof r.kas)
2361 |= [cof=cafe vax=vase]
2459 |= [cof=cafe vax=vase]
2362 (fine cof %noun vax)
2460 (fine cof %noun vax)
2364−This is a direct request to compile a hood at a given beam with a heel of the
2462+This is a direct request to compile a hood at a given beam with a heel
2365−given path. We comply by calling `++abut` with the given arguments and producing
2463+of the given path. We comply by calling `++abut` with the given
2366−the vase with a mark of `%noun`.
2464+arguments and producing the vase with a mark of `%noun`.
2368−## Lifecycle of a `%reef`
2466+Lifecycle of a `%reef`
2467+----------------------
2370 %reef (fine cof %noun pit)
2469 %reef (fine cof %noun pit)
2372−This is one of the simplest silks. We simply produce our context, which is zuse
2471+This is one of the simplest silks. We simply produce our context, which
2373−compiled against hoon. The mark is a `%noun`.
2472+is zuse compiled against hoon. The mark is a `%noun`.
2375−## Lifcycle of a `%ride`
2474+Lifcycle of a `%ride`
2475+---------------------
2378 %+ cool |.(leaf/"ford: ride {<`@p`(mug kas)>}")
2478 %+ cool |.(leaf/"ford: ride {<`@p`(mug kas)>}")
@@ -2382,11 +2482,12 @@ compiled against hoon. The mark is a `%noun`.
2382 |= [cof=cafe vax=vase]
2482 |= [cof=cafe vax=vase]
2383 (fine cof %noun vax)
2483 (fine cof %noun vax)
2385−This slaps evaluates the given silk, then it slaps the result against the given
2485+This slaps evaluates the given silk, then it slaps the result against
2386−twig. Since we don't know what of what mark (if any) is the result, we give it a
2486+the given twig. Since we don't know what of what mark (if any) is the
2387−mark of `%noun`.
2487+result, we give it a mark of `%noun`.
2389−## Lifecycle of a `%vale`
2489+Lifecycle of a `%vale`
2490+----------------------
2392 %+ cool |.(leaf/"ford: vale {<p.kas>} {<q.kas>} {<`@p`(mug r.kas)>}")
2493 %+ cool |.(leaf/"ford: vale {<p.kas>} {<q.kas>} {<`@p`(mug r.kas)>}")
@@ -2394,20 +2495,20 @@ mark of `%noun`.
2394 |= [cof=cafe vax=vase]
2495 |= [cof=cafe vax=vase]
2395 (fine cof `cage`[p.kas vax])
2496 (fine cof `cage`[p.kas vax])
2397−This checks whether given data is of the given mark. If we don't have the
2498+This checks whether given data is of the given mark. If we don't have
2398−definition of the mark, we check the given ship for it.
2499+the definition of the mark, we check the given ship for it.
2400−We call `++lave` to perform the check, producing a vase. We produce this vase
2501+We call `++lave` to perform the check, producing a vase. We produce this
2401−tagged with the given mark.
2502+vase tagged with the given mark.
2403 ++ lave :: validate
2504 ++ lave :: validate
2404 |= [cof=cafe for=mark his=ship som=*]
2505 |= [cof=cafe for=mark his=ship som=*]
2405 ^- (bolt vase)
2506 ^- (bolt vase)
2406 ((lake for [our %main [%da now]]) cof [%noun som])
2507 ((lake for [our %main [%da now]]) cof [%noun som])
2408−This is a thinly-veiled wrapper over `++lake`. Note that, contrary to documented
2509+This is a thinly-veiled wrapper over `++lake`. Note that, contrary to
2409−opinion, we do not in fact check the other ship's definition of a mark. This is
2510+documented opinion, we do not in fact check the other ship's definition
2410−likely a bug.
2511+of a mark. This is likely a bug.
2412At any rate, `++lake` coerces a noun into the correct type for a mark.
2513At any rate, `++lake` coerces a noun into the correct type for a mark.
@@ -2435,24 +2536,27 @@ At any rate, `++lake` coerces a noun into the correct type for a mark.
2435 (fine cof (slot 6 pro))
2536 (fine cof (slot 6 pro))
2436 (flaw cof [%leaf "ford: invalid content: {<[for bek]>}"]~)
2537 (flaw cof [%leaf "ford: invalid content: {<[for bek]>}"]~)
2438−This is going to coerce the sample into the correct type for the mark. First, we
2539+This is going to coerce the sample into the correct type for the mark.
2439−push a line onto the stack trace saying that we're checking the type. If the
2540+First, we push a line onto the stack trace saying that we're checking
2440−requested mark is a gate, core, door, hoon, or hook, then we don't do any more
2541+the type. If the requested mark is a gate, core, door, hoon, or hook,
2441−type information than just saying it's a noun, so we're done.
2542+then we don't do any more type information than just saying it's a noun,
2443−Otherwise, we get the mark definition from our `/=main=/mar` directory with
2545+Otherwise, we get the mark definition from our `/=main=/mar` directory
2444−`++fang`, which we'll describe below.
2546+with `++fang`, which we'll describe below.
2446−We check to see if our sample type nests within the type of the sample to the
2548+We check to see if our sample type nests within the type of the sample
2447−door. If so, then we're already of the correct type, so we're done.
2549+to the door. If so, then we're already of the correct type, so we're
2449−Otherwise, we check to see if there's a `++grab` in the door, and a `++noun` in
2552+Otherwise, we check to see if there's a `++grab` in the door, and a
2450−the `++grab`. If not, there's no way we can translate to this mark, so we fail.
2553+`++noun` in the `++grab`. If not, there's no way we can translate to
2554+this mark, so we fail.
2452−If we have everything we need, we slam our sample (typed as a noun) against the
2556+If we have everything we need, we slam our sample (typed as a noun)
2453−`++noun` in `++grab`. If the sample of the door is the same as our sample, then
2557+against the `++noun` in `++grab`. If the sample of the door is the same
2454−the check succeeded, so we produce the well-typed sample of the door. Otherwise,
2558+as our sample, then the check succeeded, so we produce the well-typed
2455−we fail.
2559+sample of the door. Otherwise, we fail.
2457 ++ fang :: protocol door
2561 ++ fang :: protocol door
2458 |= [cof=cafe for=mark bek=beak]
2562 |= [cof=cafe for=mark bek=beak]
@@ -2467,6 +2571,6 @@ we fail.
2467 (cope (fade cof %hook bem) abut:(meow bem ~))
2571 (cope (fade cof %hook bem) abut:(meow bem ~))
2469A mark's definition is generally in
2573A mark's definition is generally in
2470−`/=main=/mar/[mark-name]/door/hook'. If we don't find it there, we look in`/\[given-beak\]/mar/\[mark-name\]/door/hook'.
2574+`/=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`.
2575+We parse the mark definition with `++fade` and assemble it with
2472−`++fade` is defined under the `%bake` silk.
2576+`++abut:meow`. `++fade` is defined under the `%bake` silk.