@@ -0,0 +1,181 @@
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.
67++$ suit ?(%hearts %spades %clubs %diamonds)
68++$ darc [sut=suit val=@ud]
72+The first is `suit`, which can be either `%hearts`, `%spades`, `%clubs`, or `%diamonds`.
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.
76+Our final type is `deck`, which is simply a `list` of `darc`.
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.
92+We can see this is a gate that takes a single `@ud` and produces 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 resulting in a different suit.
110+ mydeck [(num-to-suit i) j]^mydeck
114+`num-to-suit` is used in the `make-deck` arm shown above. This arm should be quite readable to you at this point. Here we simply have two loops where we use counters to build up the full set of 52 cards, by cycling through every possible suit and number and combining them. Once we have reached the point where `j` is greater than 13, we're going to jump back out to the "suit" outer-loop and increment `i`. `?.` may be an unfamiliar rune; it is simply the inverted version of `?:`, so the first branch is actually the "no" branch and the second is the "yes" branch. This is done to keep the "heaviest" branch at the bottom.
120+ ^- [hand=deck rest=deck]
125+`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`.
129+ |= [unshuffled=deck entropy=@]
132+ =/ random ~(. og entropy)
133+ =/ remaining (lent unshuffled)
138+ =^ index random (rads:random remaining)
140+ shuffled (snag index unshuffled)^shuffled
141+ remaining (dec remaining)
142+ unshuffled (oust [index 1] unshuffled)
145+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`.
147+`=|` adds a default-valued `deck` to the subject.
149+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`.
151+`?: =(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.
153+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.
155+With completed, we use `%^` to call `$` to recurse back up to `|-` with a few changes.
157+`shuffled` gets the `darc` from `unshuffled` at `index` added to the front of it.
159+`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.
161+`unshuffled` becomes the result of using `oust` to remove 1 `darc` at `index` on `unshuffled`.
163+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.
167+So now that we have this library, how do we actually use it? Let's look at a very simple `say` generator that takes advantage of what we built.
174+(shuffle-deck:playing-cards make-deck:playing-cards eny)
177+If you save our the library as `playing-cards.hoon` in the `lib` directory, you can import the library with the `/+` rune. Our above `say` -- let's call it `cards.hoon` -- imports our library in this way. It should be noted that `/+` is not a Hoon rune, but instead a rune used by Ford, the Urbit build-system. When `cards.hoon` gets built, Ford will pull in the requested library and also build that. It will also create a dependency so that if `playing-cards.hoon` changes, this file will also get rebuilt.
179+Below `/+ playing-cards`, 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 the entropy and a `deck` created by `make-deck` into `shuffle-deck` to get back a shuffled `deck`.
181+### [Next Up: Reading -- Trees, Sets, and Maps](../trees-sets-and-maps)