@@ -11,7 +11,7 @@ input and produce an output, then disappear. Generators might make sense for
11listing directory contents, or running unit tests, or fetching the contents of a
11listing directory contents, or running unit tests, or fetching the contents of a
14−There are four kinds of generators: naked, `%say`, `%get`, and `%ask`.
14+There are three kinds of generators: naked, `%say`, and `%ask`. There also used to be a fourth type of generator, `%get`, but this kind is no longer in use.
16### Naked Generators
16### Naked Generators
@@ -454,150 +454,7 @@ This is a [known issue](https://github.com/urbit/arvo/issues/840) to be resolved
455### `%get` generators
455### `%get` generators
457−`%get` generators are used for making HTTP requests through `eyre`. For this
457+`%get` generators no longer exist. They were once used for making HTTP requests through `eyre`. Such functionality is no longer supported with generators.
458−section we'll assume knowledge of generators covered in previous sections, so
459−we can jump in with an example:
466−|= [* [url=tape ~] ~]
467−^- (sole-request:sole (cask json))
468−%+ curl (scan url auri:de-purl:html)
471−=/ my-json (de-json:html q.u.r.hit)
481−The above generator was written with the
482−[Studio Ghibli API](https://ghibliapi.herokuapp.com/). It uses this API to
483−print the title of a Studio Ghibli film.
491−Here we import types from `/sur/sole.hoon` and gates from
492−`/lib/generators.hoon`. We also use `=,` to expose the namespace of
493−`generators` that we just imported.
497−|= [* [url=tape ~] ~]
500−Like with `%say` and `%ask` generators, we must include the "boilerplate":
501−code that produces a generator-specific `cell`. The head of that cell is `%get`,
502−and the tail is a gate that takes a `tape` of the URL that we are trying
506−^- (sole-request:sole (cask json))
509−Here we make sure our gate is producing a `sole-request` which contains a `cask`
514−%+ curl (scan url auri:de-purl:html)
518−Here we can see the call to `curl`, the sample of which will parse our url and
519−make sure it's in the proper format.
521−The second part of the `curl` call is the `gate` that will get called with the
522−result provided by the actual HTTP request.
528−Here we verify that the `r` face of our response is not null before
529−continuing. If it is null, the generator will crash, as there is nothing left to
533−=/ my-json (de-json:html q.u.r.hit)
536−Here we verify that data was returned to us in the `json` Hoon type.
537−`q.u.r.hit` is the actual data we care about as a `cord`. `hit` is actually an
538−entire response object, including headers, which we don't care about for this
539−example. `de-json` out of `html` will parse the `cord` and produce a `json` type
540−for us that we can then use to inspect the data.
547−After parsing the JSON structure we want to make sure we got back a valid `json`
548−type. To do that, we test for null and crash if that test passes. If it doesn't
549−pass, we use `=,` on the `dejs:format` core so that we can more easily pull arms
558−Now we come to our `produce` call. Recall that `produce` is used in all the
559−non-naked generators to output the final result. Here we want to produce a
560−`cask` of `json`, so we use the mark `%json` to indicate that.
562−Next we have what may be an unfamiliar rune: `%.`. This rune is simply `%-` with
563−the argument order reversed. `%title` is the argument passed to the next gate
564−that is called. `by` is the core that is the `map` engine. A Hoon `map` is a
565−key-value pair structure, sometimes referred to as a dictionary in other
566−languages. `got` is the arm in `by` that will produce a gate that we can call to
567−access members of a given `map`.
569−> The idiomatic way to write Hoon is to have the
570− "heaviest" code paths lowest in the program, which is why `%.`
571− is preferred in this case over `%-`. Use of this style is recommended, as it
572− results in code that is much easier to read.
574−At the moment, however, we do not have a `map`, but instead have a `json` type.
581−Here we use `om`, which is an arm in `dejs:format` that will take a `json` and
582−return a `map`. `same` is a wet gate from the standard library that takes an
583−argument of any type and returns it as that type. We could use any other gate to
584−modify the data if that were useful for the particular data we are going to be
585−processing, but here we want the data exactly as it is.
587−Since `my-json` is a `unit` of `json`, the actual data we are looking for is in
588−`u.my-json`. We take this and give it to the gate produced by the call to `om`.
589−This gate is going to transform our data by taking in the `json` structure and
590−producing a `map`. Then we can look up keys in this map using `got` from
593−`%.` performs the same function as `%-`, the rune used to call a function,
594−except with the arguments reversed so that the function is last and
595−the arguments of that function come first. It's used here to keep with the
596−principle that heaviest, or most complex, expressions should go to the bottom.
598−The key we are looking up in our new `map` we've created from `my-json` is
599−`%title`, which is an element in the original source, to produce the final
600−result of the generator.
602## Conclusion
459## Conclusion