25 KiB
%ford Guide
basic hoon and talking to the web
%ford is the arvo vane that handles asset management and publishing.
We use %ford to compose our files when programming, and also to bundle
files together for the web.
This guide assumes that you have installed and started your urbit.
Assuming you cloned the repo into /$URB_DIR you should be able to find
the unix mirror of your ship's filesystem in
/$URB_DIR/$PIER/$SHIP-NAME. All of the filesystem paths in this guide
are relative to that Unix directory.
Also, we refer to http://ship-name.urbit.org/ in our URLs, but you can
also use http://localhost:8080/ if you prefer to just talk to your
machine directly.
1. Let's publish a webpage --------------------------
In
/main/pub/fab/guide/exercise/1/hymn.hook
Put
;html
;head
;meta(charset "utf-8");
;title: Exercise 1
==
;body
;div
;h1: Exercise 1 — Simple HTML
;p: As you may notice, urbit has no problem talking to the web.
==
==
==
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/1/
What did you just do?
The code you just wrote is urbit's native programming langauge, hoon.
Generating HTML with hoon is similar to writing jade or other
similar HTML shorthand. In hoon, this shorthand is called ++sail
and it's a native part of the hoon language.
In ++sail node-names are prefixed with a ; and closed with a ==.
Nodes that have text content and are only on one line use a :, such as
our ;h1: above, and are closed implicitly with a new line. Nodes with
no content are closed with another ;, such as ;br;.
You can find more information about ++sail in our rune library
documentation.
2. Let's do some programming on the page. -----------------------------------------
In
/pub/fab/guide/exercise/2/hymn.hook
Put
;html
;head
;meta(charset "utf-8");
;title: Exercise 2
==
;body
;div
;h1: Exercise 2 — Call a function
;p: Although it may be obvious, 2+2={<(add 2 2)>}
==
==
==
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/2/
What's going on there?
Clearly, the code (add 2 2) is generating 4, and it's not too hard
to see why. add is one of the library functions that are a part of
hoon.hoon. Try replacing (add 2 2) with (sub 2 (add 2 2)). You can
find documentation for the full hoon library in the library
reference.
Since the product of (add 2 2) is a number, we need a few extra things
to have it print properly. In ++sail we use { and } to do string
interpolation. Everything after the : is expected to be a string, so
we need to tell the parser when we start writing code. The < and >
inside our { } are converting our result 4, a number, to the
string "4". hoon is a strongly typed language kind of like haskell, so
we need to explicitly convert our types.
3. Let's assign some variables. -------------------------------
In
/pub/fab/guide/exercise/3/hymn.hook
Put
=+ ^= a 1
=+ b=2
::
^- manx
;html
;head
;meta(charset "utf-8");
;title: Exercise 3
==
;body
;div
;h1: Exercise 3 — Assignment
;p: a={<a>}
;p: b={<b>}
;p: a+b={<(add a b)>}
==
==
==
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/3/
How does that work?
The first thing you should notice in this example is the =+ at the top
of our file. =+ is a rune. hoon is a programming with no reserved
words. We don't use if this or function at all. Instead, runes
have their own pronunciation. =+ is pronounced 'tislus'. You can find
the table of pronunciation here. In hoon you construct your
programs using runes, which are two character ascii pairs. You can see
the whole set of runes in the rune index.
=+ pushes an expression on to our subject. The subject in hoon is
similar to this in other languages. hoon being a functional language
if we want something to be available further on in our computation we
need to attach it to the subject first.
The second thing you should notice is the ^- manx. Here the rune
[^-]() is used to cast our product to a ++manx, which you can
think of like the hoon MIME type for XML. Using a ^- is not required,
but helps us produce more informative error messages when we generate a
type error or mismatch.
Looking at the rendered page it's clear that we're assigning a to be
1 and b to be 2. Looking at the code, however, you can see that
we're doing this in two different ways. Runes in hoon can have irregular
forms, and ^= is one of them. The first two lines of our example are
doing the same thing, where a=2 is simply the irregular form of
^= a 2. You can see the full list of irregular forms here.
Looking at the simple computation on the page, you can try changing the
values of a and b to any integers to produce similar results.
4. Let's build our own computation ----------------------------------
In
/pub/fab/guide/exercise/4/hymn.hook
Put
|%
++ start 1
++ end 10
++ length
|= [s=@ud e=@ud]
(sub e s)
--
::
^- manx
;html
;head
;meta(charset "utf-8");
;title: Exercise 4
==
;body
;div
;h1: Exercise 4 — Cores
;p: We'll be starting at {<start>}
;p: And ending at {<end>}
;p: Looks like a length of {<(length start end)>}
==
==
==
Try it
(and be sure to put two spaces between ++ and arm names)
http://ship-name.urbit.org/main/pub/fab/guide/exercise/4/
What's happening?
As you can see from the output, we have written a little function that
takes two numbers, s and e and returns their difference. The first
thing to notice about our code is the first rune. |% is a core rune.
You can think of cores like functions or objects in other languages.
|% runes contain an arbitrary number of arms, denoted with either ++
or +- and closed with --.
Each arm has a value, either static data (in the case of ++start and
++end) or a gate (in the case of ++length). A gate is a kind of
core. Gates only have one arm and are quite similar to a function in
other languages. We use |= to construct our gate. Runes in hoon are
generally categorized by their first character. | indicates a rune
having to do with cores. You can find all of the | runes in the rune
library.
Our ++length gate takes two arguments, s and e. In hoon we
call the data passed in to a gate the 'sample'. Every |= has two
parts: the sample type and the computation, also known as a tile and a
twig. Casually, [s=@ud e=@ud] means that the gate takes two
arguments, labelled going forward as s and e, and required to both
be @ud or unsigned decimal. Our computation, (sub e s) simply
computes the difference between e and s.
@ud is an odor. Odors aren't quite types, but they're similar. You'll
learn the difference by example as we progress, and you can always refer
to the odor index.
You probably also noticed our indentation. In general hoon has both tall and wide forms. In tall form, hoon uses two spaces for indentation and is back-stepped so nested code doesn't drift away toward the right margin. In wide form we use parenthesis just like almost everyone else.
5. --
In
/pub/fab/guide/exercise/5/hymn.hook
Put
|%
++ dist ,[start=@ud end=@ud]
++ length
|= [d=dist]
(sub end.d start.d)
--
::
^- manx
;html
;head
;meta(charset "utf-8");
;title: Exercise 5
==
;body
;div
;h1: Exercise 5 — Cores
;p: How long does it take to get from 2 to 20? {<(length 2 20)>}
==
==
==
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/5/
What's the difference?
Clearly we're producing the same result as before, but we're doing it in a different way.
The first line in our gate, ++length always specifies the sample tile.
As you can see here, our sample tile is actually a ++dist, the body of
which, ,[start=@ud end=@ud] looks very similar to our previous example
in that it accepts two @ud. The important difference is that ++dist
is now defined in a way that can be re-used. hoon is a strongly typed
language, but it encourages the creation of your own types using what we
call tiles.
At a high level you can think of hoon as being composed of two things, tiles and twigs. Twigs are the actual AST structures that get consumed by the compiler. Tiles reduce to twigs and provide major affordances for the programmer. If you're interested in learning about tiles more deeply you can find an in-depth explanation in the tile overview.
It should suffice, for now, to say that we create tiles in the same way
that you would think of creating type definitions in another language.
The primary way we do this is with $ runes you can find more about
them in the $ section of the rune library.
In this specific example we are using the $, tile rune in its
irregular form, ,. , generates a validator from the given
expression. In effect, ++dist uses the type system to only produce
cells that appear in the form [start=@ud end=@ud]. When we use it in
our ++length gate we assert that our input must be validated by
++dist. To test that out, you can try passing something that isn't an
unsigned decimal (or @ud) to ++length. Try replacing (length 2 20)
with (length 2 'a'). As we continue you'll see how this pattern can be
quite useful.
One other thing to point out which may be immediately confusing coming
from other languages is the order of addressing start and end. We
call these labels faces, and we address them in the opposite order than
you're usually familiar with. We still separate our addressing with .,
but do it from the inside out. Given a tuple such as
[a=1 b=[c=[d=2 e=3]]] we can address the value of e with e.c.b.
You can read more about how faces work in the commentary on ++type
here.
6. --
In
/pub/fab/guide/exercise/6/hymn.hook
Put
|%
++ fib
|= x=@
?: (lte x 2)
1
(add $(x (dec x)) $(x (sub x 2)))
--
::
^- manx
;html
;head
;meta(charset "utf-8");
;title: Exercise 6
==
;body
;div
;h1: Exercise 6 — Loops
;p: {<(fib 1)>}, {<(fib 2)>}, {<(fib 3)>}, {<(fib 4)>}
==
==
==
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/6/
What is that doing?
We're printing a few members of the fibonacci sequence by
calling our arm ++fib with a few values. The fibonacci sequence is a
fairly straight forward algorithm: F(n-1) + F(n-2) where F(1) = 1
and F(2) = 1. As is obvious from the formula, generating the fibonacci
value at any number requires us to recurse, or loop. Let's walk through
the code.
Our example here should look similar to the previous one. We build a
core with |% and add the arm ++fib. ++fib is a gate which takes
one argument x, an atom. Using ?: we test if x is less
than 2 with the library function lte to handle our seed
values of F(1) = 1 and F(2) = 1. ?: is a member of the ?
runes, related to true / false values, or loobeans. In hoon true
and false are 0 and 1 respectively and take the odor @f. We tend
to say 'yes' and 'no' instead of 'true' and 'false' to keep track of the
switch. Our built-in function lte produces a loobean, so we evaluate
our first line if true, and second if false.
If x is not less than 2 we compute F(n-1) + F(n-2) by using $.
We mentioned previously that a gate is a special kind of core with only
one arm, called $. Here we're using $ to mimic the behavior of a
loop. You can read the expression $(x (dec x)) as 'call the gate again
with x replaced by (dec x). For more on how this works, check out
the documentation of %= and %-. With that in mind it
should be clear how the last line of ++fib produces the member of the
sequence at a given value x.
7. --
In
/pub/fab/guide/exercise/7/hymn.hook
Put
::
::
:::: /hook/hymn/7/exercise/guide/fab/pub/
::
/? 314
/= gas /$ fuel
::
^- manx
;html
;head
;meta(charset "utf-8");
;title: %ford Example 1
==
;body
;div
;h1: %ford Example 1 — Page Variables
;div.who: {<(~(get ju aut.ced.gas) 0)>}
;div.where: {(spud s.bem.gas)} rev {(scow %ud p.r.bem.gas)}
;code
;pre: {<gas>}
==
==
==
==
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/7/
http://ship-name.urbit.org/gin/del/main/pub/fab/guide/exercise/7/
Here we're putting our publishing framework, %ford to work a little
bit. We're printing out some of the parameters our page is passed: who
is looking at it, where it is and what revision our desk is on. We have
also thrown in all our FCGI parameters in a codeblock for reference.
To do this we have introduced some new runes, /?, /= and /$. We
tend to call runes with a leading / "%ford runes" since they are
used by the %ford vane for resource loading and composition. By
convention, we indent four spaces after them to make them more obvious.
They belong at the top of the file.
/? simply checks for compatibility. In this case the line means 'need
urbit 314 or below', or in hoon: (lte zuse 314). 314 is the number
in the kelvin versioning system, which you can read about here.
/= is similar to the combination of =+ =^, or assignment. /$
calls a parsing function, which we specify as ++fuel with the
++beam and ++path of our current file.
/= gas /$ fuel is a common way to open your page, since the
product of ++fuel is useful when writing pages to the web. The use of
++fuel is not enforced — you can also write your own parser.
Our page is made up of two generated parts: who requested the page, the
location of the page and its revision. Both are parsed out of the gas
variable using some straightforward library functions, ++ju,
++spud and ++scow. You can follow those links to the
library reference to learn more about them. You'll also notice our
addressing moving in the opposite direction as you may be used to.
aut.ced.gas pulls aut from inside ced from inside gas.
Inside of the ;code tag we also print (for our own reference) the
entire gas, so you can take a look at the contents. This can be a
helpful trick when debugging. To fully understand what gets put in
gas, we can take a look at ++fuel and note that it produces a
++epic, which also contains a ++cred. You can follow
those links to learn more about them.
When we try changing the url from main to gin/del/main we're
using some of the access methods from %eyre (the urbit webserver) to
pretend to be the urbit ~del. You can find documentation on those
access methods in the %eyre commentary, here.
Path and identity are useful, but there are some other parameters worth checking out as well.
8. --
In
/pub/fab/guide/exercise/8/hymn.hook
Put
::
::
:::: /hook/hymn/8/exercise/guide/fab/pub/
::
/? 314
/= gas /$ fuel
::
^- manx
;html
;head
;title: %ford Example 2
==
;body
;div: Do you have a code?
;div: ?code={<(fall (~(get by qix.gas) %code) '')>}
==
==
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/8/
http://ship-name.urbit.org/main/pub/fab/guide/exercise/8/?code=yes-i-do
This is a simple example, showing off another use of
/= gas /$ fuel. In this case we're just pulling out the value of
the code query string parameter. You should be able to change that
value to any url-safe string and see it appear on the page.
We're using a few simple library functions to actually pull the value
out, ++fall and get:by. Query string parameters are
stored in qix.gas as a ++map, one of the main container constructs
used in hoon. We'll encounter a lot of maps along the way, and you can
learn more about them in the map section of the library doc.
9. --
In
/pub/fab/guide/exercise/9/hymn.hook
Put
::
::
:::: /hook/hymn/exercise/9/guide/fab/pub/
::
/? 314
::
// /%%/lib
^- manx
;html
;head
;title: %ford Example 3
==
;body
;h1: %ford Example 3
;p: {<(fib 1)>}, {<(fib 2)>}, {<(fib 3)>}, {<(fib 4)>}
==
==
And in
/pub/fab/guide/exercise/9/lib.hoon
Put
|%
++ fib
|= x=@
?: (lte x 2)
1
(add $(x (dec x)) $(x (sub x 2)))
--
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/9/
How are they getting combined?
Clearly this looks a lot like our previous example using ++fib, only
now we're using two separate files. The majority of this code should be
familiar to you from example 6, so let's focus on a single line,
// /%%/lib.
// is a %ford rune that loads a resource from a given path. // is
used as a way to organize project code into separate files, not for
loading libraries and structures. We'll show some examples of how urbit
handles those things shortly. You can think of // as a kind of
include or require. // takes a beam, an absolute global path in
%clay — the global urbit filesystem.
In %clay we use % to navigate relative paths. % is sort of like
. when moving around the unix file system. Although we put our code in
the unix path /pub/fab/guide/exercise/9/hymn.hook the file extension
is just a hint to the system. /%/ (the equivalent of a unix ./)
actually resolves to /pub/fab/guide/exercise/9/hymn.
We commonly use two kinds of extensions, .hoon for source files and
.hook for files that generate something else. Since our hymn file is
generating html, it's a .hook, and our source file is just a .hoon.
In order to find our file one level up we need two %% to get to
/pub/fab/guide/exercise/9/. Adding lib resolve to our neighboring
file. You can read more about how %clay paths are parsed in the
%clay overview. It's also pretty easy to try them out using
/=main=, /=try, /try/a/b/c/d, etc.
and :ls in your %arvo terminal.
10. ---
In
/pub/fab/guide/exercise/10/hymn.hook
Put
::
::
:::: /hook/hymn/10/exercise/guide/fab/pub/
::
/? 314
/= gas /$ fuel
// /%%/lib
::
=+ ^= arg
%+ slav
%ud
%+ fall
%- ~(get by qix.gas) %number
'0'
::
^- manx
;html
;head
;title: %ford Example 4
==
;body
;div: {<(fib arg)>}
==
==
And in
/pub/fab/guide/exercise/10/lib.hoon
Put
|%
++ fib
|= x=@
?: (lte x 2)
1
(add $(x (dec x)) $(x (sub x 2)))
--
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/10/
http://ship-name.urbit.org/main/pub/fab/guide/exercise/10/?number=7
http://ship-name.urbit.org/main/pub/fab/guide/exercise/10/?number=12
As you can see by changing the URL, we're now passing our query string
parameter to our ++fib script and printing the output. It's common to
pull some data out of the URL and do something with it, but we don't
have any type information about our query string parameters and hoon is
a strongly typed languge. As you can see, we're calling ++fib with a
parameter arg. Let's look closely at how we generate arg.
The first part of our assignment should look familiar from previous
example, =+ ^= arg puts the face arg on the product of our
remaining computation. In short, you can read the code that produces
arg as (slav %ud (fall (~(get by qix.gas) %number) '0')). We use %
runes to write this in tall form. % runes are used for calling gates
or evaluating changes. %+ 'slams' or calls a gate with two arguments,
and %- 'slams' or calls a gate with one argument. As usual, you can
find more about the % runes in the % section of the rune
library.
To get a value out of our map of query string parameters qix.gas we
use a method from the maps library that produces a ++unit.
++units are a common type in hoon used for optional values. A
++unit is either ~ or [~ p=value]. Since we need to
specify a value for (fib arg) even when someone doesn't enter the
query string we use ++fall, which produces either the value of
the unit, or the second argument if the ++unit is null. Since our
qix.gas has string values in it we specify a string in our second
argument, '0'. As an aside, '0' is different from "0" in hoon. You
can read about the difference in ++cord and ++tape.
Our outermost call, to ++slav, casts our string to a @ud —
which is the type expected by ++fib. ++slav takes the name of an
odor and a value, and tries to cast the value to that odor.
11. ---
In
/pub/fab/guide/exercise/11/hymn.hook
Put
/= posts /: /%%/lib
/; |= a=(list (pair ,@ ,manx))
%+ turn
a
|= [* b=manx]
b
/@
/psal/
::
^- manx
;html
;head
;meta(charset "utf-8");
;title: %ford Example 11
==
;body
;h1: Ford example — Loading Resources by Number
;* posts
==
==
In
/pub/fab/guide/exercise/11/lib/1.md
Put
#1
This is my first post.
In
/pub/fab/guide/exercise/11/lib/2.md
Put
#2
This is my second post.
Try it
http://ship-name.urbit.org/main/pub/fab/guide/exercise/11/
http://ship-name.urbit.org/main/pub/fab/guide/exercise/11/lib/1/
http://ship-name.urbit.org/main/pub/fab/guide/exercise/11/lib/2/
Experiment with it
Try adding other .md files with numeric file names (such as 3.md) to
the 11/lib/ directory to get a feel for what's going on.
What's happening?
As you can see, we're loading the markdown files in 11/lib and putting
them in to our page. Let's dive into the code.
We're using /= to assign the posts face. /: sets the ++beam for
the computation below it. You can think of it sort of like setting an
environment variable. Everything below uses our ++beam /%%/lib.
If we take the next few lines and write them as pseudo code in wide form
they might look something like this, (/; [gate] (/@ /psal/)). That
being the case, let's start at the bottom and move upwards since that's
how our data flows. In depth documentation on individual ++horn runes
can be found in the horn section of the rune library.
/psal/ loads our psal mark. Marks are like content types, and we
keep them in /main/mar/. You can open /main/mar/psal/door.hook to
see that we specify the ways in which a particular mark can be converted
to produced well typed output. The general form of this is /mark/
where mark exists in the /main/mar/ directory. A psal is a partial
hymn, where hymn is the hoon structure for html.
/@ loads a list of files in numerical order from the previously
specified ++beam using our mark, psal. /@ has a few close
relatives. /&, for example, reads files by @da or absolute date. You
can see the rest in the horn section of the library.
/; takes the output from /@ and /psal/ and passes it to a twig. In
this case, a gate. Our /@ actually produces a ++list of
pairs of [@ manx] where the @ is the filename, and the manx is the
converted contents. We use ++turn, one of our ++list
operator functions, to iterate through the list and produce only a list
of ++manx. This is the output assigned to posts.
Then, further down, we use ;* to write the list to the page.
12. ---
Look in
/pub/fab/guide/hymn.hook
/pub/fab/guide/main.css
/pub/fab/guide/main.js
Try it
http://ship-name.urbit.org/main/pub/fab/guide/
Bring it all together
It turns out it's pretty easy to pull our examples together into a single blog-like page using what we just covered. We include some css to make things a bit prettier, and this should give you a good jumping off point for experimenting with your own publishing code.