From 8e60cf2b869a7c358e9922b531783519803e4ec5 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Mon, 5 May 2008 19:12:22 -0500 Subject: [PATCH] , documentation updates --- extra/help/handbook/handbook.factor | 12 ++--- extra/io/launcher/launcher-docs.factor | 16 ++++--- extra/io/launcher/launcher.factor | 5 ++- extra/io/pipes/pipes-docs.factor | 47 ++++++++++++++++++++ extra/io/pipes/pipes-tests.factor | 6 +-- extra/io/pipes/pipes.factor | 2 +- extra/io/unix/launcher/launcher-tests.factor | 21 +++++---- extra/io/unix/launcher/launcher.factor | 5 ++- extra/io/unix/pipes/pipes-tests.factor | 8 ++-- extra/io/windows/nt/launcher/launcher.factor | 1 - 10 files changed, 92 insertions(+), 31 deletions(-) create mode 100644 extra/io/pipes/pipes-docs.factor diff --git a/extra/help/handbook/handbook.factor b/extra/help/handbook/handbook.factor index d9eeb6c96b..a8271a0e3b 100755 --- a/extra/help/handbook/handbook.factor +++ b/extra/help/handbook/handbook.factor @@ -193,17 +193,19 @@ ARTICLE: "io" "Input and output" "Utilities:" { $subsection "stream-binary" } { $subsection "styles" } -{ $heading "Files" } -{ $subsection "io.files" } -{ $subsection "io.mmap" } -{ $subsection "io.monitors" } { $heading "Encodings" } { $subsection "encodings-introduction" } { $subsection "io.encodings" } { $subsection "io.encodings.string" } -{ $heading "Other features" } +{ $heading "Files" } +{ $subsection "io.files" } +{ $subsection "io.mmap" } +{ $subsection "io.monitors" } +{ $heading "Communications" } { $subsection "network-streams" } { $subsection "io.launcher" } +{ $subsection "io.pipes" } +{ $heading "Other features" } { $subsection "io.timeouts" } { $subsection "checksums" } ; diff --git a/extra/io/launcher/launcher-docs.factor b/extra/io/launcher/launcher-docs.factor index c50e1aa42b..45bbec20e3 100755 --- a/extra/io/launcher/launcher-docs.factor +++ b/extra/io/launcher/launcher-docs.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2007, 2008 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. -USING: help.markup help.syntax quotations kernel io math -calendar ; +USING: help.markup help.syntax quotations kernel io io.files +math calendar ; IN: io.launcher ARTICLE: "io.launcher.command" "Specifying a command" @@ -26,10 +26,10 @@ $nl "To specify redirection, set the " { $snippet "stdin" } ", " { $snippet "stdout" } " and " { $snippet "stderr" } " slots of a " { $link process } " to one of the following values:" { $list { { $link f } " - default value; the stream is either inherited from the current process, or is a " { $link } " pipe" } - { { $link +inherit+ } " - the stream is inherited from the current process, overriding a " { $link } " pipe" } { { $link +closed+ } " - the stream is closed; reads will return end of file and writes will fails" } { { $link +stdout+ } " - a special value for the " { $snippet "stderr" } " slot only, indicating that the standard output and standard error streams should be merged" } { "a path name - the stream is sent to the given file, which must exist for input and is created automatically on output" } + { "an " { $link appender } " wrapping a path name - output is sent to the end given file, as with " { $link } } { "a file stream or a socket - the stream is connected to the given Factor stream, which cannot be used again from within Factor and must be closed after the process has been started" } } ; @@ -47,12 +47,16 @@ ARTICLE: "io.launcher.priority" "Setting process priority" HELP: +closed+ { $description "Possible value for the " { $snippet "stdin" } ", " { $snippet "stdout" } ", and " { $snippet "stderr" } " slots of a " { $link process } "." } ; -HELP: +inherit+ -{ $description "Possible value for the " { $snippet "stdin" } ", " { $snippet "stdout" } ", and " { $snippet "stderr" } " slots of a " { $link process } "." } ; - HELP: +stdout+ { $description "Possible value for the " { $snippet "stderr" } " slot of a " { $link process } "." } ; +HELP: appender +{ $class-description "An object representing a file to append to. Instances are created with " { $link } "." } ; + +HELP: +{ $values { "path" "a pathname string" } { "appender" appender } } +{ $description "Creates an object which may be stored in the " { $snippet "stdout" } " or " { $snippet "stderr" } " slot of a " { $link process } " instance." } ; + HELP: +prepend-environment+ { $description "Possible value of " { $snippet "environment-mode" } " slot of a " { $link process } "." $nl diff --git a/extra/io/launcher/launcher.factor b/extra/io/launcher/launcher.factor index f3590469b9..286febd589 100755 --- a/extra/io/launcher/launcher.factor +++ b/extra/io/launcher/launcher.factor @@ -27,9 +27,12 @@ handle status killed ; SYMBOL: +closed+ -SYMBOL: +inherit+ SYMBOL: +stdout+ +TUPLE: appender path ; + +: ( path -- appender ) appender boa ; + SYMBOL: +prepend-environment+ SYMBOL: +replace-environment+ SYMBOL: +append-environment+ diff --git a/extra/io/pipes/pipes-docs.factor b/extra/io/pipes/pipes-docs.factor new file mode 100644 index 0000000000..d51ae94bc7 --- /dev/null +++ b/extra/io/pipes/pipes-docs.factor @@ -0,0 +1,47 @@ +USING: help.markup help.syntax continuations io ; +IN: io.pipes + +HELP: pipe +{ $class-description "A low-level pipe. Instances are created by calling " { $link (pipe) } " and closed by calling " { $link dispose } "." } ; + +HELP: (pipe) +{ $values { "pipe" pipe } } +{ $description "Opens a new pipe. This is a low-level word; the " { $link } " and " { $link run-pipeline } " words can be used in most cases instead." } ; + +HELP: +{ $values { "encoding" "an encoding specifier" } { "stream" "a bidirectional stream" } } +{ $description "Opens a new pipe and wraps it in a stream. Data written from the stream can be read back from the same stream instance." } +{ $notes "Pipe streams must be disposed by calling " { $link dispose } " or " { $link with-disposal } " to avoid resource leaks." } ; + +HELP: run-pipeline +{ $values { "seq" "a sequence of pipeline components" } { "results" "a sequence of pipeline results" } } +{ $description + "Creates a pipe between each pipeline component, with the output of each component becoming the input of the next." + $nl + "The first component reads input from " { $link input-stream } " and the last component writes output to " { $link output-stream } "." + $nl + "Each component runs in its own thread, and the word returns when all components finish executing. Each component outputs a result value." + $nl + "Pipeline components must be one of the following:" + { $list + { "A quotation. The quotation is called with both " { $link input-stream } " and " { $link output-stream } " rebound, except for the first and last pipeline components, and it must output a single value." } + { "A process launch descriptor. See " { $link "io.launcher.descriptors" } "." } + } +} +{ $examples + "Print the lines of a log file which contain the string ``error'', sort them and filter out duplicates, using Unix shell commands only:" + { $code "{ \"cat log.txt\" \"grep error\" \"sort\" \"uniq\" } run-pipeline" } +} ; + +ARTICLE: "io.pipes" "Pipes" +"A " { $emphasis "pipe" } " is a unidirectional channel for transfer of bytes. Data written to one end of the pipe can be read from the other. Pipes can be used to pass data between processes; they can also be used within a single process to implement communication between coroutines." +$nl +"Low-level pipes:" +{ $subsection pipe } +{ $subsection (pipe) } +"High-level pipe streams:" +{ $subsection } +"Pipelines of coroutines and processes:" +{ $subsection run-pipeline } ; + +ABOUT: "io.pipes" diff --git a/extra/io/pipes/pipes-tests.factor b/extra/io/pipes/pipes-tests.factor index 812128f792..0b93e4dff2 100644 --- a/extra/io/pipes/pipes-tests.factor +++ b/extra/io/pipes/pipes-tests.factor @@ -10,8 +10,8 @@ IN: io.pipes.tests ] with-stream ] unit-test -[ { } ] [ { } with-pipeline ] unit-test -[ { f } ] [ { [ f ] } with-pipeline ] unit-test +[ { } ] [ { } run-pipeline ] unit-test +[ { f } ] [ { [ f ] } run-pipeline ] unit-test [ { "Hello" } ] [ "Hello" [ { [ input-stream [ utf8 ] change readln ] } with-pipeline @@ -22,5 +22,5 @@ IN: io.pipes.tests { [ output-stream [ utf8 ] change "Hello" print flush f ] [ input-stream [ utf8 ] change readln ] - } with-pipeline + } run-pipeline ] unit-test diff --git a/extra/io/pipes/pipes.factor b/extra/io/pipes/pipes.factor index 8317f9af36..3e91c5e48e 100644 --- a/extra/io/pipes/pipes.factor +++ b/extra/io/pipes/pipes.factor @@ -50,7 +50,7 @@ GENERIC: wait-for-pipeline-element ( obj -- result ) M: object wait-for-pipeline-element ; -: with-pipeline ( seq -- results ) +: run-pipeline ( seq -- results ) [ pipeline-element-quot ] map with-pipe-fds [ wait-for-pipeline-element ] map ; diff --git a/extra/io/unix/launcher/launcher-tests.factor b/extra/io/unix/launcher/launcher-tests.factor index 8a25bc9fa9..97ffc5287f 100755 --- a/extra/io/unix/launcher/launcher-tests.factor +++ b/extra/io/unix/launcher/launcher-tests.factor @@ -34,15 +34,6 @@ accessors kernel sequences io.encodings.utf8 ; ascii contents ] unit-test -[ f ] [ - - "cat" - "launcher-test-1" temp-file - 2array >>command - +inherit+ >>stdout - ascii contents -] unit-test - [ ] [ [ "launcher-test-1" temp-file delete-file ] ignore-errors ] unit-test @@ -107,3 +98,15 @@ accessors kernel sequences io.encodings.utf8 ; temp-directory "aloha" append-path utf8 file-contents ] unit-test + +[ ] [ "append-test" temp-file delete-file ] unit-test + +[ "hi\nhi\n" ] [ + 2 [ + + "echo hi" >>command + "append-test" temp-file >>stdout + try-process + ] times + "append-test" temp-file utf8 file-contents +] unit-test diff --git a/extra/io/unix/launcher/launcher.factor b/extra/io/unix/launcher/launcher.factor index ce66a1dd0c..043b2bd73e 100755 --- a/extra/io/unix/launcher/launcher.factor +++ b/extra/io/unix/launcher/launcher.factor @@ -46,6 +46,9 @@ USE: unix >r >r normalize-path r> file-mode open dup io-error r> redirect-fd ; +: redirect-file-append ( obj mode fd -- ) + >r drop path>> normalize-path open-append r> redirect-fd ; + : redirect-closed ( obj mode fd -- ) >r >r drop "/dev/null" r> r> redirect-file ; @@ -53,8 +56,8 @@ USE: unix { { [ pick not ] [ redirect-inherit ] } { [ pick string? ] [ redirect-file ] } + { [ pick appender? ] [ redirect-file-append ] } { [ pick +closed+ eq? ] [ redirect-closed ] } - { [ pick +inherit+ eq? ] [ redirect-closed ] } { [ pick integer? ] [ >r drop dup reset-fd r> redirect-fd ] } [ >r >r underlying-handle r> r> redirect ] } cond ; diff --git a/extra/io/unix/pipes/pipes-tests.factor b/extra/io/unix/pipes/pipes-tests.factor index 997c54775b..8ff9ba61c8 100644 --- a/extra/io/unix/pipes/pipes-tests.factor +++ b/extra/io/unix/pipes/pipes-tests.factor @@ -1,8 +1,8 @@ -USING: tools.test io.pipes io.unix.pipes io.encodings.utf8 io -namespaces sequences ; +USING: tools.test io.pipes io.unix.pipes io.encodings.utf8 +io.encodings io namespaces sequences ; IN: io.unix.pipes.tests -[ { 0 0 } ] [ { "ls" "grep x" } with-pipeline ] unit-test +[ { 0 0 } ] [ { "ls" "grep x" } run-pipeline ] unit-test [ { 0 f 0 } ] [ { @@ -12,5 +12,5 @@ IN: io.unix.pipes.tests input-stream get lines reverse [ print ] each f ] "grep x" - } with-pipeline + } run-pipeline ] unit-test diff --git a/extra/io/windows/nt/launcher/launcher.factor b/extra/io/windows/nt/launcher/launcher.factor index ee9c93b243..d74bf8ab95 100755 --- a/extra/io/windows/nt/launcher/launcher.factor +++ b/extra/io/windows/nt/launcher/launcher.factor @@ -52,7 +52,6 @@ IN: io.windows.nt.launcher : redirect ( default obj access-mode create-mode -- handle ) { { [ pick not ] [ redirect-default ] } - { [ pick +inherit+ eq? ] [ redirect-inherit ] } { [ pick +closed+ eq? ] [ redirect-closed ] } { [ pick string? ] [ redirect-file ] } [ redirect-stream ]