Grant: Pretty Printer rewrite

Overview

This project consists of a small project, doccords clean-up, and a larger project, a rewrite of the pretty printer.

The doccords section consists mainly of finalizing the documentation and working with the Urbit Foundation to add the documentation in an appropriate place in docs.urbit.org, probably developer tools, dojo tools, or both. There is some programming work to complete the doccords functionality.

Bugs in the pretty printer and problems with the output format have been long standing frustrations to Urbit developers. Many of these issues have been documented in UIP-119, https://github.com/urbit/UIPs/blob/main/UIPS/UIP-0119.md. This grant addresses most of those documented issues.

Questions at a core blitz session can likely clarify many issues.

General Requirements

1. Clarify ambiguities in the comments of the doccord sample file.

2. Fulfill doccord functionality specified in the sample file or remove it from the user documentation. Coordinate with the core team that code changes are not breaking. Potential breaking changes to user code are probably acceptable.

3. Adapt the text in the file as suitable documentation for docs.urbit.org and work with the UF to implement. Include documentation for both dojo and hoon API (scry) useage.

4. Make code changes to pretty printer to change output format where appropriate to either tall or wide form hoon using : col and $ buc runes. Coordinate with the core team that code changes are not breaking. Potential breaking changes to user code are probably acceptable.

5. Establish an appropriate cell depth beyond which the pretty printer will cease text output.

6. Decorate pretty printer arms with appropriate doccords.

Specific requirements are listed in the acceptance criteria

Acceptance

Doccords

The doccords sample file, and currently only documentation, is ~/base/lib/deco.hoon. All references to documentation below refer to this file.

Doccords parsing arms, +clad, +coat, +scye, and +seam are in the main parsing arm, +vast in the file ~/base/sys/hoon.hoon

When not specifically noted, documentation changes refer to changing deco.hoon and inclusion in new docs.urbit.org docs.

Changes to functionality require writing tests and working with the core team to implement in the core workflow.

1. "any line longer than 60 characters is probably too long" Does this apply to the doccord text alone, or also the leading :: and spaces? Presumably this is so a consuming app like a tooltip is not too wide.

2. "uppercase or non-ascii letters are strongly discouraged" Beginning a prose sentence with lower case looks bad. What is the argument for doing this? There may be other cases that warrant upper case in prose. Maybe "uppercase or non-ascii letters are strongly discouraged (except starting prose sentences)"

3. "the cores are labeled {%arch} (structures) and {%work} (productions)" A short explanation of why %arch in the docs.urbit.com documentation. Also "> # deco/work" results in "Could not find help B". There should be a working demo example, further information, or don't mention it at all.

4. "there are three ways to mark the beginning of a formal comment" Stick with "doccord comment" or "doccord decoration" and "common hoon comment" or just comment to distinguish other comments. Other ideas welcome.

5. style 1, style 2, style 3... The method of printing doccords in the dojo, #, only prints the line with arm defined, and not subsequent paragraphs. (At least this is true for style 2.) Is there a good reason for paragraph text to be separated by EXACTLY 2 or 4 aces and code by 6? Could this not be simplified to a minimum of 2 aces? Support # printing the paragraphs follwing +foo: and $foo:

6. Document the scry to programattically retrieve # and ?? doccords.

7. Implement multi-line doccord. Multi line ceratinly does not work in the dojo, don't know about scry. Confirm this with the core team. Add tests.

8. Only document +foo: and $foo: in docs.urbit.org. Do not confuse users with future plans.

9. For docs.urbit.com, include results for the dojo # and ?? examples. It is worth calling out in this document that +| pseudo-arm has a functional use in doccords.

Pretty Printer

~/base/lib/pprint.hoon

Changes to functionality require writing tests and working with the core team to implement all tests in the core workflow. Sufficient tests is objectively judged by Groundwire and the core team, i.e. no recognized edge case left untested.

References to expected/actual are about the functionality of ~base/lib/test.hoon. Refer to this file for underlying pprint.hoon functionality.

References to need/have can be resolved by looking at the hoon compiler or ~base/lib/test.hoon.

Since the core team has ultimate authority on merging changes, it is prudent to do development in pprint.hoon on new arms with parallel functionality to the existing arms. This allows for easy context switching during development.

1. -:!>(*peer-state:ames) prints #t/#peer-state In the dojo the doccords print, "> ?? *peer-state:ames", gives a useful print out. Tap into this fuctionality for !>. Alternately, create a new hint rune for -:!> if the core team objects to this change.

2. !>(*) , +<.. , ->:!>(\*noun) ,^-((unit dome:clay) *dome:clay) all fail in some manner or produce too much output. When printing value or mold cells, track the cell depth and establish a reasonable maximum depth resulting in printing an ellipsis, ... , or some other mark. (See expected/actual discussion below.)

3. ^-((tree [@t @]) (malt ~[[';' 1] [':' 2] ['!' 3]])) : Prints the tree using set-like {…} syntax. Always print trees with n,l,p cell faces as deep as allowed by the cell depth governor. Print sets as trees as well, this will be required for expected/actual. (See below.)

4. Decorate pprint.hoon arms with doccords. Suggest adding hoon/arrow signature notation "[type1 aura1 ...] -> type-out" to all ++ arms on first line following +foo: and descriptive prose when warranted.

5. expected/actual (printing noun productions)

5a) When the noun is an unmolded atom print the atom value formatted for the aura, if available, otherwise print the @ud formatted atom value.

5b) For cell productions assume a printable area consisting of 80 character columns and as many rows as necessary. Print the production as correctly formatted hoon code.

5c) If an entire cell, including inner cells, fits in the remaining horizontal space, print as wide format hoon.

5d) If printing in tall format, indent inner cells by two aces from the indentation of the parent cell. "Remaining horizontal space" is 80 minus the current indentation index. The == terminating lists, :~, and large tuples, :*, belongs at the same indentation index as the inner cells.

5e) If the top cell production is a molded type, the first print line is "^- {molded-type}". If there is sufficient remaining horizontal space, print the entire molded cell following. If not, begin printing the cell production on the next line, not indented.

5f) If inner cells have faces, and if all the inner cells fit into the remaining horizontal space with faces, print in wide format with faces. If wide format will fit without faces, then print in wide format without faces.

5g) Always print faces, when available, in tall format.

5h) Whether aura-typed or not, never split an atom with a newline, run off the end of horizontal space instead.

5i) When printing recursive types, lists or trees, continue indenting head and tail inner cells for a maximum of 12 iterations. Beyond this print an elipsis for the inner cell and return to the parent indentation.

5j) Always print the i and h faces for lists, and n,l,r faces for trees, even in wide format.

5k) Print sets as trees. ({} is not valid hoon.)

5l) (stretch goal subject to core team) If the mold informaton is available (for inner cells), prefix recursive molds with ^- {mold} on its own line in tall format and the start of the cell production on the next line not indented. Mold definitions may run over the horizontal space.

5m) In tall format, regardless if printing recursive inner cells, or tuple inner cells, if the current indentation index is > 66, print an elipsis and return to the outer cell level.

6. need/have (printing molds) Format as wide and/or tall format mold hoon following essentially the indentation rules as productions.