@@ -1,10 +1,10 @@
11+++
2−title = "Libraries"
2+title = "2.3.1 Walkthrough: Libraries"
33weight = 0
44template = "doc.html"
55+++
66
7−As in other languages, it's often very useful in hoon to create a library for your code. Let's take a look at one example of a library for dealing with playing cards.
7+In Hoon, like in other languages, it's often useful to create a library for other code to access. In this example, we look at one example of a library that can be used to represent a deck of 52 playing cards. The core below builds such a library, and can be accessed by programs.
88
99```
1010|%
@@ -58,7 +58,10 @@ As in other languages, it's often very useful in hoon to create a library for yo
5858--
5959```
6060
61−After creating a core, we use the `+$` arm to create three types we're going to need.
61+On the very first line, we create a core with `|%`. This core contains all of our library code, and is closed by the `--` on the final line.
62+
63+To create three types we're going to need, we use `+$`, which is an arm used to define a type.
64+
6265
6366```
6467+$ suit ?(%hearts %spades %clubs %diamonds)
@@ -66,13 +69,13 @@ After creating a core, we use the `+$` arm to create three types we're going to
6669+$ deck (list darc)
6770```
6871
69−The first is `suit` which can be one of `%hearts`, `%spades`, `%clubs`, or `%diamonds`.
72+The first is `suit`, which can be either `%hearts`, `%spades`, `%clubs`, or `%diamonds`.
7073
71−Next is a `darc` which is a pair of `suit` and an `@ud` which is a numeric value for the card. Why is it called `darc` and not `card`? `card` already has a meaning in gall where we are likely to use this library so it's worth while to avoid any name confusion in the future.
74+Next is a `darc`, which which is a pair of `suit` and a `@ud`. By pairing a suit and a number, it forms a particular card, such as "nine of hearts." Why do we call it `darc` and not `card`? Because `card` already has a meaning in gall, the Arvo app module, where one would likely to use this (or any) library. It's worthwhile to avoid any confusion over names.
7275
73−Our final type is `deck` which is simply a `list` of `darc`
76+Our final type is `deck`, which is simply a `list` of `darc`.
7477
75−One way to get a feel for how a library works is to skim the arm names before diving into any specific arm. In this library, the arms are `make-deck`, `num-to-suit`, `shuffle-deck`, and `draw`. In this case, these names should be very clear with the exception of `num-to-suit` though you could probably hazard a guess at what it does. Let's take a closer look at that one first.
78+One way to get a feel for how a library works is to skim the `++` arm-names before diving into any specific arm. In this library, the arms are `make-deck`, `num-to-suit`, `shuffle-deck`, and `draw`. These names should be very clear, with the exception of `num-to-suit` though you could probably hazard a guess at what it does. Let's take a closer look at that one first.
7679
7780```
7881++ num-to-suit
@@ -88,7 +91,7 @@ One way to get a feel for how a library works is to skim the arm names before di
8891
8992We can see this is a gate that takes a single `@ud` and produces a `suit`.
9093
91−The `?+` rune is the rune to switch against a value with a default. The default here is to crash with `!!`. Then we have the four possible options 1-4 which each result in a suit.
94+The `?+` rune is the rune to switch against a value with a default. The default here is to crash with `!!`. Then we have the four options of 1 through 4, based on the value of `val`, which each result in a different suit.
9295
9396```
9497++ draw
@@ -98,7 +101,7 @@ The `?+` rune is the rune to switch against a value with a default. The default
98101 (slag n d)
99102```
100103
101−`draw` takes two arguments, `n` a number and `d` a `deck`. It's going to produce a cell of two `decks` the first contains a hand of `n` `darcs` and the second is the rest of the `deck`. This is done with the `scag` and `slag` gates.
104+`draw` takes two arguments: `n`, a number; and `d`, a `deck`. It's going to produce a cell of two `decks`. The cell is created using `scag` and `slag`. [`scag`](https://urbit.org/docs/reference/library/2b/#scag) is a standard-library gate produces the first `n` elements from a list, and [`slag`](https://urbit.org/docs/reference/library/2b/#slag) is a standard-library gate that produces the remaining elements of a list starting after the `n`th element. So we use `scag` to produce the drawn hand of `n` cards in the head of the cell as `hand`, and `slag` to produce the remaining deck in the tail of the cell as `rest`.
102105
103106```
104107++ shuffle-deck
@@ -118,17 +121,17 @@ The `?+` rune is the rune to switch against a value with a default. The default
118121 unshuffled (oust [index 1] unshuffled)
119122```
120123
121−Finally we come to `shuffle-deck`. This gate takes two arguments, a `deck` and a `@` as a bit of `entropy` to seed the `og` core. It's going to produce a `deck`.
124+Finally, in the code above, we come to `shuffle-deck`. This gate takes two arguments: a `deck`, and a `@` as a bit of `entropy` to seed the `og` core. It's going to produce a `deck`.
122125
123−`=|` adds a defaulted `deck` to the subject.
126+`=|` adds a default-valued `deck` to the subject.
124127
125−Next we feed the `og` core the entropy it needs in preparation for using it and we get the length of the unshuffled deck with `lent`.
128+Next, with `=/ random ~(. og entropy)`, we feed the `og` core the entropy it needs in preparation for using it. Then, with `=/ remaining (lent unshuffled)`, we get the length of the unshuffled deck with `lent`.
126129
127−If we have only one card remaining, we produce a cell of `shuffled` and that one card left in `unshuffled` with the `:_` rune so we can have the heavier twig to the bottom of the expression.
130+`?: =(remaining 1)` checks if have only one card remaining. If that's true, we produce a cell of `shuffled` and the one card left in `unshuffled`. We use the `:_` rune here, so that the "heavier" hoon is at the bottom of the expression.
128131
129−Else we are going to do a little work. `=^` is a rune that pins the head of a pair and changes the leg with a tail. It's useful for interacting with the `og` core arms as many of them produce a pair of a random number and the next state of the core. We're going to put the random number in the subject with the face `index` and change `random` to be the next core.
132+If the above conditional evaluates to false, we are going to do a little work. `=^` is a rune that pins the head of a pair and changes the leg with a tail. It's useful for interacting with the `og` core arms, as many of them produce a pair of a random numbers and the next state of the core. We're going to put the random number in the subject with the face `index` and change `random` to be the next core.
130133
131−That completed, we use `%^` to call `$` to recurse back up to the `|-` with a few changes.
134+With completed, we use `%^` to call `$` to recurse back up to `|-` with a few changes.
132135
133136`shuffled` gets the `darc` from `unshuffled` at `index` added to the front of it.
134137
@@ -136,7 +139,9 @@ That completed, we use `%^` to call `$` to recurse back up to the `|-` with a fe
136139
137140`unshuffled` becomes the result of using `oust` to remove 1 `darc` at `index` on `unshuffled`.
138141
139−This is a very naive shuffling algorithm and you could imagine a better one. Implementation of a better algorithm is left as an exercise for the reader.
142+This is a very naive shuffling algorithm, and you could imagine a better one. Implementation of a better algorithm is left as an exercise for the reader.
143+
144+## Using the Library
140145
141146So now that we have this library, how do we actually use it? Let's look at a very simple `say` generator that uses it.
142147
@@ -150,4 +155,4 @@ So now that we have this library, how do we actually use it? Let's look at a ver
150155
151156If you save this in the `gen` directory and the library as `playing-cards.hoon` in the `lib` directory, you can import the library with the `/+` rune. This is not a hoon rune, but instead a rune used by Ford, the Urbit build system. When this file gets built, Ford will pull in the requested library and also build it. It will also create a dependency so that if `playing-cards.hoon` changes, this file will also get rebuilt.
152157
153−Here you have the standard `say` generator boilerplate that allows us to get a bit of entropy from `arvo` when the generator is run. Then we feed that and a `deck` created by `make-deck` into `shuffle-deck` to get back a shuffled `deck`.
158+Here you have the standard `say` generator boilerplate that allows us to get a bit of entropy from `arvo` when the generator is run. Then we feed that and a `deck` created by `make-deck` into `shuffle-deck` to get back a shuffled `deck`.