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

docs/reference/troubleshooting.umd+3−3

compare with master

unifiedsplit

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

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

2 sort/'6'

3− title/'Troubleshooting'

3+ title/'Hoon Errors'

4 ==

5;>

6

7−# Troubleshooting

7+# Hoon Errors

8

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

10

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

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

164functional language, but it still happens.

165

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

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

167This pretty-prints its argument:

168

169```

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

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

27the tree that `%gh` exposes:

28

29```

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

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

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

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

32```

33

34`%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

37implemented. We can explore this tree:

38

39```

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

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

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

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

42```

43

44And eventually:

45

46```

47− /- gh

47+/- gh

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

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

49− <issue...>

49+<issue...>

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

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

51− 'philipcmonktest'

51+'philipcmonktest'

52```

53

54The 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

56the `:pipe` app:

57

58```

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

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

60```

61

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

63`%public` `:talk` channel:

64

65```

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

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

67```

68

69You'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

104main core:

105

106```

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

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

108```

109

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

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

112

113```

114− ++ place

114+++ place

115− $: guard/mold

115+ $: guard/mold

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

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

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

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

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

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

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

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

120− ==

120+ ==

121```

122

123- `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

31normal arguments for `|merge`:

32

33```

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

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

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

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

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

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

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

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

38```

39

40This 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.

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

67`examples-ping-message`.

68

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

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).

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).

73

70

74```

71```

75− ::

72+::

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

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

77− ::

74+ ::

78− /? 314

75+/? 314

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

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

80− ++ grab

77+++ grab

81− |%

78+ |%

82− ++ noun [@p @t]

79+ ++ noun [@p @t]

83− --

80+ --

84− --

81+--

85```

82```

86

83

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

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

88

85

89```

86```

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

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

91− ::

88+::

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

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

93− ::

90+ ::

94− /? 314

91+/? 314

95− |%

92+|%

96− ++ move [bone term wire *]

93+ ++ move [bone term wire *]

97− --

94+--

98− !:

95+!:

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

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

100− ::

97+::

101− ++ poke-examples-ping-message

98+++ poke-examples-ping-message

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

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

103− ~& 'sent'

100+ ~& 'sent'

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

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

105− :- ^- (list move)

102+ :- ^- (list move)

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

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

107− ==

104+ ==

108− +>.$

105+ +>.$

109− ::

106+::

110− ++ poke-atom

107+++ poke-atom

111− |= arg=@

108+ |= arg=@

112− ~& 'received'

109+ ~& 'received'

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

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

114− ::

111+ ::

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

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

116− [~ +>.$]

113+ [~ +>.$]

117− ::

114+::

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

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

119− --

116+--

120```

117```

121

118

122Now we can run this with:

119Now we can run this with:

123

120

124```

121```

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

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

126− >=

123+>=

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

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

128− >=

125+>=

129```

126```

130

127

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

128And 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,

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

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

138

135

139```

136```

140− :- %say

137+:- %say

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

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

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

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

143```

140```

144

141

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

142A 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,

154This is run as follows:

151This is run as follows:

155

152

156```

153```

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

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

158− >=

155+>=

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

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

160− >=

157+>=

161```

158```

162

159

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

160Which 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

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

85r=cage]` from `zuse`.

86

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

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−> However, beware the ambiguity surrounding "hiss": there's ++hiss in

88+

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

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`.

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`.

98

90

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

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

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

92which 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`.

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

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

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

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

109

101

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

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.

112−> triggered at exactly the requested time.

113

103

114Let's take a look at our state:

104Let's take a look at our state:

115

105

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

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

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

131`|` (false).

121`|` (false).

132

122

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

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

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.

135−> current context and state.

136

124

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

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

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

126first 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

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

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

148

136

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

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

138+

150```

139```

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

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

152```

141```

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

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

62```

63~fintud-macrep:dojo> &atom 9

649

65+

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

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

66'9'

67'9'

68+

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

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

68− -'57'

70+ '57'

69```

71```

70

72

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

73ASCII 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`

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

63

64In 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/)).

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

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

68first 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.

153

154*Exercise*:

155

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.

157

158## Sending a message to another urbit

159

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

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

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

39

40```

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

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

42```

43

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

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

91You can similarly POST:

92

93```

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"}}}'

95```

96

97This 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

107happening here:

108

109```

110− /+ basic-auth

110+/+ basic-auth

111```

112

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

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

131five "special" arms:

132

133- `++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

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.

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.

135+ - `[%give httr]`, where httr is an http response. This 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

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.

143− the authentication process.

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

137+ - `[%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

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.

148− driver to filter the requests, decorating them with

149− authentication data.

150−```

151−

152- `++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.

139- `++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−

154- `++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.

140- `++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−

156- `++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`.

141- `++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−

158- `++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 `~`.

142- `++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 `~`.

159

143

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

144For 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

80very long.

81

82In 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.

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

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

86

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

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

142

143- `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.

144

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 => |_`

146

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

148