adds rune-form twig expansions

[joemfb]

As I read more of the kernel source, I've found the existing, keyword-based twig expansions to be confusing. I haven't memorized the keywords, and they're not heavily used anywhere, so I went ahead and translated the expansions into runes. This was a useful exercise for me, and I think it's a nice addition to the docs, but it does make them a bit busier...

Along the way, I found some issues with the expansions; I'll comment on those inline.

[joemfb]

I replaced the explicit core with trap, because of the rune description: "form a trap and kick it".

[galenwp]

This looks awesome.

[joemfb]

:lost is another non-existent twig expansion; it looks to me like [%lost] is expanded in the AST, which signals the compiler to actually throw mint.lost, but there's no twig to signify that, and, therefore, no valid expansion

[joemfb]

Github's not showing it here, but I replaced :lost with ~|(%mint-lost ...) ...

[ohAitch]

It is a :lost though: it's only a problem if you try to compile it with a
non-void type, and ++open doesn't discriminate on what the input type is.

On Thursday, 7 July 2016, Joe Bryan notifications@github.com wrote:

In docs/hoon/twig/wut-test/hep-case.md
#55 (comment):

:ifno q
:lost
:if :fits(p.i.q p)
q.i.q
:moar(q t.q)

+```
+|-
+?.  q
+  :lost
+?:  ?=(p.i.q p)
+  q.i.q
+$(q t.q)
+```
+
 ## Syntax

Github's not showing it here, but I replaced :lost with ~|(%mint-lost ...)
...

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/urbit/docs/pull/55/files/8c309518d1325589ec5ca032103f436687191997#r70024501,
or mute the thread
https://github.com/notifications/unsubscribe/ABxXhq1SCjnMCUY5qEIrlaMJU4nQICctks5qTdRjgaJpZM4I9D6c
.

[joemfb]

What's a small lie among friends in search of a greater truth?

[joemfb]

... ;)

I guess it depends on the purpose of the expansions; :lost is a syntax error, so it seems like a cruel kind of nerd-sniping to include it in the official docs. Does the distinction between it and a tracing printf matter to anyone who won't be reading the compiler source?

[joemfb]

The inline comment threads above make it clear that documenting the twig expansions is a hard problem. I'd like to make it an easy problem, by redefining it.

It seems that twigs could be classified in 3 ways: "core", "syntax sugar", and "macros". (I clearly don't have @cgyarvin's gift for naming things...)

• core twigs: =>, %=, |%, :-, etc. The irreducibles
• syntax sugar twigs: =<, %-, |-, |=, :_, etc.
• macros: ?&, ?|, :~, ;:, etc.

"core" twigs are definitionally non-expandable, and not a problem. "syntax sugar" twigs are trivially (for some value of) expandable, and also not a problem, I think. It's those pesky "macro" twigs that aren't really expressable in valid syntax.

I propose that, assuming these distinctions are valid and well-formed, they be made at least somewhat clear in the docs. For instance, the "macro" twigs could have "Pseudo Expansions" or somesuch, in actual pseudocode or approximated in Hoon, but clearly differentiated from the "syntax sugar" twig expansions.

[joemfb]

I've rebased this PR into two commits, attempting to split along those lines.

[ohAitch]

For natural runes(i.e. core twigs), it might be informative to show
nock expansions: =+ is 8, ?: is 6, etc., though this seems a lot lower
priority than other possible doc.

Something like "non-finite-state reductions" definitely make sense like a
separate category, though I'd probably throw :~ into the "straightforward
sugar" pile, and %- as of 151 into "macro magic".

On Thursday, 23 June 2016, Joe Bryan notifications@github.com wrote:

The inline comment threads above make it clear that documenting the twig
expansions is a hard problem. I'd like to make it an easy problem, by
redefining it.

It seems that twigs could be classified in 3 ways: "core", "syntax sugar",
and "macros". (I clearly don't have @cgyarvin
https://github.com/cgyarvin's gift for naming things...)

• core twigs: =>, %=, |%, :-, etc. The irreducibles
• syntax sugar twigs: =<, %-, |-, |=, :_, etc.
• macros: ?&, ?|, :~, ;:, etc.

"core" twigs are definitionally non-expandable, and not a problem. "syntax
sugar" twigs are trivially (for some value of) expandable, and also not a
problem, I think. It's those pesky "macro" twigs that aren't really
expressable in valid syntax.

I propose that, assuming these distinctions are valid and well-formed,
they be made at least somewhat clear in the docs. For instance, the "macro"
twigs could have "Pseudo Expansions" or somesuch, in actual pseudocode or
approximated in Hoon, but clearly differentiated from the "syntax sugar"
twig expansions.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#55 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/ABxXhrdOiIgftiHxUqVnpdE8hSqS7Svoks5qOzP9gaJpZM4I9D6c
.

[joemfb]

Of course, after I posted this, I read https://github.com/urbit/old-urbit.org/tree/master/doc/hoon/tut and saw that there were already names for natural and synthetic runes. I should've known no possible vector of Hoon concepts remained unnamed...

I think Nock expansions would be very cool.

:~ expands to a pair-wise list reduction of the AST; it's straightforward, but not a literal expansion that can be copied and run. Doesn't %- still reduce to %~($ p q)?

And of course, my proposal leaves unresolved the question of how to actually document the macro magic...

[ohAitch]

:~ is in fact non-finite state, but "~[1 2 3] expands to [1 2 3 ~]" is
a sufficient explanation in a way few others(though perhaps ;:) have.

%^(a b c d) reduces to %~($ a b c d) reduces to %*($ a ,.&1.+< b, ,.&2.+<
c, ,.|2.+> d): if you can link into macro-rune docs, it's fine, but the
path down to =+ %= has definitely stopped being the nonmagic =+(a $.-(+< [b
c d]:+)).

On Thursday, 23 June 2016, Joe Bryan notifications@github.com wrote:

Of course, after I posted this, I read
https://github.com/urbit/old-urbit.org/tree/master/doc/hoon/tut and saw
that there were already names for natural and synthetic runes. I
should've known no possible vector of Hoon concepts remained unnamed...

I think Nock expansions would be very cool.

:~ expands to a pair-wise list reduction of the AST; it's
straightforward, but not a literal expansion that can be copied and run.
Doesn't %- still reduce to %~($ p q)?

And of course, my proposal leaves unresolved the question of how to
actually document the macro magic...

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#55 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/ABxXhnYFXgl98H-R9PK-_bDzgM0Vhvygks5qO3PygaJpZM4I9D6c
.

[philipcmonk]

Is this ready to merge, then?

[joemfb]

I don't think so. The distinction between natural and synthetic runes is already present in the docs (although it could be clearer). Does it make sense to draw a distinction between those synthetic runes that can be directly translated into valid Hoon expressions, and those which cannot (ie, the "macro" runes in my previous comment)? And is that something you'd like to move forward on?

My first commit covers the simpler synthetic runes; it just needs a fix for the :open (%~) expansion. And I don't know of a hygienic expansion that doesn't use deprecated runes...

The second commit adds rune-form expansions for the more advance synthetic runes ("macro"), but it doesn't distinguish them from the simpler forms in any way. That could be rectified with a custom heading or a short note after the expansion on each page - the greater obstacle remains in deciding how to expand them. Right now, they're basically AST transformations; clear enough with context, but not necessary helpful as explanations, particularly for new users.

I could split this into two PRs if you'd like to merge the simpler expansions first, or could continue working on it here.

[joemfb]

I've made a pass at the advanced synthetic twigs, adding explicitly-marked pseudocode expansions, and separately titled Compiler Macros -- the best heading I could come up with... I've also added notes about macro-hygiene where the expansions appear to be non-hygienic.

And, on a personal note, it's pretty cool how much more sense these all make after 2 weeks ;)

[cgyarvin]

The expansions are always hygienic! Good lord! "Young man, I don't know
what you're talking about. My equations are correct." I also note that he
or she who understands ;~, understands everything.

It's pretty cool how deep into Arvo you've gotten in 2 weeks. Has it only
been 2 weeks?

Not to push my luck too far, but one thing that would be really neat is if
you can produce a small retrospective essay on the general experience of
learning to program in Hoon/Urbit. We'd love to put any such thing up on
the blog urbit.org (by anyone who wants to write one, not just Joe...)

On Thu, Jul 7, 2016 at 6:18 PM, Joe Bryan notifications@github.com wrote:

I've made a pass at the advanced synthetic twigs, adding explicitly-marked
pseudocode expansions, and separately titled Compiler Macro -- the best
heading I could come up with... I've also added notes about macro-hygiene
where the expansions appear to be non-hygienic.

And, on a personal note, it's pretty cool how much more sense these all
make after 2 weeks ;)

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#55 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/AALyATU2olQziYmU_HKhVbztfF5fQU3Gks5qTaVqgaJpZM4I9D6c
.

[cgyarvin]

Or at least, either hygienic or biblical :P

On Thursday, 7 July 2016, Curtis Yarvin curtis.yarvin@gmail.com wrote:

The expansions are always hygienic! Good lord! "Young man, I don't know
what you're talking about. My equations are correct." I also note that he
or she who understands ;~, understands everything.

It's pretty cool how deep into Arvo you've gotten in 2 weeks. Has it only
been 2 weeks?

Not to push my luck too far, but one thing that would be really neat is if
you can produce a small retrospective essay on the general experience of
learning to program in Hoon/Urbit. We'd love to put any such thing up on
the blog urbit.org (by anyone who wants to write one, not just Joe...)

On Thu, Jul 7, 2016 at 6:18 PM, Joe Bryan <notifications@github.com
javascript:_e(%7B%7D,'cvml','notifications@github.com');> wrote:

I've made a pass at the advanced synthetic twigs, adding
explicitly-marked pseudocode expansions, and separately titled Compiler
Macro -- the best heading I could come up with... I've also added notes
about macro-hygiene where the expansions appear to be non-hygienic.

And, on a personal note, it's pretty cool how much more sense these all
make after 2 weeks ;)

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#55 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/AALyATU2olQziYmU_HKhVbztfF5fQU3Gks5qTaVqgaJpZM4I9D6c
.

You received this message because you are subscribed to the Google Groups
"urbit" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to urbit-dev+unsubscribe@googlegroups.com
javascript:_e(%7B%7D,'cvml','urbit-dev%2Bunsubscribe@googlegroups.com');
.
To post to this group, send email to urbit-dev@googlegroups.com
javascript:_e(%7B%7D,'cvml','urbit-dev@googlegroups.com');.
For more options, visit https://groups.google.com/d/optout.

[joemfb]

Well, I meant two weeks since I opened this PR ... ;)

I'm about a month into learning Hoon... I'll think about writing something up

[joemfb]

And the hygiene comments are in regards to the Hoon expansions in the docs -- I mean no ill will towards ++open!

[joemfb]

This PR is now handling several different issues:

• adding rune-syntax expansions for simple synthetic runes
• rounding out the truncated discussion section for %~ (see #30)
• adding comments to explain that non-hygienic Hoon expansions are illustrative-only
• adding descriptive pseudocode "compiler macro" expansions in keyword and rune syntax for advanced synthetic twigs

Would it be easier to review as separate PRs? I think the first two are non-controversial, but the last two are more disruptive ...

[philipcmonk]

I like all four points, honestly. Do you have any more concerns before I merge this?

[joemfb]

I'm comfortable with these changes, but every commit after the first includes some amount of editorializing on my part.

• Should the hygiene comments make it explicit that the expansions are always hygienic (or be re-worded in some other way)?
• Are the pseudocode expansions clear without being (too) wrong?
• Are you comfortable with my use of ~|(%mint-lost ...) in place of :lost?

[cgyarvin]

I want to go over it, but I'm happy to do that after it's merged...

Sent from my iPhone

On Jul 13, 2016, at 11:58 AM, Philip Monk notifications@github.com wrote:

I like all four points, honestly. Do you have any more concerns before I merge this?

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

[philipcmonk]

I don't think we need to emphasize that expansions are always hygienic -- one of our systemic problems has been pulling in random facts in the name of "completeness", when it's actually the wrong place for it.

[cgyarvin]

I have merged the mega-PR with rune expansions!

I do feel this area needs a little revisiting in future -- there needs to be one format that's not pseudocody at all. Even the compiler macros are still really pseudocode. They're understandable, though.

I must insist on one point, however: sentence case in all headings :-) It's modern! It's fresh!