This is a request for comments.

runtime/bin/process.dart

Index: runtime/bin/process.dart
diff --git a/runtime/bin/process.dart b/runtime/bin/process.dart
index 181f6c6e7f6f0bbfa1e0a43a071bc7c8d7f908e8..cfd47be18e07c48110149c086108686319097e09 100644
--- a/runtime/bin/process.dart
+++ b/runtime/bin/process.dart
@@ -13,30 +13,58 @@ interface Process default _Process {
    * been successfully started [onStart] is called. If the process
    * fails to start [onError] is called.
    *
-   * An optional [workingDirectory] can be passed to specify where the process
-   * is run from. Note that the change of directory occurs before executing
-   * the process on some platforms, which may have impact when using relative
-   * paths for [executable] and [arguments].
+   * An optional [ProcessOptions] object can be passed to specify
+   * options other than the executable and the arguments.
    *
    * No data can be written to the process stdin and the process
    * cannot be closed nor killed before [onStart] has been invoked.
    */
   Process.start(String executable,
                 List<String> arguments,
-                [String workingDirectory]);
+                [ProcessOptions options]);
+
+  /**
+   * Creates a new process object, starts a process and runs it
+   * non-interactively to completion. The process run is [executable]
+   * with the specified [arguments]. When the process has been
+   * successfully started [onStart] is called. If the process fails to
+   * start [onError] is called.
+   *
+   * Options other than the executable and the arguments are specified
+   * using a [ProcessOptions] object. If no options are required,
+   * [null] can be passed as the options.
+   *
+   * No communication via [stdin], [stdout] or [stderr] can take place
+   * with a non-interactive process. Instead, the process is run to
+   * completion at which point the exit code and stdout and stderr are
+   * supplied to the [callback] parameter.
+   */
+  Process.run(String executable,
+              List<String> arguments,
+              ProcessOptions options,
+              void callback(int exitCode, String stdout, String stderr));
 
   /**
    * Returns an input stream of the process stdout.
+   *
+   * Throws an [UnsupportedOperationException] if the process is
+   * non-interactive.
    */
   InputStream get stdout();
 
   /**
    * Returns an input stream of the process stderr.
+   *
+   * Throws an [UnsupportedOperationException] if the process is
+   * non-interactive.
    */
   InputStream get stderr();
 
   /**
    * Returns an output stream to the process stdin.
+   *
+   * Throws an [UnsupportedOperationException] if the process is
+   * non-interactive.
    */
   OutputStream get stdin();
 
@@ -47,7 +75,11 @@ interface Process default _Process {
   void set onStart(void callback());
 
   /**
-   * Sets an exit handler which gets invoked when the process terminates.
+   * Sets an exit handler which gets invoked when the process
+   * terminates.
+   *
+   * Throws an [UnsupportedOperationException] if the process is
+   * non-interactive.
    */
   void set onExit(void callback(int exitCode));
 
@@ -75,6 +107,43 @@ interface Process default _Process {
 }
 
 
+/**
+ * [ProcessOptions]q represents the options that can be supplied when

[Søren Gjesse, 2012/04/12 15:02:21]

q?

[Mads Ager (google), 2012/04/13 08:49:39]

Done.

+ * starting a process.
+ */
+class ProcessOptions {
+  /**
+   * The working directory from which the process is started.  Note
+   * that the change of directory occurs before executing the process
+   * on some platforms, which may have impact when using relative
+   * paths for the executable and the arguments.
+   */
+  String workingDirectory;
+
+  /**
+   * The encoding used for text on stdout when starting a
+   * non-interactive process with [:Process.run:].
+   *
+   * This option is ignored for interactive processes started with
+   * [:Process.start:].
+   *
+   * The default stdoutEncoding is UTF_8.
+   */
+  Encoding stdoutEncoding;

[Søren Gjesse, 2012/04/12 15:02:21]

The encodings are gnored when passing this to Process.start. Should we just
ignore that or throw an exception if one of then are not null in that case?

[Mads Ager (google), 2012/04/13 08:49:39]

I went for ignoring. I don't think it matters much as long as we document the
behavior. I would be fine with changing this if someone finds a compelling
reason to change it.

+
+  /**
+   * The encoding used for text on stderr when starting a
+   * non-interactive process with [:Process.run:].
+   *
+   * This option is ignored for interactive processes started with
+   * [:Process.start:].
+   *
+   * The default stderrEncoding is UTF_8.
+   */
+  Encoding stderrEncoding;

[Søren Gjesse, 2012/04/12 15:02:21]

Should there be a string or bytearray that will be piped in through stdin when a
process is run?

[Mads Ager (google), 2012/04/13 08:49:39]

Yes, there probably should. I'll add that in a separate change. Similarly, there
should be a way to set environment variables for the spawned process.

+}
+
+
 class ProcessException implements Exception {
   const ProcessException([String this.message, int this.errorCode = 0]);
   String toString() => "ProcessException: $message";