From 9b28623b4fdd932972f7e80301ca01ee1139601a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Sat, 29 Mar 2014 11:10:01 +0100
Subject: [PATCH] Docs: examples for io.launcher words

---
 basis/io/launcher/launcher-docs.factor | 60 ++++++++++++++++++++++++--
 basis/io/timeouts/timeouts-docs.factor | 10 ++++-
 2 files changed, 65 insertions(+), 5 deletions(-)

diff --git a/basis/io/launcher/launcher-docs.factor b/basis/io/launcher/launcher-docs.factor
index 60d923be9f..08d3f6b99d 100644
--- a/basis/io/launcher/launcher-docs.factor
+++ b/basis/io/launcher/launcher-docs.factor
@@ -98,7 +98,14 @@ HELP: get-environment
 
 HELP: current-process-handle
 { $values { "handle" "a process handle" } }
-{ $description "Returns the handle of the current process." } ;
+{ $description "Returns the handle of the current process." }
+{ $examples
+  { $example
+    "USING: io.launcher ;"
+    "current-process-handle ."
+    "6881"
+  }
+} ;
 
 HELP: run-process*
 { $values { "process" process } { "handle" "a process handle" } }
@@ -108,6 +115,20 @@ HELP: run-process*
 HELP: run-process
 { $values { "desc" "a launch descriptor" } { "process" process } }
 { $description "Launches a process. The object can either be a string, a sequence of strings or a " { $link process } ". See " { $link "io.launcher.descriptors" } " for details." }
+{ $examples
+  { $example
+    "USING: io.launcher ;"
+    "\"pwd\" run-process ."
+    "/tmp"
+    "T{ process"
+    "    { command \"pwd\" }"
+    "    { environment H{ } }"
+    "    { environment-mode +append-environment+ }"
+    "    { group +same-group+ }"
+    "    { status 0 }"
+    "}"
+  }
+}
 { $notes "The output value can be passed to " { $link wait-for-process } " to get an exit code." } ;
 
 HELP: run-detached
@@ -126,13 +147,37 @@ HELP: process-failed
 
 HELP: try-process
 { $values { "desc" "a launch descriptor" } }
-{ $description "Launches a process and waits for it to complete. If it exits with a non-zero status code, throws a " { $link process-failed } " error." } ;
+{ $description "Launches a process and waits for it to complete. If it exits with a non-zero status code, throws a " { $link process-failed } " error." }
+{ $examples
+  { $example
+    "USING: continuations io.launcher ;"
+    "[ \"ls --invalid-flag\" try-process ] [ ] recover ."
+    "ls: unknown flag \"--invalid-flag\""
+    "Try with ”ls --help” for more information."
+    "T{ process-failed"
+    "    { process"
+    "         T{ process"
+    "         { command \"ls --invalid-flag\" }"
+    "         { environment H{ } }"
+    "         { environment-mode +append-environment+ }"
+    "         { group +same-group+ }"
+    "         { status 2 }"
+    "    }"
+    "}"
+  }
+} ;
 
 { run-process try-process run-detached } related-words
 
 HELP: kill-process
 { $values { "process" process } }
-{ $description "Kills a running process. Does nothing if the process has already exited." } ;
+{ $description "Kills a running process. Does nothing if the process has already exited." }
+{ $examples
+  { $example
+    "USING: io.launcher ;"
+    "\"cat\" run-detached kill-process"
+  }
+} ;
 
 HELP: kill-process*
 { $values { "process" "process" } }
@@ -182,7 +227,14 @@ HELP: with-process-reader
   { "encoding" "an encoding descriptor" }
   { "quot" quotation }
 }
-{ $description "Launches a process and redirects its output via a pipe. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to this pipe." } ;
+{ $description "Launches a process and redirects its output via a pipe. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to this pipe." }
+{ $examples
+  { $example
+    "USING: io.launcher ;"
+    "\"ls -dl /etc\" utf8 [ contents ] with-process-reader ."
+    "\"drwxr-xr-x 213 root root 12288 mar 11 18:52 /etc\\n\""
+  }
+} ;
 
 HELP: with-process-writer
 { $values
diff --git a/basis/io/timeouts/timeouts-docs.factor b/basis/io/timeouts/timeouts-docs.factor
index 3ae3b62c5d..cf7ba5167c 100644
--- a/basis/io/timeouts/timeouts-docs.factor
+++ b/basis/io/timeouts/timeouts-docs.factor
@@ -7,7 +7,15 @@ HELP: timeout
 
 HELP: set-timeout
 { $values { "dt/f" { $maybe duration } } { "obj" object } }
-{ $contract "Sets an object's timeout." } ;
+{ $contract "Sets an object's timeout." }
+{ $examples "Waits five seconds for a process that sleeps for ten seconds:"
+  { $example
+    "USING: calendar io.launcher io.timeouts ;"
+    "\"sleep 10\" >process 5 seconds over set-timeout run-process"
+    "Process was killed as a result of a call to"
+    "kill-process, or a timeout"
+  }
+} ;
 
 HELP: cancel-operation
 { $values { "obj" object } }