515a95f · urbit.org · git.iko.soy

89#### Reading

90

91A connector exposes a tree of data. Every read request has a

92−`care`, which is generally either `%x` or `%y. `%x` is a request

92+`care`, which is generally either `%x` or `%y`. `%x` is a request

93for a particular piece of data, while `%y` is a request for a

94directory listing. Roughly, `%x` means Unix `cat` and `%y` means

95Unix `ls`.

802we don't take any other immediate action. If it was both off and not in

803progress, then we send an HTTP request.

804

805−If the argument is neither 'off' nor 'on', then we assume it's an

805+If the argument is neither `'off'` nor `'on'`, then we assume it's an

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

807

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

811[ost.hid %hiss /request ~ %httr %purl (need (de-purl:html target))]

812```

813

814−> Remember, we are expected to produce a **list** of moves. Note the `~` after the move in the full example. This is a convenient shortcut for creating a list of a single element. It's part of a small family of such shortcuts. `~[a b c]` is `[a b c ~]`, `[a b c]~` is `[[a b c] ~]` and `\`[a b c]` is `[~ a b c]`. These may be mixed and matched to create various convoluted structures and emojis.

814+> Remember, we are expected to produce a **list** of moves. Note the `~` after the move in the full example. This is a convenient shortcut for creating a list of a single element. It's part of a small family of such shortcuts. `~[a b c]` is `[a b c ~]`, `[a b c]~` is `[[a b c] ~]` and `` `[a b c] `` is `[~ a b c]`. These may be mixed and matched to create various convoluted structures and emojis.

815

816The correspondence between this move and `[bone card]` can be hard to

817visualize on one line. Here it is more pedantically:

949 '57'

950```

951

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

952+ASCII `9` is `57`. There's no requirement, implicit or otherwise,

953that conversions back and forth between marks be inverses of each

954other. These are semantic conversions, in that they refer to the

955same concept. They're not isomorphisms.

1246

1247Let's walk through each of these elements step by step.

1248

1249−###### Bones ("cause")

1249+##### Bones ("cause")

1250

1251If you look up `++bone` in `hoon.hoon`, you'll see that it's a number (`@ud`),

1252and that it's an opaque reference to a duct. `++duct` in `hoon.hoon` is a list

1262the event to appropriate kernel module for handling.

1263

1264Sometimes, the module can immediately handle the event and produce any necessary

1265−results. For example, when we poked the `++poke-atom` arm above, we poked %gall,

1265+results. For example, when we poked the `++poke-atom` arm above, we poked `%gall`,

1266our application server, which was able to respond to our poke directly. When the

1267module cannot service the request itself, it sends instructions to another

1268−kernel module or application (through the %gall module) to do a specified

1268+kernel module or application (through the `%gall` module) to do a specified

1269action, and produces the result from that.

1270

1271Furthermore, when one module sends a message to another kernel module or

1300##### Term (sys-call)

1301

1302Each move also has a `term`, composed of lowercase ASCII and/or `-`. This `term`

1303−has the sign `@tas`. In this case, our `term` is `%poke`, which is the name of

1303+has the aura `@tas`. In this case, our `term` is `%poke`, which is the name of

1304the particular kind of move we're sending. You can always use `%poke` to message

1305an app. Other common names include `%warp`, to read from the filesystem;

1306`%wait`, to set a timer; and `%them`, to send an http request.

1323

1324- Modify `pong.hoon` to print out a message when it receives acknowledgement.

1325

1326−- Write two apps, `even` and `odd`. When you pass an atom to `even`, check whether it's even. If so, divide it by two and recurse; otherwise, poke `odd` with it. When `odd` receives an atom, check whether it's equal to one. If so, terminate, printing "%success". Otherwise, check whether it's odd. If so, multiply it by three, add one, and recurse; otherwise, poke `even` with it. When either app receives a number, print it out along with the name of the app. In the end, you should be able to watch Collatz's conjecture play out between the two apps. Sample output:

1326+- Write two apps, `even` and `odd`. When you pass an atom to `even`, check whether it's even. If so, divide it by two and recurse; otherwise, poke `odd` with it. When `odd` receives an atom, check whether it's equal to one. If so, terminate, printing `%success`. Otherwise, check whether it's odd. If so, multiply it by three, add one, and recurse; otherwise, poke `even` with it. When either app receives a number, print it out along with the name of the app. In the end, you should be able to watch Collatz's conjecture play out between the two apps. Sample output:

1327

1328```

1329~fintud-macrep:dojo> :even &atom 18

1350%success

1351```

1352

1353−- Put `even` and `odd` on two separate urbits and pass the messages over the network. Post a link to a working solution in :talk to receive a cookie.

1353+- Put `even` and `odd` on two separate urbits and pass the messages over the network. Post a link to a working solution in `:talk` to receive a cookie.

1354

1355

1356## Security Drivers

1618`+https://api.github.com/user` and get a response indicating who

1619you're logged in as.

1620

1621−Some drivers a slightly more complicated. For example, Github's

1621+Some drivers are slightly more complicated. For example, Github's

1622access token's don't expire, but that's not the case for all

1623−service. The googleapis driver shows the flow when the access

1623+services. The googleapis driver shows the flow when the access

1624token can expire. Twitter uses OAuth1, for which we have another

1625library.

1626

1711of things in `++bowl`, search for `++ bowl` (note: two spaces) in

1712`/arvo/zuse.hoon`.

1713

1714−> This is, perhaps, the most common way to learn Hoon. The easiest way to learn about an identifier you see in code is to search in `/arvo/sys/zuse.hoon` and `/arvo/sys/hoon.hoon` for it.\\ Urbit's codebase is less than 30000 lines of code combined, including the hoon parser, the compiler, and the `/arvo` microkernel, so you can usually use the code and its comments as a reference doc. You can also read [zuse.hoon](https://github.com/urbit/urbit/blob/master/pkg/arvo/sys/zuse.hoon) and [hoon.hoon](https://github.com/urbit/urbit/blob/master/pkg/arvo/sys/hoon.hoon) in your browser.

1714+> This is, perhaps, the most common way to learn Hoon. The easiest way to learn about an identifier you see in code is to search in `/arvo/sys/zuse.hoon` and `/arvo/sys/hoon.hoon` for it. Urbit's codebase is less than 30000 lines of code combined, including the hoon parser, the compiler, and the `/arvo` microkernel, so you can usually use the code and its comments as a reference doc. You can also read [zuse.hoon](https://github.com/urbit/urbit/blob/master/pkg/arvo/sys/zuse.hoon) and [hoon.hoon](https://github.com/urbit/urbit/blob/master/pkg/arvo/sys/hoon.hoon) in your browser.

1715

1716The second thing we should clear up is this: Urbit needs no "serialize to disk"

1717step. Everything you produce in the app state is persistent across calls to the

1724

1725**Exercises**:

1726

1727−- Modify `:sum` to reset the counter when you poke it with 0.

1727+- Modify `:sum` to reset the counter when you poke it with `0`.

1728

1729−- Write an app called `last` that prints out the previous value you poked it with.

1729+- Write an app called `:last` that prints out the previous value you poked it with.

1730

1731Sample output:

1732

1884

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

1886

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

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

1888

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

1890

1924>=

1925```

1926

1927−###### :source

1927+##### :source

1928

1929Hopefully you can get a sense for what's happening here. When we poke

1930`:sink` with `%on`, `:sink` subscribes to `:source`,

1981`[%noun non]`". This is fairly dense code, but what it's doing is

1982straightforward!

1983

1984−###### :sink

1984+##### :sink

1985

1986`:source` should now make sense. `:sink` is a little longer, but not much more

1987complicated.

2001

2002The only state we need for `:sink` is a boolean to indicate whether

2003we're already subscribed to `:source`. We use `val=?`, where `?`

2004−is the sign of type boolean (similar to `*`, `@`), which defaults to true (that

2004+is the type associated with boolean (similar to `*`, `@`), which defaults

2005−is, `0`).

2005+to `%.y` (that is, `0`).

2006

2007−In `++poke-noun` we check our input to see both if it's `%on` and we're

2007+In `++poke-noun` we check our input to see both if it's `%on` and

2008−available (`val` is true). If so, we produce the move to subscribe to

2008+available (`val` is `%.y`). If so, we produce the move to subscribe to

2009`:source`:

2010

2011```hoon

2018==

2019```

2020

2021−Also, in the preceding lines, we set `val` to false (`|`) with `+>.$(val |)`.

2021+Also, in the preceding lines, we set `val` to `%.n` (`|`) with `+>.$(val |)`.

2022Remember that the `:_` constructs an inverted cell, with the first child

2023−(`+>.$(val |` in our case) as the tail and the second child as the head. Here,

2023+(`+>.$(val |)` in our case) as the tail and the second child as the head. Here,

2024−the cell we produce when our subscription is `%on` and `val` is true has a

2024+the cell we produce when our subscription is `%on` and `val` is `%.y` has a

2025−head with our new state where `val` is set to false and a tail of our list of

2025+head with our new state where `val` is set to `%.n` and a tail of our list of

2026moves, which is shown in the code block above.

2027

2028Otherwise, if our input is `%off` and we're already subscribed (i.e. `val`

2029−is false), then we unsubscribe from `:source` and set `val` back to true (`&`),

2029+is `%.n`), then we unsubscribe from `:source` and set `val` back to `%.y` (`&`),

2030again using our handy inverted cell constructor mold `:_`:

2031

2032```hoon

2038one we originally subscribed on.

2039

2040If neither of these cases are true, then we print our current subscription

2041−state, based on whether `val` is true or false, and return a cell containing

2041+state, based on whether `val` is `%.y` or `%.n`, and return a cell containing

2042a null list of moves and our unchanged app state:

2043

2044```hoon

2134

2135We also convert from json by parsing a json string with `so:dejs-soft:format`,

2136asserting the parsing succeeded with `need`, and asserting the

2137−result was 'click' with `?>`, which asserts that its first child

2137+result was `'click'` with `?>`, which asserts that its first child

2138is true.

2139

2140> Note the argument to `++json`is `jon=^json`. Why `^json`? `++json` shadows the type definition, so if we want to refer to the type, we have to prepend a `^`. This extends to multiple levels: `^^^foo` means the fourth most innermost instance of `foo`.

2178`clicks` is just an atom. We convert to json by creating an

2179object with a single field "clicks" with our value.

2180

2181−> Be sure to check out section 3bD, JSON and XML, in zuse.hoon `frond:enjs:format` is just a function that takes a key-value pair and produces a JSON object with one element.

2181+> Be sure to check out section 3bD, JSON and XML, in `zuse.hoon`. `frond:enjs:format` is just a function that takes a key-value pair and produces a JSON object with one element.

2182

2183```

2184~fintud-macrep:dojo> &json &clicks 6

2275```

2276

2277We set up two event handlers. When we click the button, we run

2278−`window.urb.send`, which sends a poke to the app specified as the first argument, in this case our :click app. The arguments

2278+`window.urb.send`, which sends a poke to the app specified as the first argument, in this case our `:click` app. The arguments

2279are data, parameters, and the callback. The data is the specific

2280data we want to send. The parameters are all optional, but here's a list

2281of the available ones:

2296message saying the poke succeeded. As is common, we gray

2297out the button when it is clicked. It is only reenabled when positive acknowledgement is received.

2298

2299−Our second event handler is `window.urb.bind`, which is called immediately when the page is loaded, subscribing the page to the specified data stream on the app set with `urb.appl` (which is, in this case, :click). It also takes three arguments: path, parameters, and callback. The path is the path on the app to subscribe to. The parameters are all optional (indeed, we omit them entirely here), but are similar to those for `send`:

2299+Our second event handler is `window.urb.bind`, which is called immediately when the page is loaded, subscribing the page to the specified data stream on the app set with `urb.appl` (which is, in this case, `:click`). It also takes three arguments: path, parameters, and callback. The path is the path on the app to subscribe to. The parameters are all optional (indeed, we omit them entirely here), but are similar to those for `send`:

2300

2301- `ship`: target urbit. Defaults to `window.urb.ship`, which defaults to the urbit which served the page.

2302- `appl`: target app. Defaults to `window.urb.appl`, which defaults to null.