222ef82 · urbit.org · git.iko.soy

27Below is a generator that performs a Caesar cipher on a tape. This example

28isn't the most compact implementation of such a cipher in Hoon, but it

29demonstrates important principles that more laconic code would not. Save it as

30−`caesar.hoon` in your `/gen` directory.

30+`caesar.hoon` in the `/gen` directory of your `%base` desk.

31

32```hoon

33!:

131The `!:` in the first line of the above code enables a full stack trace in the

132event of an error.

133

134−`|= [msg=tape steps=@ud]` creates a [gate](/docs/glossary/gate/) that takes a cell. The head of this cell

134+`|= [msg=tape steps=@ud]` creates a [gate](/docs/glossary/gate/) that takes a cell. The head of this cell

135is a `tape`, which is a string type that's a list of `cord`s. Tapes are represented

136as text surrounded by double-quotes, such as this: `"a tape"`. We give this input

137tape the face `msg`. The tail of our cell is a `@ud` -- an unsigned decimal [atom](/docs/glossary/atom/)

141second child expression as the subject. In this case, we evaluate the

142expressions in the code chunk below against the [core](/docs/glossary/core/) declared later, which

143allows us reference the core's contained [arms](/docs/glossary/arm/) before they are defined. Without

144−`=<`, we would need to put the code chunk below at the bottom of our program. In Hoon, as previously

144+`=<`, we would need to put the code chunk below at the bottom of our program. In Hoon, as previously

145stated, we always want to keep the longer code towards the bottom of our programs - `=<` helps us do that.

146

147```hoon

150(unshift msg steps)

151```

152

153−`=. msg (cass msg)` changes the input string `msg` to lowercases. `=.` changes

153+`=. msg (cass msg)` changes the input string `msg` to lowercases. `=.` changes

154the leg of the subject to something else. In our case, the leg to be changed is

155`msg`, and the thing to replace it is `(cass msg)`. `cass` is a standard-library

156gate that converts uppercase letters to lowercase.

157

158−`:- (shift msg steps)` and `(unshift msg steps)` simply composes a

158+`:- (shift msg steps)` and `(unshift msg steps)` simply composes a

159cell of a right-shifted cipher and a left-shifted cipher of our original message.

160We will see how this is done using the core described below, but this is the final

161output of our generator.

162

163`|%` creates a `core`, the second child of `=<`. Everything after `|%` is part of that

164second child `core`, and will be used as the subject of the first child of `=<`, described

165−above. The various parts, or `arm`s, of the `core` are denoted by `++` beneath it, for

165+above. The various parts, or `arm`s, of the `core` are denoted by `++` beneath it, for

166instance:

167

168```hoon

174```

175

176The `rotation` arm takes takes a specified number of characters off of a tape and

177−puts them on the end of the tape. We're going to use this to create our shifted alphabet,

177+puts them on the end of the tape. We're going to use this to create our shifted alphabet,

178based on the number of `steps` given as an argument to our gate.

179

180−`|= [my-alphabet=tape my-steps=@ud]` creates a gate that takes two arguments: `my-alphabet`, a `tape`,

180+`|= [my-alphabet=tape my-steps=@ud]` creates a gate that takes two arguments: `my-alphabet`, a `tape`,

181and `my-steps`, a `@ud`.

182

183−`=/ length=@ud (lent my-alphabet)` stores the length of `my-alphabet` to make the following

183+`=/ length=@ud (lent my-alphabet)` stores the length of `my-alphabet` to make the following

184code a little clearer.

185

186`trim` is a a gate from the standard library that splits a tape at into two

187−parts at a specified position. So `=+ (trim (mod my-steps length) my-alphabet)` splits the

187+parts at a specified position. So `=+ (trim (mod my-steps length) my-alphabet)` splits the

188tape `my-alphabet` into two parts, `p` and `q`, which are now directly available in the subject.

189We call the modulus operation `mod` to make sure that the point at which we split our `tape` is

190a valid point inside of `my-alphabet` even if `my-steps` is greater than `length`, the length of

191−`my-alphabet`. Try trim in the dojo:

191+`my-alphabet`. Try trim in the dojo:

192

193```

194> (trim 2 "abcdefg")

221associates a key with a value. If, for example, we wanted to have an association

222between `a` and 1 and `b` and 2, we could use a `map`.

223

224−`|= [a=tape b=tape]` builds a gate that takes two tapes, `a` and `b`, as its

224+`|= [a=tape b=tape]` builds a gate that takes two tapes, `a` and `b`, as its

225sample.

226

227−`^- (map @t @t)` casts the gate to a `map` with a `cord` (or `@t`) key and a `cord`

227+`^- (map @t @t)` casts the gate to a `map` with a `cord` (or `@t`) key and a `cord`

228value.

229

230You might wonder, if our gate in this arm takes `tape`s, why then are we producing

231a map of `cord` keys and values?

232

233−As we discussed earlier, a `tape` is a list of `cord`s. In this case what we are going to do

233+As we discussed earlier, a `tape` is a list of `cord`s. In this case what we are going to do

234is map a single element of a `tape` (either our alphabet or shifted-alphabet) to an element of

235−a different `tape` (either our shifted-alphabet or our alphabet). This pair will therefore be

235+a different `tape` (either our shifted-alphabet or our alphabet). This pair will therefore be

236−a pair of `cord`s. When we go to use this `map` to convert our incoming `msg`, we will take

236+a pair of `cord`s. When we go to use this `map` to convert our incoming `msg`, we will take

237each element (`cord`) of our `msg` `tape`, use it as a `key` when accessing our `map` and get

238the corresponding `value` from that position in the `map`. This is how we're going to encode

239or decode our `msg` `tape`.

240

241−`=| chart=(map @t @t)` adds a [noun](/docs/glossary/noun/) to the subject with the default value of

241+`=| chart=(map @t @t)` adds a [noun](/docs/glossary/noun/) to the subject with the default value of

242the `(map @t @t)` type, and gives that noun the face `chart`.

243

244−`?. =((lent key-position) (lent value-result))` checks if the two `tape`s are the same length. If not,

244+`?. =((lent key-position) (lent value-result))` checks if the two `tape`s are the same length. If not,

245−the program crashes with an error message of `%uneven-lengths`, using `|~ %uneven-lengths !!`.

245+the program crashes with an error message of `%uneven-lengths`, using `|~ %uneven-lengths !!`.

246

247If the two `tape`s are of the same length, we continue on to create a trap.

248`|-` creates a [trap](/docs/glossary/trap/), a gate that is called immediately.

249

250−`?: |(?=(~ key-position) ?=(~ value-result))` checks if either `tape` is empty. If this is true, the

250+`?: |(?=(~ key-position) ?=(~ value-result))` checks if either `tape` is empty. If this is true, the

251`map-maker` arm is finished and can return `chart`, the `map` that we have been

252creating.

253

254If the above test finds that the `tape`s are not empty, we trigger a recursion

255that constructs our `map`: `$(chart (~(put by chart) i.a i.b), a t.a, b t.b)`.

256This code recursively adds an entry in our `map` where the head of the `tape` `a`

257−maps to the value of the head of `tape` `b` with `~(put by chart)`, our calling

257+maps to the value of the head of `tape` `b` with `~(put by chart)`, our calling

258of the `put` arm of the `by` map-engine core (note that `~(<wing> <door> <sample>`) is

259−a shorthand for `%~ <wing> <door> <sample>` (see the [Calls % ('cen')](/docs/hoon/reference/rune/cen#censig)

259+a shorthand for `%~ <wing> <door> <sample>` (see the [Calls % ('cen')](/docs/hoon/reference/rune/cen#censig)

260documentation for more information). The recursion also "consumes"

261those heads with every iteration by changing `a` and `b` to their tails using `a t.a, b t.b`.

262

271 (~(put by (map-maker key-position value-result)) ' ' ' ')

272```

273

274−`|= [key-position=tape value-result=tape]` creates a gate that takes two `tapes`.

274+`|= [key-position=tape value-result=tape]` creates a gate that takes two `tapes`.

275

276We use the `put` arm of the `by` core on the next line, giving it a `map` produced

277by the `map-maker` arm that we created before as its sample. This adds an entry to the

300In both cases, we create a gate that accepts a `@ud` named `steps`.

301

302In `encoder`:

303−`=/ value-tape=tape (rotation alpha steps)` creates a `value-tape` noun by calling `rotation`

303+`=/ value-tape=tape (rotation alpha steps)` creates a `value-tape` noun by calling `rotation`

304on `alpha`. `alpha` is our arm which contains a `tape` of the entire alphabet. The

305`value-tape` will be the list of `value`s in our `map`.

306

307In `decoder`:

308−`=/ key-tape (rotation alpha steps)` does the same work, but when passed to `space-adder`

308+`=/ key-tape (rotation alpha steps)` does the same work, but when passed to `space-adder`

309it will be the list of `key`s in our `map`.

310

311`(space-adder alpha value-tape)`, for `encoder`, and `(space-adder key-tape alpha)`, for