<appender>, documentation updates

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" } ;
 

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 <process-stream> } " pipe" }
-    { { $link +inherit+ } " - the stream is inherited from the current process, overriding a " { $link <process-stream> } " 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 <file-appender> } }
     { "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 <appender> } "." } ;
+
+HELP: <appender>
+{ $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

extra/io/launcher/launcher.factor

@@ -27,9 +27,12 @@ handle status
 killed ;
 
 SYMBOL: +closed+
-SYMBOL: +inherit+
 SYMBOL: +stdout+
 
+TUPLE: appender path ;
+
+: <appender> ( path -- appender ) appender boa ;
+
 SYMBOL: +prepend-environment+
 SYMBOL: +replace-environment+
 SYMBOL: +append-environment+

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 <pipe> } " and " { $link run-pipeline } " words can be used in most cases instead." } ;
+
+HELP: <pipe>
+{ $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 <pipe> }
+"Pipelines of coroutines and processes:"
+{ $subsection run-pipeline } ;
+
+ABOUT: "io.pipes"

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 <decoder> ] change readln ] } with-pipeline
@@ -22,5 +22,5 @@ IN: io.pipes.tests
     {
         [ output-stream [ utf8 <encoder> ] change "Hello" print flush f ]
         [ input-stream [ utf8 <decoder> ] change readln ]
-    } with-pipeline
+    } run-pipeline
 ] unit-test

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 ;

extra/io/unix/launcher/launcher-tests.factor

@@ -34,15 +34,6 @@ accessors kernel sequences io.encodings.utf8 ;
     ascii <process-reader> contents
 ] unit-test
 
-[ f ] [
-    <process>
-        "cat"
-        "launcher-test-1" temp-file
-        2array >>command
-        +inherit+ >>stdout
-    ascii <process-reader> 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 [
+        <process>
+            "echo hi" >>command
+            "append-test" temp-file <appender> >>stdout
+        try-process
+    ] times
+    "append-test" temp-file utf8 file-contents
+] unit-test

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 ;

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

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 ]