Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Updated the popen docs.

  • Loading branch information...
commit 544924a4696f034dcd78ddd6613bb15df5d95fb8 1 parent 6b4f716
Kris Kowal kriskowal authored

Showing 1 changed file with 57 additions and 47 deletions. Show diff stats Hide diff stats

  1. +57 47 docs/lib/os/popen.md
104 docs/lib/os/popen.md
Source Rendered
... ... @@ -1,70 +1,80 @@
1 1
2   -; popen(process):Popen
3   -: process may be a String or Array of args. If it is a String, popen uses "/bin/sh", "-e" to execute your program.
  2 + popen(process):Popen
  3 +
  4 +process may be a String or Array of args. If it is a String, popen uses "/bin/sh", "-e" to execute your program.
4 5
5 6 Popen
6 7 -----
7 8
8   -; stdin
9   -: a text writer IO object attached to the stdin of subprocess.
10   -; stdout
11   -: a text reader IO object attached to the stdout of the supbrocess.
12   -; stderr
13   -: a text reader IO object attached to the stderr of the subprocess.
14   -
15   -; wait() -> code:Number
16   -: blocks execution until the subprocess has exited.
  9 +Returns an object with the following properties:
17 10
18   -; communicate([stdin[, stdout[, stderr]]]):Communicate
19   -: communicates with the process on stdin, stdout, and stderr concurrently with the attached streams. the given stdin may be a stream, string, or stringio stream. stdout and stderr may be streams or stringio objects, and default to stringio. communicate returns the pipes used to communicate with stdin, stdout, and stderr, by default providing stdout and stderr as stringio objects that have accumulated the entire output and errput of the subprocess.
  11 +* `stdin IO` - a text writer IO object attached to the stdin of subprocess.
  12 +* `stdout IO` - a text reader IO object attached to the stdout of the
  13 + supbrocess.
  14 +* `stderr IO` - a text reader IO object attached to the stderr of the
  15 + subprocess.
  16 +* `wait() Number` - blocks on the subprocess until it exits and returns the
  17 + exit status code.
  18 +* `communicate(stdin_opt, stdout_opt, stderr_opt) Communicate` - communicates
  19 + with the process on `stdin`, `stdout`, and `stderr` concurrently with the
  20 + attached streams. The given `stdin` may be an IO stream, String, or StringIO
  21 + stream. `stdout` and `stderr` may be streams or `StringIO` objects, and
  22 + default to `StringIO`. `communicate` returns the streams used to communicate
  23 + with `stdin`, `stdout`, and `stderr`, by default providing `stdout` and
  24 + `stderr` as `StringIO` objects that have accumulated the entire output and
  25 + errput of the subprocess.
20 26
21 27 Communicate
22 28 -----------
23 29
24   -; stdin
25   -: the text reader object used to communicate with the subprocess. if no stdin was provided as an argument to communicate, stdin will be an empty stringio. if a string was provided, stdin will be a stringio with whatever input was not consumed by the subprocess. if any other stream was provided, stdin will be that stream.
26   -; stdout
27   -: the text writer object that the subprocess wrote to on stdout. if no stdout was provided as an argument to communicate, stdout will be a stringio containing all of the accumulated output of the subprocess.
28   -; stderr
29   -: the text writer object that the subprocess wrote to on stderr. if no stderr was provided as an argument to communicate, stderr will be a stringio containing all of the accumulated errput of the subprocess.
30   -; code
31   -: the exit code of the subprocess
  30 +* `stdin` - the text reader object used to communicate with the subprocess. If
  31 + no `stdin` was provided as an argument to `communicate`, `stdin` will be an
  32 + empty `StringIO`. If a String was provided, `stdin` will be a `StringIO`
  33 + with whatever input was not consumed by the subprocess. If any other stream
  34 + was provided, `stdin` will be that stream.
  35 +* `stdout` - the text writer object that the subprocess wrote to on `stdout`.
  36 + If no `stdout` was provided as an argument to `communicate`, `stdout` will be
  37 + a `StringIO` containing all of the accumulated output of the subprocess.
  38 +* `stderr` - the text writer object that the subprocess wrote to on stderr. If
  39 + no `stderr` was provided as an argument to `communicate`, `stderr` will be a
  40 + `StringIO` containing all of the accumulated errput of the subprocess.
  41 +* `status` - the exit status code of the subprocess
32 42
33 43 Examples
34 44 --------
35 45
36 46 This is the implementation of "system" in the "os" module:
37 47
38   - exports.system = function (command, options) {
39   - var process = exports.popen(command, options);
40   - return process.communicate(
41   - '',
42   - system.stdout,
43   - system.stderr
44   - ).code;
45   - };
  48 + OS.system = function (command, options) {
  49 + var process = OS.popen(command, options);
  50 + return process.communicate(
  51 + system.stdin,
  52 + system.stdout,
  53 + system.stderr
  54 + ).status;
  55 + };
46 56
47 57 This is the implementation of the "command" function in the "os" module. "command" executes a subprocess and returns all of the output of the subprocess as a String. If the exit status code of the subprocess is non-zero, it throws an error containing all of the accumulated errput of the subprocess.
48 58
49   - exports.command = function (command) {
50   - var process = exports.popen(command);
51   - var result = process.communicate();
52   - if (result.code !== 0)
53   - throw new Error(result.stderr.read());
54   - return result.stdout.read();
55   - };
  59 + OS.command = function (command) {
  60 + var process = OS.popen(command);
  61 + var result = process.communicate();
  62 + if (result.status !== 0)
  63 + throw new Error(result.stderr.read());
  64 + return result.stdout.read();
  65 + };
56 66
57 67 This function uses the "sort" command to sort a list of numbers.
58 68
59   - var io = require("io");
60   - var os = require("os");
61   -
62   - var list = io.StringIO();
63   - list.print("30");
64   - list.print("4");
65   - list.print("1000");
66   - list.print("200");
67   -
68   - var process = os.popen(["sort", "-n", "-"]);
69   - process.communicate(list).stdout.forEach(print);
  69 + var IO = require("io");
  70 + var OS = require("os");
  71 +
  72 + var list = IO.StringIO();
  73 + list.print("30");
  74 + list.print("4");
  75 + list.print("1000");
  76 + list.print("200");
  77 +
  78 + var process = OS.popen(["sort", "-n", "-"]);
  79 + process.communicate(list).stdout.forEach(print);
70 80

0 comments on commit 544924a

Please sign in to comment.
Something went wrong with that request. Please try again.