Urbit: Outdated docs, not sure how to fix.

[mikolajpp]

So, in an attempt to learn hoon, I am delving into the docs.
Unfortunately, there seem to be some changes to the examples, and docs are out of sync.
As an example: The echo example from https://urbit.org/docs/arvo/network/
is written a bit differently. One of training exercises says to modify the examples, but I am not even sure how to do it properly.

The current echo is:

!:
|_  {bow/bowl $~}                                       ::<  stateless
::
++  poke-atom
  |=  arg/@
  ^-  (quip $~ +>.$)
  ~&  [%square (mul arg arg)]
  [~ +>.$]
::
--

Does introducing another subject into the core (haha, not sure if this is the correct martian sentence)
using =| is a futile attempt (what does stateless means).

Lets say change the code to have the following:

  =|  b/@
  |-  ^-  @u
  ?:  (lth n b)
     0
  $(b  (add b 1)

For some reason I keep getting invalid core.

So basically the complaint/humble request is that the tutorials are out of sync, and pretty impossible for adept martians to follow. I will keep trying, maybe the 3rd sun of our system will shine on me ;-)

[galenwp]

Well, that's embarrassing. I think @keatondunsford updated these recently, which may have caused them to fall out of sync.

Thanks for catching this!

[galenwp]

(Your second example seems to have mismatched parens on line 5, but I imagine that's not the problem you ran in to)

[tonlur]

It's great to see your interest in Urbit and learning Hoon and Arvo! It's horrible to see that you happened to find these docs during a time of great change. In short, I'm in the middle of restructuring and rewriting the docs to better match our refreshed examples repository (please follow those all the way through and let me know your feedback!). So these docs will be fixed very shortly. But I can definitely still try and help this make sense for you!

Looking at your comment and the exercises at the end of the doc, it looks like you're wanting to try and extend the :echo app to accept a network input in addition to a noun. Actually, it looks like this network doc is confused, because that code block is actually for a different app, :square. Let's just start over with a fresh, clean, commented :echo app and hopefully I can explain things clearly:

/=examples=/app/echo.hoon

!:
::  Accepts any noun from :dojo and prints it out
::
::  /=examples=/app/echo/hoon
::
!:
|%                                                      ::>  not producing yet
++  move  $~                                            ::>  not producing yet
++  card  $%  $~
          ==
::
|_  {bow/bowl $~}                                       ::<  no storing state yet
::
++  poke-noun                                           ::<  call with &noun mark
  |=  non/*                                             ::>  cast arm product to
  ^-  (quip move +>.$)                                  ::<  mold: [moves state]
  ~&  echo+noun+non                                     ::<  print noun in :dojo
  [~ +>.$]                                              ::<  produce no effects
::
++  coup                                                ::<  poke succeed or err
  |=  {wir/wire err/(unit tang)}                        ::<  move wire, maybe err
  ^-  (quip move +>.$)                                  ::<  list of moves, state
  ?~  err                                               ::<  if there's no error
    ~&  echo+success+'Poke succeeded!'                  ::<  :dojo print success
    [~ +>.$]                                            ::<  and change nothing
  ~&  echo+error+'Poke failed. Error:'                  ::<  else, print error 
  [~ +>.$]                                              ::<  produce no effects
--

First, follow the _Local Install_ of the examples repository.

Afterwards, save the above app code in a file at the exact path /=examples=/app/echo.hoon (dependent on your urbit's name and where it's running from in Unix). %clay should recognize a change to your %examples desk's :echo app.

Then, run in your %examples desk :dojo:

~your-urbit:dojo/examples> |start %echo
~your-urbit:dojo/examples> :echo &noun 42

which should produce:

[%echo %noun 42]
[%echo %success 'Poke succeeded!']

Hopefully you can understand most of ++poke-noun in this app so far from reading the /arvo/network doc (I added some printf's and irregular syntax to make things more helpful). ^- (quip move +>.$) here does the exact same thing as ^- {(list move) _+>.$}; by looking up ++quip in the hoon.hoon source code, it produces a list of the first input and the example (mold) of the second input. ++coup either acknowledges a successful poke or errors. The general structure of the file, containing a first core of molds and a second core of gates, matches what you'll see most Hoon app files look like. But we aren't producing any Arvo moves or storing/changing any app state, so I defined those ++move and ++card types to be nil for this app. Don't be confused, it's just a style.

The way to make this produce network messages like pong is to create a custom mark that takes a pair of an urbit ship name and a noun, then create a ++poke-custom-mark arm that produce a move that releases (sends) the noun to the given ship, the sample of the poke gate call.

The best example of this, if you want to cheat slightly, is :ping in the new examples repo, which does exactly this. It uses a structure file, defining a ++message in /sur, to allow sharing of the structure between the app file and the mark file. You may want to go ahead and jump to the /arvo/marks doc to try and understand those better. Just keep in mind I need to update that doc with the new examples as well.

Hopefully this helps. Don't hesitate to comment with any further questions if you have them!

Thanks for bearing with us while we work hard to seriously improve all this.

[mikolajpp]

Thanks for your kind replies! I will go over the examples.