Merge branch 'master' of https://github.com/urbit/urbit

arvo/ames.hoon

@@ -439,7 +439,7 @@
             vix=(bex +((cut 0 [25 2] mag)))             ::  width of sender
             tay=(cut 0 [27 5] mag)                      ::  message type
         ==
-    ?>  =(0 vez)
+    ?>  =(1 vez)
     ?>  =(chk (end 0 20 (mug bod)))
     :+  [(end 3 wix bod) (cut 3 [wix vix] bod)]
       (kins tay)
@@ -459,7 +459,7 @@
     =+  tay=(ksin q.kec)
     %+  mix
       %+  can  0
-      :~  [0 7]
+      :~  [3 1]
           [20 (mug bod)]
           [2 yax]
           [2 qax]
@@ -1047,7 +1047,7 @@
     ++  gnaw                                            ::    gnaw:am
       |=  [kay=cape ryn=lane pac=rock]                  ::  process packet
       ^-  [p=(list boon) q=fort]
-      ?.  =(0 (end 0 3 pac))  [~ fox]
+      ?.  =(1 (end 0 3 pac))  [~ fox]
       =+  kec=(bite pac)
       ?:  (goop p.p.kec)  [~ fox]
       ?.  (~(has by urb.ton.fox) q.p.kec)

arvo/ford.hoon

@@ -390,10 +390,10 @@
       %_(+> mow :_(mow [hen %give gef]))
     ::
     ++  fade                                            ::  compile to hood
-      |=  [cof=cafe bem=beam]
+      |=  [cof=cafe for=mark bem=beam]
       ^-  (bolt hood)
       %+  cool  |.(leaf/"ford: fade {<[(tope bem)]>}")
-      %+  cope  (make cof [%bake %hoon bem ~])
+      %+  cope  (make cof [%bake for bem ~])
       |=  [cof=cafe cay=cage]
       %+  (clef %hood)  (fine cof bem(r [%ud 0]) cay)
       ^-  (burg (pair beam cage) hood)
@@ -416,11 +416,13 @@
           =+  oak=[our %main %da now]
           ?.  =(~ (ska %cy (tope [oak pax])))  oak
           bek
-      (cope (fade cof bem) abut:(meow bem ~))
+      (cope (fade cof %hook bem) abut:(meow bem ~))
     ::
     ++  fair                                            ::  hood parsing rule
       |=  bem=beam
-      =+  vez=(vang | (tope bem(r [%ud 0])))
+      =+  :*  vez=(vang | (tope bem(r [%ud 0])))
+              voz=(vang | (tope bem))
+          == 
       =<  hood
       |%  
       ++  case
@@ -430,8 +432,8 @@
         ?.  ?=([%$ ?(%da %ud %tas) *] a)  ~
         [~ u=(^case a)]
       ::
-      ++  hath  (cook plex:vez (stag %clsg poor:vez))   ::  hood path
-      ++  have  (sear tome hath)                        ::  hood beam
+      ++  hath  (cook plex:voz (stag %clsg poor:voz))   ::  hood path
+      ++  have  (sear tome ;~(pfix fas hath))           ::  hood beam
       ++  hood
         %+  ifix  [gay gay]
         ;~  plug
@@ -473,7 +475,7 @@
       ::
       ++  hoop
         ;~  pose
-          (stag %| ;~(pfix fas have))
+          (stag %| ;~(pfix ;~(plug fas fas gap) have))
           (stag %& tall:vez)
         ==
       ::
@@ -613,8 +615,8 @@
       |=  [cof=cafe arc=arch]
       ?^  q.arc
         (cope (cope (liar cof bem) (lake for bek)) fest)
-      ?:  (~(has by r.arc) %hoon)
-        %+  cope  (fade cof bem)
+      ?:  (~(has by r.arc) %hook)
+        %+  cope  (fade cof %hook bem)
         |=  [cof=cafe hyd=hood]
         (cope (cope (abut:(meow bem arg) cof hyd) (lake for bek)) fest)
       (fine cof ~)
@@ -624,7 +626,7 @@
       |=  [cof=cafe sam=vase]
       ^-  (bolt vase)
       %+  cool  |.(leaf/"ford: check {<[for bek `@p`(mug q.sam)]>}")
-      ?:  ?=(?(%gate %core %door %hoon %hook %hood) for)
+      ?:  ?=(?(%gate %core %door %hoon %hook) for)
         ::  ~&  [%lake-easy for bek]
         (fine cof sam)
       %+  cope  (fang cof for bek)
@@ -1065,7 +1067,7 @@
             (flaw cof [%leaf "structure mismatch: {<~[p.u.byf q.i.bir]>}"]~)
           $(bir t.bir)
         =+  bem=(hone ?:(p.i.bir %gate %core) %sur q.i.bir)
-        %+  cope  (fade cof bem)
+        %+  cope  (fade cof %hook bem)
         |=  [cof=cafe hyd=hood]
         %+  cope  (apex(boy ~) cof hyd)
         |=  [cof=cafe sel=_..head]
@@ -1101,7 +1103,7 @@
             (flaw cof [%leaf "library mismatch: {<~[p.u.byf i.bir]>}"]~)
           $(bir t.bir)
         =+  bem=(hone %core %lib i.bir)
-        %+  cope  (fade cof bem)
+        %+  cope  (fade cof %hook bem)
         |=  [cof=cafe hyd=hood]
         %+  cope  (apex(zeg goz, boy ~) cof hyd)
         |=  [cof=cafe sel=_..neck]
@@ -1116,13 +1118,15 @@
       ++  wilt                                          ::  process body entry
         |=  [cof=cafe hop=hoop]
         ^-  (bolt _..wilt)
+        ~&  [%wilt hop]
         ?-    -.hop
             %&  (fine cof ..wilt(boy [p.hop boy]))
             %| 
+          %+  cool  |.(leaf/"ford: wilt {<[(tope p.hop)]>}")
           %+  cope  (lend cof p.hop)
           |=  [cof=cafe arc=arch]
           ?:  (~(has by r.arc) %hoon)
-            %+  cope  (fade cof p.hop)
+            %+  cope  (fade cof %hoon p.hop)
             |=  [cof=cafe hyd=hood]
             %+  cope  (apex(boy ~) cof hyd)
             |=  [cof=cafe sel=_..wilt]
@@ -1136,6 +1140,7 @@
             %+  cope  ^$(all r.all, cof cof, sel sel)
             |=  [cof=cafe rig=(map term foot) sel=_..wilt]
             %+  cope  
+              ~&  [%wilt-cope (tope p.hop(s [p.n.all s.p.hop]))]
               %=    ^^^^$
                   cof      cof
                   ..wilt   sel(boy ~)

main/mac/mime/door.hook

@@ -0,0 +1,13 @@
+::
+::::  /hoon/core/mime/pro
+  ::
+/?  314
+|_  own=[p=mite q=octs]
+++  grab
+  |% 
+  ++  noun                                              ::  convert from %noun
+    |=  src=*
+    ^+  +>+
+    +>+(own (,[mite octs] src))
+  --
+--

main/pub/src/doc/ref/nock.md

@@ -607,12 +607,33 @@ original **subject** and the new variable.
 
     35 ::    *[a 9 b c]       *[a 7 c 2 [0 1] 0 b]
 
+**Operator 9** takes a **subject** and produces a new **subject** containing both code and data, also known as a **core**. A formula is then both extracted from, and applied to this new **core** **subject**. As its breakdown demonstrates, **Operator 9** is a macro that can compose recursive functions, as it encapsulates the functionality of both **Operator 7**(function composition) and **Operator 2** (recursion).
 
+The reduced pseudo code demonstrates this clearly:
+
+    *[*[a c] *[*[a c] 0 b]]
+
+Here, `c` is some formula that produces a **core** when applied to **subject** `a`. This new **core** is then paired with a formula extracted from **axis** `b` within an identical copy of the new **core**. In higher-level languages that compile to Nock, functions that loop recursively often generate **Operator 9**, as it is the easiest way for a function (or **gate**, to use proper Hoon technology) to recall itself with changes made to its data.  
+
+ 
 ##Op 10: Hint
 
     36 ::    *[a 10 [b c] d]  *[a 8 c 7 [0 3] d]
     37 ::    *[a 10 b c]      *[a c]
 
+**Operator 10** serves as a hint to the interpreter.
+
+As shown above, there are two cases of **Operator 10**. The latter has the formula `[10 b c]`, which then simply reduces to `c`. Although `[10 b c]` has to be semantically equivalent to `c`, it doesn't have to be practically equivalent. Since whatever information in `b` is discarded, a practical interpreter is free to ignore it, or to use it as a hint, as long as it does not affect the results of the computation.
+
+The former case is slightly more complicated. While it may appear that its reduction `*[*[[*[a c] a] 0 3] d]` could be reduced further to simply `[a d]`, as `*[[*[a c] a] 0 3]` could seem to return just `a`. However, there is a possibility that `c` does not terminate, in which case `[a d]` would be incorrect. Therefore, `*[*[[*[a c] a] 0 3] d]` is the most this case can be reduced. This is because **Operator 10** in either case is a hint. If `x` in `[10 x y]` is an atom, we reduce line 37 and `x` is simply discarded. Otherwise, `x` is a cell `[b c]`; b is discarded, but c is computed as a formula and its result is discarded.
+
+Effectively, this mechanism lets us feed both static and dynamic information into the interpreter's hint mechanism.  
+
+
+
+
+
+
 ##Crash default
 
     39 ::    *a               *a

main/pub/src/doc/ref/vol0.md

@@ -7,10 +7,26 @@ volume 0, Kelvin Versioning
 
 Declares the current Hoon version number in degrees Kelvin.
 
-In Kelvin versioning -the true Martian way to permanently freeze a
-system- releases count down by integer degrees Kelvin. At absolute
-zero, the system can no longer be changed.  At 1K, one more
-modification is possible. And so on. 
+
+When normal people release normal software, they count by fractions, and they
+count up. Thus, they can keep extending and revising their systems
+incrementally. This is generally considered a good thing. It generally is.
+
+In some cases, however, specifications needs to be permanently frozen. This
+requirement is generally found in the context of standards. Some standards are
+extensible or versionable, but some are not. ASCII, for instance, is
+perma-frozen. So is IPv4 (its relationship to IPv6 is little more than nominal
+- if they were really the same protocol, they'd have the same ethertype).
+Moreover, many standards render themselves incompatible in practice through
+excessive enthusiasm for extensibility. They may not be perma-frozen, but they
+probably should be.
+
+The true, Martian way to perma-freeze a system is what I call Kelvin
+versioning. In Kelvin versioning, releases count down by integer degrees
+Kelvin. At absolute zero, the system can no longer be changed. At 1K, one more
+modification is possible. And so on. For instance, Nock is at 5K. It might
+change, though it probably won't. Nouns themselves are at 0K - it is impossible
+to imagine changing anything about their three sentence definition.
 
 ---
 
@@ -18,6 +34,7 @@ modification is possible. And so on.
 ~zod/try=> stub
 164
 ```
+
 ---
 
 

main/pub/src/doc/ref/vol1.md

@@ -1,5 +1,5 @@
 volume 1, Hoon Structures
-========================
+=======================
 
 XX Introduction/overview of structures goes here.
 
@@ -98,6 +98,16 @@ Atom with odor [#type]. A @tD is a single Unicode byte.
 
 ---
 
+###chub
+
+++  chub                                                ::  registered battery
+          $:  p=(pair chum tyre)                        ::  definition
+              q=*                                       ::  battery
+              r=(unit (pair axis chub))                 ::  parent
+          ==   
+
+---
+
 ###chum
 
     ++  chum  $?  lef=term                                  ::  jet name
@@ -118,84 +128,224 @@ A %fern of the following cases:
 
 ---
 
-++  claw  
-    XX  unused?
+###claw
 
-++  coat  
-++  coil  
-++  coin  
+    ++  claw  
+        XX  unused?
+
+---
+
+###clue
+
+    ++  clue  ,[p=axis q=chum r=tyre]                       ::  battery definition
+
+---
+
+###coat  
+
+    ++  coat  ,[p=path q=vase]                              ::
+
+---
+
+###coil  
+
+    ++  coil  $:  p=?(%gold %iron %lead %zinc)              ::
+                  q=type                                    ::
+                  r=[p=?(~ ^) q=(map term foot)]            ::
+              ==                                            ::
+
+---
+
+###coin  
+
+    ++  coin  $%  [%$ p=dime]                               ::
+                  [%blob p=*]                               ::
+                  [%many p=(list coin)]                     ::
+              ==                                            ::
+
+---
+
+
+###cord  
+
+    ++  cord  ,@t                                           ::  text atom (UTF-8)
+
+One of Hoon's two string types (the other being ++tape). A cord is an
+atom of UTF-8 text.
+
+Atom with odor. @t is a Unicode atom. The order of bytes in a @t are
+little-endian, i.e. the first character in the text is the low byte of
+the atom.
 
-++  cord  
-    One of Hoon's two string types (the other being ++tape). A cord is an
-    atom of UTF-8 text.
-    ---
-    Atom with odor. @t is a Unicode atom. The order of bytes in a @t are
-    little-endian, i.e. the first character in the text is the low byte of
-    the atom.
-    ---
     ~zod/try=> `@ux`'foobar'
     0x7261.626f.6f66
-    ---
 
-++  date  
-    A point in time. 
-    ---
-    A loobean designating AD or BC, a year atom, a month atom, and a ++tarp
-    , which is a day atom and a time.
-    ---
-    ++yell produces a ++date from a @da (a date atom)
+---
+
+###date  
+
+    ++  date  ,[[a=? y=@ud] m=@ud t=tarp]                   ::  parsed date
+
+A point in time. 
+
+A loobean designating AD or BC, a year atom, a month atom, and a ++tarp, which
+is a day atom and a time.
+
+++yell produces a ++date from a @da (a date atom)
 
     ~zod/try=> (yell ~2014.6.6..21.09.15..0a16)
     [d=106.751.991.820.172 h=21 m=9 s=15 f=~[0xa16]]
-    ---
 
-++  dime  
-++  dram 
-    The structure of a unix filesystem tree.
-    ---
-    One of two cases: 
-    | a directory - a map of names to deeper tree structures.
-    % a file - a numbered atom of data.
-    ---
-    Cards %dire and %pour in zuse require a ++dram argument to target.
-    ---
-++  each  
-++  edge  
-++  foot  
-++  gear  
-++  hair  
-++  hapt  
-++  like  
-++  limb  
-++  line  
-++  list  
-++  mane  
-++  mano  
-++  manx  
-++  marl  
-++  mars  
-++  mart  
-++  marx  
-++  metl  
-++  null  
-++  odor  
-++  tarp  
-++  time  
-++  tree  
-++  nail  
-++  numb  
-++  pair  
-++  pass  
-++  path  
-++  pint  
-++  port  
-++  post  
-++  prop  
-++  qual  
-++  rege  
-++  ring  
-++  rule  
-++  span
+---
+
+###dime  
+
+    ++  dime  ,[p=@ta q=@]                                  ::
+
+---
+
+### dram 
+
+    ++  dram  $%  [| p=(map ,@tas dram)]                    ::  simple unix dir
+                  [& p=@ud q=@]                             ::
+
+The structure of a unix filesystem tree.
+
+One of two cases: 
+
+- `|` a directory - a map of names to deeper tree structures.
+- `&` a file - a numbered atom of data.
+
+Cards %dire and %pour in zuse require a ++dram argument to target.
+
+---
+
+###each  
+
+    ++  each  |*([a=$+(* *) b=$+(* *)] $%([& p=a] [| p=b])) ::
+
+###edge
+
+    ++  edge  ,[p=hair q=(unit ,[p=* q=nail])]              ::  parsing output
+
+###foot
+
+    ++  foot  $%  [%ash p=twig]                             ::  dry arm, geometric
+                  [%elm p=twig]                             ::  wet arm, generic
+                  [%oak ~]                                  ::  XX not used
+                  [%yew p=(map term foot)]                  ::  XX not used
+              ==                                            ::
+
+###gate
+
+    ++  gate  $+(* *)                                       ::  general gate
+### gear  
+
+    ++  gear  |*  a=_,*                                     ::  XX list generator
+              $_                                            ::
+              =|  b=*                                       ::
+              |?                                            ::
+              ?@  b                                         ::
+                ~                                           ::
+              [i=(a -.b) t=^?(..$(b +.b))]                  ::
+###hair  
+
+    ++  hair  ,[p=@ud q=@ud]                                ::  parsing trace
+
+###hapt  
+
+    ++  hapt  (list ,@ta)                                   ::  XX not used
+
+###like  
+
+    ++  like  |*  a=_,*                                     ::  generic edge
+              |=  b=_`*`[(hair) ~]                          ::
+              :-  p=(hair -.b)                              ::
+              ^=  q                                         ::
+              ?@  +.b  ~                                    ::
+              :-  ~                                         ::
+              u=[p=(a +>-.b) q=[p=(hair -.b) q=(tape +.b)]] ::
+
+###limb  
+
+    ++  limb  $|(term $%([%& p=axis] [%| p=@ud q=term]))    ::
+
+
+###line  
+
+    ++  line  ,[p=[%leaf p=odor q=@] q=tile]                ::  %kelp case
+
+###list  
+
+    ++  list  |*  a=_,*                                     ::  null-term list
+              $|(~ [i=a t=(list a)])                        ::
+
+###lone
+
+    ++  lone  |*(a=$+(* *) ,p=a)                            ::  just one thing
+
+###mane  
+
+    ++  mane  $|(@tas [@tas @tas])                          ::  XML name/space
+
+
+###manx  
+
+  ++  manx  ,[g=marx c=marl]                              ::  XML node
+
+
+###marl  
+
+    ++  marl  (list manx)                                   ::  XML node list
+
+###mars  
+
+    ++  mars  ,[t=[n=%$ a=[i=[n=%$ v=tape] t=~]] c=~]       ::  XML cdata
+
+###mart  
+
+    ++  mart  (list ,[n=mane v=tape])                       ::  XML attributes
+
+###marx  
+
+    ++  marx  ,[n=mane a=mart]                              ::  XML tag
+
+###metl  
+
+    ++  metl  ?(%gold %iron %zinc %lead)                    ::  core variance
+
+###noun
+
+    ++  noun  ,*                                            ::  any noun
+
+###null  
+
+    ++  null  ,~                                            ::  null, nil, etc
+
+###odor  
+
+    ++  odor  ,@ta                                          ::  atom format
+
+###tarp  
+
+    ++  tarp  ,[d=@ud h=@ud m=@ud s=@ud f=(list ,@ux)]      ::  parsed time
+
+###time  
+###tree  
+###nail  
+###numb  
+###pair  
+###pass  
+###path  
+###pint  
+###port  
+###post  
+###prop  
+###qual  
+###rege  
+###ring  
+###rule  
+###span
     A restricted text atom for canonical atom syntaxes. The prefix is `~.`.
     There are no escape sequences except `~~`, which means `~`, and `~-`,
     which means `_`. - and .  encode themselves. No other characters

main/pub/src/doc/synth/down.hood

@@ -1,36 +0,0 @@
-/?  314
-!:
-::::::   /hoon/down/synth/doc
-::
-  =>
-::::::  models
-|%
-++  down
-  $&  [p=down q=down]
-  $%  [%$ p=tape]
-      [%code p=tape]
-      [%inco p=tape]
-      [%head p=@ud q=down]
-      [%link p=tape q=tape r=(unit tape)]
-      [%lord p=(list down)]
-      [%lund p=(list down)]
-      [%parg p=down]
-      [%quot p=down]
-      [%rong p=down]
-      [%emph p=down]
-      [%hrul ~]
-      [%html p=tape]
-  ==
---  
-::::::  generator
-::
-~&  [%hood-at %]
-%-  (fest /synth/doc %)
-|=  pic=epic
-=+  unt=|=(a=cord (biff (~(get by qix.pic) a) |=(b=cord (slaw %ud b))))
-=+  moo=(both (unt %foo) (unt %bar))
-?~  moo  [%$ "Hoop, world: usage: url?foo=x&bar=y"]
-:*  [%$ "Hoop, "]
-    [%emph %$ "world"]
-    [%$ ": {<-.u.moo>} plus {<+.u.moo>} is {<(add u.moo)>}."]
-==

main/pub/src/doc/synth/down.hook

@@ -1,7 +0,0 @@
-!:
-::::::   /hook/down/synth/doc
-::
-%-  (folk /down/synth/doc %)
-|=  [bem=beam but=path]
-:+  %ride  [%reef ~]
-[%drag bem but]

main/pub/src/doc/synth/down.hoon

@@ -1,35 +0,0 @@
-!:
-::::::   /hoon/down/synth/doc
-::
-  =>
-::::::  models
-|%
-++  down
-  $&  [p=down q=down]
-  $%  [%$ p=tape]
-      [%code p=tape]
-      [%inco p=tape]
-      [%head p=@ud q=down]
-      [%link p=tape q=tape r=(unit tape)]
-      [%lord p=(list down)]
-      [%lund p=(list down)]
-      [%parg p=down]
-      [%quot p=down]
-      [%rong p=down]
-      [%emph p=down]
-      [%hrul ~]
-      [%html p=tape]
-  ==
---  
-::::::  generator
-::
-~&  [%choon-at %]
-%-  (fest /synth/doc %)
-|=  pic=epic
-=+  unt=|=(a=cord (biff (~(get by qix.pic) a) |=(b=cord (slaw %ud b))))
-=+  moo=(both (unt %foo) (unt %bar))
-?~  moo  [%$ "Hm, world: usage: url?foo=x&bar=y"]
-:*  [%$ "Hm, "]
-    [%emph %$ "world"]
-    [%$ ": {<-.u.moo>} plus {<+.u.moo>} is {<(add u.moo)>}."]
-==

main/sur/down/gate.hook

@@ -0,0 +1,6 @@
+::
+::::  /hoon/gate/down/sur
+  ::
+/?  314
+/-  *markdown
+down

main/sur/wand/gate.hook

@@ -0,0 +1,6 @@
+::
+::::  /hoon/gate/down/sur
+  ::
+/?  314
+/-  *markdown
+down