revise hoon school lesson on ford

[drbeefsupreme]

The long anticipated Ford Fusion arrived with urbit-os-v1.0.24, and with it comes necessary revision to our documentation.

The most pressing one in terms of how much it is probably used by the community is the Hoon school lesson on Ford at /tutorials/hoon/ford.md and unit tests at tutorials/hoon/test-sets.md. Since I wrote these lessons and plan to write Clay documentation this quarter, this seems to naturally fall to me.

[matildepark]

I also believe a few Ford runes no longer exist?

[belisarius222]

Yes, the Ford runes have changed significantly.  I need to write up the specification for how they work; apologies for the delay on that.

— ~rovnys-ricfer https://urbit.org

On Thu, Jul 02, 2020 at 3:39 PM, matildepark < notifications@github.com > wrote:

I also believe a few Ford runes no longer exist?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub ( https://github.com/urbit/docs/issues/905#issuecomment-653187981 ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/AAGVR5JRVUXYMPF6XMLGE4DRZTO7VANCNFSM4ON47XZA ).

[drbeefsupreme]

Yeah I will set up a meeting with you @belisarius222 when I revise this lesson to get your input. It's at least a few weeks away, though.

[belisarius222]

There are now only four Ford runes.  A file can contain zero, one, or many of each, but each Ford expression can only be one line, and they must be in the standard order of /-s, /+s, /=s, and then /*s.

/-  foo, *bar, baz=qux

The /- rune imports a structures file from /sur.  You can import it as just foo, in which case the build result of that file (usually a core with mold definitions) will be pinned into the compilation subject with the face foo.  If you prefix it with a * as in *bar, the result will be pinned into the subject with no face; if the structures file compiled to a core, this exposes all the arms into the namespace of the compilation subject. Finally, if you import it as baz=qux, the baz face will be applied instead of qux. This is similar to "import as" in other languages.

/+  foo, *bar, baz=qux

The /+ rune imports a library file from /lib. Aside from the different source folder, the syntax and semantics are the same as for /-.

/=  clay-raw  /sys/vane/clay

The /= rune imports the result of building a hoon file from a user-specified path (the second argument), wrapping it in a face specified by the first argument. The final /hoon at the end of the path must be omitted. This is mostly useful for importing a file for testing. The file at the specified path will be built as a normal userspace hoon file; i.e. its compilation subject will be Zuse augmented with the results of any Ford runes it has at the top of the file.

/*  hello-gen  %hoon  /gen/hello/hoon

The /* rune imports the contents of a file in the desk, specified as the third argument with the full path including the trailing mark, converted to the mark specified by the second argument, and pinned into the compilation subject wrapped in the face specified by the first argument. This can be used to import static data at build-time, such as a data file, a media file, or in the case of this example, a hoon file as source text rather than already built.

A valid userspace hoon file must contain a nonempty list of hoons (hoon source expressions) below the Ford runes, separated by gap (more than one space, or at least one newline). The system wraps this list of hoons in a =~ expression so that the result of the previous hoon is used as the subject of the next hoon. The result of the Ford runes is used as the compilation subject for this =~ hoon; informally, the shape of the compilation subject can be thought of as:

[fastar-2 fastar-1 fastis-2 fastis-1 faslus-2 faslus-1 fashep-2 fashep-1 <zuse>]

[tinnus-napbus]

hoon school has now been fully rewritten