172195e · urbit.org · git.iko.soy

git.iko.soy/urbit.org

clarified some things for beginniners

commit172195e5e64907a36402af859cb59866b4f9e5cb authorRobert <robert@tlon.io> dateThu 21 Mar 2019, 13:41 (8 years ago) parent4614e19

3 files changed+19−11

compare with master

unifiedsplit

learn/hoon/hoon-tutorial/nouns.udon+13−5 learn/hoon/workbook/list.udon+5−5 using.udon+1−1

learn/hoon/hoon-tutorial/nouns.udon+13−5

@@ -12,7 +12,7 @@ In Urbit every piece of data is a noun. In order to understand Hoon one must fi

1212

1313## Noun Definition

1414

15−A *noun* is either an atom or a cell. An *atom* is an unsigned integer of any size. A *cell* is an [ordered pair](https://en.wikipedia.org/wiki/Ordered_pair) of nouns, usually indicated with square brackets around the nouns in question; i.e., `[a b]`, where `a` and `b` are nouns.

15+A *noun* is either an atom or a cell. An *atom* is a natural number ("unsigned integer" in computer lingo) of any size, including zero. A *cell* is an [ordered pair](https://en.wikipedia.org/wiki/Ordered_pair) of nouns, usually indicated with square brackets around the nouns in question; i.e., `[a b]`, where `a` and `b` are nouns.

1616

1717Here are some atoms:

1818

@@ -121,7 +121,9 @@ As for why the dojo deleted your zero: it parses the command line as you type, a

121121

122122### Atom Auras

123123

124−Atoms are nothing more than unsigned integers, but it's often useful to interpret an atom as being a different kind of data. This is done with an *aura*. The aura of an atom is type meta-data used by Hoon to determine how interpret that atom. It answers the question: What type of information is this atom?

124+Atoms are nothing more than unsigned integers -- natural numbers -- but it's often useful to represent an atom in a different way. This is done with an *aura*. The aura of an atom is type meta-data used by Hoon to determine how to interpret that atom. It answers the question: What type of information is this atom?

125+

126+We use auras because data isn't always represented as a positive decimal number. Sometimes we want to represent data as binary, as text, or as a negative number. Auras allow us to to use such types of data _without changing the underlying atom_.

125127

126128We won't fully explain auras and their various uses yet. Auras will be covered more comprehensively in a later lesson. For now let's just look at the various kinds of [literal syntax](https://en.wikipedia.org/wiki/Literal_(computer_programming%29) associated with a few atom auras.

127129

@@ -185,7 +187,7 @@ The `\`@\`` syntax is used to 'cast' a value to a raw atom, i.e., an atom withou

185187

186188#### Identities, Cords, and Terms

187189

188−Urbit identities such as `~zod` and `~sorreg-namtyv` are also atoms with their own distinctive syntax:

190+Urbit identities such as `~zod` and `~sorreg-namtyv` are also atoms, but of the aura `@p`:

189191

190192```

191193> ~zod

@@ -197,11 +199,17 @@ Urbit identities such as `~zod` and `~sorreg-namtyv` are also atoms with their o

197199> `@`~zod

1982000

199201

202+> `@p`0

203+~zod

204+

200205> `@`~sorreg-namtyv

2012065.702.400

207+

208+> `@p`5.702.400

209+~sorreg-namtyv

202210```

203211

204−Hoon permits the use of atoms as strings. Strings that are encoded as atoms are called *cords*. The literal syntax of a cord is text inside a pair of single-quotes, e.g., `'Hello world!'`.

212+Hoon permits the use of atoms as strings. Strings that are encoded as atoms are called *cords*. Cords are of the aura `@t`. The literal syntax of a cord is text inside a pair of single-quotes, e.g., `'Hello world!'`.

205213

206214```

207215> 'Howdy!'

@@ -217,7 +225,7 @@ Hoon permits the use of atoms as strings. Strings that are encoded as atoms are

21722510.334.410.032.606.748.633.331.426.632

218226```

219227

220−Hoon also has *terms*. These are strings preceded with a `%` and made up of lower-case letters, numbers, and hyphens, i.e., 'kebab case'. The first character after the `%` must be a letter. For example, `%a`, `%hello`, `%this-is-kebab-case123`.

228+Hoon also has *terms*, of the aura `@tas`. Terms are constant values that are used to tag data using the type system. These are strings preceded with a `%` and made up of lower-case letters, numbers, and hyphens, i.e., 'kebab case'. The first character after the `%` must be a letter. For example, `%a`, `%hello`, `%this-is-kebab-case123`.

221229

222230```

223231> %howdy

learn/hoon/workbook/list.udon+5−5

@@ -23,11 +23,11 @@ Below is a simple Hoon program that takes a single number `n` from the user as i

2323$(count (add 1 count)) :: 8

2424```

2525

26−The easiest way to use such a program is to run it as a _generator_. Saving a file in the `/home/gen` directory of your ship allows you to run it from your ship's Dojo (command line) as a generator. Save the above code there as `list.udon`. Now you can run it in the Dojo as so:

26+The easiest way to use such a program is to run it as a _generator_. Saving a file in the `/home/gen` directory of your ship allows you to run it from your ship's Dojo (command line) as a generator. Save the above code there as `list.hoon`. Now you can run it in the Dojo as so:

2727

2828`~your-ship:> +list 5`

2929

30−Try it! You can choose any natural number to put after `+list`, but it can't be zero or blank. The `+` lets the Dojo know that it's looking for a generator with the name that follows.

30+Try it! You can choose any natural number to put after `+list`, but it can't be zero or blank. The `+` lets the Dojo know that it's looking for a generator with the name that follows. You don't write out the `.hoon` part of the file name when running it in the Dojo.

3131

3232But what do all these squiggly symbols in the program _do_? It probably isn't immediately clear. Let's go through each component of this code.

3333

@@ -45,7 +45,7 @@ In our example program, we use comments with line numbers for convenient referen

4545

4646There's a few things going on in our first line. The first part of it, `|=`, is a kind of *rune*. Runes are the building blocks of all Hoon code, represented as a pair of non-alphanumeric ASCII characters. Runes form expressions; runes are used how keywords are used in other languages. In other words, all computations in Hoon ultimately require runes. Runes and other Hoon expressions are all separated from one another by either two spaces or a line break.

4747

48−All runes take a fixed number of "children." Children can themselves be runes with children, and Hoon programs work by chaining through these until a value -- not another rune -- is arrived at. Keep this scheme in mind when examining Hoon code.

48+All runes take a fixed number of "children." Children can themselves be runes with children, and Hoon programs work by chaining through these until a value -- not another rune -- is arrived at. For this reason, we very rarely need to close expressions. Keep this scheme in mind when examining Hoon code.

4949

5050The specific purpose of the `|=` rune is to create a *gate*. A gate is what would be called a function in other languages: it takes an input, performs a specified computation, and then produces an output.

5151

@@ -63,7 +63,7 @@ This line begins with the `=/` rune, which stores a value with a name and specif

6363

6464`count=@` (the first child) stores `1` (the second child) as `count` and as specifies that has the `@` type.

6565

66−We're using `count` to keep track of what numbers we're adding to the list we're building. We'll use it later in the program.

66+We're using `count` to keep track of what numbers we're including in the list we're building. We'll use it later in the program.

6767

6868### Line 3

6969

@@ -110,7 +110,7 @@ $(count (add 1 count))

110110

111111The above code is, once again, a compact way of writing a rune expression. All you need to know is that this line of code restarts the program at `|-`, except with the value stored in `count` incremented by 1. The construction of `(count (add 1 count))` tells the computer, "replace the value of count with count+1".

112112

113−You'll notice that we use an unfamiliar word here: `add`. Unlike `count` and `end`, `add` is not defined anywhere in our program. That's because it's a gate that's predefined in the Hoon *standard library*. The standard library is filled with pre-defined gates that are generally useful, and these gates can be used just like something that you defined in your own program.

113+You'll notice that we use an unfamiliar word here: `add`. Unlike `count` and `end`, `add` is not defined anywhere in our program. That's because it's a gate that's predefined in the Hoon *standard library*. The standard library is filled with pre-defined gates that are generally useful, and these gates can be used just like something that you defined in your own program. You can see this gate, and other mathematical operators, in [section 1a](/docs/reference/library/1a) of the standard-library documentation.

114114

115115## Explanation

116116

using.udon+1−1

@@ -6,7 +6,7 @@

77# Using

9−This section contains guides to using your Urbit.

9+This section contains guides to using your urbit.

1010

1111- [Admin and Operation](admin) is a guide to the basic commands used to interact with your ship.

1212- [Messaging](messaging) tells you how to use Talk, our chat system.