urbit/developers.urbit.org
1
1
Fork 0
mirror of https://github.com/urbit/developers.urbit.org.git synced 2024-09-11 13:55:59 +03:00
Code Issues Packages Projects Releases Wiki Activity

Post corrected top blocks for HS.

Browse Source
This commit is contained in:
Sigilante 2022-06-27 11:38:22 -05:00
parent 74ab57ca12
commit 2267dc193f
21 changed files with 429 additions and 226 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
content/guides/additional/overview.md
View File

@ -19,7 +19,7 @@ media primitives and common factors. The docs for Graph Store have been moved
to the Urbit-native `%docs` app.
```hoon
|install ~TODO %docs
|install ~pocwet %docs
```
## [Threads](/guides/additional/threads/)
@ -50,4 +50,3 @@ using the `@urbit/http-api` Javascript module.
uses to represent text.
- [Unit tests](/guides/additional/hoon/unit-tests) afford the developer
confidence in designing code and avoiding certain categories of bugs.

318
content/guides/core/hoon-school/.ipynb_checkpoints/manipulator-checkpoint.ipynb Normal file
View File

@ -0,0 +1,318 @@
{
"cells": [
{
"cell_type": "code",
"execution_count": 40,
"id": "f11e2531",
"metadata": {},
"outputs": [],
"source": [
"from glob import glob\n",
"\n",
"filenames = glob('*-*.md')\n",
"\n",
"import re"
]
},
{
"cell_type": "code",
"execution_count": 43,
"id": "4214fd19",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"A-intro.md\n",
"B-syntax.md\n",
"C-azimuth.md\n",
"D-gates.md\n",
"E-types.md\n",
"F-cores.md\n",
"G-trees.md\n",
"H-libraries.md\n",
"I-testing.md\n",
"J-stdlib-text.md\n",
"K-doors.md\n",
"L-struct.md\n",
"L2-struct.md\n",
"M-logic.md\n",
"N-subject.md\n",
"O-stdlib-io.md\n",
"P-func.md\n",
"Q-metals.md\n",
"R-math.md\n"
]
}
],
"source": [
"for filename in sorted(filenames):\n",
" with open(filename, 'r') as f:\n",
" text = f.read()\n",
" text = text.replace('nodes: ', 'nodes: [')\n",
" sol = text.find('nodes: [')\n",
" eol = text[sol:].find('\\n') + sol\n",
" text = text[:eol]+']'+text[eol:]\n",
" \n",
" text = text.replace('objectives:\\n - ', 'objectives: [')\n",
" sol = text.find('objectives: [')\n",
" eol = text[sol:].find('---') + sol\n",
" text = text[:eol]+']'+text[eol:]\n",
" i = sol\n",
" while text[i:i+3] != '---':\n",
" if text[i:i+5] == '\\n - ':\n",
" text = text[:i]+\", \"+text[i+5:]\n",
" i += 1\n",
" \n",
" text = text.replace('\\n]---\\n', ']\\n+++\\n')\n",
" text = text.replace('---\\n', '+++\\n')\n",
" \n",
" with open(filename, 'w') as f:\n",
" f.write(text)\n",
" print(filename)"
]
},
{
"cell_type": "code",
"execution_count": 44,
"id": "bb5f47b2",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"A-intro.md\n",
"B-syntax.md\n",
"C-azimuth.md\n",
"D-gates.md\n",
"E-types.md\n",
"F-cores.md\n",
"G-trees.md\n",
"H-libraries.md\n",
"I-testing.md\n",
"J-stdlib-text.md\n",
"K-doors.md\n",
"L-struct.md\n",
"L2-struct.md\n",
"M-logic.md\n",
"N-subject.md\n",
"O-stdlib-io.md\n",
"P-func.md\n",
"Q-metals.md\n",
"R-math.md\n"
]
}
],
"source": [
"for filename in sorted(filenames):\n",
" with open(filename, 'r') as f:\n",
" text = f.read()\n",
" text = text.replace('\"], [\"', '\", \"')\n",
" with open(filename, 'w') as f:\n",
" f.write(text)\n",
" print(filename)"
]
},
{
"cell_type": "code",
"execution_count": 45,
"id": "9399188a",
"metadata": {},
"outputs": [],
"source": [
"!git mv R-math.md S-math.md"
]
},
{
"cell_type": "code",
"execution_count": 46,
"id": "07dae118",
"metadata": {},
"outputs": [],
"source": [
"!git mv Q-metals.md R-metals.md"
]
},
{
"cell_type": "code",
"execution_count": 48,
"id": "a7e31ca0",
"metadata": {},
"outputs": [],
"source": [
"!git mv R-fund.md R-func.md"
]
},
{
"cell_type": "code",
"execution_count": 49,
"id": "25bb6d78",
"metadata": {},
"outputs": [],
"source": [
"!git mv R-func.md Q-func.md"
]
},
{
"cell_type": "code",
"execution_count": 50,
"id": "5a97e7f7",
"metadata": {},
"outputs": [],
"source": [
"!git mv O-stdlib-io.md P-stdlib-io.md"
]
},
{
"cell_type": "code",
"execution_count": 51,
"id": "5063edea",
"metadata": {},
"outputs": [],
"source": [
"!git mv N-subject.md O-subject.md"
]
},
{
"cell_type": "code",
"execution_count": 52,
"id": "4fef1acd",
"metadata": {},
"outputs": [],
"source": [
"!git mv M-logic.md N-logic.md"
]
},
{
"cell_type": "code",
"execution_count": 53,
"id": "e875e80e",
"metadata": {},
"outputs": [],
"source": [
"!git mv L2-struct.md M-struct.md"
]
},
{
"cell_type": "code",
"execution_count": 54,
"id": "a54b515d",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/R-math.md/S-math.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": 55,
"id": "4271af78",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/Q-metals.md/R-metals.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": 56,
"id": "0ca7cd68",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/P-func.md/Q-func.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": 57,
"id": "ecb03df8",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/O-stdlib-io.md/P-stdlib-io.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": 58,
"id": "92d1eb7b",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/N-subject.md/O-subject.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": 59,
"id": "04de4f25",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/M-logic.md/N-logic.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": 60,
"id": "5bc1bfa2",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/L2-struct.md/M-struct.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": 61,
"id": "daf9b75e",
"metadata": {},
"outputs": [],
"source": [
"!git mv M-struct.md M-typecheck.md"
]
},
{
"cell_type": "code",
"execution_count": 62,
"id": "264f0e44",
"metadata": {},
"outputs": [],
"source": [
"!sed -i 's/M-struct.md/M-typecheck.md/g' *.md"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b64a8014",
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.7"
}
},
"nbformat": 4,
"nbformat_minor": 5
}

17
content/guides/core/hoon-school/A-intro.md
View File

@ -1,11 +1,10 @@
---
title: Introduction to Hoon
nodes: 100, 103
objectives:
- "Explain what an Urbit ship is."
- "Distinguish a fakeship from a liveship."
- "Pronounce ASCII characters per standard Hoon developer practice."
---
+++
title = "Introduction to Hoon"
weight = 10
template = "doc.html"
nodes: [100, 103]
objectives: ["Explain what an Urbit ship is.", "Distinguish a fakeship from a liveship.", "Pronounce ASCII characters per standard Hoon developer practice."
+++
# Introduction to Hoon
@ -114,7 +113,7 @@ Hoon uses _runes_, or two-character ASCII symbols, to describe its structure. (
It is highly advisable for you to learn these pronunciations, as the documentation and other developers employ them frequently. For instance, a rune like `|=` is called a “bartis”, and you will find it designated as such in the docs, in the source code, and among the developers.
| Name | Character | Name | Character | Name | Character |
| ---- | ----- | ---- | ----- | ---- | ----- |
| ]---- | ----- | ---- | ----- | ---- | ----- |
| `ace` | `␣` | `gap` | `␣␣`, `\n` | pat | `@` |
| `bar` | `|` | `gar` | `>` | `sel` | `[` |
| `bas` | `\` | `hax` | `#` | `ser` | `]` |

15
content/guides/core/hoon-school/B-syntax.md
View File

@ -1,15 +1,8 @@
---
+++
title: Hoon Syntax
nodes: 110, 113
objectives:
- "Distinguish nouns, cells, and atoms."
- "Apply auras to transform an atom."
- "Identify common Hoon molds, such as cells, lists, and tapes."
- "Pin a face to the subject."
- "Make a decision at a branch point."
- "Distinguish loobean from boolean operations."
- "Slam a gate (call a function)."
---
nodes: [110, 113]
objectives: ["Distinguish nouns, cells, and atoms.", "Apply auras to transform an atom.", "Identify common Hoon molds, such as cells, lists, and tapes.", "Pin a face to the subject.", "Make a decision at a branch point.", "Distinguish loobean from boolean operations.", "Slam a gate (call a function)."]
+++
# Hoon Syntax

20
content/guides/core/hoon-school/C-azimuth.md
View File

@ -1,18 +1,10 @@
---
title: The Structure of Azimuth
nodes: 102, 112
objectives:
- "Understand the role of the public-key infrastructure in Urbit."
- "Describe the high-level architecture of the Urbit ID address space and distinguish types of points."
- "Interpret and apply the Azimuth point naming scheme."
- "Identify point features such as activity."
- "List at least two services/roles provided by a galaxy for the network."
- "List at least two services provided by a star for its planets."
- "Use Hoon to map the Azimuth address space domains and boundaries."
- "Identify points, sponsors, neighbors, etc. from `@p` identifiers and simple operations."
---
+++
title: Azimuth (Urbit ID)
nodes: [102, 112]
objectives: ["Understand the role of the public-key infrastructure in Urbit.", "Describe the high-level architecture of the Urbit ID address space and distinguish types of points.", "Interpret and apply the Azimuth point naming scheme.", "Identify point features such as activity.", "List at least two services/roles provided by a galaxy for the network.", "List at least two services provided by a star for its planets.", "Use Hoon to map the Azimuth address space domains and boundaries.", "Identify points, sponsors, neighbors, etc. from `@p` identifiers and simple operations."]
+++
# The Structure of Azimuth
# Azimuth (Urbit ID)
_This module introduces how Urbit ID is structured and provides practice in converting and working with `@p` identity points. It may be considered optional and skipped if you are speedrunning Hoon School._

18
content/guides/core/hoon-school/D-gates.md
View File

@ -1,16 +1,8 @@
---
title: Gates
nodes: 111, 115, 120
objectives:
- "Use the `+ls` generator to show a directory's contents."
- "`|mount` and `|commit` a desk."
- "Identify current known irregular syntax."
- "Convert between regular and irregular forms of runes to date."
- "Employ a gate to defer a computation."
- "Produce a gate as a generator."
- "Annotate Hoon code with comments."
- "Produce a generator to convert a value between auras."
---
+++
title: Gates (Functions)
nodes: [111, 115, 120]
objectives: ["Use the `+ls` generator to show a directory's contents.", "`|mount` and `|commit` a desk.", "Identify current known irregular syntax.", "Convert between regular and irregular forms of runes to date.", "Employ a gate to defer a computation.", "Produce a gate as a generator.", "Annotate Hoon code with comments.", "Produce a generator to convert a value between auras."]
+++
# Gates (Functions)

16
content/guides/core/hoon-school/E-types.md
View File

@ -1,14 +1,8 @@
---
title: Gates
nodes: 125
objectives:
- "Identify a mold in the hierarchy of Urbit types (nouns, molds, marks)."
- "Understand how type inference and type checking takes place."
- "Bunt a mold."
- "Produce a type union."
- "Produce a named tuple."
- "Identify type using `!>`."
---
+++
title: Molds (Types)
nodes: [125]
objectives: ["Identify a mold in the hierarchy of Urbit types (nouns, molds, marks).", "Understand how type inference and type checking takes place.", "Bunt a mold.", "Produce a type union.", "Produce a named tuple.", "Identify type using `!>`."]
+++
# Molds (Types)

17
content/guides/core/hoon-school/F-cores.md
View File

@ -1,15 +1,8 @@
---
+++
title: Cores
nodes: 130, 133
objectives:
- "Employ a trap to produce a reentrant block of code."
- "Produce a recursive gate."
- "Distinguish head and tail recursion."
- "Consider Hoon structures as cores."
- "Identify the special role of the `$` buc arm in many cores."
- "Order neighboring cores within the subject for addressibility."
- "Produce a type arm."
---
nodes: [130, 133]
objectives: ["Employ a trap to produce a reentrant block of code.", "Produce a recursive gate.", "Distinguish head and tail recursion.", "Consider Hoon structures as cores.", "Identify the special role of the `$` buc arm in many cores.", "Order neighboring cores within the subject for addressibility.", "Produce a type arm."]
+++
# Cores
@ -347,7 +340,7 @@ This core defines a set of types intended to work with playing cards:
+$ rank ?(1 2 3 4 5 6 7 8 9 10 11 12 13)
+$ card [sut=suit val=rank]
+$ deck (list card)
---
--
```
#### Cores in Generators

26
content/guides/core/hoon-school/G-trees.md
View File

@ -1,20 +1,8 @@
---
+++
title: Trees, Addressing, and Lists
nodes: 135, 140, 156
objectives:
- "Address nodes in a tree using numeric notation."
- "Address nodes in a tree using lark notation."
- "Address data in a tree using faces."
- "Distinguish `.` and `:` notation."
- "Diagram Hoon structures such as gates into the corresponding abstract syntax tree."
- "Use lists to organize data."
- "Convert between kinds of lists (e.g. tapes)."
- "Diagram lists as binary trees."
- "Operate on list elements using `snag`, `find`, `weld`, etc."
- "Explain how Hoon manages the subject and wing search paths."
- "Explain how to skip to particular matches in a wing search path through the subject."
- "Identify common Hoon patterns: batteries, and doors, arms, wings, and legs."
---
nodes: [135, 140, 156]
objectives: ["Address nodes in a tree using numeric notation.", "Address nodes in a tree using lark notation.", "Address data in a tree using faces.", "Distinguish `.` and `:` notation.", "Diagram Hoon structures such as gates into the corresponding abstract syntax tree.", "Use lists to organize data.", "Convert between kinds of lists (e.g. tapes).", "Diagram lists as binary trees.", "Operate on list elements using `snag`, `find`, `weld`, etc.", "Explain how Hoon manages the subject and wing search paths.", "Explain how to skip to particular matches in a wing search path through the subject.", "Identify common Hoon patterns: batteries, and doors, arms, wings, and legs."]
+++
# Trees, Addressing, and Lists
@ -200,7 +188,7 @@ A null-terminated tuple is almost the same thing as a list. (That is, to Hoon a
## Addressing Limbs
Everything in Urbit is a binary tree. And all code in Urbit is also represented as data. One corollary of these facts is that we can access any arbitrary part of an expression, gate, core, whatever, via addressing (assuming proper permissions, of course). (In fact, we can even hot-swap parts of cores, which is how [wet gates](./Q-metals.md) work.)
Everything in Urbit is a binary tree. And all code in Urbit is also represented as data. One corollary of these facts is that we can access any arbitrary part of an expression, gate, core, whatever, via addressing (assuming proper permissions, of course). (In fact, we can even hot-swap parts of cores, which is how [wet gates](./R-metals.md) work.)
There are three different ways to access values:
@ -236,7 +224,7 @@ Much like relative directions, one can also state “left, left, right, left”
![](binary-tree-lark.png)
Lark notation can locate a position in a tree of any size. However, it is most commonly used to grab the head or tail of a cell, e.g. in the _type spear_ (on which [more later](./L2-struct.md)):
Lark notation can locate a position in a tree of any size. However, it is most commonly used to grab the head or tail of a cell, e.g. in the _type spear_ (on which [more later](./M-typecheck.md)):
```hoon
-:!>('hello Mars')
@ -772,8 +760,6 @@ First, bind these faces.
- Write a gate that takes in a list `a` and returns `%.y` if `a` is a palindrome and `%.n` otherwise. You may use the `++flop` function.
---
#### Solutions to Exercises
- Fruit Tree:

20
content/guides/core/hoon-school/H-libraries.md
View File

@ -1,16 +1,8 @@
---
+++
title: Libraries
nodes: 145, 153, 175
objectives:
- "Import a library using `/+` faslus."
- "Create a new library in `/lib`."
- "Identify the role of a desk in the Clay filesystem."
- "Identify the components of a beak."
- "Identify filesystem locations (including desks)."
- "Identify the components of a path."
- "Build code samples with `-build-file` thread."
- "Discuss Ford import runes."
---
nodes: [145, 153, 175]
objectives: ["Import a library using `/+` faslus.", "Create a new library in `/lib`.", "Identify the role of a desk in the Clay filesystem.", "Identify the components of a beak.", "Identify filesystem locations (including desks).", "Identify the components of a path.", "Build code samples with `-build-file` thread.", "Discuss Ford import runes."]
+++
# Libraries
@ -77,7 +69,7 @@ Watch for these being used in generators and libraries over the next few modules
#### Exercise: A Playing Card Library
In this exercise, we examine a library that can be used to represent a deck of 52 playing cards. The core below builds such a library, and can be accessed by programs. You should recognize most of the things this program does aside from the `++shuffle-deck` arm which uses a [door](./K-doors.md) to produce [randomness](./N-subject.md). This is fairly idiomatic Hoon and it relies a lot on the convention that heavier code should be lower in the expression. This means that instead of `?:` wutcol you may see [`?.` wutdot](https://urbit.org/docs/hoon/reference/rune/wut#-wutdot), which inverts the order of the true/false arms, as well as other new constructions.
In this exercise, we examine a library that can be used to represent a deck of 52 playing cards. The core below builds such a library, and can be accessed by programs. You should recognize most of the things this program does aside from the `++shuffle-deck` arm which uses a [door](./K-doors.md) to produce [randomness](./O-subject.md). This is fairly idiomatic Hoon and it relies a lot on the convention that heavier code should be lower in the expression. This means that instead of `?:` wutcol you may see [`?.` wutdot](https://urbit.org/docs/hoon/reference/rune/wut#-wutdot), which inverts the order of the true/false arms, as well as other new constructions.
```hoon
|%
@ -242,7 +234,7 @@ Unfortunately `/` fas runes don't work in the Dojo right now, so we need to buil
> =playing-cards -build-file /===/lib/playing-cards/hoon
```
We then invoke it using the _entropy_ or system randomness. (This is an unpredictable value we will use when we want a process to be random. We will discuss it in detail when we talk about [subject-oriented programming](./N-subject.md).)
We then invoke it using the _entropy_ or system randomness. (This is an unpredictable value we will use when we want a process to be random. We will discuss it in detail when we talk about [subject-oriented programming](./O-subject.md).)
```hoon
> =deck (shuffle-deck:playing-cards make-deck:playing-cards eny)

15
content/guides/core/hoon-school/I-testing.md
View File

@ -1,13 +1,10 @@
---
title: Building Code Confidently
nodes: 170, 190
objectives:
- "Run existing unit tests."
- "Produce a unit test."
- "Employ a debugging strategy to identify and correct errors in Hoon code."
---
+++
title: Testing Code
nodes: [170, 190]
objectives: ["Run existing unit tests.", "Produce a unit test.", "Employ a debugging strategy to identify and correct errors in Hoon code."]
+++
# Building Code Confidently
# Testing Code
_This module will discuss how we can have confidence that a program does what it claims to do, using unit testing and debugging strategies._

27
content/guides/core/hoon-school/J-stdlib-text.md
View File

@ -1,21 +1,12 @@
---
title: Handling Text
nodes: 160, 163
objectives:
- "Review Unicode text structure."
- "Distinguish cords and tapes and their characteristics."
- "Transform and manipulate text using text conversion arms."
- "Interpolate text."
- "Employ sigpam logging levels."
- "Create a `%say` generator."
- "Identify how Dojo sees and interprets a generator as a cell with a head tag."
- "Identify the elements of a `sample` for a `%say` generator."
- "Produce a `%say` generator with optional arguments."
---
+++
title: Text Processing I
nodes: [160, 163]
objectives: ["Review Unicode text structure.", "Distinguish cords and tapes and their characteristics.", "Transform and manipulate text using text conversion arms.", "Interpolate text.", "Employ sigpam logging levels.", "Create a `%say` generator.", "Identify how Dojo sees and interprets a generator as a cell with a head tag.", "Identify the elements of a `sample` for a `%say` generator.", "Produce a `%say` generator with optional arguments."]
+++
# Text Processing I
_This module will discuss how text is represented in Hoon, discuss tools for producing and manipulating text, and introduce the `%say` generator, a new generator type. We don't deal with formatted text (`tank`s) or parsers here, deferring that discussion. Formatted text and text parsing are covered [in a later module](./O-stdlib-io.md)._
_This module will discuss how text is represented in Hoon, discuss tools for producing and manipulating text, and introduce the `%say` generator, a new generator type. We don't deal with formatted text (`tank`s) or parsers here, deferring that discussion. Formatted text and text parsing are covered [in a later module](./P-stdlib-io.md)._
## Text in Hoon
@ -115,7 +106,7 @@ A further tweak of the ASCII-only concept, the `@tas` `term` permits only “tex
`term`s are rarely used for message-like text, but they are used all the time for internal labels in code. They differ from regular text in a couple of key ways that can confuse you until you're used to them.
For instance, a `@tas` value is also a mold, and the value will _only_ match its own mold, so they are commonly used with [type unions](./M-logic.md) to filter for acceptable values.
For instance, a `@tas` value is also a mold, and the value will _only_ match its own mold, so they are commonly used with [type unions](./N-logic.md) to filter for acceptable values.
```hoon
> ^- @tas %5
@ -330,7 +321,7 @@ To _tokenize_ text is to break it into pieces according to some rule. For insta
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
```
Hoon has a sophisticated parser built into it that [we'll use later](./O-stdlib-io.md). There are a lot of rules to deciding what is and isn't a rune, and how the various parts of an expression relate to each other. We don't need that level of power to work with basic text operations, so we'll instead use basic `list` tools whenever we need to extract or break text apart for now.
Hoon has a sophisticated parser built into it that [we'll use later](./P-stdlib-io.md). There are a lot of rules to deciding what is and isn't a rune, and how the various parts of an expression relate to each other. We don't need that level of power to work with basic text operations, so we'll instead use basic `list` tools whenever we need to extract or break text apart for now.
#### Exercise: Break Text at a Space
@ -637,8 +628,6 @@ Having already saved the library as `/lib/playing-cards.hoon`, you can import it
Below `/+ playing-cards`, you have the standard `say` generator boilerplate that allows us to get a bit of entropy from `arvo` when the generator is run. Then we feed the entropy and a `deck` created by `make-deck` into `shuffle-deck` to get back a shuffled `deck`.
---
#### Solutions to Exercises
- Roll-Your-Own-`++snag`:

18
content/guides/core/hoon-school/K-doors.md
View File

@ -1,12 +1,8 @@
---
title: Doors
nodes: 150, 155
objectives:
- "Identify the structure of a door and relate it to a core."
- "Pull an arm in a door."
- "Build cores for later use and with custom samples."
- "Identify the `$` buc arm in several structures and its role."
---
+++
title: Cores and Doors
nodes: [150, 155]
objectives: ["Identify the structure of a door and relate it to a core.", "Pull an arm in a door.", "Build cores for later use and with custom samples.", "Identify the `$` buc arm in several structures and its role."]
+++
# Cores and Doors
@ -193,7 +189,7 @@ It follows from this definition that a gate is a special case of a door. A gate
Doors are created with the [`|_` barcab](https://urbit.org/docs/hoon/reference/rune/bar#_-barcab) rune. Doors get used for a few different purposes in the standard library:
- instrumenting and storing persistent data structures like `map`s (this module and the next)
- implementing state machines (the [subject-oriented programming module](./N-subject.md))
- implementing state machines (the [subject-oriented programming module](./O-subject.md))
One BIG pitfall for thinking about doors is thinking of them as “containing” gates, as if they were more like “objects”. Instead, think of them the same way as you think of gates, just that they can be altered at a higher level.
@ -369,7 +365,7 @@ Readers with some mathematical background may notice that `~( )` expressions all
Thus, you may think of the `c` door as a function for making functions. Use the `~(arm c arg)` syntax—`arm` defines which kind of gate is produced (i.e., which arm of the door is used to create the gate), and `arg` defines the value of `b` in that gate, which in turn affects the product value of the gate produced.
The standard library provides [currying functionality](./P-func.md) outside of the context of doors.
The standard library provides [currying functionality](./Q-func.md) outside of the context of doors.
#### Creating Doors with a Modified Sample

11
content/guides/core/hoon-school/L-struct.md
View File

@ -1,11 +1,8 @@
---
+++
title: Data Structures
nodes: 183
objectives:
- "Identify units, sets, maps, and compound structures like jars and jugs."
- "Explain why units and vases are necessary."
- "Use helper arms and syntax: `` ` ``, `biff`, `some`, etc."
---
nodes: [183]
objectives: ["Identify units, sets, maps, and compound structures like jars and jugs.", "Explain why units and vases are necessary.", "Use helper arms and syntax: `` ` ``, `biff`, `some`, etc."]
+++
# Data Structures

13
content/guides/core/hoon-school/L2-struct.md → content/guides/core/hoon-school/M-typecheck.md
View File

@ -1,9 +1,8 @@
---
+++
title: Type Checking
nodes: 183
objectives:
- "Use assertions to enforce type constraints."
---
nodes: [183]
objectives: ["Use assertions to enforce type constraints."]
+++
# Type Checking
@ -208,7 +207,7 @@ nest-fail
nest-fail
```
We'll talk in more detail about the various kinds of type-checking that can occur at arm evaluation [when we discuss type polymorphism](./Q-metals.md).
We'll talk in more detail about the various kinds of type-checking that can occur at arm evaluation [when we discuss type polymorphism](./R-metals.md).
This isn't a comprehensive list of the type checks in Hoon: for instance, some other runes that include a type check are [`=.`](https://urbit.org/docs/hoon/reference/rune/tis#-tisdot) and [`%_` cencab](https://urbit.org/docs/hoon/reference/rune/cen#_-cencab).
@ -253,7 +252,7 @@ It's important to remember to include a cast rune with each gate and trap expres
### (Dry) Gate Sample Definitions
By now you've used the `|=` rune to define several gates. This rune is used to produce a _dry gate_, which has different type-checking and type-inference properties than a _wet gate_ does. We won't explain the distinction until [a later module](./Q-metals.md)—for now, just keep in mind that we're only dealing with one kind of gate (albeit the more common kind).
By now you've used the `|=` rune to define several gates. This rune is used to produce a _dry gate_, which has different type-checking and type-inference properties than a _wet gate_ does. We won't explain the distinction until [a later module](./R-metals.md)—for now, just keep in mind that we're only dealing with one kind of gate (albeit the more common kind).
The first subexpression after the `|=` defines the sample type. Any faces used in this definition have the type declared for it in this definition. Consider an addition generator `/gen/add.hoon`:

13
content/guides/core/hoon-school/M-logic.md → content/guides/core/hoon-school/N-logic.md
View File

@ -1,11 +1,8 @@
---
title: Gates
nodes: 184
objectives:
- "Produce loobean expressions."
- "Reorder conditional arms."
- "Switch against a union with or without default."
---
+++
title: Conditional Logic
nodes: [184]
objectives: ["Produce loobean expressions.", "Reorder conditional arms.", "Switch against a union with or without default."]
+++
# Conditional Logic

18
content/guides/core/hoon-school/N-subject.md → content/guides/core/hoon-school/O-subject.md
View File

@ -1,16 +1,12 @@
---
+++
title: Subject-Oriented Programming
nodes: 165, 180
objectives:
- "Review subject-oriented programming as a design paradigm."
- "Discuss stateful v. stateless applications and path dependence."
- "Enumerate Hoon's tools for dealing with state: `=.` tisdot, `=^` tisket, `;<` micgal, `;~` micsig."
- "Defer a computation."
---
nodes: [165, 180]
objectives: ["Review subject-oriented programming as a design paradigm.", "Discuss stateful v. stateless applications and path dependence.", "Enumerate Hoon's tools for dealing with state: `=.` tisdot, `=^` tisket, `;<` micgal, `;~` micsig.", "Defer a computation."]
+++
# Subject-Oriented Programming
_This module discusses how Urbit's subject-oriented programming paradigm structures how cores and values are used and maintain state, as well as how deferred computations and remote value lookups (“scrying”) are handled. This module does not cover core genericity and variance, which will be explained in [a later module](./Q-metals.md)._
_This module discusses how Urbit's subject-oriented programming paradigm structures how cores and values are used and maintain state, as well as how deferred computations and remote value lookups (“scrying”) are handled. This module does not cover core genericity and variance, which will be explained in [a later module](./R-metals.md)._
## The Subject
@ -30,7 +26,7 @@ Generally speaking, the following rune families allow you to do certain things t
- `%` cen runes pull arms in cores
- `=` tis runes modify the subject by introducing or replacing values
Different kinds of cores can expose or conceal functionality (such as their sample) based on their variance model. We don't need to be concerned about that yet, but if you are building certain kinds of library code or intend to build code expressions directly, you'll need to read [that module](./Q-metals.md) as well.
Different kinds of cores can expose or conceal functionality (such as their sample) based on their variance model. We don't need to be concerned about that yet, but if you are building certain kinds of library code or intend to build code expressions directly, you'll need to read [that module](./R-metals.md) as well.
### Accessing the Subject
@ -360,7 +356,7 @@ We have some more tools available for managing deferred or chained computations,
### `++og` Randomness
A _random number generator_ provides a stream of calculable but unpredictable values from some _distribution_. In [a later lesson](./R-math.md), we explain how random numbers can be generated from entropy; for now, let's see what's necessary to use such a random-number generator.
A _random number generator_ provides a stream of calculable but unpredictable values from some _distribution_. In [a later lesson](./S-math.md), we explain how random numbers can be generated from entropy; for now, let's see what's necessary to use such a random-number generator.
An RNG emits a sequence of values given a starting _seed_. For instance, a very simple RNG could emit digits of the number _π_ given a seed which is the number of digits to start from.

18
content/guides/core/hoon-school/O-stdlib-io.md → content/guides/core/hoon-school/P-stdlib-io.md
View File

@ -1,12 +1,8 @@
---
title: Gates
nodes: 185
objectives:
- "Identify tanks, tangs, wains, walls, and similar formatted printing data structures."
- "Interpret logging message structures (`%leaf`, `$rose`, `$palm`)."
- "Interpolate to tanks with `><` syntax."
- "Produce useful error annotations using `~|` sigbar."
---
+++
title: Text Processing II
nodes: [185]
objectives: ["Identify tanks, tangs, wains, walls, and similar formatted printing data structures.", "Interpret logging message structures (`%leaf`, `$rose`, `$palm`).", "Interpolate to tanks with `><` syntax.", "Produce useful error annotations using `~|` sigbar."]
+++
# Text Processing II
@ -29,7 +25,7 @@ We frequently need to convert from text to data, and between different text-base
- How can we evaluate Nock expressions?
- [`++mink`](https://urbit.org/docs/hoon/reference/stdlib/4n#mink)
(If you see a `|*` bartar rune in the code, it's similar to a `|=` bartis, but produces what's called a [_wet gate_](./Q-metals.md).)
(If you see a `|*` bartar rune in the code, it's similar to a `|=` bartis, but produces what's called a [_wet gate_](./R-metals.md).)
The `++html` core of the standard libary contains some additional important tools for working with web-based data, such as [MIME types](https://en.wikipedia.org/wiki/Media_type) and [JSON strings](https://en.wikipedia.org/wiki/JSON).
@ -160,7 +156,7 @@ This generator requires a path argument in its sample and optionally accepts a v
=+ lon=.^(arch (cat 3 vane %y) arg)
```
We saw [`.^` dotket](https://urbit.org/docs/hoon/reference/rune/dot#-dotket) for the first time in [the previous module](./N-subject.md), where we learned that it performs a _peek_ or _scry_ into the state of an Arvo vane. Most of the time this functionality is used to ask `%c` Clay or `%g` Gall for information about a path, desk, agent, etc. In this case, `(cat 3 %c %y)` is a fancy way of collocating the two `@tas` terms into `%cy`, a Clay file or directory lookup. The type of this lookup is `+$arch`, and the location of the file or directory is given by `arg` from the sample.
We saw [`.^` dotket](https://urbit.org/docs/hoon/reference/rune/dot#-dotket) for the first time in [the previous module](./O-subject.md), where we learned that it performs a _peek_ or _scry_ into the state of an Arvo vane. Most of the time this functionality is used to ask `%c` Clay or `%g` Gall for information about a path, desk, agent, etc. In this case, `(cat 3 %c %y)` is a fancy way of collocating the two `@tas` terms into `%cy`, a Clay file or directory lookup. The type of this lookup is `+$arch`, and the location of the file or directory is given by `arg` from the sample.
```hoon
tang+[?~(dir.lon leaf+"~" (show-dir vane arg dir.lon))]~

15
content/guides/core/hoon-school/P-func.md → content/guides/core/hoon-school/Q-func.md
View File

@ -1,15 +1,8 @@
---
+++
title: Functional Programming
nodes: 233, 283, 383
objectives:
- "Reel, roll, turn a list."
- "Curry, cork functions."
- "Change arity of a gate."
- "Tokenize text simply using `find` and `trim`."
- "Identify elements of parsing: `nail`, `rule`, etc."
- "Use `++scan` to parse `tape` into atoms."
- "Construct new rules and parse arbitrary text fields."
---
nodes: [233, 283, 383]
objectives: ["Reel, roll, turn a list." ], ["Curry, cork functions." ], ["Change arity of a gate.", "Tokenize text simply using `find` and `trim`.", "Identify elements of parsing: `nail`, `rule`, etc.", "Use `++scan` to parse `tape` into atoms.", "Construct new rules and parse arbitrary text fields."]
+++
# Functional Programming

19
content/guides/core/hoon-school/Q-metals.md → content/guides/core/hoon-school/R-metals.md
View File

@ -1,15 +1,8 @@
---
title: Gates
nodes: 288, 299
objectives:
- "Distinguish dry and wet cores."
- "Describe use cases for wet gates (using genericity)."
- "Enumerate and distinguish use cases for dry cores (using variance):"
- "- Covariant (`%zinc`)"
- "- Contravariant (`%iron`)"
- "- Bivariant (`%lead`)"
- "- Invariant (`%gold`)"
---
+++
title: Generic and Variant Cores
nodes: [288, 299]
objectives: ["Distinguish dry and wet cores.", "Describe use cases for wet gates (using genericity).", "Enumerate and distinguish use cases for dry cores (using variance):", "- Covariant (`%zinc`)", "- Contravariant (`%iron`)", "- Bivariant (`%lead`)", "- Invariant (`%gold`)"]
+++
# Adaptive Cores
@ -66,7 +59,7 @@ In a nutshell, compare these two gates:
[%dog %cat]
```
The dry gate does not preserve the type of `a` and `b`, but downcasts it to `*`; the wet gate does preserve the input types. It is good practice to include a cast in all gates, even wet gates. But in many cases the desired output type depends on the input type. How can we cast appropriately? Often we can cast by example, using the input values themselves (using `^+` ketlus).
The dry gate does not preserve the type of `a` and `b`, but downcasts it to `*`; the wet gate does preserve the input types. It is good practice to include a cast in all gates, even wet gates. But in many cases the desired output type depends on the input type. How can we cast appropriately? Often we can cast by example, using the input values themselves (using `^+` ketlus).
Wet gates are therefore used when incoming type information is not well known and needs to be preserved. This includes parsing, building, and structuring arbitrary nouns. (If you are familiar with them, you can think of C++'s templates and operator overloading, and Haskell's typeclasses.) Wet gates are very powerful; they're enough rope to hang yourself with. Don't use them unless you have a specific reason to do so. (If you see `mull-*` errors then something has gone wrong with using wet gates.)

18
content/guides/core/hoon-school/R-math.md → content/guides/core/hoon-school/S-math.md
View File

@ -1,16 +1,8 @@
---
+++
title: Mathematics
nodes: 234, 236, 284
objectives:
- "Review floating-point mathematics including IEEE-754."
- "Examine `@r` atomic representation of floating-point values."
- "Manipulate and convert floating-point values using the `@r` operations."
- "Examine `@s` atomic representation of signed integer values."
- "Use `+si` to manipulate `@s` signed integer values."
- "Define entropy and its source."
- "Utilize `eny` in a random number generator (`og`)."
- "Distinguish insecure hashing (`mug`) from secure hashing (`shax` and friends)."
---
nodes: [234, 236, 284]
objectives: ["Review floating-point mathematics including IEEE-754.", "Examine `@r` atomic representation of floating-point values.", "Manipulate and convert floating-point values using the `@r` operations.", "Examine `@s` atomic representation of signed integer values.", "Use `+si` to manipulate `@s` signed integer values.", "Define entropy and its source.", "Utilize `eny` in a random number generator (`og`).", "Distinguish insecure hashing (`mug`) from secure hashing (`shax` and friends)."]
+++
# Mathematics
@ -662,7 +654,7 @@ Computers often mix both deterministic processes (called “pseudorandom number
### Random Numbers
Given a source of entropy to seed a random number generator, one can then use the [`++og`](https://urbit.org/docs/hoon/reference/stdlib/3d#og) door to produce various kinds of random numbers. The basic operations of `++og` are described in [the lesson on subject-oriented programming](./N-subject.md).
Given a source of entropy to seed a random number generator, one can then use the [`++og`](https://urbit.org/docs/hoon/reference/stdlib/3d#og) door to produce various kinds of random numbers. The basic operations of `++og` are described in [the lesson on subject-oriented programming](./O-subject.md).
#### Exercise: Implement a random-number generator from scratch