9d0e129 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

various minor gall doc fixes

commit9d0e12996a0b804bd70caca44bd034261f977a33 authorjoshuareagan <joshuareagan@gmail.com> dateTue 2 Oct 2018, 13:24 (8 years ago) parentc2f44cf

9 files changed+100−128

compare with master

unifiedsplit

docs/reference/troubleshooting.umd+3−3 docs/tutorials/gall/api.umd+19−19 docs/tutorials/gall/generators.umd+56−59 docs/tutorials/gall/http.umd+6−17 docs/tutorials/gall/marks.umd+4−2 docs/tutorials/gall/network.umd+2−2 docs/tutorials/gall/security-driver.umd+8−24 docs/tutorials/gall/state.umd+1−1 docs/tutorials/gall/subscriptions.umd+1−1

docs/reference/troubleshooting.umd+3−3

@@ -1,10 +1,10 @@

11:- :~ navhome/'/docs/'

22 sort/'6'

3− title/'Troubleshooting'

3+ title/'Hoon Errors'

44 ==

55;>

7−# Troubleshooting

7+# Hoon Errors

99Ideally your Hoon works perfectly the first time. But...

1010

@@ -163,7 +163,7 @@ The worst possibility, of course, is that your code runs but does

163163the wrong thing. This is relatively unusual in a typed

164164functional language, but it still happens.

165165

166−`~&` ([*sigpam*](../rune/sig/pam)) is Hoon's debugging printf.

166+`~&` ([*sigpad*](../rune/sig/pad)) is Hoon's debugging printf.

167167This pretty-prints its argument:

168168

169169```

docs/tutorials/gall/api.umd+19−19

@@ -27,8 +27,8 @@ After starting `%gh` (`|start %gh`), let's look at the root of

2727the tree that `%gh` exposes:

2828

2929```

30− ~your-urbit:dojo> .^(arch %gy /=gh=)

31− [fil=~ dir={[p=~.issues q=~]}]

30+~your-urbit:dojo> .^(arch %gy /=gh=)

31+[fil=~ dir={[p=~.issues q=~]}]

3232```

3333

3434`%gh` is currently a skeleton -- it contains examples of all the

@@ -37,18 +37,18 @@ aren't implemented. As we can see here, only issues are

3737implemented. We can explore this tree:

3838

3939```

40− ~your-urbit:dojo> .^(arch %gy /=gh=/issues)

41− [fil=~ dir={[p=~.by-repo q=~] [p=~.mine q=~]}]

40+~your-urbit:dojo> .^(arch %gy /=gh=/issues)

41+[fil=~ dir={[p=~.by-repo q=~] [p=~.mine q=~]}]

4242```

4343

4444And eventually:

4545

4646```

47− /- gh

48− .^(issue:gh %gx /=gh=/issues/by-repo/philipcmonktest/testing/7)

49− <issue...>

50− login.user:.^(issue:gh %gx /=gh=/issues/by-repo/philipcmonktest/testing/7)

51− 'philipcmonktest'

47+/- gh

48+.^(issue:gh %gx /=gh=/issues/by-repo/philipcmonktest/testing/7)

49+<issue...>

50+login.user:.^(issue:gh %gx /=gh=/issues/by-repo/philipcmonktest/testing/7)

51+'philipcmonktest'

5252```

5353

5454The other thing an API connector needs to do is expose event

@@ -56,14 +56,14 @@ streams. One straightforward way to use this capacity is with

5656the `:pipe` app:

5757

5858```

59− :pipe|connect %gh /listen/philipcmonktest/testing/issues/'issue_comment' %public

59+:pipe|connect %gh /listen/philipcmonktest/testing/issues/'issue_comment' %public

6060```

6161

6262Now creating an issue results in the following message in your

6363`%public` `:talk` channel:

6464

6565```

66− ~your-urbit[philipcmonktest@github]: opened issue #11: i found a bug!

66+~your-urbit[philipcmonktest@github]: opened issue #11: i found a bug!

6767```

6868

6969You'll also get notifications of issue status changes and

@@ -104,20 +104,20 @@ returned by a place). This can just be a line at the top of the

104104main core:

105105

106106```

107− =+ connector=(connector move sub-result) :: Set up connector library

107+=+ connector=(connector move sub-result) :: Set up connector library

108108```

109109

110110Most of the Github-specific logic is in `++places`, which is a

111111list of all the places we can request. A place consists of:

112112

113113```

114− ++ place

115− $: guard/mold

116− read-x/$-(path move)

117− read-y/$-(path move)

118− sigh-x/$-(jon/json (unit sub-result))

119− sigh-y/$-(jon/json (unit arch))

120− ==

114+++ place

115+ $: guard/mold

116+ read-x/$-(path move)

117+ read-y/$-(path move)

118+ sigh-x/$-(jon/json (unit sub-result))

119+ sigh-y/$-(jon/json (unit arch))

120+ ==

121121```

122122

123123- `guard`, the type of the paths we should match. For example, to match `/issues/<user>/<repo>` use `{$issues @t @t $~}`.

docs/tutorials/gall/generators.umd+56−59

@@ -31,10 +31,10 @@ Another generator is `+hood/merge`. Try running `+hood/merge` with the

3131normal arguments for `|merge`:

3232

3333```

34− ~fintud-macrep:dojo> +hood/merge %home our %they

35− [syd=%home her=~fintud-macrep sud=%they gem=%auto]

36− ~fintud-macrep:dojo> +hood/merge %home our %they, =gem %this

37− [syd=%home her=~fintud-macrep sud=%they gem=%auto]

34+~fintud-macrep:dojo> +hood/merge %home our %they

35+[syd=%home her=~fintud-macrep sud=%they gem=%auto]

36+~fintud-macrep:dojo> +hood/merge %home our %they, =gem %this

37+[syd=%home her=~fintud-macrep sud=%they gem=%auto]

3838```

3939

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

@@ -66,66 +66,63 @@ it lets the user optionally specify the message as well.

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

6767`examples-ping-message`.

6868

69−> For app-specific marks, it's good style to prefix the name of the mark

70−> with the name of the app. Since many apps have several such marks,

71−> subdirectories in `/mar` are rendered as `-`, so that `ping-message`

72−> is written in (/mar/examples/ping/message.hoon).

69+> 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/examples/ping/message.hoon).

7370

7471```

75− ::

76− :::: /hoon/message/ping/examples/app

77− ::

78− /? 314

79− |_ [to=@p message=@t]

80− ++ grab

81− |%

82− ++ noun [@p @t]

83− --

84− --

72+::

73+:::: /hoon/message/ping/examples/app

74+ ::

75+/? 314

76+|_ [to=@p message=@t]

77+++ grab

78+ |%

79+ ++ noun [@p @t]

80+ --

81+--

8582```

8683

8784The app can easily be modified to use this (`/app/examples/ping.hoon`):

8885

8986```

90− :: Allows one ship to ping another with a string of text

91− ::

92− :::: /hoon/ping/examples/app

93− ::

94− /? 314

95− |%

96− ++ move [bone term wire *]

97− --

98− !:

99− |_ [bowl:gall state=$~]

100− ::

101− ++ poke-examples-ping-message

102− |= [to=@p message/@t}

103− ~& 'sent'

104− ^- [(list move) _+>.$]

105− :- ^- (list move)

106− :~ `move`[ost %poke /sending [to dap] %atom message]

107− ==

108− +>.$

109− ::

110− ++ poke-atom

111− |= arg=@

112− ~& 'received'

113− ^- [(list move) _+>.$]

114− ::

115− ~& [%receiving (@t arg)]

116− [~ +>.$]

117− ::

118− ++ coup |=(* `+>)

119− --

87+:: Allows one ship to ping another with a string of text

88+::

89+:::: /hoon/ping/examples/app

90+ ::

91+/? 314

92+|%

93+ ++ move [bone term wire *]

94+--

95+!:

96+|_ [bowl:gall state=$~]

97+::

98+++ poke-examples-ping-message

99+ |= [to=@p message/@t}

100+ ~& 'sent'

101+ ^- [(list move) _+>.$]

102+ :- ^- (list move)

103+ :~ `move`[ost %poke /sending [to dap] %atom message]

104+ ==

105+ +>.$

106+::

107+++ poke-atom

108+ |= arg=@

109+ ~& 'received'

110+ ^- [(list move) _+>.$]

111+ ::

112+ ~& [%receiving (@t arg)]

113+ [~ +>.$]

114+::

115+++ coup |=(* `+>)

116+--

120117```

121118

122119Now we can run this with:

123120

124121```

125− ~fintud-macrep:dojo> |start %examples-ping

126− >=

127− ~fintud-macrep:dojo> :examples-ping &examples-ping-message [~sampel-sipnym 'heyya']

128− >=

122+~fintud-macrep:dojo> |start %examples-ping

123+>=

124+~fintud-macrep:dojo> :examples-ping &examples-ping-message [~sampel-sipnym 'heyya']

125+>=

129126```

130127

131128And on `~sampel-sipnym`, assuming it's running `:examples-ping` as well,

@@ -137,9 +134,9 @@ mandatory, and optional arguments are hard. Let's make a generator,

137134`:examples-ping`, let's put it in `/gen/examples/ping/send.hoon`:

138135

139136```

140− :- %say

141− |= [^ [to=@p message=?($~ [text=@t $~])] $~]

142− [%examples-ping-message to ?~(message 'howdy' text.message)]

137+:- %say

138+|= [^ [to=@p message=?($~ [text=@t $~])] $~]

139+[%examples-ping-message to ?~(message 'howdy' text.message)]

143140```

144141

145142A couple of new things here. Firstly, `message=?($~ [text=@t $~])`

@@ -154,10 +151,10 @@ anything that's in either `a` or `b`. Thus, in our case,

154151This is run as follows:

155152

156153```

157− ~fintud-macrep:dojo> :examples-ping|send ~sampel-sipnym

158− >=

159− ~fintud-macrep:dojo> :examples-ping|send ~sampel-sipnym 'how do you do'

160− >=

154+~fintud-macrep:dojo> :examples-ping|send ~sampel-sipnym

155+>=

156+~fintud-macrep:dojo> :examples-ping|send ~sampel-sipnym 'how do you do'

157+>=

161158```

162159

163160Which causes `~sampel-sipnym` to print `[%receiving 'howdy']` and

docs/tutorials/gall/http.umd+6−17

@@ -84,17 +84,9 @@ code quoted above includes a bunch of otherwise unnecessary faces for

8484the purpose of illustration. Compare: `[%hiss p=(unit iden) q=mark

8585r=cage]` from `zuse`.

8686

87−> You can grep zuse.hoon and arvo.hoon for most of these definitions.

88−> However, beware the ambiguity surrounding "hiss": there's ++hiss in

89−> section 3bI of `zuse` ("Arvo structures"), and there's `%hiss` the

90−> move that is sent to %eyre to make our HTTP request happen. Here we're

91−> talking about the latter. See `++kiss-eyre` in `zuse`.

92−

93−> Recall that `++unit` means "maybe". Formally, "`(unit a)` is

94−> either null or a pair of null and a value in `a`". Also recall

95−> that to pull a value out of a unit (`u.unit`), you must first

96−> verify that the unit is not null (for example with `?~`). See

97−> `++need`.

87+> You can grep zuse.hoon and arvo.hoon for most of these definitions. However, beware the ambiguity surrounding "hiss": there's ++hiss in section 3bI of `zuse` ("Arvo structures"), and there's `%hiss` the move that is sent to %eyre to make our HTTP request happen. Here we're talking about the latter. See `++kiss-eyre` in `zuse`.

88+

89+> Recall that `++unit` means "maybe". Formally, "`(unit a)` is either null or a pair of null and a value in `a`". Also recall that to pull a value out of a unit (`u.unit`), you must first verify that the unit is not null (for example with `?~`). See `++need`.

9890

9991A `purl` is a parsed url structure, which can be created with `++epur`,

10092which is a function that takes a url as text and parses it into a `(unit

@@ -107,9 +99,7 @@ response, which we handle later on in `++sigh-httr`.

10799For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will

108100produce a `%wake` when the time comes.

109101

110−> A timer is guaranteed to not be triggered before the given

111−> time, but it's currently impossible to guarantee the timer will be

112−> triggered at exactly the requested time.

102+> A timer is guaranteed to not be triggered before the given time, but it's currently impossible to guarantee the timer will be triggered at exactly the requested time.

113103

114104Let's take a look at our state:

115105

@@ -130,9 +120,7 @@ of `value`, but make the default value be `value`". Thus, our

130120type is still a boolean, just like `?`, but the default value is

131121`|` (false).

132122

133−> This is the same `_` used in `_+>.$`, which means "the same

134−> type as the value "+>.$". In other words, the same type as our

135−> current context and state.

123+> This is the same `_` used in `_+>.$`, which means "the same type as the value "+>.$". In other words, the same type as our current context and state.

136124

137125Let's take a look at `++poke-atom`. When we're poked with an atom, we

138126first check whether the atom is `'off'`. If so, we set our state

@@ -147,6 +135,7 @@ If the argument is neither 'off' nor 'on', then we assume it's an

147135actual url, so we save it in `target`.

148136

149137Here's the move that sends the HTTP request:

138+

150139```

151140[ost.hid %hiss /request ~ %httr %purl (need (epur target))]

152141```

docs/tutorials/gall/marks.umd+4−2

@@ -62,10 +62,12 @@ marked atom and convert it to our new mark.

6262```

6363~fintud-macrep:dojo> &atom 9

64649

65+

6566~fintud-macrep:dojo> &examples-cord &atom 9

6667'9'

67−-~fintud-macrep:dojo> &examples-cord &atom &examples-cord &atom 9

68− -'57'

68+

69+~fintud-macrep:dojo> &examples-cord &atom &examples-cord &atom 9

70+ '57'

6971```

7072

7173ASCII 9 is 57. There's no requirement, implicit or otherwise,

docs/tutorials/gall/network.umd+2−2

@@ -62,7 +62,7 @@ from the command line, which we we did with `:echo 5`

6262(`:[app-name] [argument(s)]`).

6363

6464In this case, `++poke-noun` takes an argument (*sample*) `arg` and

65−prints it to dojo with `~&` ([sigpam](../../hoon/rune/sig/pam/)).

65+prints it to dojo with `~&` ([sigpad](../../../reference/rune/sig/pad/)).

6666This is an unusual rune that formally "does nothing", but the interpreter

6767detects it and printfs the first child, before executing the second as if the

6868first didn't exist. This is a slightly hacky way of printing to the console,

@@ -153,7 +153,7 @@ so we'll be getting quite used to them.

153153

154154*Exercise*:

155155

156−- Write an app that computes fizzbuzz on its input (as in the previous section).

156+- Write an app that computes fizzbuzz on its input.

157157

158158## Sending a message to another urbit

159159

docs/tutorials/gall/security-driver.umd+8−24

@@ -38,7 +38,7 @@ simplest way to interact with the Github API is to just fetch

3838https://api.github.com from the dojo:

3939

4040```

41− ~your-urbit:dojo> +https://api.github.com

41+~your-urbit:dojo> +https://api.github.com

4242```

4343

4444Github exposes a few endpoints to the general web, and the root

@@ -91,7 +91,7 @@ you're logged in as.

9191You can similarly POST:

9292

9393```

94− ~your-urbit:dojo> +https://api.github.com/gists &json _(cork poja need) '{"files":{"file1.txt":{"content":"can\'t stop the signal"}}}'

94+~your-urbit:dojo> +https://api.github.com/gists &json _(cork poja need) '{"files":{"file1.txt":{"content":"can\'t stop the signal"}}}'

9595```

9696

9797This creates a gist, go to `https://gist.github.com/<username>` to

@@ -107,7 +107,7 @@ Let's take a look at the code and see if we can figure out what's

107107happening here:

108108

109109```

110− /+ basic-auth

110+/+ basic-auth

111111```

112112

113113First, we load a library called `basic-auth`. This library

@@ -131,30 +131,14 @@ Additionally, a security driver contains at least one out of the

131131five "special" arms:

132132

133133- `++filter-request` is a function which takes a hiss (http request) and produces a `sec-move` (defined in zuse), which is one of:

134−

135−```

136− * `[%send hiss]`, which sends the new hiss. This is the

137− case in, for example, basic auth, where all we need to do is

138− add an extra header to the request.

139− * `[%give httr]`, where httr is an http response. This

140− immediately returns an http response to the sender.

141− * `[%show purl]`, where a purl is a parsed url. This displays

142− a message asking the user to visit the given url to continue

143− the authentication process.

144− * `[%redo ~]`, which redoes the request.

145−

146− * `%eyre` calls `++filter-request` just before sending an HTTP

147− request to the specified domain. This allows the security

148− driver to filter the requests, decorating them with

149− authentication data.

150−```

151−

134+ - `[%send hiss]`, which sends the new hiss. This is the case in, for example, basic auth, where all we need to do is add an extra header to the request.

135+ - `[%give httr]`, where httr is an http response. This immediately returns an http response to the sender.

136+ - `[%show purl]`, where a purl is a parsed url. This displays a message asking the user to visit the given url to continue the authentication process.

137+ - `[%redo ~]`, which redoes the request.

138+ - `%eyre` calls `++filter-request` just before sending an HTTP request to the specified domain. This allows the security driver to filter the requests, decorating them with authentication data.

152139- `++filter-response` is a function which takes an httr and produces a `sec-move`. `%eyre` calls it after receiving an HTTP response from the specified domain. This allows the security driver to handle authentication errors, commonly caused by expired tokens, and retry the request.

153−

154140- `++receive-auth-query-string` is a function that takes a `quay` (list of query parameters) and produces a `sec-move`. `%eyre` calls it when it receives a request on the callback url. Generally, this happens in OAuth after the user has granted access to the urbit app, and the service makes a request to the callback url with the code. The security driver should then make a request to convert the code into an access token.

155−

156141- `++receive-auth-response` is a function that takes an httr and produces a `sec-move`. `%eyre` calls it when it gets a response to the request made in `++receive-auth-query-string`.

157−

158142- `++update` is a function which converts old state to a new format when the security driver gets updated. If you want to just get rid of the old state, define `++discard-state` as `~`.

159143

160144For basic auth, we only have to worry about `++filter-request`,

docs/tutorials/gall/state.umd+1−1

@@ -80,7 +80,7 @@ memory, which you need to serialize to disk if you want to keep it around for

8080very long.

8181

8282In Urbit, app state is a single (usually complex) value. In our example, we have

83−very simple state, so we defined `sum/@`, meaning that our state is an atom.

83+very simple state, so we defined `sum=@`, meaning that our state is an atom.

8484Of course, `sum` is just a name, and you're free to name your state whatever

8585you like. But let's clarify a couple other things before we continue.

8686

docs/tutorials/gall/subscriptions.umd+1−1

@@ -142,7 +142,7 @@ Two notes:

142142

143143- `bowl` is the type of the system state within our app. For example, it includes things like `our`, the name of the host urbit, and `now`, the current time.

144144

145−- You may have noticed the separate `|%` ([barcen](../../hoon/rune/bar/cen/)) above the application core `|_` ([barcab](../../hoon/rune/bar/cab/). We usually put our types in another core on top of the application core. We can access these type from our `|_` because in `hoon.hoon` files, all cores are called against each other. (The shorthand for 'called' is `=>`.) Thus, the `|%` with the types is in the context of the `|_`, as it lies above it: `hoon.hoon` `=> |% w types => |_`

145+- You may have noticed the separate `|%` above the application core `|_`. We usually put our types in another core on top of the application core. We can access these type from our `|_` because in `hoon.hoon` files, all cores are called against each other. (The shorthand for 'called' is `=>`.) Thus, the `|%` with the types is in the context of the `|_`, as it lies above it: `hoon.hoon` `=> |% w types => |_`

146146

147147Here's some sample output of the two working together:

148148