Delete Expressions doc?

[joshuareagan]

I've been looking over Hoon docs and making some revisions. With the latest changes to Hoon and some distinctions Curtis has made (e.g. value/pattern) I think we're on the right track.

Given these changes though, the current Expressions doc for Hoon makes little sense. We have two options:

(1) Rewrite it so it makes sense, or

(2) Delete it.

As it stands, this doc is quite sloppy about the distinction between a Hoon source expression and the result of parsing the expression into an AST node. There's little point in revising the doc so that it's just about expressions; the Syntax page handles those. Do we want a page about AST nodes? These are mentioned a bit in the Concepts page. How much does a Hoon beginner really need to know about AST stuff?

In the interest of avoiding beginner concept overload, I vote deletion for this page. About the only way it would make sense to save it is to turn it into a "compiler" page, where we go through parsing with ream and then mint:ut. But a rewrite that drastic is tantamount to deletion anyway.

Are there reasons to keep this page? If so, what exactly is the objective? (At the very least, clarifying what the goal of this doc is a must.)

[cgyarvin]

I favor (2).

Sent from my iPhone

On Dec 10, 2017, at 4:31 AM, Joshua Reagan notifications@github.com wrote:

I've been looking over Hoon docs and making some revisions. With the latest changes to Hoon and some distinctions Curtis has made (e.g. value/pattern) I think we're on the right track.

Given these changes though, the current Expressions doc for Hoon makes little sense. We have two options:

(1) Rewrite it so it makes sense, or

(2) Delete it.

As it stands, this doc is quite sloppy about the distinction between a Hoon source expression and the result of parsing the expression into an AST node. There's little point in revising the doc so that it's about expressions; the Syntax page handles those. Do we want a page about AST nodes? These are mentioned a bit in the Concepts page. How much does a Hoon beginner really need to know about AST stuff?

In the interest of avoiding beginner concept overload, I vote deletion for this page. About the only way it would make sense to save it is to turn it into a "compiler" page, where we go through parsing with ream and then mint:ut. But rewrite that drastic is tantamount to deletion anyway.

Are there reasons to keep this page? If so, what exactly is the objective? (At the very least, clarifying what the goal of this doc is a must.)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[ohAitch]

Re redundancy, my memory is that we intentionally have two parallel doc series: the top-down immediate-results oriented one, and the bottom-up incremental full understanding one. Since you're likening the page to mint:ut, I'm guest this is part of the latter; what is your opinion on the rest of the docs in the same directory? If you think they cover twigs sufficiently /without jumping out to the parallel doc track/, by all means delete the page; if you think all of them are generally inferior to their counterparts, I think you've stumbled on the section of the docs aimed at a learning style incompatible with yours.

The whole choice to have two takes on the same baseline information as part of the Official Docs is a bit wonky, and perhaps we should revisit that; though I feel like in the past we have been way to eager to delete documentation we later decide is obviously necessary after all. I'm pretty sure I've written a "comprehensive irregular form overview" on at least three separate occasions, after failing to find the previous one anywhere in the doc, and for all I know it's been ~cleaned up~ again in the past half year :P

On Sunday, 10 December 2017, cgyarvin notifications@github.com wrote:

I favor (2).

Sent from my iPhone

On Dec 10, 2017, at 4:31 AM, Joshua Reagan notifications@github.com wrote:

I've been looking over Hoon docs and making some revisions. With the latest changes to Hoon and some distinctions Curtis has made (e.g. value/pattern) I think we're on the right track.

Given these changes though, the current Expressions doc for Hoon makes little sense. We have two options:

(1) Rewrite it so it makes sense, or

(2) Delete it.

As it stands, this doc is quite sloppy about the distinction between a Hoon source expression and the result of parsing the expression into an AST node. There's little point in revising the doc so that it's about expressions; the Syntax page handles those. Do we want a page about AST nodes? These are mentioned a bit in the Concepts page. How much does a Hoon beginner really need to know about AST stuff?

In the interest of avoiding beginner concept overload, I vote deletion for this page. About the only way it would make sense to save it is to turn it into a "compiler" page, where we go through parsing with ream and then mint:ut. But rewrite that drastic is tantamount to deletion anyway.

Are there reasons to keep this page? If so, what exactly is the objective? (At the very least, clarifying what the goal of this doc is a must.)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-350565780, or mute the thread https://github.com/notifications/unsubscribe-auth/ABxXhryjIRYoIP65baZz-g2O3xkbmd01ks5s_BqwgaJpZM4Q8ecZ .

[joshuareagan]

I'm okay with the 2-track idea. But I'm not sure where this doc fits in that discussion. My understanding is the "top-down" style is great for those who don't care about foundations and who want to write apps ASAP. "I don't need to understand every little detail, I just want high-level abstraction that gives me a good approximation of the semantics in a hurry." This approach clearly is compatible with sacrificing a little semantic accuracy in favor of fostering quick learning with a few noble lies. Totally legitimate.

But it's not clear to me that this is what's going on with the current Expressions page. I think it's just not all that helpful on any track. I may not be understanding what role it's supposed to play though, hence my asking what the learning objective for it is even supposed to be.

There are some tantalizing claims in it. I rather like the idea that "The definition of [hoon] is the definition of Hoon." A doc that follows up on that, and more or less teaches the reader to understand Hoon by understanding the compiler sounds like a great idea. I favor it, and, God willing, maybe I'll even help write it one day. But this current doc isn't close to that. And it isn't good for explaining what a source code expression is either. The latter is clearly a Syntax topic, and we have that already.

As far as deletion goes, I have no objection to saving this doc elsewhere in case we change our minds later. I certainly don't want anyone to rewrite something they've already written. I just don't think it's going to help newbies in its current form.

But if I'm wrong, and of course I may be, then at least say what the goal of "Expressions" is. Then I can assess it more fairly, and help revise it to meet that goal if necessary.

[belisarius222]

Yeah I think deleting this for now makes sense. The only problem with deleting it is that it’s the only real explanation of moss and seed, which are used extensively in the individual rune docs.

In order for a set of hoon docs to be complete, they should include detailed documentation about the compiler itself, since hoon is defined metacircularly and can call its own compiler in various ways. Calling the hoon compiler is a crucial part of using hoon, at least for system code. It should be one of the last subjects taught in a hoon course, but those docs should exist. I don’t think they really do at the moment. That’s the place to describe the AST. The rune docs should probably say instead of seed. I think that would be less confusing.

On Sun, Dec 10, 2017 at 11:08 PM Joshua Reagan notifications@github.com wrote:

I'm okay with the 2-track idea. But I'm not sure where this doc fits in that discussion. My understanding is the "top-down" style is great for those who don't care about foundations and who want to write apps ASAP. "I don't need to understand every little detail, I just want high-level abstraction that gives me a good approximation of the semantics in a hurry." This approach clearly is compatible with sacrificing a little semantic accuracy in favor of fostering quick learning with a few noble lies. Totally legitimate.

But it's not clear to me that this is what's going on with the current Expressions page. I think it's just not all that helpful on any track. I may not be understanding what role it's supposed to play though, hence my asking what the learning objective for it is even supposed to be.

There are some tantalizing claims in it. I rather like the idea that "The definition of [hoon] is the definition of Hoon." A docs that follows up on that, and more or less teaches the reader to understand Hoon by understanding the compiler sounds like a great idea. I favor it, and, God willing, maybe I'll even help write it one day. But this current doc isn't close to that. And it isn't good for explaining what a source code expression is either. The latter is clearly a Syntax topic, and we have that already.

As far as deletion goes, I have no objection to saving this doc elsewhere in case we change our minds later. I certainly don't want anyone to rewrite something they've already written. I just don't think it's going to help newbies in its current form.

But if I'm wrong, and of course I may be, then at least say what the goal of "Expressions" is. Then I can assess it more fairly, and help revise it to meet that goal if necessary.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-350639261, or mute the thread https://github.com/notifications/unsubscribe-auth/AA1Y9U_Oh0twzj7DPmZtrpBF9-RwctPOks5s_NTegaJpZM4Q8ecZ .

[joshuareagan]

The moss and seed vocab will need to be removed too. We'll need some different conventions for the rune docs.

I think @cgyarvin wants to use the value/pattern terms for subexpressions? So maybe something like:

The syntax for the :- rune is:

:-  <value>  <value>

The syntax for the ^- rune is:

^-  <pattern>  <value>

[belisarius222]

That looks good to me.

On Tue, Dec 12, 2017 at 7:07 AM, Joshua Reagan notifications@github.com wrote:

The moss and seed vocab will need to be removed too. We'll need some different conventions for the rune docs.

I think @cgyarvin https://github.com/cgyarvin wants to use the value/pattern terms for subexpressions? So maybe something like, "The syntax for the :- rune is :- ." And, "The syntax for the ^- rune is ^- ."

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351078623, or mute the thread https://github.com/notifications/unsubscribe-auth/AA1Y9Zf9sKjsvrxLazBER4XKEYHO0E_6ks5s_paqgaJpZM4Q8ecZ .

[cgyarvin]

Yes. I’ve been through so much terminology on this issue...

Sent from my iPhone

On Dec 12, 2017, at 10:15 AM, Ted Blackman notifications@github.com wrote:

That looks good to me.

On Tue, Dec 12, 2017 at 7:07 AM, Joshua Reagan notifications@github.com wrote:

The moss and seed vocab will need to be removed too. We'll need some different conventions for the rune docs.

I think @cgyarvin https://github.com/cgyarvin wants to use the value/pattern terms for subexpressions? So maybe something like, "The syntax for the :- rune is :- ." And, "The syntax for the ^- rune is ^- ."

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351078623, or mute the thread https://github.com/notifications/unsubscribe-auth/AA1Y9Zf9sKjsvrxLazBER4XKEYHO0E_6ks5s_paqgaJpZM4Q8ecZ .

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[joshuareagan]

Sometimes you need to test thousands of materials as filaments, to make a better light bulb...

I'll work on a PR that removes "Expressions" and that revises the rune docs accordingly.

[joshuareagan]

Actually I'd really rather just say <value> and <mold>. Are there any pattern expressions that aren't molds? Using a new word carries a cost, so what's the benefit?

[cgyarvin]

I am trying to get “model” to be a preferred synonym for “mold.” Will rename ++tile to ++modl I think.

Maybe the model is the ++modl is the abstract description; the mold is the gate we build from it. The transformation from model to mold is not trivial!

Sent from my iPhone

On Dec 12, 2017, at 6:36 PM, Joshua Reagan notifications@github.com wrote:

Actually I'd really rather just say and . Are there any pattern expressions that aren't molds? Using a new word carries a cost, so what's the benefit?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[joshuareagan]

Ok, so if I understand you correctly, the model is evaluated against the subject to become a mold?

[joshuareagan]

Actually I don't think I understand you...

[cgyarvin]

The model is rendered (by ++ax) into a hoon. Rather confusingly, the raw hoon produced by the parser is boiled to produce a model! I intend to simplify this a little, but for now...

So it’s hoon (raw AST)->model->hoon (normalizing gate).

Sent from my iPhone

On Dec 12, 2017, at 6:52 PM, Joshua Reagan notifications@github.com wrote:

Actually I don't think I understand you...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[belisarius222]

@cgyarvin please correct me if I butcher this, but here’s my understanding:

The model is a data structure used by the hoon compiler when doing type-checking. Let’s say you have a |= a. ..., and you call that gate somewhere in your code on a value whose type is defined by a moldb. It’s not obvious how to check whether the type defined by the mold bnests inside the type defined by the mold a if you only have the mold functions themselves, which are rather opaque pieces of executable code. You want to know the “models” used to generate the mold functions. So, the hoon compiler, when it sees a mold definition, first creates a model, then uses that model both to generate the mold function and to check for nest-fails.

On Tue, Dec 12, 2017 at 7:06 PM cgyarvin notifications@github.com wrote:

The model is rendered (by ++ax) into a hoon. Rather confusingly, the raw hoon produced by the parser is boiled to produce a model! I intend to simplify this a little, but for now...

So it’s hoon (raw AST)->model->hoon (normalizing gate).

Sent from my iPhone

On Dec 12, 2017, at 6:52 PM, Joshua Reagan notifications@github.com wrote:

Actually I don't think I understand you...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351268324, or mute the thread https://github.com/notifications/unsubscribe-auth/AA1Y9WzqelN2D37gTxvSwmNeERU5hHhuks5s_z87gaJpZM4Q8ecZ .

[ohAitch]

Mm not quite: the hoon compiler, whenever it compiles an "opaque" executable, generates a type for its output, and type checking is performed against that.

Models are just a convenient short-hand syntax for creating molds, and are composed of irreguar(or regular) form $ runes, * ^ @ ? ~ base types, and %~.some_constant fixed atoms. This syntax can be opted out of with ,foo and foo, which are mold irregular forms of $, and $

I suppose models are also primitives for pattern-matching with ?= (and thereby ?-), but I think conceptually that's supposed to still be an operation on the model's mold

On Wednesday, 13 December 2017, Ted Blackman notifications@github.com wrote:

@cgyarvin please correct me if I butcher this, but here’s my understanding:

The model is a data structure used by the hoon compiler when doing type-checking. Let’s say you have a |= a. ..., and you call that gate somewhere in your code on a value whose type is defined by a moldb. It’s not obvious how to check whether the type defined by the mold bnests inside the type defined by the mold a if you only have the mold functions themselves, which are rather opaque pieces of executable code. You want to know the “models” used to generate the mold functions. So, the hoon compiler, when it sees a mold definition, first creates a model, then uses that model both to generate the mold function and to check for nest-fails.

On Tue, Dec 12, 2017 at 7:06 PM cgyarvin notifications@github.com wrote:

The model is rendered (by ++ax) into a hoon. Rather confusingly, the raw hoon produced by the parser is boiled to produce a model! I intend to simplify this a little, but for now...

So it’s hoon (raw AST)->model->hoon (normalizing gate).

Sent from my iPhone

On Dec 12, 2017, at 6:52 PM, Joshua Reagan notifications@github.com wrote:

Actually I don't think I understand you...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351268324, or mute the thread https://github.com/notifications/unsubscribe-auth/ AA1Y9WzqelN2D37gTxvSwmNeERU5hHhuks5s_z87gaJpZM4Q8ecZ .

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351443411, or mute the thread https://github.com/notifications/unsubscribe-auth/ABxXhgVDLYhCJrH-BfML4OXurj566sMQks5s__qHgaJpZM4Q8ecZ .

[cgyarvin]

Yeah no. The type-checker never sees the model (currently ++tile, will be ++modl).

Think of a ++tile as an intermediate data structure that's used in macro expansion. Most runes work by expanding themselves to other hoons in ++open:ap. ++ax, the tile engine, is entirely within this process.

On Wed, Dec 13, 2017 at 8:25 AM, Ted Blackman notifications@github.com wrote:

@cgyarvin please correct me if I butcher this, but here’s my understanding:

The model is a data structure used by the hoon compiler when doing type-checking. Let’s say you have a |= a. ..., and you call that gate somewhere in your code on a value whose type is defined by a moldb. It’s not obvious how to check whether the type defined by the mold bnests inside the type defined by the mold a if you only have the mold functions themselves, which are rather opaque pieces of executable code. You want to know the “models” used to generate the mold functions. So, the hoon compiler, when it sees a mold definition, first creates a model, then uses that model both to generate the mold function and to check for nest-fails.

On Tue, Dec 12, 2017 at 7:06 PM cgyarvin notifications@github.com wrote:

The model is rendered (by ++ax) into a hoon. Rather confusingly, the raw hoon produced by the parser is boiled to produce a model! I intend to simplify this a little, but for now...

So it’s hoon (raw AST)->model->hoon (normalizing gate).

Sent from my iPhone

On Dec 12, 2017, at 6:52 PM, Joshua Reagan notifications@github.com wrote:

Actually I don't think I understand you...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351268324, or mute the thread https://github.com/notifications/unsubscribe-auth/ AA1Y9WzqelN2D37gTxvSwmNeERU5hHhuks5s_z87gaJpZM4Q8ecZ .

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351443411, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAd-O3CRjKTilZB0KEn_YVx20udjJks5s__qGgaJpZM4Q8ecZ .

[joshuareagan]

So that others can check my understanding, here's my attempt:

I start with Hoon source, which the parser turns into a hoon, an AST. Certain (sub-)hoons in that AST were molds in the source, like a=@ and [p=^ q=@] or whatever. These got parsed in "pattern" mode to become models (i.e. currently ++tiles, soon to be ++modls). When the time is right, these models are converted (in a non-trivial process) to become hoons again; in particular, these hoons are molds (as Hoon ASTs).

Is this right?

As someone who finds this process intrinsically interesting to learn about, I'm happy to pursue this thread. But I'm left wondering whether it's appropriate to talk about the model/mold distinction in the introductory docs. It may be that the best way to implement molds in the compiler is to have these intermediate structures, but in a purely semantic sense how much do these implementation details matter?

I think of the semantics of Hoon as being like a legendary myth that prepares the mind for communion with the ideal forms in Plato's heaven. It's a story beginners tell themselves so they have a convenient mental model of what the program will do when run. This story is basically a mathematical construct, a formalism that can be realized in different ways.

One guaranteed correct semantics is one that says exactly what the compiler does. But that's not beginner friendly (to say the least). What's wrong with saying the following?: there are two kinds of expression, value and mold. When you put molds after a door/gate, it determines the default value and the sample type. When you put molds with a cast rune, it sets the type of the gate output. When you call a gate, it normalizes data.

This semantic account is cognitively a lot less demanding. The simplification is only a bad thing if it causes beginners to make bad predictions about the results of running their programs. It's not clear to me that this happens.

@ohAitch mentions that ?= runes use models for pattern matching, but we can make clear that there are limits on what the ?= rune can do to detect type. (The current docs actually make this caveat.) The neophyte is edified and not overwhelmed.

For anyone who would be a Hoon master, full enlightenment isn't achieved until one completes the circle and understands mold implementation in the compiler. Everyone learning Hoon should take on this challenge at some point. But we can make the learning curve less steep by setting aside compiler details until the proper time.

I know I'm well into "too big for his britches" territory! I'm just worried about feeding misconceptions about the supposed difficulty of Hoon. But if I'm misunderstanding something, let me know and I'll confess my sins and accept the appointed punishment!

[joemfb]

If i've read this correctly, it seems like a simpler name change than it's being made out to be: "clam" -> "mold"; "mold" -> "model".

In other words, we've been using the word "mold" to refer to that which is bunted, cast by, inferred over, etc. Now, mold would refer only to the normalizing gate that is generated if necessary, and model would refer to all the uses in general.

[joshuareagan]

My question is just this: what benefit in predictive power at the semantic level is gained by taking one concept and splitting it in two?

[cgyarvin]

Your interpretation is correct, but let me fill in some missing pieces that might change your opinion.

I feel that the main thing that makes learning Hoon, or any part of Urbit, difficult for people, is that they feel the system has depths they are afraid of. This feeling can be alleviated, but the only real cure for the disorder is touching the bottom of the river with their own feet. While it persists, it makes everything much harder and more stressful.

Some people can swim comfortably without touching the bottom. Other people cannot swim. They can only wade.

There are five main components to understanding Hoon: the data structure itself, ++hoon; the compiler core, ++ut, and the type system ++type (formerly ++span); the macro expander ++ap; the model engine ++ax (formerly ++al); and the parser ++vast.

My feeling is that, to be confident with the system at an intermediate level, you should understand ++hoon, ++ax, ++ap, and ++type, and be comfortable looking at the source code for these. It would be nice if ++ap wasn't dog ugly. ++ax is clean enough to eat off and ++type is pretty simple.

++vast is hideous. ++ut is elegant but intimidating. These things could be changed in the long run, but won't be changed soon.

One major confusion right now is the fact that hoons are ++boiled into tiles (later to become models). This is just a temporary internal adaptation measure that hasn't been cleaned up yet. The parser should produce ++modls directly. If you look at ++hoon, you'll see that some hoons recurse into ++hoon, whereas others have subtrees that are ++root. These should be ++tile or ++modl. So, in order to properly explain the data structure that your code gets parsed into, you have to explain the concept of a model.

Furthermore, a piece of Hoon that is about to get another pass -- really the last design pass in developing the language -- is the type prettyprinter, which needs to be updated for doccords. In order to improve our printing of types and typed values, an absolutely crucial aspect of a programming language, which we are currently quite mediocre at, I intend to stick some or all ++modls into ++type hints so that they can be used for printing.

(Imagine if when you typed "ls" in a web terminal, in a folder full of images, it showed you image thumbnails. Why shouldn't I be able to ~& a noun and, if that noun contains an image, see a thumbnail? I know this is daring and visionary but it seems like something that ought to be possible at some point in the 21st century.)

On Thu, Dec 14, 2017 at 6:56 AM, Joshua Reagan notifications@github.com wrote:

So that others can check my understanding, here's my attempt:

I start with Hoon source, which the parser turns into a hoon, an AST. Certain (sub-)hoons in that AST were molds in the source, like a=@ and [p=^ q=@] or whatever. These got parsed in "pattern" mode to become models (i.e. currently ++tiles, soon to be ++modls). When the time is right, these models are converted (in a non-trivial process) to become hoons again; in particular, these hoons are molds (as Hoon ASTs).

Is this right?

As someone who finds this process intrinsically interesting to learn about, I'm happy to pursue this thread. But I'm left wondering whether it's appropriate to talk about the model/mold distinction in the introductory docs. It may be that the best way to implement molds in the compiler is to have these intermediate structures, but in a purely semantic sense how much do these implementation details matter?

I think of the semantics of Hoon as being like a legendary myth that prepares the mind for communion with the ideal forms in Plato's heaven. It's a story beginners tell themselves so they have a convenient mental model of what the program will do when run. This story is basically a mathematical construct, a formalism that can be realized in different ways.

One guaranteed correct semantics is one that says exactly what the compiler does. But that's not beginner friendly (to say the least). What's wrong with saying the following?: there are two kinds of expression, value and mold. When you put molds after a door/gate, it determines the default value and the sample type. When you put molds with a cast rune, it sets the type of the gate output. When you call a gate, it normalizes data.

This semantic account is cognitively a lot less demanding. The simplification is only a bad thing if it causes beginners to make bad predictions about the results of running their programs. It's not clear to me that this happens.

@ohAitch https://github.com/ohaitch mentions that ?= runes use models for pattern matching, but we can make clear that there are limits on what the ?= rune can do to detect type. (The current docs actually make this caveat.) The neophyte is edified and not overwhelmed.

For anyone who would be a Hoon master, full enlightenment isn't achieved until one completes the circle and understands mold implementation in the compiler. Everyone learning Hoon should take on this challenge at some point. But we can make the learning curve less steep by setting aside compiler details until the proper time.

I know I'm well into "too big for his britches" territory! I'm just worried about feeding misconceptions about the supposed difficulty of Hoon. But if I'm misunderstanding something, let me know and I'll confess my sins and accept the appointed punishment!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351734056, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAUz-b-FQQc9AciiKpo6kM3wXAzIUks5tATcygaJpZM4Q8ecZ .

[cgyarvin]

Here is my interpretation of what a model is.

A model is a noun shape. It's an abstract description of a noun-based data structure. It can be used as a macro for generating hoons, in three ways.

One, it can build a mold -- a hoon that produces a gate which accepts any noun, and produces a correctly-typed instance of the data structure. Two, it can build a bunt -- a hoon that produces a constant default example of the data structure. Three, it can build a test -- a hoon that checks if any noun fits this model, for pattern-matching.

(In fact, the implementation of ?= doesn't use the model directly. It makes a bunt and generates Nock, not Hoon, using the type of the bunt. You could argue that this is wrong, but fixing it is a low priority. In any case, this is the kind of detail that you do want to abstract from the learner, I think.)

A mold is just an ordinary Hoon gate (function) that works as a normalizer. (Hoon is not Coq -- it does not and cannot check this property.) You can supply your own mold and use it as an opaque part in a model. For instance, if you write [a=foo b=bar], this is a model. ++ax takes care of writing the function that accepts * and produces a pair of foo and bar. Somewhere else, you wrote ++foo and ++bar, maybe by defining a model that was used to build a mold.

Suppose ++foo is defined as [x=@ y=@]. Since ++ax does not see the type system and is just a macro builder, it cannot in any way connect the model [a=foo b=bar] to the model [x=@ y=@], as models. But we still want the behavior of the model [a=foo b=bar] to be exactly the same as the behavior of the model [a=[x=@ y=@] b=bar].

On Thu, Dec 14, 2017 at 10:00 AM, Curtis Yarvin curtis.yarvin@gmail.com wrote:

Your interpretation is correct, but let me fill in some missing pieces that might change your opinion.

I feel that the main thing that makes learning Hoon, or any part of Urbit, difficult for people, is that they feel the system has depths they are afraid of. This feeling can be alleviated, but the only real cure for the disorder is touching the bottom of the river with their own feet. While it persists, it makes everything much harder and more stressful.

Some people can swim comfortably without touching the bottom. Other people cannot swim. They can only wade.

There are five main components to understanding Hoon: the data structure itself, ++hoon; the compiler core, ++ut, and the type system ++type (formerly ++span); the macro expander ++ap; the model engine ++ax (formerly ++al); and the parser ++vast.

My feeling is that, to be confident with the system at an intermediate level, you should understand ++hoon, ++ax, ++ap, and ++type, and be comfortable looking at the source code for these. It would be nice if ++ap wasn't dog ugly. ++ax is clean enough to eat off and ++type is pretty simple.

++vast is hideous. ++ut is elegant but intimidating. These things could be changed in the long run, but won't be changed soon.

One major confusion right now is the fact that hoons are ++boiled into tiles (later to become models). This is just a temporary internal adaptation measure that hasn't been cleaned up yet. The parser should produce ++modls directly. If you look at ++hoon, you'll see that some hoons recurse into ++hoon, whereas others have subtrees that are ++root. These should be ++tile or ++modl. So, in order to properly explain the data structure that your code gets parsed into, you have to explain the concept of a model.

Furthermore, a piece of Hoon that is about to get another pass -- really the last design pass in developing the language -- is the type prettyprinter, which needs to be updated for doccords. In order to improve our printing of types and typed values, an absolutely crucial aspect of a programming language, which we are currently quite mediocre at, I intend to stick some or all ++modls into ++type hints so that they can be used for printing.

(Imagine if when you typed "ls" in a web terminal, in a folder full of images, it showed you image thumbnails. Why shouldn't I be able to ~& a noun and, if that noun contains an image, see a thumbnail? I know this is daring and visionary but it seems like something that ought to be possible at some point in the 21st century.)

On Thu, Dec 14, 2017 at 6:56 AM, Joshua Reagan notifications@github.com wrote:

So that others can check my understanding, here's my attempt:

I start with Hoon source, which the parser turns into a hoon, an AST. Certain (sub-)hoons in that AST were molds in the source, like a=@ and [p=^ q=@] or whatever. These got parsed in "pattern" mode to become models (i.e. currently ++tiles, soon to be ++modls). When the time is right, these models are converted (in a non-trivial process) to become hoons again; in particular, these hoons are molds (as Hoon ASTs).

Is this right?

As someone who finds this process intrinsically interesting to learn about, I'm happy to pursue this thread. But I'm left wondering whether it's appropriate to talk about the model/mold distinction in the introductory docs. It may be that the best way to implement molds in the compiler is to have these intermediate structures, but in a purely semantic sense how much do these implementation details matter?

I think of the semantics of Hoon as being like a legendary myth that prepares the mind for communion with the ideal forms in Plato's heaven. It's a story beginners tell themselves so they have a convenient mental model of what the program will do when run. This story is basically a mathematical construct, a formalism that can be realized in different ways.

One guaranteed correct semantics is one that says exactly what the compiler does. But that's not beginner friendly (to say the least). What's wrong with saying the following?: there are two kinds of expression, value and mold. When you put molds after a door/gate, it determines the default value and the sample type. When you put molds with a cast rune, it sets the type of the gate output. When you call a gate, it normalizes data.

This semantic account is cognitively a lot less demanding. The simplification is only a bad thing if it causes beginners to make bad predictions about the results of running their programs. It's not clear to me that this happens.

@ohAitch https://github.com/ohaitch mentions that ?= runes use models for pattern matching, but we can make clear that there are limits on what the ?= rune can do to detect type. (The current docs actually make this caveat.) The neophyte is edified and not overwhelmed.

For anyone who would be a Hoon master, full enlightenment isn't achieved until one completes the circle and understands mold implementation in the compiler. Everyone learning Hoon should take on this challenge at some point. But we can make the learning curve less steep by setting aside compiler details until the proper time.

I know I'm well into "too big for his britches" territory! I'm just worried about feeding misconceptions about the supposed difficulty of Hoon. But if I'm misunderstanding something, let me know and I'll confess my sins and accept the appointed punishment!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/219#issuecomment-351734056, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAUz-b-FQQc9AciiKpo6kM3wXAzIUks5tATcygaJpZM4Q8ecZ .

[xykj61]

Alright, the /docs/hoon/twig/ doc has been superseded by the new /docs/hoon/rune/ doc, which has no description of models versus patterns and just lists all the runes reference style for the time being. This should buy some time for @joshuareagan and I to rewrite it.

Also note, effective now: rune docs are now at /docs/hoon/rune/cen/tis/ now, for example, instead of /docs/hoon/twig/cen-call/tis-make/.