@@ -0,0 +1,157 @@
2+title = "2.3.1 Walkthrough: Libraries"
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.
11++$ suit ?(%hearts %spades %clubs %diamonds)
12++$ darc [sut=suit val=@ud]
27+ mydeck [(num-to-suit i) j]^mydeck
39+ |= [unshuffled=deck entropy=@]
42+ =/ random ~(. og entropy)
43+ =/ remaining (lent unshuffled)
48+ =^ index random (rads:random remaining)
50+ shuffled (snag index unshuffled)^shuffled
51+ remaining (dec remaining)
52+ unshuffled (oust [index 1] unshuffled)
55+ ^- [hand=deck rest=deck]
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.
63+To create three types we're going to need, we use `+$`, which is an arm used to define a type.
66++$ suit ?(%hearts %spades %clubs %diamonds)
67++$ darc [sut=suit val=@ud]
71+The first is `suit`, which can be either `%hearts`, `%spades`, `%clubs`, or `%diamonds`.
73+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.
75+Our final type is `deck`, which is simply a `list` of `darc`.
77+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.
91+We can see this is a gate that takes a single `@ud` and produces a `suit`.
93+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.
98+ ^- [hand=deck rest=deck]
103+`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`.
107+ |= [unshuffled=deck entropy=@]
110+ =/ random ~(. og entropy)
111+ =/ remaining (lent unshuffled)
116+ =^ index random (rads:random remaining)
118+ shuffled (snag index unshuffled)^shuffled
119+ remaining (dec remaining)
120+ unshuffled (oust [index 1] unshuffled)
123+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`.
125+`=|` adds a default-valued `deck` to the subject.
127+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`.
129+`?: =(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.
131+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.
133+With completed, we use `%^` to call `$` to recurse back up to `|-` with a few changes.
135+`shuffled` gets the `darc` from `unshuffled` at `index` added to the front of it.
137+`remaining` gets decremented. Why are we using a counter here instead of just checking the length of `unshuffled` on each loop? `lent` traverses the entire list every time it's called so maintaining a counter in this fashion is much faster.
139+`unshuffled` becomes the result of using `oust` to remove 1 `darc` at `index` on `unshuffled`.
141+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.
145+So now that we have this library, how do we actually use it? Let's look at a very simple `say` generator that uses it.
152+(shuffle-deck:playing-cards make-deck:playing-cards eny)
155+If 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.
157+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`.