Tutorial on Hoon subject modification.

gistfile1.txt

::
:: Hoon Tutorial 1
::
::  {<(func arg1 arg2)>}  forces the result inta a hoon representation.
::  {(func arg1 arg2)}  Does no casting just interpolates the value in.
::  {value} when you aren't calling a function then don't use the parens.
::
::::::
    ::
    ::
/?    310
::
|%
++  showcode
  |=  [code=tape]
  ;code
    ;pre: {code}
    ;pre: product => {<.*(~ (make (crip code)))>}
  ==
++  newlines
  |*  [a=tape b=tape]
  ;:  welp
    a
    "\0a"
    b
  ==
++  testcode
  ;:  newlines
    "=+  a=1"
    "a"
  ==
++  testdoubleadd
  ;:  newlines
    "=+  a=1  :: Push a onto the subject"
    "=+  b=2  :: push b onto the subject"
    "[a b]"
  ==
++  testdoubleaddeasy
  ;:  newlines
    "=+  [a=1 b=2]  :: push a and b onto the subject"
    "[a b]"
  ==
++  testtisdot
  ;:  newlines
    "=+  [a=1 b=2]  :: push a and b onto the subject"
    "=.  b  3       :: Set b in the subject to 3"
    "b"
  ==
++  testalias
  ;:  newlines
    "=+  a=1  :: push a onto the subject"
    "=*  b  a  :: Alias b to the a we just pushed."
    "=.  a  2  :: modify a on the subject."
    "[a b]"
  ==
++  testshadowing
  ;:  newlines
    "=+  a=1  :: push a onto the subject"
    "=*  b  a  :: Alias b to the a we just pushed."
    "=+  a=2  :: push a different a onto the subject."
    "[a b]"
  ==
++  testsubject
  ;:  newlines
    "=+  a=1  :: push a"
    "=+  a=2  :: push a again"
    "=+  c=3  :: push c"
    "."
  ==
--
::
^-  manx
;html
  ;head
    ;title: Hoon Tutorial 1 - Subject modification
  ==
  ;body
    ;h1: Hoon Tutorial 1 - Subject modification
    ;div
      ;p:'''
         The subject in hoon is similar to a scope in other
         languages. It is the space of data available to work with in
         a hoon formula. The subject is the world your hoon formula
         can see.
         '''
      ;p:'''
         Where you would do a variable assignment in say javascript you
         would instead modify the subject in hoon. But subject modification
         is more than just variable assignments. It is also how you modify
         the entire world. You can do more than just add new items to the
         world. You can in fact replace the entire world for an formula.
         You can batch up changes to the world or make a single small tweak.
         Each with the appropriate Hoon Rune.
         '''
      ;p:'''
         Let's start with something a little closer to home though. Pushing
         a single piece of data onto the subject. This would be analogous
         to defining a variable and assigning a value to it.
         '''
      ;h2: Adding to the subject.
      ;+  %-(showcode testcode)
      ;p:'''
         In the example above we made a single modification to the subject.
         Trying to reference b, for example, would not work since b has not
         been pushed on to the subject.
         '''
      ;code
        ;pre:'''
             =+  a=1
             b
             '''
        ;pre: product: error: find-none.
      ==
      ;p:'''
         If on the other hand we add b to the subject then we can reference it.
         '''
      ;+  %-(showcode testdoubleadd)
      ;p:'''
         It would get old having to keep doubling up those adds so we have an
         easier way to do it.
         '''
      ;+  %-(showcode testdoubleaddeasy)
      ;h2: Changing a subject value
      ;p:'''
         If we want to modify an already existing value in our subject then
         we use tisdot.
         '''
      ;+  %-(showcode testtisdot)
      ;p:'''
         In order to see the difference between tislus and tisdot we need to
         use another subject modifier, tistar (=*). Which adds an alias to
         another limb in our subject.
         '''
      ;+  %-(showcode testalias)
      ;p:'''
         Notice that b changes with the value of a.
         '''
      ;p:'''
         What happens if we use tislus instead of tisdot to change the value
         of a in that code though?
         '''
      ;+  %-(showcode testshadowing)
      ;p:'''
         This time b is referencing the first a we put on the subject and does
         not change when we push a different a on the subject.
         '''
      ;h2: What exactly does a subject look like?
      ;p: We can take a look at our subject with (.) in our formula.
      ;+  %-(showcode testsubject)
      ;p: As you can see each push has its own limb on the subject.
    ==
  ==
==