the issue with compiling not working is with doccords on the deferred
expression, not everything that follows (which would turn off doccords
for anything past =*)
see #6307
this turns doccord parsing off for =* and +*, which was not intended to
be allowed for the first release, but it ended up not compiling if
postfix doccords were put on either of these.
the right way to fix this is to actually implement doccord parsing for
=* and +*, but at least turning them off seems to fix the compile error here.
In the `+ape` parser constructor, we were providing `0` as the parsing result
for the zero character. Hoon syntax dictates this is a `@ud` however,
resulting in a parsing output type of `?(@ud etc)`. Since `+ape` is commonly
used for parsing atoms of various kinds, one might end up with a result
of `?(@ud @)`, which would fail to nest directly under, say, `@uv`, requiring
parsers to add a casting step.
Here, we simply cast the zero result to `@` to make it perfectly generic. This
should alleviate the need for a casting step in parsers that need to fit their
output into a specific aura.
(The output type in the common case (ie, `+hex:ag`, `+viz:ag`) is now `?(@ @)`,
which is still somewhat strange, but should have better ergonomics.)
Since `@` can be used in any place `@ud` is accepted, this is a non-breaking
change.
This reverts commit 31bb93846c, reversing
changes made to 7940dd442b.
Reverting because we can't upgrade jetted code without ensuring the jets
change in lockstep.
See #6052. This is completely different from the +* used at the top
of doors, and has almost entirely been replaced by |$. The exception is
the use of the `%made` spec, not present in `|$`. I do not see an
obvious way to change `|$` to use `%made` since this `+*` parser uses
the name of the arm in the `%made` structure, unless we change the
AST of |$.
|* foo bar is sugar for =+ foo |@ ++ $ bar --, and newbies find
the old style confusing. this switches out the |@ pattern for the |*
one, at least in layer <=4. the only ones remaining are +toad, +rune,
and +runo, which are already tweaked in #5873 so we omit them here.
all this did was set .nut. while it could be used with doccords, it is
currently unused, and none of the other values in the sample of _ax are
set this way (bug, def, cox, hay, dom). i experimented a little bit with
trying to make use of this but it made things overall more unreadable,
and it wouldn't make sense to do it without doing the same for other
values of the sample. im guessing this is just an old style.
when +apse sees a link, it presume that the following a batch comment,
and stops parsing so that it can be picked up by apex:docs next
this required a change to +leap, which has been rewritten to pretty much
look like +gap but stop parsing when encountering doccords.
previously we just threw them out and wasn't sure whether it was the
right answer. this violates the principle of least surprise - even
though it hard to see the value of attaching multiple empty $cuff notes
to an arm, we shouldn't stop the programmer from doing it without any
indication or explanation as to why. its the behaviour you'd expect
given how doccords is structured.
it is desirable for both apex:docs and apse:docs to parse into an
intermediate representation that never ends up in an AST so that it is
clear that these parsed representations may be altered in the future
without worrying about old types nesting with new types. this was
already the case for $whit, but apse:docs parsed directly as a $help,
which is used in ASTs. so apse:docs now parses as a $whiz, which is
simply a cord. in the future, if postfix comments are used for something
like invariants, or allow $links, we may want to change this.
this also changes $whit to remove .use, which was unused. similarly,
+glom is removed since its not used anywhere.
this might actually be undesirable, don't want to leave this as a trap
for somebody in the future thinking we knew it was definitely the right
answer. having batch comments follow the chapter declaration does make a
certain amount of sense, stylistically
future-proofing %gist specs by putting a %help tag on the $help. this
looks pointless at first glance, but it allows the opportunity for %gist
specs to have a $% in the future in a way such that the old type nests
with the new one, eliding the need for a typo->type migration
