mirror of
https://github.com/urbit/shrub.git
synced 2025-01-05 11:09:30 +03:00
Unified # syntax for documentation.
This commit is contained in:
Elliot Glaysher
parent
d5f32f972a
commit
de2ed36fbe
553
app/dojo.hoon
553
app/dojo.hoon
@ -42,6 +42,7 @@
|
||||
{$poke p/goal} :: poke app
|
||||
{$show p/?($0 $1 $2 $3)} :: print val+span+twig
|
||||
{$verb p/term} :: store variable
|
||||
{$help p/(list term)} :: look up help
|
||||
== ::
|
||||
++ dojo-source :: construction node
|
||||
$: p/@ud :: assembly index
|
||||
@ -170,6 +171,18 @@
|
||||
(dp-variable (cold %lib lus) ;~(pfix gap dp-hooves))
|
||||
==
|
||||
==
|
||||
::
|
||||
;~ pfix hax
|
||||
;~ pose
|
||||
;~ pfix ace
|
||||
%+ cook
|
||||
|= a/(list term)
|
||||
[[%help a] 0 %ex [%make p=~[[%.y p=1]] q=~]]
|
||||
(most col sym)
|
||||
==
|
||||
(easy [[%help ~] 0 %ex [%make p=~[[%.y p=1]] q=~]])
|
||||
==
|
||||
==
|
||||
::
|
||||
;~((glue ace) dp-sink dp-source)
|
||||
(stag [%show %0] dp-source)
|
||||
@ -461,10 +474,10 @@
|
||||
$eny ~|(%entropy-is-eternal !!)
|
||||
$now ~|(%time-is-immutable !!)
|
||||
$our ~|(%self-is-immutable !!)
|
||||
$lib
|
||||
$lib
|
||||
.(lib ((dy-cast (list hoof:ford) !>(*(list hoof:ford))) q.cay))
|
||||
::
|
||||
$sur
|
||||
$sur
|
||||
.(sur ((dy-cast (list hoof:ford) !>(*(list hoof:ford))) q.cay))
|
||||
::
|
||||
$dir =+ ^= pax ^- path
|
||||
@ -478,7 +491,14 @@
|
||||
rose+[" " `~]^~[leaf+"=%" (smyt (en-beam he-beak s.dir))]
|
||||
==
|
||||
::
|
||||
$poke
|
||||
$help
|
||||
:: =* type +.p.mad
|
||||
:: ?~ type
|
||||
:: (dy-show-help-overview p.q.cay)
|
||||
(dy-inspect +.p.mad p.q.cay)
|
||||
:: (dy-show-help-for-topic type p.q.cay)
|
||||
::
|
||||
$poke
|
||||
%- he-card(poy ~)
|
||||
:* %deal
|
||||
/poke
|
||||
@ -537,6 +557,526 @@
|
||||
t=(turn `wain`?~(r.hit ~ (to-wain:format q.u.r.hit)) trip)
|
||||
==
|
||||
::
|
||||
++ dy-inspect
|
||||
|= {topic/(list term) sut/span}
|
||||
%+ dy-rash %tan
|
||||
|^ ^- tang
|
||||
=+ to-display=(find-item-in-span (flop topic) sut)
|
||||
?~ to-display
|
||||
[%leaf "Could not find help"]~
|
||||
(flop (print-item u.to-display))
|
||||
:> # %models
|
||||
+|
|
||||
::
|
||||
:> an overview of all named things in the span.
|
||||
:>
|
||||
:> each item in the overview list is either a documentation for a sublist
|
||||
:> or an association between a term and documentation for it.
|
||||
++ overview (list overview-item)
|
||||
::
|
||||
:> in instance in the ++overview list.
|
||||
++ overview-item
|
||||
$% :> a header {doc} which will indent its {children}.
|
||||
{$header doc/what children/overview}
|
||||
:> an item in a list with {name} and {docs}.
|
||||
{$item name/tape doc/what}
|
||||
==
|
||||
::
|
||||
:> the part of a {span} being inspected.
|
||||
++ item
|
||||
$% :> overview of span
|
||||
{$view items/overview}
|
||||
:> inspecting a full core.
|
||||
$: $core
|
||||
name/tape
|
||||
docs/what
|
||||
r/span
|
||||
con/coil
|
||||
children/(unit item)
|
||||
==
|
||||
:> inspecting a single arm on a core.
|
||||
$: $arm
|
||||
name/tape
|
||||
docs/what
|
||||
r/span
|
||||
con/coil
|
||||
==
|
||||
:> inspecting a single chapter on a core.
|
||||
$: $chapter
|
||||
name/tape
|
||||
docs/what
|
||||
con/coil
|
||||
chapter-id/@
|
||||
==
|
||||
:> inspecting a face and what's behind it.
|
||||
$: $face
|
||||
name/tape
|
||||
docs/what
|
||||
children/(unit item)
|
||||
==
|
||||
==
|
||||
:> #
|
||||
:> # %searching
|
||||
:> #
|
||||
:> functions which find what to print
|
||||
+|
|
||||
:> returns the item to print while searching through {topic}.
|
||||
:>
|
||||
:> this gate is called recursively to find the path {topic} in the span
|
||||
:> {sut}. once it finds the correct part of the span, it switches to
|
||||
:> ++build-inspectable-recursively to describe that part of the span.
|
||||
++ find-item-in-span
|
||||
|= {topics/(list term) sut/span}
|
||||
^- (unit item)
|
||||
?~ topics
|
||||
:: we have no more search path. return the rest as an overview
|
||||
(build-inspectable-recursively sut)
|
||||
?- sut
|
||||
{$atom *} ~
|
||||
::
|
||||
{$cell *}
|
||||
=+ lhs=$(sut p.sut)
|
||||
?~ lhs
|
||||
$(sut q.sut)
|
||||
lhs
|
||||
::
|
||||
{$core *}
|
||||
=+ core-docs=r.q.sut
|
||||
?~ p.core-docs
|
||||
:: todo: this core has no toplevel documentation. it might have
|
||||
:: an arm though. check that next.
|
||||
$(sut p.sut)
|
||||
?~ (find `(list term)`[i.topics ~] p.core-docs)
|
||||
:: the current topic isn't the toplevel core topic.
|
||||
=+ arm-docs=(find-arm-in-coil i.topics q.sut)
|
||||
?~ arm-docs
|
||||
:: the current topic is neither the name of the core or an arm
|
||||
:: on the core.
|
||||
$(sut p.sut)
|
||||
`[%arm (trip i.topics) u.arm-docs p.sut q.sut]
|
||||
?~ t.topics
|
||||
:: we matched the core name and have no further search terms.
|
||||
=* compiled-against (build-inspectable-recursively p.sut)
|
||||
`[%core (trip i.topics) q.core-docs p.sut q.sut compiled-against]
|
||||
:: search the core for chapters.
|
||||
=/ tombs/(list (pair @ tomb)) (~(tap by q.s.q.sut))
|
||||
|-
|
||||
^- (unit item)
|
||||
?~ tombs
|
||||
~
|
||||
?~ (find `(list term)`[i.t.topics ~] p.p.q.i.tombs)
|
||||
:: this isn't the topic.
|
||||
$(tombs t.tombs)
|
||||
`[%chapter (trip i.t.topics) q.p.q.i.tombs q.sut p.i.tombs]
|
||||
::
|
||||
{$face *}
|
||||
?. ?=(term q.p.sut)
|
||||
:: todo: is there something we could do if we have a tune?
|
||||
~
|
||||
?. =(i.topics q.p.sut)
|
||||
:: this face has a name, but it's not the name we're looking for.
|
||||
~
|
||||
?~ t.topics
|
||||
`[%face (trip q.p.sut) p.p.sut (build-inspectable-recursively q.sut)]
|
||||
(find-item-in-span t.topics q.sut)
|
||||
::
|
||||
{$fork *}
|
||||
=/ spans/(list span) (~(tap in p.sut))
|
||||
|-
|
||||
?~ spans
|
||||
~
|
||||
=+ res=(find-item-in-span topics i.spans)
|
||||
?~ res
|
||||
$(spans t.spans)
|
||||
res
|
||||
::
|
||||
{$help *}
|
||||
:: while we found a raw help, it's associated on the wrong side of a
|
||||
:: set of topics. Walk through it instead of showing it.
|
||||
(find-item-in-span t.topics q.sut)
|
||||
::
|
||||
{$hold *} $(sut (~(play ut p.sut) q.sut))
|
||||
$noun ~
|
||||
$void ~
|
||||
==
|
||||
::
|
||||
:> changes a {span} into an {item}.
|
||||
++ build-inspectable-recursively
|
||||
|= sut/span
|
||||
^- (unit item)
|
||||
?- sut
|
||||
::
|
||||
{$atom *} ~
|
||||
::
|
||||
{$cell *}
|
||||
%+ join-items
|
||||
(build-inspectable-recursively p.sut)
|
||||
(build-inspectable-recursively q.sut)
|
||||
::
|
||||
{$core *}
|
||||
=/ name/term
|
||||
?~ p.r.q.sut
|
||||
''
|
||||
i.p.r.q.sut
|
||||
=* compiled-against (build-inspectable-recursively p.sut)
|
||||
`[%core (trip name) q.r.q.sut p.sut q.sut compiled-against]
|
||||
::
|
||||
{$face *}
|
||||
?. ?=(term q.p.sut)
|
||||
:: todo: can we do anything here if this face doesn't have a term?
|
||||
~
|
||||
=* compiled-against (build-inspectable-recursively q.sut)
|
||||
`[%face (trip q.p.sut) p.p.sut compiled-against]
|
||||
::
|
||||
{$fork *}
|
||||
=/ spans (~(tap in p.sut))
|
||||
=/ items (turn spans build-inspectable-recursively)
|
||||
(roll items join-items)
|
||||
::
|
||||
{$help *}
|
||||
=* rest-span (build-inspectable-recursively q.sut)
|
||||
`[%view [%header p.sut (item-as-overview rest-span)]~]
|
||||
::
|
||||
{$hold *} $(sut (~(play ut p.sut) q.sut))
|
||||
$noun ~
|
||||
$void ~
|
||||
==
|
||||
::
|
||||
:> combines two {(unit item)} together
|
||||
++ join-items
|
||||
|= {lhs/(unit item) rhs/(unit item)}
|
||||
^- (unit item)
|
||||
?~ lhs rhs
|
||||
?~ rhs lhs
|
||||
`[%view (weld (item-as-overview lhs) (item-as-overview rhs))]
|
||||
::
|
||||
:> changes an item into an overview.
|
||||
++ item-as-overview
|
||||
|= uit/(unit item)
|
||||
^- overview
|
||||
?~ uit ~
|
||||
=+ itm=u.uit
|
||||
?- itm
|
||||
::
|
||||
{$view *}
|
||||
items.itm
|
||||
::
|
||||
{$core *}
|
||||
?~ name.itm
|
||||
(item-as-overview children.itm)
|
||||
:- [%item name.itm docs.itm]
|
||||
(item-as-overview children.itm)
|
||||
::
|
||||
{$arm *}
|
||||
[%item name.itm docs.itm]~
|
||||
::
|
||||
{$chapter *}
|
||||
[%item name.itm docs.itm]~
|
||||
::
|
||||
{$face *}
|
||||
?~ name.itm
|
||||
~
|
||||
[%item name.itm docs.itm]~
|
||||
==
|
||||
::
|
||||
:> translate the internals of a core's {tomb} into an {overview}.
|
||||
++ arms-as-overview
|
||||
|= a/(map term (pair what foot))
|
||||
^- overview
|
||||
%+ turn (~(tap by a))
|
||||
|= (pair term (pair what foot))
|
||||
[%item (weld "++" (trip p)) p.q]
|
||||
::
|
||||
:> if {arm-name} is an arm in {c}, returns its documentation.
|
||||
++ find-arm-in-coil
|
||||
|= {arm-name/term con/coil}
|
||||
^- (unit what)
|
||||
=/ tombs (~(tap by q.s.con))
|
||||
|-
|
||||
?~ tombs
|
||||
~
|
||||
=+ item=(~(get by q.q.i.tombs) arm-name)
|
||||
?~ item
|
||||
$(tombs t.tombs)
|
||||
[~ p.u.item]
|
||||
::
|
||||
:> returns an overview for a core's arms and chapters.
|
||||
:>
|
||||
:> returns an overview for arms which are part of unnamed chapters,
|
||||
:> and an overview of the named chapters.
|
||||
++ arm-and-chapter-overviews
|
||||
|= {con/coil core-name/tape}
|
||||
^- {overview overview}
|
||||
=| arm-docs/overview :< documented arms
|
||||
=| chapter-docs/overview :< documented chapters
|
||||
=/ tombs (~(tap by q.s.con))
|
||||
|-
|
||||
?~ tombs
|
||||
[(sort-overview arm-docs) (sort-overview chapter-docs)]
|
||||
=* current q.i.tombs
|
||||
?~ p.p.current
|
||||
:: this chapter has no name. add all the foot documentation
|
||||
:: to arm-docs.
|
||||
=. arm-docs (weld arm-docs (arms-as-overview q.current))
|
||||
$(tombs t.tombs)
|
||||
:: this chapter has a name. add it to the list of chapters
|
||||
=. chapter-docs
|
||||
%+ weld chapter-docs
|
||||
^- overview
|
||||
[%item :(weld (trip i.p.p.current) ":" core-name) q.p.current]~
|
||||
$(tombs t.tombs)
|
||||
::
|
||||
:> returns an overview of the arms in a specific chapter.
|
||||
++ arms-in-chapter
|
||||
|= {con/coil chapter-id/@}
|
||||
^- overview
|
||||
=/ chapter-tomb (~(got by q.s.con) chapter-id)
|
||||
(sort-overview (arms-as-overview q.chapter-tomb))
|
||||
::
|
||||
:> sort the items.
|
||||
++ sort-overview
|
||||
|= ovr/overview
|
||||
^- overview
|
||||
%+ sort ovr
|
||||
|= {lhs/overview-item rhs/overview-item}
|
||||
(aor (get-overview-name lhs) (get-overview-name rhs))
|
||||
::
|
||||
++ get-overview-name
|
||||
|= ovr/overview-item
|
||||
?- ovr
|
||||
{$header *} ""
|
||||
{$item *} name.ovr
|
||||
==
|
||||
::
|
||||
:> #
|
||||
:> # %printing
|
||||
:> #
|
||||
:> functions which display output of various types.
|
||||
+|
|
||||
++ print-item
|
||||
|= itm/item
|
||||
^- tang
|
||||
?- itm
|
||||
{$view *} (print-overview items.itm)
|
||||
{$core *} (print-core +.itm)
|
||||
{$arm *} (print-arm +.itm)
|
||||
{$chapter *} (print-chapter +.itm)
|
||||
{$face *} (print-face +.itm)
|
||||
==
|
||||
::
|
||||
:> renders the documentation for a full core.
|
||||
++ print-core
|
||||
|= {core-name/tape docs/what spn/span con/coil uit/(unit item)}
|
||||
^- tang
|
||||
=+ [arms chapters]=(arm-and-chapter-overviews con core-name)
|
||||
;: weld
|
||||
(print-header (turn p.r.con trip) q.r.con)
|
||||
::
|
||||
:: todo: figure out how to display the default arm, which should
|
||||
:: be rendered separately.
|
||||
::
|
||||
?~ arms
|
||||
~
|
||||
(print-overview [%header `['arms:' ~] arms]~)
|
||||
::
|
||||
?~ chapters
|
||||
~
|
||||
(print-overview [%header `['chapters:' ~] chapters]~)
|
||||
::
|
||||
=+ compiled=(item-as-overview uit)
|
||||
?~ compiled
|
||||
~
|
||||
(print-overview [%header `['compiled against:' ~] compiled]~)
|
||||
==
|
||||
::
|
||||
:> renders the documentation for a single arm in a core.
|
||||
++ print-arm
|
||||
|= {arm-name/tape doc/what r/span con/coil}
|
||||
:: todo: use the coil to figure out what this arm is.
|
||||
?~ doc
|
||||
`tang`[%leaf "{arm-name}: (Undocumented)"]~
|
||||
%+ weld
|
||||
`tang`[%leaf "{arm-name}: {(trip p.u.doc)}"]~
|
||||
(print-sections q.u.doc)
|
||||
::
|
||||
:> renders the documentation for a chapter in a core.
|
||||
++ print-chapter
|
||||
|= {name/tape docs/what con/coil chapter-id/@}
|
||||
;: weld
|
||||
`tang`[%leaf name]~
|
||||
::
|
||||
?~ docs
|
||||
~
|
||||
(print-sections q.u.docs)
|
||||
::
|
||||
=+ arms=(arms-in-chapter con chapter-id)
|
||||
?~ arms
|
||||
~
|
||||
(print-overview [%header `['arms:' ~] arms]~)
|
||||
==
|
||||
::
|
||||
:> renders the documentation for a face.
|
||||
++ print-face
|
||||
|= {name/tape docs/what children/(unit item)}
|
||||
%+ weld
|
||||
(print-header [name ~] docs)
|
||||
?~ children
|
||||
~
|
||||
(print-item u.children)
|
||||
::
|
||||
:> returns a set of lines from a {chap}
|
||||
++ print-header
|
||||
:: todo: it's weird that (list tape) is the type used for names.
|
||||
|= {p/(list tape) docs/what}
|
||||
^- tang
|
||||
?~ p
|
||||
?~ docs
|
||||
[%leaf "(Undocumented)"]~
|
||||
%+ weld
|
||||
`tang`[%leaf "{(trip p.u.docs)}"]~
|
||||
(print-sections q.u.docs)
|
||||
?~ docs
|
||||
[%leaf "{i.p}"]~
|
||||
%+ weld
|
||||
`tang`[%leaf "{i.p}: {(trip p.u.docs)}"]~
|
||||
(print-sections q.u.docs)
|
||||
::
|
||||
:> renders an overview as {tang}
|
||||
++ print-overview
|
||||
|= ovr/overview
|
||||
^- tang
|
||||
|^ (print-level ovr 0)
|
||||
++ print-level
|
||||
:> indentation: multiply by 2 to get number of spaces.
|
||||
|= {ovr/overview indentation/@u}
|
||||
^- tang
|
||||
:> max-key-length: length of the longest {item} term.
|
||||
=/ max-key-length (calculate-max-key-length ovr)
|
||||
:> output: what we return
|
||||
=| output/tang
|
||||
|-
|
||||
?~ ovr
|
||||
output
|
||||
?- i.ovr
|
||||
::
|
||||
{$header *}
|
||||
%= $
|
||||
output ;: weld
|
||||
output
|
||||
?~ doc.i.ovr
|
||||
~
|
||||
`tang`[[%leaf ""] [%leaf "{(trip p.u.doc.i.ovr)}"] ~]
|
||||
?~ doc.i.ovr
|
||||
~
|
||||
(print-sections q.u.doc.i.ovr)
|
||||
(print-level children.i.ovr (add 1 indentation))
|
||||
==
|
||||
ovr t.ovr
|
||||
==
|
||||
::
|
||||
{$item *}
|
||||
=* rendered (render-item indentation max-key-length +.i.ovr)
|
||||
%= $
|
||||
output (weld output rendered)
|
||||
ovr t.ovr
|
||||
==
|
||||
==
|
||||
::
|
||||
:>
|
||||
++ calculate-max-key-length
|
||||
|= ovr/overview
|
||||
^- @u
|
||||
%- dy-longest-tape
|
||||
(turn ovr get-overview-name)
|
||||
::
|
||||
:> renders a single item line with the given indentation level.
|
||||
++ render-item
|
||||
|= {indentation/@u max-key-length/@u name/tape docs/what}
|
||||
^- tang
|
||||
=+ spaces=(mul indentation 2)
|
||||
=+ line=(weld (dy-build-space spaces) name)
|
||||
=+ line-len=(lent line)
|
||||
=+ name-len=(lent name)
|
||||
=+ diff=(sub max-key-length name-len)
|
||||
=? line (gth diff 0)
|
||||
(weld line (dy-build-space diff))
|
||||
=/ slogan/tape
|
||||
?~ docs
|
||||
~
|
||||
(trip p.u.docs)
|
||||
=? line !=(0 (lent slogan))
|
||||
;: weld
|
||||
line
|
||||
" : "
|
||||
(dy-truncate (sub 80 :(add 1 spaces line-len)) slogan)
|
||||
==
|
||||
[%leaf line]~
|
||||
--
|
||||
::
|
||||
:> renders a list of sections as {tang}
|
||||
:>
|
||||
:> prints the longform documentation.
|
||||
++ print-sections
|
||||
|= sections/(list sect)
|
||||
^- tang
|
||||
=| output/tang
|
||||
|-
|
||||
?~ sections
|
||||
output
|
||||
=. output ;: weld
|
||||
output
|
||||
`tang`[%leaf ""]~
|
||||
(print-section i.sections)
|
||||
==
|
||||
$(sections t.sections)
|
||||
::
|
||||
:> renders an individual {sect} to a {tang}
|
||||
++ print-section
|
||||
|= section/sect
|
||||
^- tang
|
||||
%+ turn section
|
||||
|= pica
|
||||
^- tank
|
||||
?: p
|
||||
[%leaf (trip q)]
|
||||
[%leaf " {(trip q)}"]
|
||||
--
|
||||
::
|
||||
:> truncates `t` down to `i` characters, adding an ellipsis.
|
||||
++ dy-truncate
|
||||
:: todo: when ~palfun's string library is landed, switch to his
|
||||
:: implementation.
|
||||
|= {i/@u t/tape}
|
||||
^- tape
|
||||
=+ t-len=(lent t)
|
||||
?: (lth t-len i)
|
||||
t
|
||||
:(weld (scag (sub i 4) t) "...")
|
||||
::
|
||||
:> creates a tape of i spaces, used for padding.
|
||||
++ dy-build-space
|
||||
:: todo: when ~palfun's string library is landed, switch to his
|
||||
:: implementation.
|
||||
|= i/@u
|
||||
^- tape
|
||||
=| t/tape
|
||||
|-
|
||||
?: =(0 i)
|
||||
t
|
||||
$(t (weld " " t), i (sub i 1))
|
||||
::
|
||||
:> returns the length of the longest tape in c.
|
||||
++ dy-longest-tape
|
||||
|= c/(list tape)
|
||||
=| ret/@ud
|
||||
|-
|
||||
?~ c
|
||||
ret
|
||||
=+ l=(lent i.c)
|
||||
?: (gth l ret)
|
||||
$(ret l, c t.c)
|
||||
$(c t.c)
|
||||
::
|
||||
++ dy-show-span-noun
|
||||
|= a/span ^- tank
|
||||
=- >[-]<
|
||||
@ -653,6 +1193,13 @@
|
||||
?~(b !>([~ ~]) (dy-vase p.u.b))
|
||||
::
|
||||
++ dy-twig-head :: dynamic state
|
||||
:: todo: how do i separate the toplevel 'dojo state' comment?
|
||||
:> dojo state
|
||||
:>
|
||||
:> our: the name of this urbit
|
||||
:> now: the current time
|
||||
:> eny: a piece of random entropy
|
||||
:>
|
||||
^- cage
|
||||
:- %noun
|
||||
=+ sloop=|=({a/vase b/vase} ?:(=(*vase a) b ?:(=(*vase b) a (slop a b))))
|
||||
|
||||
Loading…
Reference in New Issue
Block a user