OLD | NEW |
---|---|
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * [Process] objects are used to start new processes and interact with | 6 * [Process] is used to start new processes. |
7 * them. | |
8 */ | 7 */ |
9 interface Process default _Process { | 8 class Process { |
10 /** | 9 /** |
11 * Creates a new process object and starts a process running the | 10 * Starts a process running the [executable] with the specified |
12 * [executable] with the specified [arguments]. When the process has | 11 * [arguments]. Returns an [InteractiveProcess] object that can be |
13 * been successfully started [onStart] is called. If the process | 12 * used to interact with the process. |
14 * fails to start [onError] is called. | 13 * |
14 * An optional [ProcessOptions] object can be passed to specify | |
15 * options other than the executable and the arguments. | |
16 */ | |
17 static InteractiveProcess start(String executable, | |
18 List<String> arguments, | |
19 [ProcessOptions options]) { | |
20 return _Process.start(executable, arguments, options); | |
21 } | |
22 | |
23 /** | |
24 * Starts a process and runs it non-interactively to completion. The | |
25 * process run is [executable] with the specified [arguments]. | |
15 * | 26 * |
16 * An optional [ProcessOptions] object can be passed to specify | 27 * An optional [ProcessOptions] object can be passed to specify |
17 * options other than the executable and the arguments. | 28 * options other than the executable and the arguments. |
18 * | 29 * |
19 * No data can be written to the process stdin and the process | 30 * Returns a [:Future<ProcessResult>:] that completes with the |
20 * cannot be closed nor killed before [onStart] has been invoked. | 31 * result of running the process, i.e., exit code, standard out and |
32 * standard in. | |
21 */ | 33 */ |
22 Process.start(String executable, | 34 static Future<ProcessResult> run(String executable, |
23 List<String> arguments, | 35 List<String> arguments, |
24 [ProcessOptions options]); | 36 [ProcessOptions options]) { |
37 return _Process.run(executable, arguments, options); | |
38 } | |
39 } | |
25 | 40 |
26 /** | 41 /** |
27 * Creates a new process object, starts a process and runs it | 42 * [InteractiveProcess] represents a process which users can |
28 * non-interactively to completion. The process run is [executable] | 43 * communicate with using streams. |
29 * with the specified [arguments]. When the process has been | 44 * |
30 * successfully started [onStart] is called. If the process fails to | 45 * When the process has been successfully started [onStart] is |
31 * start [onError] is called. | 46 * called. If the process fails to start [onError] is called. |
32 * | 47 * |
33 * Options other than the executable and the arguments are specified | 48 * No data can be written to the process stdin and the process |
34 * using a [ProcessOptions] object. If no options are required, | 49 * cannot be closed nor killed before [onStart] has been invoked. |
35 * [null] can be passed as the options. | 50 */ |
36 * | 51 interface InteractiveProcess { |
Bob Nystrom
2012/05/10 17:14:21
The split between this and Process is unclear. Doe
Mads Ager (google)
2012/05/10 17:33:19
Thanks Bob! That makes a lot of sense to me. I hav
| |
37 * No communication via [stdin], [stdout] or [stderr] can take place | |
38 * with a non-interactive process. Instead, the process is run to | |
39 * completion at which point the exit code and stdout and stderr are | |
40 * supplied to the [callback] parameter. | |
41 */ | |
42 Process.run(String executable, | |
43 List<String> arguments, | |
44 ProcessOptions options, | |
45 void callback(int exitCode, String stdout, String stderr)); | |
46 | |
47 /** | 52 /** |
48 * Returns an input stream of the process stdout. | 53 * Returns an input stream of the process stdout. |
49 * | 54 * |
50 * Throws an [UnsupportedOperationException] if the process is | 55 * Throws an [UnsupportedOperationException] if the process is |
51 * non-interactive. | 56 * non-interactive. |
52 */ | 57 */ |
53 InputStream get stdout(); | 58 InputStream get stdout(); |
54 | 59 |
55 /** | 60 /** |
56 * Returns an input stream of the process stderr. | 61 * Returns an input stream of the process stderr. |
(...skipping 44 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
101 * process to free the system resources associated with it. Usually, | 106 * process to free the system resources associated with it. Usually, |
102 * close should be called in [onExit]. Once a process has been | 107 * close should be called in [onExit]. Once a process has been |
103 * closed it can no longer be killed and [onExit] is detached so the | 108 * closed it can no longer be killed and [onExit] is detached so the |
104 * application is not notified of process termination. | 109 * application is not notified of process termination. |
105 */ | 110 */ |
106 void close(); | 111 void close(); |
107 } | 112 } |
108 | 113 |
109 | 114 |
110 /** | 115 /** |
116 * [ProcessResult] represents the result of running a non-interactive | |
117 * process started with [:Process.run:]. | |
118 */ | |
119 interface ProcessResult { | |
120 /** | |
121 * Exit code for the process. | |
122 */ | |
123 int get exitCode(); | |
124 | |
125 /** | |
126 * Standard output from the process as a string. | |
127 */ | |
128 String get stdout(); | |
129 | |
130 /** | |
131 * Standard error from the process as a string. | |
132 */ | |
133 String get stderr(); | |
134 } | |
135 | |
136 | |
137 /** | |
111 * [ProcessOptions] represents the options that can be supplied when | 138 * [ProcessOptions] represents the options that can be supplied when |
112 * starting a process. | 139 * starting a process. |
113 */ | 140 */ |
114 class ProcessOptions { | 141 class ProcessOptions { |
115 /** | 142 /** |
116 * The working directory from which the process is started. Note | 143 * The working directory from which the process is started. Note |
117 * that the change of directory occurs before executing the process | 144 * that the change of directory occurs before executing the process |
118 * on some platforms, which may have impact when using relative | 145 * on some platforms, which may have impact when using relative |
119 * paths for the executable and the arguments. | 146 * paths for the executable and the arguments. |
120 */ | 147 */ |
(...skipping 28 matching lines...) Expand all Loading... | |
149 * Currently, only ASCII environment variables are supported and | 176 * Currently, only ASCII environment variables are supported and |
150 * errors are likely to occur if an environment variables with | 177 * errors are likely to occur if an environment variables with |
151 * code-points outside the ASCII range is passed in. | 178 * code-points outside the ASCII range is passed in. |
152 */ | 179 */ |
153 Map<String, String> environment; | 180 Map<String, String> environment; |
154 } | 181 } |
155 | 182 |
156 | 183 |
157 class ProcessException implements Exception { | 184 class ProcessException implements Exception { |
158 const ProcessException([String this.message, int this.errorCode = 0]); | 185 const ProcessException([String this.message, int this.errorCode = 0]); |
159 String toString() => "ProcessException: $message"; | 186 String toString() => "ProcessException: $message ($errorCode)"; |
160 | 187 |
161 /** | 188 /** |
162 * Contains the system message for the process exception if any. | 189 * Contains the system message for the process exception if any. |
163 */ | 190 */ |
164 final String message; | 191 final String message; |
165 | 192 |
166 /** | 193 /** |
167 * Contains the OS error code for the process exception if any. | 194 * Contains the OS error code for the process exception if any. |
168 */ | 195 */ |
169 final int errorCode; | 196 final int errorCode; |
170 } | 197 } |
OLD | NEW |