From ad2ae73b67892efd30f0bd40ee62520d8ad7a64b Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Mon, 25 Jan 2010 18:02:38 +1300 Subject: [PATCH 1/7] mason.child: run nmake on Windows --- extra/mason/child/child-tests.factor | 2 +- extra/mason/child/child.factor | 9 ++++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/extra/mason/child/child-tests.factor b/extra/mason/child/child-tests.factor index 2d5a7c6635..6fedac87bd 100644 --- a/extra/mason/child/child-tests.factor +++ b/extra/mason/child/child-tests.factor @@ -1,7 +1,7 @@ IN: mason.child.tests USING: mason.child mason.config tools.test namespaces io kernel sequences ; -[ { "make" "winnt-x86-32" } ] [ +[ { "nmake" "/f" "nmakefile" } ] [ [ "winnt" target-os set "x86.32" target-cpu set diff --git a/extra/mason/child/child.factor b/extra/mason/child/child.factor index 193ac1e212..017e4401d8 100644 --- a/extra/mason/child/child.factor +++ b/extra/mason/child/child.factor @@ -1,14 +1,17 @@ -! Copyright (C) 2008, 2009 Eduardo Cavazos, Slava Pestov. +! Copyright (C) 2008, 2010 Eduardo Cavazos, Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: accessors arrays calendar combinators.short-circuit fry continuations debugger io.directories io.files io.launcher io.pathnames io.encodings.ascii kernel make mason.common mason.config mason.platform mason.report mason.notify namespaces sequences -quotations macros ; +quotations macros system combinators ; IN: mason.child : make-cmd ( -- args ) - gnu-make platform 2array ; + { + { [ target-os get "winnt" = ] [ { "nmake" "/f" "nmakefile" } ] } + [ gnu-make platform 2array ] + } cond ; : make-vm ( -- ) "factor" [ From aadf2873d11723ff78f7a8d289eba2c578867b1e Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Mon, 25 Jan 2010 19:10:17 +1300 Subject: [PATCH 2/7] ui.gadgets: make fast-children-on more flexible and take a quotation instead of always calling loc>> on elements of the children array. This enables a bug fix for M\ grid children-on, discovered from UI mis-rendering of '\ blend-mode help' --- basis/ui/gadgets/gadgets.factor | 21 ++++++++++---------- basis/ui/gadgets/grids/grids-tests.factor | 24 +++++++++++++++++++++-- basis/ui/gadgets/grids/grids.factor | 13 +++++++----- basis/ui/gadgets/packs/packs.factor | 5 ++--- basis/ui/gadgets/panes/panes.factor | 5 +++-- 5 files changed, 46 insertions(+), 22 deletions(-) diff --git a/basis/ui/gadgets/gadgets.factor b/basis/ui/gadgets/gadgets.factor index 8eb11a7753..7e47bf627b 100644 --- a/basis/ui/gadgets/gadgets.factor +++ b/basis/ui/gadgets/gadgets.factor @@ -1,4 +1,4 @@ -! Copyright (C) 2005, 2009 Slava Pestov. +! Copyright (C) 2005, 2010 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: accessors arrays hashtables kernel math namespaces make sequences quotations math.vectors combinators sorting @@ -62,18 +62,19 @@ M: gadget children-on nip children>> ; ) - [ swap loc>> v- ] dip v. 0 <=> ; - -:: (fast-children-on) ( dim axis children -- i ) - children [ dim axis ((fast-children-on)) ] search drop ; +:: (fast-children-on) ( point axis children quot -- i ) + children [ + [ point ] dip + quot call( value -- loc ) v- + axis v. 0 <=> + ] search drop ; inline PRIVATE> -: fast-children-on ( rect axis children -- from to ) - [ [ loc>> ] 2dip (fast-children-on) 0 or ] - [ [ rect-bounds v+ ] 2dip (fast-children-on) ?1+ ] - 3bi ; +:: fast-children-on ( rect axis children quot -- slice ) + rect loc>> axis children quot (fast-children-on) 0 or + rect rect-bounds v+ axis children quot (fast-children-on) ?1+ + children ; inline M: gadget contains-rect? ( bounds gadget -- ? ) dup visible?>> [ call-next-method ] [ 2drop f ] if ; diff --git a/basis/ui/gadgets/grids/grids-tests.factor b/basis/ui/gadgets/grids/grids-tests.factor index b83f1a7003..3dc0e6b862 100644 --- a/basis/ui/gadgets/grids/grids-tests.factor +++ b/basis/ui/gadgets/grids/grids-tests.factor @@ -1,12 +1,14 @@ USING: ui.gadgets ui.gadgets.grids tools.test kernel arrays namespaces math.rectangles accessors ui.gadgets.grids.private -ui.gadgets.debug sequences ; +ui.gadgets.debug sequences classes ; IN: ui.gadgets.grids.tests [ { 0 0 } ] [ { } pref-dim ] unit-test : 100x100 ( -- gadget ) { 100 100 } >>dim ; +: 200x200 ( -- gadget ) { 200 200 } >>dim ; + [ { 100 100 } ] [ 100x100 1array 1array pref-dim @@ -81,4 +83,22 @@ IN: ui.gadgets.grids.tests "g" get dup layout children>> [ loc>> ] map -] unit-test \ No newline at end of file +] unit-test + +! children-on logic was insufficient +[ ] [ + 100x100 dup "a" set 200x200 2array + 100x100 dup "b" set 200x200 2array 2array f >>fill? "g" set +] unit-test + +[ ] [ "g" get prefer ] unit-test +[ ] [ "g" get layout ] unit-test + +[ { 0 50 } ] [ "a" get loc>> ] unit-test +[ { 0 250 } ] [ "b" get loc>> ] unit-test + +[ gadget { 200 200 } ] +[ { 120 20 } "g" get pick-up [ class ] [ dim>> ] bi ] unit-test + +[ gadget { 200 200 } ] +[ { 120 220 } "g" get pick-up [ class ] [ dim>> ] bi ] unit-test \ No newline at end of file diff --git a/basis/ui/gadgets/grids/grids.factor b/basis/ui/gadgets/grids/grids.factor index 9b5b737406..2e964b48b6 100644 --- a/basis/ui/gadgets/grids/grids.factor +++ b/basis/ui/gadgets/grids/grids.factor @@ -1,7 +1,8 @@ -! Copyright (C) 2006, 2009 Slava Pestov. +! Copyright (C) 2006, 2010 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. -USING: arrays kernel math math.order math.matrices namespaces make sequences words io -math.vectors ui.gadgets ui.baseline-alignment columns accessors strings.tables +USING: arrays kernel math math.order math.matrices namespaces +make sequences words io math.vectors ui.gadgets +ui.baseline-alignment columns accessors strings.tables math.rectangles fry ; IN: ui.gadgets.grids @@ -115,8 +116,10 @@ M: grid layout* [ grid>> ] [ ] bi grid-layout ; M: grid children-on ( rect gadget -- seq ) dup children>> empty? [ 2drop f ] [ - [ { 0 1 } ] dip grid>> - [ 0 fast-children-on ] [ concat ] bi + [ { 0 1 } ] dip + [ grid>> ] [ dim>> ] bi + '[ _ [ loc>> vmin ] reduce ] fast-children-on + concat ] if ; M: grid gadget-text* diff --git a/basis/ui/gadgets/packs/packs.factor b/basis/ui/gadgets/packs/packs.factor index f47b374aeb..5f21d74180 100644 --- a/basis/ui/gadgets/packs/packs.factor +++ b/basis/ui/gadgets/packs/packs.factor @@ -1,4 +1,4 @@ -! Copyright (C) 2005, 2009 Slava Pestov. +! Copyright (C) 2005, 2010 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: sequences ui.gadgets ui.baseline-alignment ui.baseline-alignment.private kernel math math.functions math.vectors @@ -100,5 +100,4 @@ M: pack layout* dup children>> pref-dims pack-layout ; M: pack children-on ( rect gadget -- seq ) - [ orientation>> ] [ children>> ] bi - [ fast-children-on ] keep ; + [ orientation>> ] [ children>> ] bi [ loc>> ] fast-children-on ; diff --git a/basis/ui/gadgets/panes/panes.factor b/basis/ui/gadgets/panes/panes.factor index 50a609b897..8fec7e45ce 100644 --- a/basis/ui/gadgets/panes/panes.factor +++ b/basis/ui/gadgets/panes/panes.factor @@ -1,4 +1,4 @@ -! Copyright (C) 2005, 2009 Slava Pestov. +! Copyright (C) 2005, 2010 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: arrays hashtables io kernel namespaces sequences strings quotations math opengl combinators memoize math.vectors @@ -352,7 +352,8 @@ M: paragraph stream-format GENERIC: sloppy-pick-up* ( loc gadget -- n ) M: pack sloppy-pick-up* ( loc gadget -- n ) - [ orientation>> ] [ children>> ] bi (fast-children-on) ; + [ orientation>> ] [ children>> ] bi + [ loc>> ] (fast-children-on) ; M: gadget sloppy-pick-up* children>> [ contains-point? ] with find-last drop ; From d4435ed32af75c088e7ee00bcfce02169504efce Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Mon, 25 Jan 2010 19:20:13 +1300 Subject: [PATCH 3/7] command-line: if -e= is passed, don't run main vocab after evaluation ends --- basis/bootstrap/finish-bootstrap.factor | 11 ++++++++--- basis/command-line/command-line-docs.factor | 4 ---- basis/command-line/command-line.factor | 3 --- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/basis/bootstrap/finish-bootstrap.factor b/basis/bootstrap/finish-bootstrap.factor index 70ccaedad4..387903d1e9 100644 --- a/basis/bootstrap/finish-bootstrap.factor +++ b/basis/bootstrap/finish-bootstrap.factor @@ -8,9 +8,14 @@ namespaces eval kernel vocabs.loader io ; (command-line) parse-command-line load-vocab-roots run-user-init - "e" get [ eval( -- ) ] when* - ignore-cli-args? not script get and - [ run-script ] [ "run" get run ] if* + + "e" get script get or [ + "e" get [ eval( -- ) ] when* + script get [ run-script ] when* + ] [ + "run" get run + ] if + output-stream get [ stream-flush ] when* 0 exit ] [ print-error 1 exit ] recover diff --git a/basis/command-line/command-line-docs.factor b/basis/command-line/command-line-docs.factor index 697f95b14f..11ee46c227 100644 --- a/basis/command-line/command-line-docs.factor +++ b/basis/command-line/command-line-docs.factor @@ -37,10 +37,6 @@ HELP: main-vocab HELP: default-cli-args { $description "Sets global variables corresponding to default command line arguments." } ; -HELP: ignore-cli-args? -{ $values { "?" "a boolean" } } -{ $description "On Mac OS X, source files to run are supplied by the Cocoa API, so to avoid running them twice the startup code has to call this word." } ; - ARTICLE: "runtime-cli-args" "Command line switches for the VM" "A handful of command line switches are processed by the VM and not the library. They control low-level features." { $table diff --git a/basis/command-line/command-line.factor b/basis/command-line/command-line.factor index 939fb82f00..643afef669 100644 --- a/basis/command-line/command-line.factor +++ b/basis/command-line/command-line.factor @@ -67,7 +67,4 @@ SYMBOL: main-vocab-hook main-vocab "run" set ] bind ; -: ignore-cli-args? ( -- ? ) - os macosx? "run" get "ui" = and ; - [ default-cli-args ] "command-line" add-startup-hook From de3168ad7119906f949fcbcd902b593bafa757cb Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Tue, 26 Jan 2010 01:01:12 +1300 Subject: [PATCH 4/7] Various documentation improvements --- basis/compression/lzw/lzw-docs.factor | 4 +- basis/eval/eval-docs.factor | 60 +++++++++++++++++-- basis/listener/listener-docs.factor | 7 ++- .../stylesheet/stylesheet-docs.factor | 14 ++--- basis/vocabs/refresh/refresh-docs.factor | 8 ++- core/parser/parser-docs.factor | 32 ++++------ core/vocabs/loader/loader-docs.factor | 24 +++++--- core/vocabs/parser/parser-docs.factor | 2 +- extra/combinators/tuple/tuple-docs.factor | 2 +- 9 files changed, 105 insertions(+), 48 deletions(-) diff --git a/basis/compression/lzw/lzw-docs.factor b/basis/compression/lzw/lzw-docs.factor index dccfb25a39..28dc36902b 100644 --- a/basis/compression/lzw/lzw-docs.factor +++ b/basis/compression/lzw/lzw-docs.factor @@ -52,7 +52,7 @@ HELP: reset-lzw-uncompress } { $description "Reset the LZW uncompressor state (either at initialization time or immediately after receiving a Clear Code). " } ; -ARTICLE: "compression.lzw.differences" "LZW Differences between TIFF and GIF" +ARTICLE: "compression.lzw.differences" "LZW differences between TIFF and GIF" { $vocab-link "compression.lzw" } $nl "There are some subtle differences between the LZW algorithm used by TIFF and GIF images." @@ -66,7 +66,7 @@ $nl "TIFF and GIF both add the concept of a 'Clear Code' and a 'End of Information Code' to the LZW algorithm. In both cases, the 'Clear Code' is equal to 2**(code-size - 1) and the 'End of Information Code' is equal to the Clear Code + 1. These 2 codes are reserved in the string table. So in both cases, the LZW string table is initialized to have a length equal to the End of Information Code + 1." ; -ARTICLE: "compression.lzw" "LZW Compression" +ARTICLE: "compression.lzw" "LZW compression" { $vocab-link "compression.lzw" } $nl "Implements both the TIFF and GIF variations of the LZW algorithm." diff --git a/basis/eval/eval-docs.factor b/basis/eval/eval-docs.factor index 250241dcfc..2021a2d10d 100644 --- a/basis/eval/eval-docs.factor +++ b/basis/eval/eval-docs.factor @@ -1,25 +1,73 @@ IN: eval -USING: help.markup help.syntax strings io effects ; +USING: help.markup help.syntax strings io effects parser +listener vocabs.parser debugger combinators ; + +HELP: (eval) +{ $values { "str" string } { "effect" effect } } +{ $description "Parses Factor source code from a string, and calls the resulting quotation, which must have the given stack effect." } +{ $notes "This word must be wrapped within " { $link with-file-vocabs } " or " { $link with-interactive-vocabs } ", since it assumes that the " { $link manifest } " variable is set in the current dynamic scope." } +{ $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ; HELP: eval { $values { "str" string } { "effect" effect } } { $description "Parses Factor source code from a string, and calls the resulting quotation, which must have the given stack effect." } +{ $notes "The code string is parsed and called in a new dynamic scope with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary. The evaluated code can use " { $link "word-search-syntax" } " to alter the search path." } { $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ; HELP: eval( { $syntax "eval( inputs -- outputs )" } { $description "Parses Factor source code from the string at the top of the stack, and calls the resulting quotation, which must have the given stack effect." } +{ $notes + "This parsing word is just a slightly nicer syntax for " { $link eval } ". The following are equivalent:" + { $code + "eval( inputs -- outputs )" + "(( inputs -- outputs )) eval" + } +} { $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ; HELP: eval>string { $values { "str" string } { "output" string } } -{ $description "Evaluates the Factor code in " { $snippet "str" } " with " { $link output-stream } " rebound to a string output stream, then outputs the resulting string. The code in the string must not take or leave any values on the stack." } ; +{ $description "Evaluates the Factor code in " { $snippet "str" } " with " { $link output-stream } " rebound to a string output stream, then outputs the resulting string. The code in the string must not take or leave any values on the stack." } +{ $errors "If the code throws an error, the error is caught, and the result of calling " { $link print-error } " on the error is returned." } ; -ARTICLE: "eval" "Evaluating strings at runtime" -"The " { $vocab-link "eval" } " vocabulary implements support for evaluating strings at runtime." +ARTICLE: "eval-vocabs" "Evaluating strings with a different vocabulary search path" +"Strings passed to " { $link eval } " are always evaluated with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary. This is the same search path that source files start out with. This behavior can be customized by taking advantage of the fact that " { $link eval } " is composed from two simpler words:" +{ $subsections + (eval) + with-file-vocabs +} +"Code in the listener tool starts out with a different initial search path, with more vocabularies are available by default. Strings of code can be evaluated in this search path by using " { $link (eval) } " with a different combinator:" +{ $subsections + with-interactive-vocabs +} +"When using " { $link (eval) } ", the quotation passed to " { $link with-file-vocabs } " and " { $link with-interactive-vocabs } " can also make specific vocabularies available to the evaluated string. This is done by having the quotation change the run-time vocabulary search path prior to calling " { $link (eval) } ". For run-time analogues of the parse-time " { $link "word-search-syntax" } " see " { $link "word-search-parsing" } "." +$nl +"The vocabulary set used by " { $link with-interactive-vocabs } " can be altered by rebinding a dynamic variable:" +{ $subsections interactive-vocabs } +{ $heading "Example" } +"In this example, a string is evaluated with a fictional " { $snippet "cad.objects" } " vocabulary in the search path by default, together with the listener's " { $link interactive-vocabs } "; the quotation is expected to produce a sequence on the stack:" +{ $code + """USING: eval listener vocabs.parser ; +[ + "cad-objects" use-vocab + (( -- seq )) (eval) +] with-interactive-vocabs""" +} +"Note that the search path in the outer code (set by the " { $link POSTPONE: USING: } " form) has no relation to the search path used when parsing the string parameter (this is determined by " { $link with-interactive-vocabs } " and " { $link use-vocab } ")." ; + +ARTICLE: "eval" "Evaluating strings at run time" +"The " { $vocab-link "eval" } " vocabulary implements support for evaluating strings of code dynamically." +$nl +"The main entry point is a parsing word, which wraps a library word:" { $subsections POSTPONE: eval( - eval>string -} ; + eval +} +"This pairing is analogous to that of " { $link POSTPONE: call( } " with " { $link call-effect } "." +$nl +"Advanced features:" +{ $subsections "eval-vocabs" eval>string } +; ABOUT: "eval" diff --git a/basis/listener/listener-docs.factor b/basis/listener/listener-docs.factor index a054067755..77bec12c1a 100644 --- a/basis/listener/listener-docs.factor +++ b/basis/listener/listener-docs.factor @@ -1,4 +1,4 @@ -USING: help.markup help.syntax kernel io system prettyprint continuations ; +USING: help.markup help.syntax kernel io system prettyprint continuations quotations ; IN: listener ARTICLE: "listener-watch" "Watching variables in the listener" @@ -21,6 +21,11 @@ HELP: only-use-vocabs { $values { "vocabs" "a sequence of vocabulary specifiers" } } { $description "Replaces the current manifest's vocabulary search path with the given set of vocabularies." } ; +HELP: with-interactive-vocabs +{ $values { "quot" quotation } } +{ $description "Calls the quotation in a scope with an initial vocabulary search path consisting of all vocabularies from " { $link interactive-vocabs } ", and with the current vocabulary for new definitions set to " { $vocab-link "scratchpad" } "." } +{ $notes "This is the same initial search path as used by the " { $link "listener" } " tool." } ; + HELP: show-var { $values { "var" "a variable name" } } { $description "Adds a variable to the watch list; its value will be printed by the listener after every expression." } ; diff --git a/basis/prettyprint/stylesheet/stylesheet-docs.factor b/basis/prettyprint/stylesheet/stylesheet-docs.factor index 60014514af..12781a568b 100644 --- a/basis/prettyprint/stylesheet/stylesheet-docs.factor +++ b/basis/prettyprint/stylesheet/stylesheet-docs.factor @@ -8,33 +8,31 @@ HELP: effect-style { "effect" "an effect" } { "style" "a style assoc" } } -{ $description "The styling hook for stack effects" } ; +{ $description "The stylesheet for stack effects" } ; HELP: string-style { $values { "str" "a string" } { "style" "a style assoc" } } -{ $description "The styling hook for string literals" } ; +{ $description "The stylesheet for string literals" } ; HELP: vocab-style { $values { "vocab" "a vocabulary specifier" } { "style" "a style assoc" } } -{ $description "The styling hook for vocab names" } ; +{ $description "The stylesheet for vocab names" } ; HELP: word-style { $values { "word" "a word" } { "style" "a style assoc" } } -{ $description "The styling hook for word names" } ; +{ $description "The stylesheet for word names" } ; -ARTICLE: "prettyprint.stylesheet" "Prettyprinter Formatted Output" -{ $vocab-link "prettyprint.stylesheet" } -$nl -"Control the way that the prettyprinter formats output based on object type. These hooks form a basic \"syntax\" highlighting system." +ARTICLE: "prettyprint.stylesheet" "Prettyprinter stylesheet" +"The " { $vocab-link "prettyprint.stylesheet" } " vocabulary defines variables which control the way that the prettyprinter formats output based on object type." { $subsections word-style string-style diff --git a/basis/vocabs/refresh/refresh-docs.factor b/basis/vocabs/refresh/refresh-docs.factor index b074a9e502..ee02a491e1 100644 --- a/basis/vocabs/refresh/refresh-docs.factor +++ b/basis/vocabs/refresh/refresh-docs.factor @@ -15,7 +15,13 @@ HELP: refresh-all { refresh refresh-all } related-words ARTICLE: "vocabs.refresh" "Runtime code reloading" -"Reloading source files changed on disk:" +"The " { $vocab-link "vocabs.refresh" } " vocabulary implements automatic reloading of changed source files." +$nl +"With the help of the " { $vocab-link "io.monitors" } " vocabulary, loaded source files across all vocabulary roots are monitored for changes on disk." +$nl +"If a change to a source file is detected, the next invocation of " { $link refresh-all } " will compare the file's checksum against its previous value, reloading the file if necessary. This takes advantage of the fact that the " { $vocab-link "source-files" } " vocabulary records CRC32 checksums of source files that have been parsed by " { $link "parser" } "." +$nl +"Words for reloading source files:" { $subsections refresh refresh-all diff --git a/core/parser/parser-docs.factor b/core/parser/parser-docs.factor index 97dbab384e..42903a2cec 100644 --- a/core/parser/parser-docs.factor +++ b/core/parser/parser-docs.factor @@ -79,17 +79,6 @@ $nl "word-search-parsing" } ; -ARTICLE: "parser-files" "Parsing source files" -"The parser can run source files:" -{ $subsections - run-file - parse-file -} -"The parser cross-references source files and definitions. This allows it to keep track of removed definitions, and prevent forward references and accidental redefinitions." -$nl -"While the above words are useful for one-off experiments, real programs should be written to use the vocabulary system instead; see " { $link "vocabs.loader" } "." -{ $see-also "source-files" } ; - ARTICLE: "top-level-forms" "Top level forms" "Any code outside of a definition is known as a " { $emphasis "top-level form" } "; top-level forms are run after the entire source file has been parsed, regardless of their position in the file." $nl @@ -98,14 +87,19 @@ $nl "Also, top-level forms run in a new dynamic scope, so using " { $link set } " to store values is almost always wrong, since the values will be lost after the top-level form completes. To save values computed by a top-level form, either use " { $link set-global } " or define a new word with the value." ; ARTICLE: "parser" "The parser" -"This parser is a general facility for reading textual representations of objects and definitions. The parser is implemented in the " { $vocab-link "parser" } " and " { $vocab-link "syntax" } " vocabularies." +"The Factor parser reading textual representations of objects and definitions, with all syntax determined by " { $link "parsing-words" } ". The parser is implemented in the " { $vocab-link "parser" } " vocabulary, with standard syntax in the " { $vocab-link "syntax" } " vocabulary. See " { $link "syntax" } " for a description of standard syntax." $nl -"This section concerns itself with usage and extension of the parser. Standard syntax is described in " { $link "syntax" } "." -{ $subsections "parser-files" } -"The parser can be extended." -{ $subsections "parser-lexer" } -"The parser can be invoked reflectively;" -{ $subsections parse-stream } +"The parser cross-references " { $link "source-files" } " and " { $link "definitions" } ". This functionality is used for improved error checking, as well as tools such as " { $link "tools.crossref" } " and " { $link "editor" } "." +$nl +"The parser can be invoked reflectively, to run strings and source files." +{ $subsections + "eval" + run-file + parse-file +} +"If Factor is run from the command line with a script file supplied as an argument, the script is run using " { $link run-file } ". See " { $link "cli" } "." +$nl +"While " { $link run-file } " can be used interactively in the listener to load user code into the session, this should only be done for quick one-off scripts, and real programs should instead rely on the automatic " { $link "vocabs.loader" } "." { $see-also "parsing-words" "definitions" "definition-checking" } ; ABOUT: "parser" @@ -204,7 +198,7 @@ HELP: bootstrap-syntax HELP: with-file-vocabs { $values { "quot" quotation } } -{ $description "Calls the quotation in a scope with the initial the vocabulary search path for parsing a file. This consists of just the " { $snippet "syntax" } " vocabulary." } ; +{ $description "Calls the quotation in a scope with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary." } ; HELP: parse-fresh { $values { "lines" "a sequence of strings" } { "quot" quotation } } diff --git a/core/vocabs/loader/loader-docs.factor b/core/vocabs/loader/loader-docs.factor index 02a604ac32..f2da4a1383 100644 --- a/core/vocabs/loader/loader-docs.factor +++ b/core/vocabs/loader/loader-docs.factor @@ -28,38 +28,44 @@ ARTICLE: "vocabs.roots" "Vocabulary roots" { $subsections "add-vocab-roots" } ; ARTICLE: "vocabs.loader" "Vocabulary loader" -"The vocabulary loader is defined in the " { $vocab-link "vocabs.loader" } " vocabulary." +"The vocabulary loader combines the vocabulary system with " { $link "parser" } " in order to implement automatic loading of vocabulary source files. The vocabulary loader is implemented in the " { $vocab-link "vocabs.loader" } " vocabulary." $nl -"Vocabularies are searched for in vocabulary roots." +"When an attempt is made to use a vocabulary that has not been loaded into the image, the vocabulary loader is asked to locate the vocabulary's source files, and load them." +$nl +"The vocabulary loader searches for vocabularies in a set of directories known as vocabulary roots." { $subsections "vocabs.roots" } -"Vocabulary names map directly to source files. A vocabulary named " { $snippet "foo.bar" } " must be defined in a " { $snippet "bar" } " directory nested inside a " { $snippet "foo" } " directory of a vocabulary root. Any level of vocabulary nesting is permitted." +"Vocabulary names map directly to source files inside these roots. A vocabulary named " { $snippet "foo.bar" } " is defined in " { $snippet "foo/bar/bar.factor" } "; that is, a source file named " { $snippet "bar.factor" } " within a " { $snippet "bar" } " directory nested inside a " { $snippet "foo" } " directory of a vocabulary root. Any level of nesting, separated by dots, is permitted." $nl "The vocabulary directory - " { $snippet "bar" } " in our example - contains a source file:" { $list - { { $snippet "foo/bar/bar.factor" } " - the source file, must define words in the " { $snippet "foo.bar" } " vocabulary with an " { $snippet "IN: foo.bar" } " form" } + { { $snippet "foo/bar/bar.factor" } " - the source file must define words in the " { $snippet "foo.bar" } " vocabulary with an " { $snippet "IN: foo.bar" } " form" } } -"Two other Factor source files, storing documentation and tests, respectively, are optional:" +"Two other Factor source files, storing documentation and tests, respectively, may optionally be placed alongside the source file:" { $list { { $snippet "foo/bar/bar-docs.factor" } " - documentation, see " { $link "writing-help" } } { { $snippet "foo/bar/bar-tests.factor" } " - unit tests, see " { $link "tools.test" } } } -"Finally, three text files can contain meta-data:" +"Finally, optional three text files may contain meta-data:" { $list { { $snippet "foo/bar/authors.txt" } " - a series of lines, with one author name per line. These are listed under " { $link "vocab-authors" } } { { $snippet "foo/bar/summary.txt" } " - a one-line description" } { { $snippet "foo/bar/tags.txt" } " - a whitespace-separated list of tags which classify the vocabulary. Consult " { $link "vocab-tags" } " for a list of existing tags you can re-use" } } -"While " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " load vocabularies which have not been loaded before adding them to the search path, it is also possible to load a vocabulary without adding it to the search path:" +"The " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " words load vocabularies which have not been loaded yet, as needed." +$nl +"Vocabularies can also be loaded at run time, without altering the vocabulary search path. This is done by calling a word which loads a vocabulary if it is not in the image, doing nothing if it is:" { $subsections require } -"Forcing a reload of a vocabulary, even if it has already been loaded:" +"The above word will only ever load a vocabulary once in a given session. There is another word which unconditionally loads vocabulary from disk, regardless of whether or not is has already been loaded:" { $subsections reload } +"For interactive development in the listener, calling " { $link reload } " directly is usually not necessary, since a better facility exists for " { $link "vocabs.refresh" } "." +$nl "Application vocabularies can define a main entry point, giving the user a convenient way to run the application:" { $subsections POSTPONE: MAIN: run runnable-vocab } -{ $see-also "vocabularies" "parser-files" "source-files" } ; +{ $see-also "vocabularies" "parser" "source-files" } ; ABOUT: "vocabs.loader" diff --git a/core/vocabs/parser/parser-docs.factor b/core/vocabs/parser/parser-docs.factor index 6a7bd4d212..66900978a8 100644 --- a/core/vocabs/parser/parser-docs.factor +++ b/core/vocabs/parser/parser-docs.factor @@ -65,7 +65,7 @@ $nl } { $see-also "words" } ; -ARTICLE: "word-search-parsing" "Word lookup in parsing words" +ARTICLE: "word-search-parsing" "Reflection support for vocabulary search path" "The parsing words described in " { $link "word-search-syntax" } " are implemented using the below words, which you can also call from your own parsing words." $nl "The current state used for word search is stored in a " { $emphasis "manifest" } ":" diff --git a/extra/combinators/tuple/tuple-docs.factor b/extra/combinators/tuple/tuple-docs.factor index d0eda50cd4..600986e906 100644 --- a/extra/combinators/tuple/tuple-docs.factor +++ b/extra/combinators/tuple/tuple-docs.factor @@ -33,7 +33,7 @@ HELP: nmake-tuple { make-tuple 2make-tuple 3make-tuple nmake-tuple } related-words ARTICLE: "combinators.tuple" "Tuple-constructing combinators" -"The " { $vocab-link "combinators.tuple" } " vocabulary provides dataflow combinators that construct " { $link tuple } " objects." +"The " { $vocab-link "combinators.tuple" } " vocabulary provides combinators that construct " { $link tuple } " objects. These provide additional functionality above and beyond built-in " { $link "tuple-constructors" } "." { $subsections make-tuple 2make-tuple From cb9261d975de97c2b5bbe57d02951d80a1bc2d42 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Tue, 26 Jan 2010 01:01:22 +1300 Subject: [PATCH 5/7] grouping: add a unit test --- basis/grouping/grouping-tests.factor | 2 ++ 1 file changed, 2 insertions(+) diff --git a/basis/grouping/grouping-tests.factor b/basis/grouping/grouping-tests.factor index 52b436507e..60500558a7 100644 --- a/basis/grouping/grouping-tests.factor +++ b/basis/grouping/grouping-tests.factor @@ -30,3 +30,5 @@ IN: grouping.tests [ f ] [ [ 1.0 1 1 ] all-equal? ] unit-test [ t ] [ { 1 2 3 4 } [ < ] monotonic? ] unit-test [ f ] [ { 1 2 3 4 } [ > ] monotonic? ] unit-test + +[ { 6 7 8 3 4 5 0 1 2 } ] [ 9 iota >array dup 3 reverse! drop ] unit-test From 13e2de5cae5c921a43f733508f6c116319587eb6 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Tue, 26 Jan 2010 01:01:27 +1300 Subject: [PATCH 6/7] help.lint: flush --- basis/help/lint/lint.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/help/lint/lint.factor b/basis/help/lint/lint.factor index e0cea42b4f..47b8820f18 100644 --- a/basis/help/lint/lint.factor +++ b/basis/help/lint/lint.factor @@ -69,7 +69,7 @@ PRIVATE> '[ _ vocab-help [ article drop ] when* ] check-something ; : check-vocab ( vocab -- ) - "Checking " write dup write "..." print + "Checking " write dup write "..." print flush [ check-about ] [ words [ check-word ] each ] [ vocab-articles get at [ check-article ] each ] From 6306d58f77c7ab65638f5b25216040d4aa4bad87 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Tue, 26 Jan 2010 01:18:10 +1300 Subject: [PATCH 7/7] help.crossref, tools.crossref: improved help cross-referencing --- basis/help/crossref/crossref.factor | 4 ++-- basis/tools/crossref/crossref.factor | 36 ++++++++++++++++++---------- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/basis/help/crossref/crossref.factor b/basis/help/crossref/crossref.factor index 5e4922c7ad..36d780c99b 100644 --- a/basis/help/crossref/crossref.factor +++ b/basis/help/crossref/crossref.factor @@ -7,10 +7,10 @@ IN: help.crossref : article-links ( topic elements -- seq ) [ article-content ] dip - collect-elements [ >link ] map ; + collect-elements ; : article-children ( topic -- seq ) - { $subsection $subsections } article-links ; + { $subsection $subsections } article-links [ >link ] map ; : help-path ( topic -- seq ) [ article-parent ] follow rest ; diff --git a/basis/tools/crossref/crossref.factor b/basis/tools/crossref/crossref.factor index 134395f1a8..daa30100a4 100644 --- a/basis/tools/crossref/crossref.factor +++ b/basis/tools/crossref/crossref.factor @@ -1,9 +1,10 @@ -! Copyright (C) 2005, 2009 Slava Pestov. +! Copyright (C) 2005, 2010 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: words assocs definitions io io.pathnames io.styles kernel -prettyprint sorting see sets sequences arrays hashtables help.crossref -help.topics help.markup quotations accessors source-files namespaces -graphs vocabs generic generic.single threads compiler.units init ; +prettyprint sorting see sets sequences arrays hashtables help +help.crossref help.topics help.markup quotations accessors +source-files namespaces graphs vocabs generic generic.single +threads compiler.units init combinators.smart ; IN: tools.crossref SYMBOL: crossref @@ -50,10 +51,16 @@ M: callable uses ( quot -- assoc ) M: word uses def>> uses ; -M: link uses { $subsection $subsections $link $see-also } article-links ; +M: link uses + [ { $subsection $subsections $link $see-also } article-links [ >link ] map ] + [ { $vocab-link } article-links [ >vocab-link ] map ] + bi append ; M: pathname uses string>> source-file top-level-form>> [ uses ] [ { } ] if* ; +! To make UI browser happy +M: vocab uses drop f ; + GENERIC: crossref-def ( defspec -- ) M: object crossref-def @@ -62,18 +69,23 @@ M: object crossref-def M: word crossref-def [ call-next-method ] [ subwords [ crossref-def ] each ] bi ; +: defs-to-crossref ( -- seq ) + [ + all-words + all-articles [ >link ] map + source-files get keys [ ] map + ] append-outputs ; + : build-crossref ( -- crossref ) "Computing usage index... " write flush yield - H{ } clone crossref [ - all-words - source-files get keys [ ] map - [ [ crossref-def ] each ] bi@ - crossref get - ] with-variable + H{ } clone [ + crossref set-global + defs-to-crossref [ crossref-def ] each + ] keep "done" print flush ; : get-crossref ( -- crossref ) - crossref global [ drop build-crossref ] cache ; + crossref get-global [ build-crossref ] unless* ; GENERIC: irrelevant? ( defspec -- ? )