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