docs/tutorials/gall/generators.udon · urbit.org

git.iko.soy/urbit.org

on c19bc7a help sign in

urbit.org/docs/tutorials/gall/generators.udon

172 lines 5.6 kB history raw

1:- :~ navhome/'/docs/'

2 navuptwo/'true'

3 next/'true'

4 sort/'6'

5 title/'Using generators with apps'

6 ==

7;>

9# Generators

11Up until now we've poked apps directly. This requires the user to

12specify the mark, and it requires the app to accept the arguments in a

13way that's convenient for users to input. This is the "plumbing" way to

14interact with apps. Generators are the "porcelain" layer. This is why

15when you run a command like `+ls` or `|merge`, there are no marks in

16sight.

18We've used generators before, back in [Basic

19Operation](/docs/using/admin). At that point, we just used the

20generators to produce values -- we didn't pipe their results into apps.

21In the dojo cast, the role of a generator is to take a list of arguments

22and produce a value, which is often, though not always, piped into an

23app. Generators are pure, stateless functions, and they cannot send

24moves.

26`+ls` and `+cat` are commonly-used generators that produce a directory

27listing and print out a file, respectively. These are useful in

28themselves, so we generally don't pipe the results into an app.

30Another generator is `+hood/merge`. Try running `+hood/merge` with the

31normal arguments for `|merge`:

33```

34> +hood/merge %home our %they

35[syd=%home her=~zod sud=%they cas=[%da p=~2018.10.4..21.11.49..901c] gem=%auto]

37> +hood/merge %home our %they, =gem %this

38[syd=%home her=~zod sud=%they cas=[%da p=~2018.10.4..21.12.11..ee32] gem=%this]

39```

41This didn't run any merge, it just constructed the command that, if sent

42to `:hood`, would run it. Note first that, even though it's not printed,

43this value has mark `kiln-merge`. Also, the merge strategy `gem=%auto`

44was added automatically. Optional arguments are straightforward with

45generators.

47In general, generators are prepended by either `+` or `|`. The general

48form is `+generator`, but often generators are created specifically to

49work with a single app, they're usually placed in a subdirectory of gen

50and run with `|`. Thus, if `my-generator` generator is made for use with

51`:my-app`, then `my-generator` is put in

52`/gen/my-app/my-generator.hoon`, and can be run directly with

53`+my-app/my-generator <args>`. If you want to pipe the result into

54`:my-app`, then run `:my-app +my-app/my-generator <args>`. Because this

55pattern is so common, this can be abbreviated to

56`:my-app|my-generator <args>`. Because most built-in commands are

57generators for the `:hood` app, `:hood|generator <args>` can be

58shortened to `|generator <args>`.

60Let's write a generator for a modified version of `:pong` from

61the chapter on [Network Messages](/docs/arvo/system/network). Recall

62that `:pong` takes an urbit address, which is of mark `urbit`,

63and sends that urbit the message `'howdy'`. First--without a

64generator--let's make `:ping` that does the same, except that

65it lets the user optionally specify the message as well.

67We'll need a new mark for our arguments. Let's call it

68`ping-message`.

70> For app-specific marks, it's good style to prefix the name of the mark with the name of the app. Since many apps have several such marks, subdirectories in `/mar` are rendered as `-`, so that `ping-message` is written in (/mar/ping/message.hoon).

72```

73::

74:::: /mar/ping/message/hoon

75 ::

76/? 314

77|_ [to=@p message=@t]

78++ grab

79 |%

80 +$ noun [@p @t]

81 --

82--

83```