adding new command-line app tutorial

src/site/docs/tutorials/cmdline/index.markdown

+---
+layout: default
+title: "Write Command-Line Apps"
+description: "Basics for command-line apps"
+has-permalinks: true
+tutorial:
+  id: dart-io
+next: fetchdata/
+next-title: "Fetch Data Dynamically"
+prev: futures/
+prev-title: "Use Future-Based APIs"
+---
+
+{% capture whats_the_point %}
+
+* Server-side applications need to do input and output.
+* The dart:io library provides I/O functionality.
+* The args package helps define and parse command-line arguments.
+* Most input and output requires the use of Streams.
+* Streams provide a series of asynchronous data events.
+* To handle asynchronous data, you need to use Futures.
+
+{% endcapture %}
+
+{% capture sample_links %}
+
+<p> This tutorial features these examples:</p>
+* helloworld42
+* dcat
+* dgrep
+
+<p>
+Don't have the source code?
+<a href="https://github.com/dart-lang/dart-tutorials-samples/archive/master.zip">
+  Download it.
+</a>
+
+{% endcapture %}
+
+{% capture content %}
+
+<div class="tute-target-title">
+<h1>{{page.title}}</h1>
+<h3>An introduction to command-line apps</h3>

[Kathy Walrath, 2013/12/20 23:12:16]

change "command-line apps" to something else. (not sure what, but it's
repetitive as-is)

[mem, 2013/12/30 22:17:13]

Done.

+</div>
+
+<div id="under-construction" markdown="1">
+<h3> <i class="icon-wrench"> </i> Under construction </h3>
+
+This is a draft under construction.
+Your kindly worded
+<a
+ href="http://code.google.com/p/dart/issues/entry?template=Tutorial%20feedback"
+ target="_blank">
+comments and suggestions
+</a>
+are appreciated.
+Thank you for your patience.
+</div>
+
+This tutorial looks at a few small command-line applications.
+These programs use resources that most command-line applications need,
+including the standard output, error, and input streams,
+command-line arguments, files and directories, and more.
+
+* [Run an app with the standalone Dart VM](#run-the-first-app)
+* [Check out the dcat code](#dcat-code)
+* [Parsing command-line arguments](#cmd-line-args)
+* [Reading and writing with stdin, stdout, and stderr](#std-in-out-err)
+* [Getting info about a file](#filesystementity)
+* [Reading a file](#reading-a-file)
+* [Writing a file](#writing-a-file)
+* [Getting environment information](#env-var)
+* [Setting exit codes](#exit-codes)
+* [Check out the code for another example](#dgrep-code)
+* [Other resources](#other-resources)
+* [What next?](#what-next)
+
+## Run an app with the standalone Dart VM {#run-the-first-app}
+
+To run a command-line app, you need the Dart VM,

[Kathy Walrath, 2013/12/20 23:12:16]

VM, -> VM (`dart`),

[mem, 2013/12/30 22:17:13]

Done.

+which comes with the Dart Editor or the Dart SDK download.

[Kathy Walrath, 2013/12/20 23:12:16]

-> which comes with the Dart Editor (in the Dart download) or in the
[Dart SDK](/tools/sdk/) download.

[mem, 2013/12/30 22:17:13]

Done.

+For example,
+suppose you installed the Dart download in a directory called `~/myDartDownload`,

[Kathy Walrath, 2013/12/20 23:12:16]

For example, suppose you installed -> If you install

(shave off a few words)

[mem, 2013/12/30 22:17:13]

Done.

+you can find the Dart VM, called `dart`,

[Kathy Walrath, 2013/12/20 23:12:16]

the Dart VM, called `dart`, -> `dart`

[mem, 2013/12/30 22:17:13]

Done.

+in `~/myDartDownload/dart-sdk/bin`.
+
+<div markdown="1">
+
+![The path to the Dart VM](images/filestructure.png)
+
+</div>
+
+By putting this directory in your PATH
+you can refer to the `dart` command and other commands,
+such as the dart analyzer, by name.
+
+Let's run a small program.
+
+<ol>
+<li markdown="1">
+Create a file called `helloworld.dart` that contains this code:
+
+{% prettify dart %}
+void main() {
+  int fortyTwo = 'Hello, World';       // Type mis-match

[Kathy Walrath, 2013/12/20 23:12:16]

mis-match -> mismatch

(GLOBAL)

[mem, 2013/12/30 22:17:13]

Done.

+  print(fortyTwo);
+}
+{% endprettify %}
+</li>
+
+<li markdown="1">
+In the directory that contains the file you just created,
+run the program with the command as shown by the highlighted text.
+
+{% prettify bash %}
+% [[highlight]]dart helloworld.dart[[/highlight]]
+Hello, World!
+%
+{% endprettify %}
+
+The program runs cleanly in spite
+of the type mis-match in the source code.
+Types are optional in Dart and by default the Dart VM
+does not do type-checking.
+</li>
+
+<li markdown="1">
+Run the `helloworld.dart` program using the `--checked` flag:
+
+{% prettify bash %}
+% [[highlight]]dart --checked helloworld.dart[[/highlight]]
+Unhandled exception:
+type 'String' is not a subtype of type 'int' of 'fortyTwo'.
+...
+%
+{% endprettify %}
+
+The program fails because the program assigns a string to an integer.
+
+The `--checked` option enables
+assertion and type checks (checked mode).
+Checked mode is useful during production for finding errors

[Kathy Walrath, 2013/12/20 23:12:16]

production -> development

[mem, 2013/12/30 22:17:13]

Done.

+related to types and for testing `assert` statements.
+We recommend running your programs in checked mode during prototyping
+and development and turning it off for production.
+
+Note that the flags and options passed to the Dart VM go before the name
+of the Dart file to run.
+</li>
+</ol>
+
+## Check out the dcat code {#dcat-code}
+
+Take a quick look at the code for a small sample called `dcat`,
+which is a simplified implementation of the Unix cat utility.
+This program uses various classes, functions, and properties
+available to command-line apps, which this tutorial explains.

[Kathy Walrath, 2013/12/20 23:12:16]

delete ", which this..."

Maybe tell people to hover the mouse over green-background text to see
explanations?

[mem, 2013/12/30 22:17:13]

Done.

+
+<pre class="prettyprint lang-dart">
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:args/args.dart';
+
+const LINE_NUMBER = 'line-number';
+var NEWLINE = '\n';
+
+ArgResults argResults;
+
+void main(<a href="#" class="dart-popover" data-toggle="popover" title="Command-line arguments" data-html="true" data-trigger="hover focus" data-content="Command-line arguments are passed in by the system when the program starts.">List&lt;String&gt; arguments</a>) {
+  exitCode = 0; //presume success.
+  final parser = new ArgParser()
+      ..addFlag(LINE_NUMBER, negatable: false, abbr: 'n');
+
+  <a href="#" class="dart-popover" data-toggle="popover" title="Arguments parser" data-html="true" data-trigger="hover focus" data-content="The ArgParser class provides help with parsing command-line arguments.">argResults = parser.parse(arguments);</a>
+  List&lt;String&gt; paths = argResults.rest;
+
+  dcat(paths, argResults[LINE_NUMBER]);
+}
+
+Future dcat(List&lt;String&gt; paths, bool showLineNumbers) {
+  if (paths.isEmpty) {
+    // No files provided as arguments. Read from stdin and print each line.
+    return <a href="#" class="dart-popover" data-toggle="popover" title="Standard I/O streams" data-html="true" data-trigger="hover focus" data-content="This code reads from the standard input stream and pipes the data to the standard output stream.">stdin.pipe(stdout);</a>
+  } else {
+    return Future.forEach(paths, (path) {
+      int lineNumber = 1;
+      <a href="#" class="dart-popover" data-toggle="popover" title="Open a file for reading" data-html="true" data-trigger="hover focus" data-content="Use the File class to represent a file on the native file system.">Stream&lt;List&lt;int&gt;&gt; stream = new File(path).openRead();</a>
+      return stream
+          <a href="#" class="dart-popover" data-toggle="popover" title="Data converters" data-html="true" data-trigger="hover focus" data-content="Convert data as it becomes available on a stream.">.transform(UTF8.decoder)</a>
+          .transform(const LineSplitter())
+          <a href="#" class="dart-popover" data-toggle="popover" title="Get data from a stream" data-html="true" data-trigger="hover focus" data-content="Listen to a stream to get data when it becomes available.">.listen((line)</a> {
+            if (showLineNumbers) {
+              stdout.write('${lineNumber++} ');
+            }
+            stdout.writeln(line);
+          }).asFuture().catchError((_) =&gt; _handleError(path));
+    });
+  }
+}
+
+_handleError(String path) {
+  <a href="#" class="dart-popover" data-toggle="popover" title="Test a path" data-html="true" data-trigger="hover focus" data-content="You can get information about the file system on which your program is running.">FileSystemEntity.isDirectory(path)</a>.then((isDir) {if (isDir) {

[Kathy Walrath, 2013/12/20 23:12:16]

if (isDir) {
should be on its own line, right?

[mem, 2013/12/30 22:17:13]

Done.

+      print('error: $path is a directory');
+    } else {
+      print('error: $path not found');
+    }
+  });
+  <a href="#" class="dart-popover" data-toggle="popover" title="Exit code" data-html="true" data-trigger="hover focus" data-content="A well-behaved command-line app sets an exit code to indicate whether the program was successful.">exitCode = 2;</a>
+}
+
+</pre>
+
+## Parsing command-line arguments {#cmd-line-args}
+
+The
+<a href="https://api.dartlang.org/args.html" target="_blank">args</a>
+package provides
+parser support for transforming raw command-line arguments
+into a set of options, flags, and additional values.
+Import the library as follows:
+
+{% prettify dart %}
+import 'package:args/args.dart';
+{% endprettify %}
+
+The args library contains two classes:
+
+| Library | Description |
+|---|---|
+| <a href="https://api.dartlang.org/args/ArgParser" target="_blank">ArgParser</a> | A class that parses command-line arguments |
+| <a href="https://api.dartlang.org/args/ArgResults" target="_blank">ArgResults</a> | The result of parsing command-line arguments using ArgParser. |
+{: .table }
+
+Let's take a look at the `dcat` sample

[Kathy Walrath, 2013/12/20 23:12:16]

sample -> sample,

[mem, 2013/12/30 22:17:13]

Done.

+which uses ArgParser and ArgResults to parse and store its command-line arguments.
+
+<ol>
+<li markdown="1">
+Copy the sample file from the github repo:
+<a href="https://github.com/dart-lang/dart-tutorials-samples/blob/master/bin/dcat.dart">dcat.dart</a>.
+</li>
+
+<li markdown="1">
+Run the program from the command-line as shown by the highlighted text.

[Kathy Walrath, 2013/12/20 23:12:16]

command-line -> command line

(since it's not an adjective here)

[mem, 2013/12/30 22:17:13]

Done.

+
+{% prettify bash %}

[Kathy Walrath, 2013/12/20 23:12:16]

Weirdly, this highlights seemingly random words, such as Dart and All. Not sure
what a better formatter would be.

+$ [[highlight]]dart dcat.dart -n dcat.dart[[/highlight]]

[Kathy Walrath, 2013/12/20 23:12:16]

I found the -n dcat.dart confusing, since dcat.dart was used twice, and I didn't
know what was an argument to what.

Using a second file (maybe a .txt file) would make it clearer.

[mem, 2013/12/30 22:17:13]

Done.

+1 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+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.
+...
+{% endprettify %}
+
+The program displays the contents of the source code file and
+preceeds each line with a line number.
+</li>
+
+</ol>
+
+The following diagram shows how the `dcat` command line used above
+is parsed into the `ArgResults` object.
+
+![ArgsParser parses command-line arguments](images/commandlineargs.png)
+
+You can access flags and options by name,
+treating the ArgResults object like a Map.
+You can access other values with properties such as `rest`.
+
+Here's the code from `dcat` that deals with command-line arguments:
+
+<pre class="prettyprint lang-dart">
+
+...
+<a href="#" class="dart-popover" data-toggle="popover" title="Parsed arguments" data-html="true" data-trigger="hover focus" data-content="This object contains parsed options and flags.">ArgResults argResults;</a>
+
+void main(<a href="#" class="dart-popover" data-toggle="popover" title="Command-line arguments" data-html="true" data-trigger="hover focus" data-content="The system passes command line arguments into the program in a list of strings.">List&lt;String&gt; arguments</a>) {

[Kathy Walrath, 2013/12/20 23:12:16]

command line -> command-line

:)

[mem, 2013/12/30 22:17:13]

Done.

+  final parser = new ArgParser()
+      <a href="#" class="dart-popover" data-toggle="popover" title="Define a valid flag" data-html="true" data-trigger="hover focus" data-content="Add a flag definition to the command-line argument parser. This code defines the flag -n, which when used displays line numbers.">..addFlag(LINE_NUMBER, negatable: false, abbr: 'n')</a>;
+
+  argResults = parser.<a href="#" class="dart-popover" data-toggle="popover" title="Parse the arguments" data-html="true" data-trigger="hover focus" data-content="Parse the arguments that were passed into the main() function. The parser stops parsing if it finds an undefined option or flag.">parse(arguments)</a>;
+  List&lt;String&gt; paths = <a href="#" class="dart-popover" data-toggle="popover" title="Remaining arguments" data-html="true" data-trigger="hover focus" data-content="To get the arguments that remain after parsing all of the valid options and flags, use the rest property.">argResults.rest</a>;
+
+  dcat(paths, <a href="#" class="dart-popover" data-toggle="popover" title="Refer to options and flags by name" data-html="true" data-trigger="hover focus" data-content="You can refer to an option or flag by name treating the ArgResults object like a Map.">argResults[LINE_NUMBER])</a>;
+}
+...
+</pre>
+
+The API docs for the
+<a href="https://api.dartlang.org/args.html" target="_blank">args</a> library

[Kathy Walrath, 2013/12/20 23:12:16]

This link should be on API docs (and why isn't it markdown?). Maybe:

The [API docs for the args library](...)

[mem, 2013/12/30 22:17:13]

it's not in markdown because I want to use target=_blank.

+provides very detailed information

[Kathy Walrath, 2013/12/20 23:12:16]

provides very -> provide

[mem, 2013/12/30 22:17:13]

Done.

+about the use of the ArgsParser and ArgResults classes.

[Kathy Walrath, 2013/12/20 23:12:16]

about the use of
->
to help you use
OR
about using

[mem, 2013/12/30 22:17:13]

Done.

+
+## Reading and writing with stdin, stdout, and stderr {#std-in-out-err}
+
+Like other languages,
+Dart has standard output, standard error, and standard input streams.
+The standard I/O streams are defined at the top-level of the dart:io library,

[Kathy Walrath, 2013/12/20 23:12:16]

top-level -> top level

[mem, 2013/12/30 22:17:13]

Done.

+which you import as follows:
+
+{% prettify dart %}
+import 'dart:io';
+{% endprettify %}
+
+Only command-line applications, not web applications,
+can use the dart:io library.
+
+Standard output and standard error are 
+<a href="https://api.dartlang.org/dart_io/IOSink.html" target="_blank">IOSink</a>s
+rather than streams, but can be bound to a stream.
+Standard input is a
+<a href="https://api.dartlang.org/dart_async/Stream.html" target="_blank">Stream</a>.
+That is, the
+<a href="https://api.dartlang.org/dart_io/Stdin.html" target="_blank">Stdin</a> class
+is a subclass of the Stream class.
+
+| Library | Description |

[Kathy Walrath, 2013/12/20 23:12:16]

Library -> Object?

[mem, 2013/12/30 22:17:13]

Done.

+|---|---|
+| <a href="https://api.dartlang.org/dart_io.html#stdout" target="_blank">stdout</a> | The standard output |
+| <a href="https://api.dartlang.org/dart_io.html#stderr" target="_blank">stderr</a> | The standard error |
+| <a href="https://api.dartlang.org/dart_io.html#stdin" target="_blank">stdin</a> | The standard input |
+{: .table }
+
+### stdout
+
+Here's the code from the `dcat` program that writes the line number to the `stdout`
+(if the -n flag is set) followed by the line from the file.
+
+{% prettify dart %}
+if (showLineNumbers) {
+  [[highlight]]stdout.write('${lineNumber++} ');[[/highlight]]
+}
+
+[[highlight]]stdout.writeln(line);[[/highlight]]
+{% endprettify %}
+
+The `write()` and `writeln()` methods take an object of any type,
+convert it to a string, and print it. The `writelin()` method

[Kathy Walrath, 2013/12/20 23:12:16]

lin -> ln

[mem, 2013/12/30 22:17:13]

Done.

[mem, 2013/12/30 22:17:13]

Done.

+also prints a newline character.
+`dcat` uses the `write()` method to print the line number so the
+line number and the text appear on the same line.
+
+You can also use the `writeAll()` method to print a list of objects,
+or use `addStream()` to asynchronously print all of the elements from a stream.
+
+### stderr
+
+Use `stderr` to write error messages to the console.
+The standard error stream has the same methods as `stdout`,
+and you use it in the same way.
+Although both `stdout` and `stderr` print to the console
+their output is separate
+and can be redirected or piped at the command-line to different destinations.

[Kathy Walrath, 2013/12/20 23:12:16]

no - in command-line here!

[mem, 2013/12/30 22:17:13]

Done.

+
+This code from `dcat` prints an error message if the user
+tries to list a directory or if the file is not found.
+
+{% prettify dart %}
+if (isDir) {
+  [[highlight]]stderr.writeln('error: $path is a directory');[[/highlight]]
+} else {
+  [[highlight]]stderr.writeln('error: $path not found');[[/highlight]]
+}
+{% endprettify %}
+
+### stdin
+
+The standard input stream typically
+reads data synchronously from the keyboard,
+although it can read asynchronously
+and it can get input piped in from the standard
+output of another program.
+
+Here's a small program that reads a single line from `stdin`:
+
+{% prettify dart %}
+import 'dart:io';
+import 'dart:async';
+
+void main() {
+  stdout.writeln('What's in a name?');

[Kathy Walrath, 2013/12/20 23:12:16]

's => \'s? (This doesn't work as written, right?)

(It'll still look bad in the formatter, though. Maybe use " instead of '.)

[mem, 2013/12/30 22:17:13]

Done.

+  [[highlight]]String path = stdin.readLineSync();[[/highlight]]
+  
+  FileSystemEntity.type(path).then((type) {
+    print(type);      
+  });
+}
+{% endprettify %}
+
+The `readLineSync()` method reads text from the standard input stream

[Kathy Walrath, 2013/12/20 23:12:16]

stream -> stream,

[mem, 2013/12/30 22:17:13]

Done.

+blocking until the user types in text and presses return.
+This little program assumes the input is a pathname and prints out what
+type of file system entity the path points to.
+
+In the `dcat` program,
+if the user does not provide a filename on the command line,
+the program instead reads synchronously from stdin
+using the `pipe()` method.
+
+{% prettify dart %}
+return [[highlight]]stdin[[/highlight]].pipe(stdout);
+{% endprettify %}
+
+In this case,
+the user types in lines of text and the program copies them to stdout.
+The user signals the end of input by typing <ctl-d>.
+
+{% prettify bash %}
+$ [[highlight]]dart dcat.dart[[/highlight]]
+[[highlight]]The quick brown fox jumped over the lazy dog.[[/highlight]]
+The quick brown fox jumped over the lazy dog.
+[[highlight]]ctl-d[[/highlight]]

[Kathy Walrath, 2013/12/20 23:12:16]

ctl-d -> <ctl-d>
?

(so it'll match the description in the text)

[mem, 2013/12/30 22:17:13]

the < and gt& signs don't work with highlight. So I used ...
Done.

+{% endprettify %}
+
+## Getting info about a file {#filesystementity}
+
+The 
+<a href="https://api.dartlang.org/dart_io/FileSystemEntity.html" target="_blank">FileSystemEntity</a>
+class in the dart:io library provides
+properties and methods that help you inspect and manipulate the file system.
+
+For example, if you have a path,
+you can determine whether the path is a file, a directory, a link, or not found.

[Kathy Walrath, 2013/12/20 23:12:16]

It's a little weird that we've already seen this.
Maybe do a forward link from there?

[mem, 2013/12/30 22:17:13]

Done.

+As you saw in the previous example,
+you can use the `type()` method from the `FileSystemEntity` class.

[Kathy Walrath, 2013/12/20 23:12:16]

This is linked to the previous example, but not to the preceding sentence... it
doesn't say what `type()` does. Merge them?

[mem, 2013/12/30 22:17:13]

Done.

+Because the `type` method accesses the file system,

[Kathy Walrath, 2013/12/20 23:12:16]

type or type()?

[mem, 2013/12/30 22:17:13]

Done.

+it performs the check asynchronously within a Future.
+
+The following code from
+the `dcat` example uses `FileSystemEntity` to determine if the path provided
+on the command-line is a directory.

[Kathy Walrath, 2013/12/20 23:12:16]

command-line -> command line

[mem, 2013/12/30 22:17:13]

Done.

+The Future returns a boolean to the `then()` method that indicates

[Kathy Walrath, 2013/12/20 23:12:16]

It's not actually returned to the then() method. It's an argument to the handler
that then registers.

[mem, 2013/12/30 22:17:13]

Done.

+if the path is a directory or not.
+
+{% prettify dart %}
+[[highlight]]FileSystemEntity.isDirectory(path)[[/highlight]].then((isDir) {
+  if (isDir) {
+    stderr.writeln('error: $path is a directory');
+  } else {
+    stderr.writeln('error: $path not found');
+  }
+  exit(2);
+});
+{% endprettify %}
+
+Other interesting methods in the `FileSystemEntity` class
+include `isFile()`, `exists()`, `stat()` and `parent`,

[Kathy Walrath, 2013/12/20 23:12:16]

and -> , and

[mem, 2013/12/30 22:17:13]

Done.

+all of which also use a Future to return a value.
+`FileSystemEntity` also provides methods for deleting a file
+and renaming a file.

[Kathy Walrath, 2013/12/20 23:12:16]

Do they not return Futures? Or are there multiple deletion/rename methods?

Having these separate from the methods in the previous sentence (and not naming
the methods) made me wonder...

[mem, 2013/12/30 22:17:13]

Done.

+
+## Reading a file {#reading-a-file}
+
+For each file listed on the command-line `dcat` opens it for reading

[Kathy Walrath, 2013/12/20 23:12:16]

This sentence needs a little work, grammatically. (and command-line -> command
line!)

Maybe split it into multiple sentences?

[mem, 2013/12/30 22:17:13]

Done.

[mem, 2013/12/30 22:17:13]

Done.

+with the `openRead()` method.
+This returns a stream.

[Kathy Walrath, 2013/12/20 23:12:16]

Seems awkward. Combine with previous sentence? 

[mem, 2013/12/30 22:17:13]

Done.

+The `listen()` method registers a callback function that runs
+when data becomes available on the stream.
+
+The callback function provided by `dcat` writes the data to stdout.

[Kathy Walrath, 2013/12/20 23:12:16]

This is a little disjointed. It's unclear why it's a separate paragraph, and
it's unclear what I'm supposed to look for in the following code example. E.g. I
was surprised to see listen() highlighted below, since I expected the callback
function to be the important thing.

Maybe this should all be one paragraph?

[mem, 2013/12/30 22:17:13]

Done.

+
+{% prettify dart %}
+return Future.forEach(paths, (path) {
+  int lineNumber = 1;
+  Stream<List<int>> stream = new File(path).openRead();
+
+  return stream
+      ...
+      [[highlight]].listen((line)[[/highlight]] {
+        if (showLineNumbers) {
+          stdout.write('${lineNumber++} ');
+        }
+        stdout.writeln(line);
+      }).asFuture().then((_) { exitCode = 1; }).catchError((_) => _handleError(path));

[Kathy Walrath, 2013/12/20 23:12:16]

reduce the line length here

[mem, 2013/12/30 22:17:13]

Done.

+});
+{% endprettify %}
+
+This code uses two decoders that transform the data before the
+`listen()` callback function runs.
+The UTF8 decoder converts the data into Dart strings.
+`LineSplitter` splits the data at newlines.
+
+{% prettify dart %}
+return Future.forEach(paths, (path) {
+  int lineNumber = 1;
+  Stream<List<int>> stream = new File(path).openRead();
+
+  return stream
+      [[highlight]].transform(UTF8.decoder)
+      .transform(const LineSplitter())[[/highlight]]
+      .listen((line) {
+        if (showLineNumbers) {
+          stdout.write('${lineNumber++} ');
+        }
+        stdout.writeln(line);
+      }).asFuture().then((_) { exitCode = 1; }).catchError((_) => _handleError(path));

[Kathy Walrath, 2013/12/20 23:12:16]

another too-long line

[mem, 2013/12/30 22:17:13]

Done.

+});
+{% endprettify %}
+

[Kathy Walrath, 2013/12/20 23:12:16]

including -> , including

[mem, 2013/12/30 22:17:13]

Done.

+The dart:convert library contains these and other data converters including
+one for JSON.
+To use these converters you need to import the dart:convert library:
+
+{% prettify dart %}
+import 'dart:convert';
+{% endprettify %}
+
+## Writing a file {#writing-a-file}
+
+The easiest way to write text to a file is to
+create a 
+<a href="https://api.dartlang.org/dart_io/File.html" target="_blank">
+File

[Kathy Walrath, 2013/12/20 23:12:16]

remove newline after File

[mem, 2013/12/30 22:17:13]

Done.

+</a>
+object and use the `writeAsString()` method:
+
+{% prettify dart %}
+File quotesFile = new File('quotes.txt');
+String stronger = 'That which does not kill us makes us stronger. -Friedrich Nietzsche';

[Kathy Walrath, 2013/12/20 23:12:16]

long line

[mem, 2013/12/30 22:17:13]

Done.

+
+quotesFile.writeAsString(stronger, mode: FileMode.APPEND)
+    .then((_) { print('Data written.'); });
+{% endprettify %}
+
+The `writeAsString()` method writes the data asynchronously via a Future.
+It opens the file before writing and closes the file when done.
+To append data to an existing file you can use the optional

[Kathy Walrath, 2013/12/20 23:12:16]

long sentence, no commas!

[mem, 2013/12/30 22:17:13]

Done.

+parameter `mode` and set its value to `FileMode.APPEND` as we've done here.
+Otherwise, the mode is `FileMode.WRITE` and the previous contents of the file,
+if there is any, gets overwritten.

[Kathy Walrath, 2013/12/20 23:12:16]

delete "there is"
gets -> are

[mem, 2013/12/30 22:17:13]

Done.

+
+If you want to write more data, you can open the file for writing.
+The `openWrite()` method returns an IOSink (the same type as stdin and stderr).
+You can continue to write to the file until done.

[Kathy Walrath, 2013/12/20 23:12:16]

Combine this with the following sentence, to make it less choppy.

[mem, 2013/12/30 22:17:13]

Done.

+Then you must close the file.
+The `close()` method is asynchronous and returns a Future.
+
+{% prettify dart %}
+IOSink quotes = new File('quotes.txt').openWrite(mode: FileMode.APPEND);
+
+quotes.write('A woman is like a tea bag; ');
+quotes.write("you never know how strong it is until it's in hot water.");
+quotes.writeln(" -Eleanor Roosevelt");
+quotes.close().then((_) { print('done'); } );
+{% endprettify %}
+
+## Getting environment information {#env-var}
+
+Use the
+<a href="https://api.dartlang.org/dart_io/Platform.html" target="_blank">
+Platform

[Kathy Walrath, 2013/12/20 23:12:16]

remove newline after Platform

[mem, 2013/12/30 22:17:13]

Done.

+</a>
+class (from the dart:io library, not from the dart:html library)

[Kathy Walrath, 2013/12/20 23:12:16]

make this io vs. html aside a note, so it doesn't interrupt the flow

[mem, 2013/12/30 22:17:13]

Done.

[mem, 2013/12/30 22:17:13]

Done.

+to get information about the machine and OS that the program is running on.
+
+The `environmont` property returns a Map that contains all

[Kathy Walrath, 2013/12/20 23:12:16]

environmOnt?

[mem, 2013/12/30 22:17:13]

Done.

+the environment variables currently set.
+
+{% prettify dart %}
+Map environmentVars = Platform.environment;
+
+print('PWD = ${environmentVars["PWD"]}');
+print('LOGNAME = ${environmentVars["LOGNAME"]}');
+print('PATH = ${environmentVars["PATH"]}');
+
+environmentVars['MEANINGOFLIFE'] = 42; // Not persistent.
+
+print('MEANINGOFLIFE = ${environmentVars["MEANINGOFLIFE"]}');
+{% endprettify %}
+
+As you can see from the code, you can change values
+in the Map, but these do not persist and if you refer to

[Kathy Walrath, 2013/12/20 23:12:16]

, but -> However, 
persist and -> persist. If

(You can't see from the code that they don't persist.)

[mem, 2013/12/30 22:17:13]

Done.

+`Platform.environment` again, your changes will not be there.
+
+`Platform` provides other useful properties that give
+information about the machine and OS:

[Kathy Walrath, 2013/12/20 23:12:16]

Are the following all of the properties? If so, reign back expectations (I see
nothing about machines here). If not, say this is an example (or otherwise make
clear that this is a subset).

[mem, 2013/12/30 22:17:13]

Done.

+
+{% prettify dart %}
+Platform.isMacOS()
+Platform.isLinux()

[Kathy Walrath, 2013/12/20 23:12:16]

usually we don't use a <pre> section for non-running code. maybe use a list
instead?

[mem, 2013/12/30 22:17:13]

Done.

+Platform.isWindows()
+{% endprettify %}
+
+Get the path of the currently running program with:
+
+{% prettify dart %}

[Kathy Walrath, 2013/12/20 23:12:16]

This seems a little weird; it's not code you'd use. Maybe just fold this <pre>
into the previous sentence?

[mem, 2013/12/30 22:17:13]

Done.

+Platform.script.path;
+{% endprettify %}
+
+## Setting exit codes {#exit-codes}
+
+The dart:io library defines a top-level property

[Kathy Walrath, 2013/12/20 23:12:16]

property -> property,

[mem, 2013/12/30 22:17:13]

Done.

+`exitCode`, that you can change to set the exit code for
+the current invocation of the Dart VM.
+
+The `dcat` example sets the program's exit code
+in two different places.
+First, at the very beginning of `main()`,
+the program sets the exit code to 0.
+
+{% prettify dart %}
+...
+void main(List<String> arguments) {
+  exitCode = 0; //presume success.

[Kathy Walrath, 2013/12/20 23:12:16]

hmmm... I just noticed that comment format is different from our usual. I
expected:

// Presume success.

[mem, 2013/12/30 22:17:13]

Done.

+  ...
+}
+...
+{% endprettify %}
+
+The last assignment to `exitCode` provides the final exit code for the program.
+So, if the `dcat` program does not set the exit code again,
+it exits with a code of 0, which indicates success.
+
+Second, the program sets the error code
+in the `_handleError()` function.
+
+{% prettify dart %}
+_handleError(String path) {
+  FileSystemEntity.isDirectory(path).then((isDir) {
+    if (isDir) {
+      stderr.writeln('error: $path is a directory');
+    } else {
+      stderr.writeln('error: $path not found');
+    }
+    [[highlight]]exitCode = 2;[[/highlight]]
+  });
+}
+{% endprettify %}
+
+An exit code of 2 indicates that the program encountered an error.
+
+An alternative to using `exitCode` is to use the top-level `exit()` function,
+which sets the exit code and quits the program immediately.
+For example, the `_handleError` function could use this code

[Kathy Walrath, 2013/12/20 23:12:16]

_handleError -> _handleError()

[mem, 2013/12/30 22:17:13]

Done.

[mem, 2013/12/30 22:17:13]

Done.

+instead:
+
+{% prettify dart %}
+_handleError(String path) {

[Kathy Walrath, 2013/12/20 23:12:16]

I might just put this inline, since you don't encourage using exit(). Maybe

For example, the `_handleError()` function could call `exit(2)` instead of
setting `exitCode` to 2.

Then delete this code section. (Remember, people blindly copy code!)

[mem, 2013/12/30 22:17:13]

Done.

+  FileSystemEntity.isDirectory(path).then((isDir) {
+    if (isDir) {
+      stderr.writeln('error: $path is a directory');
+    } else {
+      stderr.writeln('error: $path not found');
+    }
+    [[highlight]]exit(2);[[/highlight]]
+  });
+}
+{% endprettify %}
+
+Generally speaking, you are better off using the `exitCode` property,
+which sets the exit code but allows the program to continue through to its
+natural completion.
+
+Although you can use any number for an exit code,
+these are defined by convention:

[Kathy Walrath, 2013/12/20 23:12:16]

I don't like "these" (or "are defined"). Rewrite if you can.

[mem, 2013/12/30 22:17:13]

Done.

+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Warnings |
+| 2 | Errors |
+{: .table }
+
+## Check out the code for another example {#dgrep-code}

[Kathy Walrath, 2013/12/20 23:12:16]

Maybe just:

## Another example: dgrep {#dgrep-code}

[mem, 2013/12/30 22:17:13]

Done.

+
+Here's the code for a simplified version of the Unix utility grep

[Kathy Walrath, 2013/12/20 23:12:16]

for a... -> for `dgrep`, a ....

[mem, 2013/12/30 22:17:13]

Done.

+called `dgrep`.
+This program makes use of some additional APIs that do not

[Kathy Walrath, 2013/12/20 23:12:16]

do not -> don't

[mem, 2013/12/30 22:17:13]

Done.

+appear in the `dcat` example.
+
+<pre class="prettyprint lang-dart">

[Kathy Walrath, 2013/12/20 23:12:16]

why use a <pre> here instead of {% prettify... %}?

Is that necessary for highlighting?

[mem, 2013/12/30 22:17:13]

it's necessary for the popups.

+import 'dart:io';
+import 'package:args/args.dart';
+
+const USAGE = 'usage: dart dgrep.dart [-rnS] patterns file_or_directory';
+const RECURSIVE = 'recursive';
+const LINE_NUMBER = 'line-number';
+const FOLLOW_LINKS = 'follow-links';
+
+ArgResults argResults;
+
+void main(List<String> arguments) {
+  final parser = new ArgParser()
+      ..addFlag(RECURSIVE, negatable: false, abbr: 'r')
+      ..addFlag(LINE_NUMBER, negatable: false, abbr: 'n')
+      ..addFlag(FOLLOW_LINKS, negatable: false, abbr: 'S');
+
+  argResults = parser.parse(arguments);
+
+  if (argResults.rest.length < 2) {
+    print(USAGE);
+    exit(1);
+  }
+
+  final searchPath = <a href="#" class="dart-popover" data-toggle="popover" title="The rest property is a List." data-html="true" data-trigger="hover focus" data-content="ArgResults.rest is a list. Use the last property to get the last command-line argument.">argResults.rest.last;</a>
+  final searchTerms = argResults.rest.sublist(0, argResults.rest.length - 1);
+
+  FileSystemEntity.isDirectory(searchPath).then((isDir) {
+    if (isDir) {
+      final startingDir = <a href="#" class="dart-popover" data-toggle="popover" title="Create a Directory" data-html="true" data-trigger="hover focus" data-content="Create a new Directory object with a pathname.">new Directory(searchPath);</a>

[Kathy Walrath, 2013/12/20 23:12:16]

What does "with a pathname" mean? How does it differ from "with a path" below?

[mem, 2013/12/30 22:17:13]

Done.

+      <a href="#" class="dart-popover" data-toggle="popover" title="Recursive directory search" data-html="true" data-trigger="hover focus" data-content="List a directory's subdirectories recursively and process each file within.">startingDir.list(recursive:   argResults[RECURSIVE],
+                       followLinks: argResults[FOLLOW_LINKS]).listen((entity)</a> {
+        if (entity is File) {
+          searchFile(entity, searchTerms);
+        }
+      });
+    } else {
+      searchFile(<a href="#" class="dart-popover" data-toggle="popover" title="Create a File" data-html="true" data-trigger="hover focus" data-content="Create a new file with a path">new File(searchPath)</a>, searchTerms);

[Kathy Walrath, 2013/12/20 23:12:16]

path -> path.

maybe: with a path -> at the specified path?

(I wasn't sure what "with" meant.)

[mem, 2013/12/30 22:17:13]

Done.

+    }
+  });
+}
+
+
+void printMatch(File file, List lines, int i) {
+  StringBuffer sb = new StringBuffer();
+  if (argResults[RECURSIVE]) sb.write('${file.path}:');
+  if (argResults[LINE_NUMBER]) sb.write('${i + 1}:');
+  sb.write(lines[i]);
+  print(sb.toString());
+}
+
+searchFile(File file, searchTerms) {
+  <a href="#" class="dart-popover" data-toggle="popover" title="Read a file as lines" data-html="true" data-trigger="hover focus" data-content="Read a file as a list of strings that contains each line separately.">file.readAsLines()</a>.then((lines) {
+    for (var i = 0; i &lt; lines.length; i++) {
+      bool found = false;
+      for (var j = 0; j &lt; searchTerms.length &amp;&amp; !found; j++) {
+        if (lines[i].contains(searchTerms[j])) {
+          printMatch(file, lines, i);
+          found = true;
+        }
+      }
+    }
+  }).catchError(print);
+}
+
+</pre>
+
+## Other resources {#other-resources}
+
+One kind of command-line app that you can write is an HTTP server.

[Kathy Walrath, 2013/12/20 23:12:16]

I'd lead with the link, instead of the discussion. Maybe:

See the [Dartiverse Search
walkthrough](/docs/dart-up-and-running/contents/ch05.html)
for an example of another kind of command-line app: an HTTP server.

(That reminds me... I wish we had a good way to link to each sample. If each
sample had a homepage that pointed to all relevant pages, that'd be cool.)

+Check out the
+<a href="https://code.google.com/p/dart/source/browse/branches/bleeding_edge/dart/samples/dartiverse_search/readme.txt">dartiverse_search</a>
+example to see a search app that uses HttpServer and WebSockets.
+
+This tutorial described some basic API found in these classes from the dart:io library:

[Kathy Walrath, 2013/12/20 23:12:16]

This intro makes this sound like a summary of the page, rather than links to
other resources.

Actually... it'd make sense to put this in a new "Summary" section, since much
of this info (and the links) is elsewhere, and this is just a handy, one-stop
place to find them.

[mem, 2013/12/30 22:17:13]

Done.

+
+| Class | Description |

[Kathy Walrath, 2013/12/20 23:12:16]

Class -> API?

[mem, 2013/12/30 22:17:13]

Done.

+|---|---|
+| <a href="https://api.dartlang.org/dart_io/IOSink.html" target="_blank">IOSink</a> | Helper class for objects that consume data from streams. |
+| <a href="https://api.dartlang.org/dart_io/File.html" target="_blank">File</a> | Represents a file on the native file system |
+| <a href="https://api.dartlang.org/dart_io/Directory.html" target="_blank">Directory</a> | Represents a directory on the native file system |
+| <a href="https://api.dartlang.org/dart_io/FileSystemEntity.html" target="_blank">FileSystemEntity</a> | Superclass for File and Directory |
+| <a href="https://api.dartlang.org/dart_io/Platform.html" target="_blank">Platform</a> | Provides information about the machine and operating system |
+| <a href="https://api.dartlang.org/dart_io.html#stdout" target="_blank">stdout</a> | The standard output |
+| <a href="https://api.dartlang.org/dart_io.html#stderr" target="_blank">stderr</a> | The standard error |
+| <a href="https://api.dartlang.org/dart_io.html#stdin" target="_blank">stdin</a> | The standard input |
+| <a href="https://api.dartlang.org/dart_io.html#exitCode" target="_blank">exitCode</a> | Sets the exit code |
+| <a href="https://api.dartlang.org/dart_io.html#exit" target="_blank">exit()</a> | Sets the exit code and quits |
+{: .table }
+
+In addition, this tutorial covers two classes that help with command-line arguments:

[Kathy Walrath, 2013/12/20 23:12:16]

This, too, is more "Summary" than "Other resources"

[mem, 2013/12/30 22:17:13]

Done.

+
+| Class | Description |
+|---|---|
+| <a href="https://api.dartlang.org/args/ArgParser" target="_blank">ArgParser</a> | A class that transforms a list of raw arguments and into a set of options, flags, and remaining values. |
+| <a href="https://api.dartlang.org/args/ArgResults" target="_blank">ArgResults</a> | The result of parsing raw command line arguments using ArgParser. |
+{: .table }
+
+Refer to the API docs for <a href="https://api.dartlang.org/dart_io.html" target="_blank">dart:io</a>,

[Kathy Walrath, 2013/12/20 23:12:16]

This seems like genuine "Other resources" material.

[mem, 2013/12/30 22:17:13]

Done.

+<a href="https://api.dartlang.org/dart_async.html" target="_blank">dart:async</a>,
+<a href="https://api.dartlang.org/dart_convert.html" target="_blank">dart:convert</a>,
+and the
+<a href="https://api.dartlang.org/dart_args.html" target="_blank">args</a>
+package for more classes, functions, and properties.
+
+## What next? {#what-next}
+
+The [Get Input from a Form](/docs/tutorials/forms/) tutorial features a client-server example,
+in which the server is an HttpServer.

[Kathy Walrath, 2013/12/20 23:12:16]

Maybe delete this line, ending the sentence at "example." It doesn't seem
necessary to talk about HttpServer here, does it?

[mem, 2013/12/30 22:17:13]

Done.

+The code for the server, which uses CORS headers and handles
+POST requests, is explained in detail.
+
+{% endcapture %}
+
+{% include tutorial.html %}