From abab72f80cd298bfabca860251860c77a50d2482 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Wed, 11 Mar 2009 07:18:24 -0500 Subject: [PATCH] Move 'see' to its own vocabulary, and fix excess newlines after panes change --- basis/help/cookbook/cookbook.factor | 2 +- basis/help/definitions/definitions.factor | 4 +- basis/help/handbook/handbook.factor | 1 + basis/help/help-docs.factor | 2 +- basis/help/markup/markup.factor | 6 +- basis/locals/definitions/definitions.factor | 2 +- basis/locals/locals-docs.factor | 2 +- basis/prettyprint/prettyprint-docs.factor | 58 +---- basis/prettyprint/prettyprint-tests.factor | 2 +- basis/prettyprint/prettyprint.factor | 232 +----------------- .../prettyprint/sections/sections-docs.factor | 2 +- basis/see/authors.txt | 1 + basis/see/see-docs.factor | 53 ++++ basis/see/see.factor | 227 +++++++++++++++++ basis/tools/crossref/crossref-docs.factor | 2 +- basis/tools/crossref/crossref.factor | 6 +- basis/ui/tools/profiler/profiler.factor | 2 +- basis/ui/tools/tools-docs.factor | 2 +- core/definitions/definitions-docs.factor | 2 +- core/generic/generic-docs.factor | 2 +- core/words/words-docs.factor | 2 +- 21 files changed, 318 insertions(+), 294 deletions(-) create mode 100644 basis/see/authors.txt create mode 100644 basis/see/see-docs.factor create mode 100644 basis/see/see.factor diff --git a/basis/help/cookbook/cookbook.factor b/basis/help/cookbook/cookbook.factor index b2b65c3913..d6693cd94f 100644 --- a/basis/help/cookbook/cookbook.factor +++ b/basis/help/cookbook/cookbook.factor @@ -1,6 +1,6 @@ USING: help.markup help.syntax io kernel math namespaces parser prettyprint sequences vocabs.loader namespaces stack-checker -help command-line multiline ; +help command-line multiline see ; IN: help.cookbook ARTICLE: "cookbook-syntax" "Basic syntax cookbook" diff --git a/basis/help/definitions/definitions.factor b/basis/help/definitions/definitions.factor index 3e4066d8b7..91ee1c9c79 100644 --- a/basis/help/definitions/definitions.factor +++ b/basis/help/definitions/definitions.factor @@ -1,8 +1,8 @@ -! Copyright (C) 2007, 2008 Slava Pestov. +! Copyright (C) 2007, 2009 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: accessors definitions help help.topics help.syntax prettyprint.backend prettyprint.custom prettyprint words kernel -effects ; +effects see ; IN: help.definitions ! Definition protocol implementation diff --git a/basis/help/handbook/handbook.factor b/basis/help/handbook/handbook.factor index 331fafbbd1..f20732c7ee 100644 --- a/basis/help/handbook/handbook.factor +++ b/basis/help/handbook/handbook.factor @@ -194,6 +194,7 @@ ARTICLE: "io" "Input and output" ARTICLE: "tools" "Developer tools" { $subsection "tools.vocabs" } "Exploratory tools:" +{ $subsection "see" } { $subsection "editor" } { $subsection "listener" } { $subsection "tools.crossref" } diff --git a/basis/help/help-docs.factor b/basis/help/help-docs.factor index 8384799dbd..733199fc60 100644 --- a/basis/help/help-docs.factor +++ b/basis/help/help-docs.factor @@ -1,6 +1,6 @@ USING: help.markup help.crossref help.stylesheet help.topics help.syntax definitions io prettyprint summary arrays math -sequences vocabs strings ; +sequences vocabs strings see ; IN: help ARTICLE: "printing-elements" "Printing markup elements" diff --git a/basis/help/markup/markup.factor b/basis/help/markup/markup.factor index 188cdd1cf8..ea64def751 100644 --- a/basis/help/markup/markup.factor +++ b/basis/help/markup/markup.factor @@ -4,7 +4,7 @@ USING: accessors arrays definitions generic io kernel assocs hashtables namespaces make parser prettyprint sequences strings io.styles vectors words math sorting splitting classes slots fry sets vocabs help.stylesheet help.topics vocabs.loader quotations -combinators call ; +combinators call see ; IN: help.markup PREDICATE: simple-element < array @@ -300,7 +300,7 @@ M: f ($instance) ] with-style ] ($block) ; inline -: $see ( element -- ) first [ see ] ($see) ; +: $see ( element -- ) first [ see* ] ($see) ; : $synopsis ( element -- ) first [ synopsis write ] ($see) ; @@ -345,6 +345,8 @@ M: f ($instance) drop "Throws an error if the I/O operation fails." $errors ; +FROM: prettyprint.private => with-pprint ; + : $prettyprinting-note ( children -- ) drop { "This word should only be called from inside the " diff --git a/basis/locals/definitions/definitions.factor b/basis/locals/definitions/definitions.factor index 99f9d0bd22..a4299d0684 100644 --- a/basis/locals/definitions/definitions.factor +++ b/basis/locals/definitions/definitions.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2007, 2008 Slava Pestov, Eduardo Cavazos. ! See http://factorcode.org/license.txt for BSD license. USING: accessors definitions effects generic kernel locals -macros memoize prettyprint prettyprint.backend words ; +macros memoize prettyprint prettyprint.backend see words ; IN: locals.definitions PREDICATE: lambda-word < word "lambda" word-prop >boolean ; diff --git a/basis/locals/locals-docs.factor b/basis/locals/locals-docs.factor index 0998d84530..18dabed4b0 100644 --- a/basis/locals/locals-docs.factor +++ b/basis/locals/locals-docs.factor @@ -1,5 +1,5 @@ USING: help.syntax help.markup kernel macros prettyprint -memoize combinators arrays generalizations ; +memoize combinators arrays generalizations see ; IN: locals HELP: [| diff --git a/basis/prettyprint/prettyprint-docs.factor b/basis/prettyprint/prettyprint-docs.factor index 1e372d7cc0..2be725c0f6 100644 --- a/basis/prettyprint/prettyprint-docs.factor +++ b/basis/prettyprint/prettyprint-docs.factor @@ -1,6 +1,7 @@ USING: prettyprint.backend prettyprint.config prettyprint.custom prettyprint.sections prettyprint.private help.markup help.syntax -io kernel words definitions quotations strings generic classes ; +io kernel words definitions quotations strings generic classes +prettyprint.private ; IN: prettyprint ARTICLE: "prettyprint-numbers" "Prettyprinting numbers" @@ -149,10 +150,6 @@ $nl { $subsection unparse-use } "Utility for tabular output:" { $subsection pprint-cell } -"Printing a definition (see " { $link "definitions" } "):" -{ $subsection see } -"Printing the methods defined on a generic word or class (see " { $link "objects" } "):" -{ $subsection see-methods } "More prettyprinter usage:" { $subsection "prettyprint-numbers" } { $subsection "prettyprint-stacks" } @@ -160,7 +157,7 @@ $nl { $subsection "prettyprint-variables" } { $subsection "prettyprint-extension" } { $subsection "prettyprint-limitations" } -{ $see-also "number-strings" } ; +{ $see-also "number-strings" "see" } ; ABOUT: "prettyprint" @@ -232,51 +229,4 @@ HELP: .s HELP: in. { $values { "vocab" "a vocabulary specifier" } } { $description "Prettyprints a " { $snippet "IN:" } " declaration." } -$prettyprinting-note ; - -HELP: synopsis -{ $values { "defspec" "a definition specifier" } { "str" string } } -{ $contract "Prettyprints the prologue of a definition." } ; - -HELP: synopsis* -{ $values { "defspec" "a definition specifier" } } -{ $contract "Adds sections to the current block corresponding to a the prologue of a definition, in source code-like form." } -{ $notes "This word should only be called from inside the " { $link with-pprint } " combinator. Client code should call " { $link synopsis } " instead." } ; - -HELP: comment. -{ $values { "string" "a string" } } -{ $description "Prettyprints some text with the comment style." } -$prettyprinting-note ; - -HELP: see -{ $values { "defspec" "a definition specifier" } } -{ $contract "Prettyprints a definition." } ; - -HELP: see-methods -{ $values { "word" "a " { $link generic } " or a " { $link class } } } -{ $contract "Prettyprints the methods defined on a generic word or class." } ; - -HELP: definer -{ $values { "defspec" "a definition specifier" } { "start" word } { "end" "a word or " { $link f } } } -{ $contract "Outputs the parsing words which delimit the definition." } -{ $examples - { $example "USING: definitions prettyprint ;" - "IN: scratchpad" - ": foo ; \\ foo definer . ." - ";\nPOSTPONE: :" - } - { $example "USING: definitions prettyprint ;" - "IN: scratchpad" - "SYMBOL: foo \\ foo definer . ." - "f\nPOSTPONE: SYMBOL:" - } -} -{ $notes "This word is used in the implementation of " { $link see } "." } ; - -HELP: definition -{ $values { "defspec" "a definition specifier" } { "seq" "a sequence" } } -{ $contract "Outputs the body of a definition." } -{ $examples - { $example "USING: definitions math prettyprint ;" "\\ sq definition ." "[ dup * ]" } -} -{ $notes "This word is used in the implementation of " { $link see } "." } ; +$prettyprinting-note ; \ No newline at end of file diff --git a/basis/prettyprint/prettyprint-tests.factor b/basis/prettyprint/prettyprint-tests.factor index b1239086d7..aaaf6b80d1 100644 --- a/basis/prettyprint/prettyprint-tests.factor +++ b/basis/prettyprint/prettyprint-tests.factor @@ -3,7 +3,7 @@ kernel math namespaces parser prettyprint prettyprint.config prettyprint.sections sequences tools.test vectors words effects splitting generic.standard prettyprint.private continuations generic compiler.units tools.walker eval -accessors make vocabs.parser ; +accessors make vocabs.parser see ; IN: prettyprint.tests [ "4" ] [ 4 unparse ] unit-test diff --git a/basis/prettyprint/prettyprint.factor b/basis/prettyprint/prettyprint.factor index af56a4d2d0..7ef15b9a2f 100644 --- a/basis/prettyprint/prettyprint.factor +++ b/basis/prettyprint/prettyprint.factor @@ -1,16 +1,14 @@ -! Copyright (C) 2003, 2008 Slava Pestov. +! Copyright (C) 2003, 2009 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. -USING: arrays generic generic.standard assocs io kernel math -namespaces make sequences strings io.styles io.streams.string -vectors words words.symbol prettyprint.backend prettyprint.custom -prettyprint.sections prettyprint.config sorting splitting -grouping math.parser vocabs definitions effects classes.builtin -classes.tuple io.pathnames classes continuations hashtables -classes.mixin classes.union classes.intersection -classes.predicate classes.singleton combinators quotations sets -accessors colors parser summary vocabs.parser ; +USING: accessors assocs colors combinators grouping io +io.streams.string io.styles kernel make math math.parser namespaces +parser prettyprint.backend prettyprint.config prettyprint.custom +prettyprint.sections quotations sequences sorting strings vocabs +vocabs.parser words ; IN: prettyprint + + : with-use ( obj quot -- ) make-pprint use/in. do-pprint ; inline @@ -165,214 +165,4 @@ SYMBOL: pprint-string-cells? ] each ] with-row ] each - ] tabular-output nl ; - -GENERIC: see ( defspec -- ) - -: comment. ( string -- ) - [ H{ { font-style italic } } styled-text ] when* ; - -: seeing-word ( word -- ) - vocabulary>> pprinter-in set ; - -: definer. ( defspec -- ) - definer drop pprint-word ; - -: stack-effect. ( word -- ) - [ [ parsing-word? ] [ symbol? ] bi or not ] [ stack-effect ] bi and - [ effect>string comment. ] when* ; - -: word-synopsis ( word -- ) - { - [ seeing-word ] - [ definer. ] - [ pprint-word ] - [ stack-effect. ] - } cleave ; - -M: word synopsis* word-synopsis ; - -M: simple-generic synopsis* word-synopsis ; - -M: standard-generic synopsis* - { - [ definer. ] - [ seeing-word ] - [ pprint-word ] - [ dispatch# pprint* ] - [ stack-effect. ] - } cleave ; - -M: hook-generic synopsis* - { - [ definer. ] - [ seeing-word ] - [ pprint-word ] - [ "combination" word-prop var>> pprint* ] - [ stack-effect. ] - } cleave ; - -M: method-spec synopsis* - first2 method synopsis* ; - -M: method-body synopsis* - [ definer. ] - [ "method-class" word-prop pprint-word ] - [ "method-generic" word-prop pprint-word ] tri ; - -M: mixin-instance synopsis* - [ definer. ] - [ class>> pprint-word ] - [ mixin>> pprint-word ] tri ; - -M: pathname synopsis* pprint* ; - -: synopsis ( defspec -- str ) - [ - 0 margin set - 1 line-limit set - [ synopsis* ] with-in - ] with-string-writer ; - -M: word summary synopsis ; - -GENERIC: declarations. ( obj -- ) - -M: object declarations. drop ; - -: declaration. ( word prop -- ) - [ nip ] [ name>> word-prop ] 2bi - [ pprint-word ] [ drop ] if ; - -M: word declarations. - { - POSTPONE: parsing - POSTPONE: delimiter - POSTPONE: inline - POSTPONE: recursive - POSTPONE: foldable - POSTPONE: flushable - } [ declaration. ] with each ; - -: pprint-; ( -- ) \ ; pprint-word ; - -M: object see - [ - 12 nesting-limit set - 100 length-limit set - - dup definer nip [ pprint-word ] when* declarations. - block> - ] with-use nl ; - -M: method-spec see - first2 method see ; - -GENERIC: see-class* ( word -- ) - -M: union-class see-class* - ; - -M: intersection-class see-class* - ; - -M: mixin-class see-class* - block> ; - -M: predicate-class see-class* - block> ; - -M: singleton-class see-class* ( class -- ) - \ SINGLETON: pprint-word pprint-word ; - -GENERIC: pprint-slot-name ( object -- ) - -M: string pprint-slot-name text ; - -M: array pprint-slot-name - - \ } pprint-word block> ; - -: unparse-slot ( slot-spec -- array ) - [ - dup name>> , - dup class>> object eq? [ - dup class>> , - initial: , - dup initial>> , - ] unless - dup read-only>> [ - read-only , - ] when - drop - ] { } make ; - -: pprint-slot ( slot-spec -- ) - unparse-slot - dup length 1 = [ first ] when - pprint-slot-name ; - -M: tuple-class see-class* - - pprint-; block> ; - -M: word see-class* drop ; - -M: builtin-class see-class* - drop "! Built-in class" comment. ; - -: see-class ( class -- ) - dup class? [ - [ - dup seeing-word dup see-class* - ] with-use nl - ] when drop ; - -M: word see - [ see-class ] - [ [ class? ] [ symbol? not ] bi and [ nl ] when ] - [ - dup [ class? ] [ symbol? ] bi and - [ drop ] [ call-next-method ] if - ] tri ; - -: see-all ( seq -- ) - natural-sort [ nl ] [ see ] interleave ; - -: (see-implementors) ( class -- seq ) - dup implementors [ method ] with map natural-sort ; - -: (see-methods) ( generic -- seq ) - "methods" word-prop values natural-sort ; - -: methods ( word -- seq ) - [ - dup class? [ dup (see-implementors) % ] when - dup generic? [ dup (see-methods) % ] when - drop - ] { } make prune ; - -: see-methods ( word -- ) - methods see-all ; + ] tabular-output nl ; \ No newline at end of file diff --git a/basis/prettyprint/sections/sections-docs.factor b/basis/prettyprint/sections/sections-docs.factor index 4f1c073a2d..ce7430d040 100644 --- a/basis/prettyprint/sections/sections-docs.factor +++ b/basis/prettyprint/sections/sections-docs.factor @@ -199,7 +199,7 @@ HELP: string comment. ] when* ; + +> pprinter-in set ; + +: word-synopsis ( word -- ) + { + [ seeing-word ] + [ definer. ] + [ pprint-word ] + [ stack-effect. ] + } cleave ; + +M: word synopsis* word-synopsis ; + +M: simple-generic synopsis* word-synopsis ; + +M: standard-generic synopsis* + { + [ definer. ] + [ seeing-word ] + [ pprint-word ] + [ dispatch# pprint* ] + [ stack-effect. ] + } cleave ; + +M: hook-generic synopsis* + { + [ definer. ] + [ seeing-word ] + [ pprint-word ] + [ "combination" word-prop var>> pprint* ] + [ stack-effect. ] + } cleave ; + +M: method-spec synopsis* + first2 method synopsis* ; + +M: method-body synopsis* + [ definer. ] + [ "method-class" word-prop pprint-word ] + [ "method-generic" word-prop pprint-word ] tri ; + +M: mixin-instance synopsis* + [ definer. ] + [ class>> pprint-word ] + [ mixin>> pprint-word ] tri ; + +M: pathname synopsis* pprint* ; + +M: word summary synopsis ; + +GENERIC: declarations. ( obj -- ) + +M: object declarations. drop ; + +: declaration. ( word prop -- ) + [ nip ] [ name>> word-prop ] 2bi + [ pprint-word ] [ drop ] if ; + +M: word declarations. + { + POSTPONE: parsing + POSTPONE: delimiter + POSTPONE: inline + POSTPONE: recursive + POSTPONE: foldable + POSTPONE: flushable + } [ declaration. ] with each ; + +: pprint-; ( -- ) \ ; pprint-word ; + +M: object see* + [ + 12 nesting-limit set + 100 length-limit set + + dup definer nip [ pprint-word ] when* declarations. + block> + ] with-use ; + +M: method-spec see* + first2 method see* ; + +GENERIC: see-class* ( word -- ) + +M: union-class see-class* + ; + +M: intersection-class see-class* + ; + +M: mixin-class see-class* + block> ; + +M: predicate-class see-class* + block> ; + +M: singleton-class see-class* ( class -- ) + \ SINGLETON: pprint-word pprint-word ; + +GENERIC: pprint-slot-name ( object -- ) + +M: string pprint-slot-name text ; + +M: array pprint-slot-name + + \ } pprint-word block> ; + +: unparse-slot ( slot-spec -- array ) + [ + dup name>> , + dup class>> object eq? [ + dup class>> , + initial: , + dup initial>> , + ] unless + dup read-only>> [ + read-only , + ] when + drop + ] { } make ; + +: pprint-slot ( slot-spec -- ) + unparse-slot + dup length 1 = [ first ] when + pprint-slot-name ; + +M: tuple-class see-class* + + pprint-; block> ; + +M: word see-class* drop ; + +M: builtin-class see-class* + drop "! Built-in class" comment. ; + +: see-class ( class -- ) + dup class? [ + [ + [ seeing-word ] [ see-class* ] bi + ] with-use + ] [ drop ] if ; + +M: word see* + [ see-class ] + [ [ class? ] [ symbol? not ] bi and [ nl ] when ] + [ + dup [ class? ] [ symbol? ] bi and + [ drop ] [ call-next-method ] if + ] tri ; + +: seeing-implementors ( class -- seq ) + dup implementors [ method ] with map natural-sort ; + +: seeing-methods ( generic -- seq ) + "methods" word-prop values natural-sort ; + +PRIVATE> + +: see-all ( seq -- ) + natural-sort [ nl nl ] [ see* ] interleave ; + +: methods ( word -- seq ) + [ + dup class? [ dup seeing-implementors % ] when + dup generic? [ dup seeing-methods % ] when + drop + ] { } make prune ; + +: see-methods ( word -- ) + methods see-all nl ; \ No newline at end of file diff --git a/basis/tools/crossref/crossref-docs.factor b/basis/tools/crossref/crossref-docs.factor index 820c957cbc..f49ac7ea76 100644 --- a/basis/tools/crossref/crossref-docs.factor +++ b/basis/tools/crossref/crossref-docs.factor @@ -3,7 +3,7 @@ IN: tools.crossref ARTICLE: "tools.crossref" "Cross-referencing tools" { $subsection usage. } -{ $see-also "definitions" "words" see see-methods } ; +{ $see-also "definitions" "words" "see" } ; ABOUT: "tools.crossref" diff --git a/basis/tools/crossref/crossref.factor b/basis/tools/crossref/crossref.factor index 494e022243..36ccaadc98 100644 --- a/basis/tools/crossref/crossref.factor +++ b/basis/tools/crossref/crossref.factor @@ -1,11 +1,11 @@ -! Copyright (C) 2005, 2008 Slava Pestov. +! Copyright (C) 2005, 2009 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: assocs definitions io io.styles kernel prettyprint -sorting ; +sorting see ; IN: tools.crossref : synopsis-alist ( definitions -- alist ) - [ dup synopsis swap ] { } map>assoc ; + [ [ synopsis ] keep ] { } map>assoc ; : definitions. ( alist -- ) [ write-object nl ] assoc-each ; diff --git a/basis/ui/tools/profiler/profiler.factor b/basis/ui/tools/profiler/profiler.factor index 0ab1519cd7..bbd9237c87 100644 --- a/basis/ui/tools/profiler/profiler.factor +++ b/basis/ui/tools/profiler/profiler.factor @@ -3,7 +3,7 @@ USING: kernel quotations accessors fry assocs present math.order math.vectors arrays locals models.search models.sort models sequences vocabs tools.profiler words prettyprint combinators.smart -definitions.icons ui ui.commands ui.gadgets ui.gadgets.panes +definitions.icons see ui ui.commands ui.gadgets ui.gadgets.panes ui.gadgets.scrollers ui.gadgets.tracks ui.gestures ui.gadgets.buttons ui.gadgets.tables ui.gadgets.search-tables ui.gadgets.labeled ui.gadgets.buttons ui.gadgets.packs ui.gadgets.labels diff --git a/basis/ui/tools/tools-docs.factor b/basis/ui/tools/tools-docs.factor index 9e63be09ab..d3078cc178 100644 --- a/basis/ui/tools/tools-docs.factor +++ b/basis/ui/tools/tools-docs.factor @@ -1,7 +1,7 @@ USING: editors help.markup help.syntax summary inspector io io.styles listener parser prettyprint tools.profiler tools.walker ui.commands ui.gadgets.panes ui.gadgets.presentations ui.operations -ui.tools.operations ui.tools.profiler ui.tools.common vocabs ; +ui.tools.operations ui.tools.profiler ui.tools.common vocabs see ; IN: ui.tools ARTICLE: "starting-ui-tools" "Starting the UI tools" diff --git a/core/definitions/definitions-docs.factor b/core/definitions/definitions-docs.factor index d43c61ff70..21537906da 100644 --- a/core/definitions/definitions-docs.factor +++ b/core/definitions/definitions-docs.factor @@ -61,7 +61,7 @@ ARTICLE: "definitions" "Definitions" { $subsection "definition-crossref" } { $subsection "definition-checking" } { $subsection "compilation-units" } -{ $see-also "parser" "source-files" "words" "generic" "help-impl" } ; +{ $see-also "see" "parser" "source-files" "words" "generic" "help-impl" } ; ABOUT: "definitions" diff --git a/core/generic/generic-docs.factor b/core/generic/generic-docs.factor index 429e272647..613dbf72a4 100644 --- a/core/generic/generic-docs.factor +++ b/core/generic/generic-docs.factor @@ -47,7 +47,7 @@ $nl { $subsection } "A " { $emphasis "method specifier" } " refers to a method and implements the " { $link "definition-protocol" } ":" { $subsection method-spec } -{ $see-also see see-methods } ; +{ $see-also "see" } ; ARTICLE: "method-combination" "Custom method combination" "Abstractly, a generic word can be thought of as a big chain of type conditional tests applied to the top of the stack, with methods as the bodies of each test. The " { $emphasis "method combination" } " is this control flow glue between the set of methods, and several aspects of it can be customized:" diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor index f5990c295e..9c32a8094e 100644 --- a/core/words/words-docs.factor +++ b/core/words/words-docs.factor @@ -161,7 +161,7 @@ $nl { $subsection "word-definition" } { $subsection "word-props" } { $subsection "word.private" } -{ $see-also "vocabularies" "vocabs.loader" "definitions" } ; +{ $see-also "vocabularies" "vocabs.loader" "definitions" "see" } ; ABOUT: "words"