From 6a5b6c016ee78be9451869e6280c94362ad772c6 Mon Sep 17 00:00:00 2001
From: Henry Ault <henry@tlon.io>
Date: Fri, 19 Feb 2016 13:44:52 -0800
Subject: [PATCH] final transfer

Conflicts:
	app/gmail.hoon
---
 app/gmail.hoon                                |  31 +-
 urb/zod/mar/gmail/req.hoon                    |   8 +
 .../dev/hoon/reference/quickref/quickref.md   | 532 ++++++++++++++++++
 urb/zod/sur/gmail-label.hoon                  |  34 ++
 urb/zod/sur/rfc.hoon                          |  21 +
 5 files changed, 610 insertions(+), 16 deletions(-)
 create mode 100644 urb/zod/mar/gmail/req.hoon
 create mode 100644 urb/zod/pub/docs/dev/hoon/reference/quickref/quickref.md
 create mode 100644 urb/zod/sur/gmail-label.hoon
 create mode 100644 urb/zod/sur/rfc.hoon

diff --git a/app/gmail.hoon b/app/gmail.hoon
index 2f9f09d4da..059299a290 100644
--- a/app/gmail.hoon
+++ b/app/gmail.hoon
@@ -18,9 +18,10 @@
 ::  See the %github app for example usage.
 ::
 /?  314
+/-  rfc, gmail-label
 /+  http
 ::::
-/=  rfc  /:  /%/rfc  /txt/
+/=  rfctext  /:  /%/rfc  /txt/
 ::
 //  /%/split
 ::/-  gmail
@@ -62,7 +63,10 @@
   ==
 ::
 ++  poke-gmail-req
-  |=  {method/meth endpoint/path quy/quay}::jon=(unit json)]
+  |=  $:  method/meth  endpoint/path  quy/quay
+          ::mes/$?(message:rfc )
+          label-req:gmail-label
+      ==
   ^-  {(list move) _+>.$}
   ?>  ?=(valid-get-endpoint endpoint)
   :_  +>.$  :_  ~
@@ -74,14 +78,10 @@
       `quay`[[%alt %json] ~] 
   ::
       :+  method  `math`(malt ~[content-type+['application/json']~])
-      =+  json-data=(joba %raw (jape (sifo (role rfc))))
-      ~&  json-data
-      =+  six-four=(tact (pojo json-data))
-      ~&  sixf+six-four
-      (some six-four)
-      ::?~  jon  ~
-      ::~&  (taco (crip (pojo u.jon)))
-      ::(some (taco (crip (pojo u.jon))))                 ::  have to make it a unit again
+      ::=+  hoon-json-object=(joba %raw s/(message-to-rfc822:rfc mes))
+      ::=+  request-body=(tact (pojo hoon-json-object))
+      ::(some request-body)
+      (some (pojo label-req-to-json:gmail-label label-req:gmail-label ~))
   ==
 ::
 ::  HTTP response.  We make sure the response is good, then
@@ -91,7 +91,6 @@
 ++  sigh-httr
   |=  {wir/wire res/httr}
   ^-  {(list move) _+>.$}
-  ~&  rfc/rfc
   ?.  ?=({care @ @ @ *} wir)
   ::  pokes don't return anything
   ~&  poke+res
@@ -100,7 +99,7 @@
   :_  +>.$  :_  ~
   :+  ost.hid  %diff
   ?+  i.wir  null+~
-      %x
+      $x
     ?~  r.res
       json+(jobe err+s+%empty-response code+(jone p.res) ~)
     =+  jon=(rush q.u.r.res apex:poja)
@@ -121,7 +120,7 @@
   `subscription-result`$(arg t.arg, u.jon ?~(new-jon ~ u.new-jon))
            ::  redo with next argument
   ::
-    %y
+    $y
   ?~  r.res 
     ~&  [err+s+%empty-response code+(jone p.res)]
       arch+*arch
@@ -141,14 +140,14 @@
     ?~  dir
       [%arch `(shax (jam u.jon)) ~]
     ?~  arg
-      [%arch `(shax (jam u.jon)) (~(run by u.dir) ,~)]
+      [%arch `(shax (jam u.jon)) (~(run by u.dir) $~)]
     =+  new-jon=(~(get by u.dir) i.arg)
     $(arg t.arg, u.jon ?~(new-jon ~ u.new-jon))
   ==
 
 ++  sigh
   |=  a=*
-  ~&  a/a
+  ~&  a+a
   :_  +>.$  ~
 ::
 ++  help
@@ -162,7 +161,7 @@
     [u.query (flop t.xap)]
   =^  arg  pax  [+ -]:(split pax)
   ~&  [pax=pax arg=arg query=query]
-  =|  mow=(list move)
+  =|  mow/(list move)
   |%
   ::  Resolve core
   ::
diff --git a/urb/zod/mar/gmail/req.hoon b/urb/zod/mar/gmail/req.hoon
new file mode 100644
index 0000000000..29543e217a
--- /dev/null
+++ b/urb/zod/mar/gmail/req.hoon
@@ -0,0 +1,8 @@
+/-  rfc, gmail-label
+
+|_  [method=meth endpoint=path query=quay mes=?(message:rfc label-req:gmail-label)] :: jon=(unit json)]
+++  grab
+  |%
+  ++  noun  ,[method=meth endpoint=path query=quay mes=?(message:rfc label-req:gmail-label)]:: jon=(unit json)]
+  --
+--
diff --git a/urb/zod/pub/docs/dev/hoon/reference/quickref/quickref.md b/urb/zod/pub/docs/dev/hoon/reference/quickref/quickref.md
new file mode 100644
index 0000000000..d71f9ca0e6
--- /dev/null
+++ b/urb/zod/pub/docs/dev/hoon/reference/quickref/quickref.md
@@ -0,0 +1,532 @@
+
+##Quick references
+
+###Lexical syntax
+
+####Comments
+
+`::` all code following '::' on a line is a comment.
+
+By convention, comments should begin on either column 39 or
+column 57.
+
+####Runes (Expressions)
+
+- Most runes have a predetermined amount of children, and thus do not need to be closed.
+
+- Runes that accept an arbitrary number of children are typically closed with
+  `==`, with the exception being the `|` runes, some of which are closed with
+  `--`.
+
+- In some cases, the second glyph denotes how many 'children' a rune accepts:
+
+  `-` two 
+  `+` three
+  `^` four
+
+- Backstep pattern: in order to avoid excess parentheses as well as code that
+  flows off the page, the last child of a rune should fall directly below it.
+  The first child should be the furthest to the right, with every subsequent
+  rune 'backstepping' two spaces towards the last child.
+  
+  XX
+
+The first glyph in a rune defines a rough semantic category of expressions:
+
+##### ? : Conditional statements
+
+`?&` Logical "and" 
+
+  - Irregular: `&`
+
+`?|` Logical "or"
+
+  - Irregular: `|.`
+
+`?!` Logical "not"
+
+  - Irregular: `!`
+
+
+`?:` - If-then-else
+
+`?.` - Inverted if-then-else
+
+`?@` - If atom-then-else
+
+`?^` - If cell-then-else
+
+
+`?-` - Switch (on type)
+
+`?+` - Swith (on type) with default
+
+
+`?>` - Assert `p` is false.
+
+`?<` - Assert `p` is true.
+
+
+`?~` - if null-then-else Note: don't forget, changes type
+`?=` - is `q` of type `p`Note: don't forget, changes the type
+
+##### % : Code execution
+
+`%-` Call `p` with 1 arg
+
+  - Irregular: `(p q)` Note: irregular form can accept n children.
+
+`%.` Inverted `%-`: call `q` with arg `p`
+
+`%+` Call `p` with 2 args
+
+`%^` Call `p` with 3 args
+
+
+`%~` Call one arm `p` within object/core `q` with arg `r`
+
+  - Irregular: `~(p q r)`
+
+`%*` Same as `%~` except `s` is a list of changes that can be made anywhere in
+the context, not just to input data.
+
+
+`%=` Evaluate `p` with changes specified in `q`
+
+  - Irregular: `a(p q.p, q p.a)`, where `a` is the code to be executed with changes
+    specified in the  `()` 
+
+`%_` Same as `%=`, except that product is cast back to type of `p`.
+
+##### : : Tuple construction
+
+`:-` Tuple of two
+
+  - Irregular `[p q ..]` Note: the irregular form can make tuples of arbitrary size
+
+`:_` Inverted tuple of two
+
+`:+` Tuple of three
+
+`:^` Tuple of four
+
+
+`:*` Tuple of arbitrary number of elements, closed with `==`
+
+`:~` Null terminated tuple of arbitrary number of elements, closed with `==`.
+
+
+`:/` XX
+
+##### | : Object aka "core" construction
+
+`|%` Generic core, closed with `--`
+
+`|_` Core with input data (aka 'sample), closed with `--`
+
+
+`|=` Function with type-checking at compile time (aka 'dry gate'); called automatically
+
+`|*` Function with type-checking at run time (aka 'wet gate'); called automatically
+
+`|.` Function (like `|=`) with no argument; called automatically
+
+`|-` Function with no arguments (like `|.`); not called automatically
+
+
+`|/` Same as `|_`, but with well typed output, closed with `--`
+
+`|^` Same as `|-`, but can contain internal arms, closed with `--`
+
+`|+` Function with unreadable argument(s) (aka 'sample'), so as to avoid type conflicts
+
+`|?` Same as `|_` but both the input and 'context' are hidden to avoid type conflicts
+
+##### $ : Type definitions
+
+`$|` Union between atom and cell
+
+`$_` 'Unbunt'; create type from example
+
+  - Irregular: `_p`, but only when in mold syntax
+
+`$:` Tuple of types (aka 'molds')
+
+  - Irregular: `{i.p i.t.p i.t.t.p}`
+
+`$%` Tagged union
+
+`$+` Type of function (type signature)
+
+`$&` Union of two cells: one w/cellular head and other w/atomic head
+
+`$*` 'Bunt'; produce default value of a type
+
+  - Irregular: `*([mold])`
+
+`$=` Add variable name; technically changes the type as well
+
+  - Irregular: `p=q`, but only when in mold syntax
+
+`$?` Union of types; non-empty list of types ('molds'). Default value ('bunt') is the value of the first element
+
+  - Irregular: `?([list of molds])`, but only when in mold syntax
+
+##### = : Subject ("context") modification XX
+
+`=>` Resolve code; use the product of `p` as the subject of `q`
+
+  - Irregular: `p:q`
+
+`=<` Inverted `=>`, used for code readability
+
+
+`=|` Push default value of type ('mold') onto subject 
+
+`=+` Push variable/value onto subject
+
+`=-` Inverted `=+`; push product of `q` onto subject `p`
+
+
+`=.` One change to subject; produce `r` with `p` in the context (in hoon the
+'subject') set to `q`
+
+`=:` Multiple changes to subject; Make a list of changes to the context (in hoon the 'subject')
+
+  XX how do we talk about subject and context.
+
+
+`=^` Used to push a new variable `q` with face `p` onto the subject `s`, as
+well as to change the value of another. `r` is a function that accepts `q` and
+produces a cell of a new value of `q`, and a new subject. XX
+
+`=~` Compose a list of twigs, applying `=>` to the list, using each result as the subject to the subsequent expressions.
+
+`=*` Make `p` an alias of `q`
+
+##### ^ : Casting
+
+`^|` Make core context unreadable so as to avoid type conflicts
+
+`^.` Cast `q` to the product type of `p`. Useful when you don't actually want to run a funciton at run time
+
+`^-` Traditional Cast `q` to the type of the default value ('bunt') of `p`
+
+  - `\`p\`q`
+
+`^+` Cast `q` to the type of `p`. Used to cast to types that have previously been made into validator functions with `$,`.
+
+`^&` Convert object/core from invariant to covariant
+
+`^~` Try to execute `p` statically at compile time. If this fails, `p` remains dynamic
+
+`^=` Put on variable name ('face')
+
+  - Irregular: `p=q`
+
+`^?` Convert core with unreadable context to a core whose input ('sample') and context are unreadable. Used to avoid type conflicts
+
+##### . : Nock operations
+
+`.^` Nock 11; loads a file from `%clay`
+
+`.+` Nock 4; increments an atom
+
+  - Irregular: `+(p)`
+
+`.*` Compute nock; formula `q` on subject `p`
+
+`.=` Nock 5; test `p` and `q` for equality
+
+  - Irregular: `=(p q)`
+
+`.?` Test if noun is cell or an atom
+
+##### # : Pretty printing
+
+`#<` Pretty print tape; only used in its irregular form
+
+  - Irregular: `<i.p i.t.p i.t.t.p>`
+
+`#>` Pretty print `++tank`; used only in it's irregular form
+
+  - Irregular: `>i.p i.t.p i.t.t.p<`
+
+##### / : Library access
+
+`//` Load a file between twigs
+
+`/~` Cached computation, similar to a `=+` at the top of the file
+
+`/$` Pull in dynamic request data, slam it through a gate
+
+`/=` Horn form of `^=`. Puts a face on a cached computation
+
+`/^` Horn form of `^-`
+
+`/;` Apply gate to result of horn
+
+`/,` Appen path to current working beam before computing horn
+
+`/:` Replace beam
+
+`/%` Reifiy the 'heel' virtual path, letting any requested resource interpret it further
+
+`/.` Construct list of specified horns
+
+`/*` similar to `/.`, but produces a map instead
+
+`/_` descend into each available subdirectory, construct a map from all successfully building versions
+
+`/&` Parse directory name as `@da`
+
+`/|` Parse directory name as `@dr`
+
+##### ~ : Compiler hints
+
+`~$` Label computation `q` as `p` for profiling
+
+`~|` `p` in stacktrace if `q` crashes
+
+`~_` Preformatted stackframe `p` (a trap producing a `++tank`) into stacktrace
+
+`~%` i.p i.t.p i.t.t.pRegister jet in core `s`
+
+`~/` XX
+
+`~<` Hint to product; applies arbitrary hint `p` to the product of `q`, which is computed beforehand
+
+`~>` Arbitrary hint `p` to `q`
+
+`~+` Memoize computation of `p`
+
+`~&` Printf
+
+`~=` Hint to avoid duplication
+
+`~?` PrintF if `q` is true
+
+`~!` Print type on compilation fail
+
+##### ! : Special runes
+
+`!_` Path and range in stack trace
+
+`!>` Produces a cell of both the type and value of `p` (called a `++vase`).
+Useful for debugging.
+
+`!=` Show nock of `p`
+
+`!?` Enforce a Hon version restriction
+
+`!!` Crash
+
+
+####Data types
+
+#####Strings
+
+`++tape` - List of chars. Used when you want to manipulate and interpolate text - `"[text]"`
+  See [list]() section for operations.
+
+`@t` - UTF-8 text; aka `++cord` - `'[text]'`
+    `++trip`: cord to string XX
+    `++taco`: cord to octet stream (for http requests) XX
+    `++slav`: parse cord to an atom of input odor XX
+
+`@ta` - Valid Hoon ASCII symbols - `~.[text]` + {`a-z`, `0-9`, `~`, `-`, `.`, `_`.}
+`@tas` - Hoon identifier ASCII subset - `%` + `a-z`, `-` (not first), `1-9` (not first)
+
+XX Would love to add half a liine about the difference between cords and tapes.
+
+#####Numbers
+
+`@`   - Generic atom (defaults to unsigned integer) - `42`
+`@u`  - Unsigned integer - `42`
+`@sd` - Signed decimal - `-42`(-), `--42` see `++si` for operations
+`@rd` - Single precision floating point - `.-42.75` (-), `.42.75` (+), see `++rd` for operations
+
+#####Other Important Atoms
+`@da` - absolute date - `~~[year].[month].[date]..[hour].[minute].[second]..[fractionals]` 
+      `++year`: `++date` to `@d` XX
+      `++yore`: `@d` to `++date` XX
+      note: year month day is mandatory, others are optional
+`@dr` - relative date (timespan) - `~d[day].h[hour]m[minute].s[second]..[fractionals]`
+      note: every measurement optional.
+      `++add`: can add `@dr`s together XX
+      `++yell`: `@d` to `++tarp`       XX
+`@p` - phonemic base - `~[valid @p]`
+      `(scot %p [number])` prints a number as a `@p`
+
+#####Data structures
+
+######Tuples are made with the `:` runes and their irregular `[]` wide forms
+
+ To construct, use [`[]`]() (irregular form of [`:` runes]()).
+
+`[3 'hello']`
+
+Special syntaxes:
+
+`~[1 2 3]` > `[1 2 3 ~]`
+
+`[1 2 3]~` > `[[1 2 3] ~]`
+
+`~[1 2 3]~` > `[[1 2 3 ~] ~]`
+
+######Autocons
+
+To eliminate need for excess `[]`, tuples automatically group to
+the right:
+
+`[1 [2 [3 ~]]]` == `[1 2 3 ~]`
+
+######pair, trel, quad put faces on tuples
+
+``=+ a=`(pair term cord)`[%h 'j']`` >  `[p=%h q='j']`
+
+Faces allow you to access specific axes within your context: 
+
+`p.a` > `%h` and `p:[p=%h q='j']` > `%h`
+
+######Lists are null-terminated and have faces of `i` and `t`
+
+- Definition:
+
+`++  list  |*  a=_,*                                     ::  null-term list
+          $|(~ [i=a t=(list a)])                        ::
+`
+
+- Constructor: `++limo` makes a list out of a null terminated tuple.
+
+`(limo [67 55 201 ~])` > `[i=67 t=[i=55 t=[i=201 t=~]]]`
+
+``(list ,@t)`(list ,@)\`~[67 55] >  <|C 7|>``
+
+- Operations:
+
+`++weld`: concatenate
+`++scag`: slice up to (and including) index number args: (index, list)
+`++slag`: slice list after index, args: (index, list)
+`++turn`: map over list, args: (list, function)
+`++reel`: right fold args: (list, function)
+`++roll`: left fold args: (list, function)
+`++sort`: quicksort, args: (list, comparator-function)
+
+######Map
+
+- Definition:
+
+` ++  map  |*  [a=_,* b=_,*]                              ::  associative tree
+         $|(~ [n=[p=a q=b] l=(map a b) r=(map a b)])    ::
+`
+
+- Constructor: `++mo` produces a map of key-val pairs from left-right cell pairs of a list
+
+`
+    ~zod/try=> (mo \`(list ,[@t *])\`[[a 1] [b 2] ~])
+    {[p=a q=1] [p=b q=2]}
+`
+
+- Operations: contained within the `++by` core
+
+`++by` accepts a map, then we use `%~` to pull the desired arm, which we then
+pass the remainder of the arguments
+
+`
+> =m (mo \`(list ,[@t *])\`[['a' 1] ['b' 2] ~])
+> (~(got by m) 'a')
+1
+`
+
+`+-all:by`: logical 'AND'
+`+-any:by`: logical 'OR'
+`+-del:by`: delete at key
+`+-dig:by`: axis of key
+`+-gas:by`: concatenate: insert a list of key-value pairs into map
+`+-get:by`: pull out value at key as a unit
+`+-got:by`: assert: pull value at key, crash if key doesn't exist
+`+-has:by`: check if key exists
+`+-int:by`: intersection: if keys match, use value from `b`
+`+-put:by`: add key value pair
+`+-rep:by`: fold over map
+`+-run:by`: 'map' over map
+`+-tap:by`: convert map to list
+`+-uni:by`: produce union between keys; if both share keys, use value from `a`
+`+-urn:by`: 'map', with key included with value as input to mapping function
+`+-wyt:by`: produce depth of tree of map
+
+######Set
+
+- Definition:
+
+` 
+    ++  set  |*  a=_,*                                      ::  set
+             $|(~ [n=a l=(set a) r=(set a)])                ::
+`
+
+- Constructor: `++sa`
+
+`
+    ~zod/try=> (sa \`(list ,@)\`[1 2 3 4 5 ~])
+    {5 4 1 3 2}
+`
+
+- Operations: contained within the `++in` core
+
+The `++in` core accepts a set, then we use `%~` to pull desired operation out
+of it, which we then pass the remainder of the arguments.
+
+    > =a (~(gas in `(set ,@t)`~) `(list ,@t)`[`a` `b` `c` ~])
+    > (~(has in a) `a`)
+    %.y
+
+
+`+-all:in`: logical 'AND'
+`+-any:in`: logical 'OR'
+`+-del:in`: delete val at key
+`+-dif:in`: difference between sets
+`+-dig:in`: produce axis `b` in set
+`+-gas:in`: concatenate: insert elements of list `b` into set
+`+-has:in`: check if element exists in set
+`+-int:in`: intersection
+`+-put:in`: add an element to set
+`+-rep:in`: fold over set
+`+-tap:in`: convert set to list
+`+-uni:in`: produces the union between two sets
+`+-wyt:in`: Produces the number of elements in set
+
+#####Addressing within nouns
+
+There are several ways you can address an axes of a noun:
+
+1. `[face].[variable-name]`
+
+2. `-.+.+.a`: 'the head, within the tail of the tail of `a`.'
+
+Can also intersperse faces: `+.a.b` reads 'the tail of `a` within `b`.
+
+3. `->+.a`: 'tail within the head of the head of `a`.'
+
+Must start with either `-` (head) or `+` (tail), and then follow with either `<` (head) or `>` (tail), so
+as to not repeat two symbols. 
+
+4. `|[number].[var]` returns the elements that follow the nth element in a list
+
+5. `&[number]` returns the nth element in a list. Cannot return the last element.
+
+####Error messages
+
+  i. hoon-how to generate the list of errors (Henry) 
+
+  ii. arvo
+    %a. Curtis
+    %b. Philip
+    %c. PHilip
+    %d. Curtis || Anton
+    %e. Anton
+    %f. Curtis || Anton
+    %g. Curtis || Anton
+
+
+
diff --git a/urb/zod/sur/gmail-label.hoon b/urb/zod/sur/gmail-label.hoon
new file mode 100644
index 0000000000..bf0f85d697
--- /dev/null
+++ b/urb/zod/sur/gmail-label.hoon
@@ -0,0 +1,34 @@
+::  This structure is the hoon equivalent of the labels resource used by the
+::  gmail api
+
+
+|%
+++  label-list-visibility
+  $?  %'labelHide'            ::  Do not show the label in the label list
+      %'labelShow'            ::  Show the label in the label list. (Default)
+      %'labelShowIfUnread'    ::  Show the label if any unread msgs w/that label.
+  ==
+++  message-list-visibility
+  $?  %hide                    ::  Do not show the label in the message list.
+      %show                    ::  Show the label in the message list. (Default)  
+  ==
+--
+
+|%
+::  label request is the body of the post request you send to gmail to create
+::  a labels resource
+++  label-req  ,[llv=label-list-visibility mlv=message-list-visibility name=@t]
+
+::  the label resource returned by gmail in response to your successful request
+++  label  ,*                       
+
+++  label-req-to-json
+  |=  label-req
+  %-  jobe  :^
+  ['name' `json`s/name]
+  ['labelListVisibility' `json`s/(crip (sifo `cord`llv))]
+  ['messageListVisibility' `json`s/(crip (sifo `cord`mlv))]
+  ~
+--
+
+
diff --git a/urb/zod/sur/rfc.hoon b/urb/zod/sur/rfc.hoon
new file mode 100644
index 0000000000..3897cb8b87
--- /dev/null
+++ b/urb/zod/sur/rfc.hoon
@@ -0,0 +1,21 @@
+:: This structure is the hoon equivalent of the RFC 822 E-mail message format
+
+|%
+++  message  ,[from=email-address to=email-address subject=@t body=@t]
+++  email-address  ,[name=@t domain=@t]
+--
+::
+|%
+++  email-adr-to-text  |=([name=@t domain=@t] (trip (rap 3 name '@' domain ~)))
+++  message-to-rfc822
+  |=  a=message  ^-  cord
+  %-  crip  ^-  tape  %-  sifo
+  %-  crip
+  """
+  From: {(email-adr-to-text from.a)}
+  To: {(email-adr-to-text to.a)}
+  Subject: {(trip subject.a)}
+  
+  {(trip body.a)}
+  """
+--