• ⟨ Get started: command-line & server apps
• Write HTTP clients & servers ⟩

Write command-line apps

What's the point?

• Command-line 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.
• A Future object represents a value that will be available at some time in the future.
• Streams provide a series of asynchronous data events.
• Most input and output requires the use of streams.

Note: This tutorial uses the async and await language features, which rely on the Future and Stream classes for asynchronous support. To learn more about these features, see the asynchronous programming codelab and the streams tutorial.

This tutorial teaches you how to build command-line appsand shows you 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.

Running an app with the standalone Dart VM

To run a command-line app, you need the Dart VM (dart),which comes when you install the Dart SDK.

Important: The location of the SDK installation directory (we’ll call it <sdk-install-dir>) depends on your platform and how you installed the SDK. You can find dart in <sdk-install-dir>/bin. By putting this directory in your PATH you can refer to the dart command and other commands, such as dartanalyzer, by name.

Let’s run a small program.

• Create a file called helloworld.dart that contains this code:

void main() {
  print('Hello, World!');
}

• In the directory that contains the file you just created, run the program:

$ dart helloworld.dart
Hello, World!

The Dart VM supports many options.Use dart —help to see commonly used options.Use dart —verbose to see all options.

Overview of the dcat app code

This tutorial covers the details of a small sample app called dcat, whichdisplays the contents of any files listed on the command line. This app usesvarious classes, functions, and properties available to command-line apps. For abrief description of key app features, click the highlighted code below.

import 'dart:convert';
import 'dart:io';
 
import 'package:args/args.dart';
 
const lineNumber = 'line-number';
 
ArgResults argResults;
 
void main(List<String> arguments) {
  exitCode = 0; // presume success
  final parser = ArgParser()
    ..addFlag(lineNumber, negatable: false, abbr: 'n');
 
  argResults = parser.parse(arguments);
  final paths = argResults.rest;
 
  dcat(paths, argResults[lineNumber] as bool);
}
 
Future dcat(List<String> paths, bool showLineNumbers) async {
  if (paths.isEmpty) {
    // No files provided as arguments. Read from stdin and print each line.
    await stdin.pipe(stdout);
  } else {
    for (var path in paths) {
      var lineNumber = 1;
      final lines = utf8.decoder
          .bind(File(path).openRead())
          .transform(const LineSplitter());
      try {
        await for (var line in lines) {
          if (showLineNumbers) {
            stdout.write('${lineNumber++} ');
          }
          stdout.writeln(line);
        }
      } catch (_) {
        await _handleError(path);
      }
    }
  }
}
 
Future _handleError(String path) async {
  if (await FileSystemEntity.isDirectory(path)) {
    stderr.writeln('error: $path is a directory');
  } else {
    exitCode = 2;
  }
}

Getting dependencies

You might notice that dcat depends on a package named args.To get the args package, use thepub package manager.

A real app has tests, license files, and so on, in a file hierarchysuch as the one in the Dart command-line app template.But for this first app, let’s do the minimum necessary to get the code to run:

• Create a directory named dcat, and change to that directory.
• Inside dcat, create a file named dcat.dartand copy the preceding code into it.
• Inside dcat, create a file named pubspec.yamlwith the following code:

name: dcat
environment:
  sdk: '>=2.6.0 <3.0.0'
dependencies:
  args: ^1.5.0

• Still in the dcat directory, run pub get to get the args package:

$ pub get
Resolving dependencies... 
+ args 1.5.2
Changed 1 dependency!

Note: To learn more about using packages and organizing your code, see the package documentation and layout conventions.

Running dcat

Once you have your app’s dependencies,you can run the app from the command line over any text file,like pubspec.yaml or quote.txt(downloadable file):

$ dart dcat.dart -n quote.txt
1 Be yourself. Everyone else is taken. -Oscar Wilde
2 Don't cry because it's over, smile because it happened. -Dr. Seuss
3 You only live once, but if you do it right, once is enough. -Mae West
...

This command displays each line of the specified file. Because the -n argumentis present, a line number is displayed before each line.

Parsing command-line arguments

The args package providesparser support for transforming command-line argumentsinto a set of options, flags, and additional values.Import the package’sargs libraryas follows:

import 'package:args/args.dart';

The args library contains these classes, among others:

Here is the dcat code that uses these classes to parse and store command-linearguments:

ArgResults argResults;
 
void main(List<String> arguments) {
  exitCode = 0; // presume success
  final parser = ArgParser()
    ..addFlag(lineNumber, negatable: false, abbr: 'n');
 
 
  argResults = parser.parse(arguments);
  final paths = argResults.rest;
 
  dcat(paths, argResults[lineNumber] as bool);
}

The runtime passes command-line arguments to the app’s main() function as alist of strings. The ArgParser is configured to parse the -n flag. Theresult of parsing command-line arguments is stored in argResults.

The following diagram shows how the dcat command line used aboveis parsed into an ArgResults object.

You can access flags and options by name,treating an ArgResults like a Map.You can access other values using the rest property.

The API referencefor the args library provides detailed information to help you usethe ArgParser and ArgResults classes.

Reading and writing with stdin, stdout, and stderr

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:

Import the dart:io library as follows:

import 'dart:io';

Note: Web apps (apps that depend on dart:html) can’t use the dart:io library.

stdout

Here’s the code from the dcat program that writes the line number tothe stdout (if the -n flag is set) followed by the line from the file.

if (showLineNumbers) {
  stdout.write('${lineNumber++} ');
}
stdout.writeln(line);

The write() and writeln() methods take an object of any type,convert it to a string, and print it. The writeln() methodalso prints a newline character.dcat uses the write() method to print the line number so theline 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.

stdout provides more functionality than the print() function.For example, you can display the contents of a stream with stdout.However, you must use print() instead of stdoutfor programs that are converted to and run in JavaScript.

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 separateand can be redirected or piped at the command lineor programmatically to different destinations.

This code from dcat prints an error message if the usertries to list a directory.

if (await FileSystemEntity.isDirectory(path)) {
  stderr.writeln('error: $path is a directory');
} else {
  exitCode = 2;
}

stdin

The standard input stream typicallyreads data synchronously from the keyboard,although it can read asynchronouslyand it can get input piped in from the standardoutput of another program.

Here’s a small program that reads a single line from stdin:

import 'dart:io';
void main() {
  stdout.writeln('Type something');
  String input = stdin.readLineSync();
  stdout.writeln('You typed: $input');
}

The readLineSync() method reads text from the standard input stream,blocking until the user types in text and presses return.This little program prints out the typed text.

In the dcat program,if the user does not provide a filename on the command line,the program instead reads from stdinusing the pipe() method.Because pipe() is asynchronous(returning a future, even though this code doesn’t use that return value),the code that calls it uses await.

await stdin.pipe(stdout);

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 pressing Control+D.

$ dart dcat.dart
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.

Getting info about a file

TheFileSystemEntityclass in the dart:io library provides properties and static methodsthat 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 foundby using the type() method from the FileSystemEntity class.Because the type() method accesses the file system,it performs the check asynchronously.

The following code from the dcat example uses FileSystemEntityto determine if the path provided on the command line is a directory.The future returns a boolean that indicates if the path is a directory or not.Because the check is asynchronous, the code calls isDirectory()using await.

if (await FileSystemEntity.isDirectory(path)) {
  stderr.writeln('error: $path is a directory');
} else {
  exitCode = 2;
}

Other interesting methods in the FileSystemEntity classinclude isFile(), exists(), stat(), delete(),and rename(), all of which also use a future to return a value.

FileSystemEntity is the superclass for the File, Directory, and Link classes.

Reading a file

dcat opens each file listed on the command linewith the openRead() method, which returns a stream.The await for block waits for the file to be readasynchronously. The data prints to stdout when itbecomes available on the stream.

for (var path in paths) {
  var lineNumber = 1;
  final lines = utf8.decoder
      .bind(File(path).openRead())
      .transform(const LineSplitter());
  try {
    await for (var line in lines) {
      if (showLineNumbers) {
        stdout.write('${lineNumber++} ');
      }
      stdout.writeln(line);
    }
  } catch (_) {
    await _handleError(path);
  }
}

The following shows the rest of the code, which uses two decoders thattransform the data before making it available in the await for block.The UTF8 decoder converts the data into Dart strings.LineSplitter splits the data at newlines.

for (var path in paths) {
  var lineNumber = 1;
  final lines = utf8.decoder
      .bind(File(path).openRead())
      .transform(const LineSplitter());
  try {
    await for (var line in lines) {
      if (showLineNumbers) {
        stdout.write('${lineNumber++} ');
      }
      stdout.writeln(line);
    }
  } catch (_) {
    await _handleError(path);
  }
}

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:

import 'dart:convert';

Writing a file

The easiest way to write text to a file is to create aFileobject and use the writeAsString() method:

final quotes = File('quotes.txt');
const stronger = 'That which does not kill us makes us stronger. -Nietzsche';
await quotes.writeAsString(stronger, mode: FileMode.append);

The writeAsString() method writes the data asynchronously.It opens the file before writing and closes the file when done.To append data to an existing file, you can use the optionalparameter mode and set its value to FileMode.append.Otherwise, the mode is FileMode.write and the previous contents of the file,if any, are overwritten.

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,at which time, you must close the file.The close() method is asynchronous and returns a future.

final quotes = File('quotes.txt').openWrite(mode: FileMode.append);
quotes.write("Don't cry because it's over, ");
quotes.writeln("smile because it happened. -Dr. Seuss");
await quotes.close();

Getting environment information

Use the Platform classto get information about the machine and OS that the program is running on.

Platform.environmentprovides a copy of the environmentvariables in an immutable map. If you need a mutable map (modifiable copy) youcan use Map.from(Platform.environment).

final envVarMap = Platform.environment;
print('PWD = ${envVarMap["PWD"]}');
print('LOGNAME = ${envVarMap["LOGNAME"]}');
print('PATH = ${envVarMap["PATH"]}');

Platform provides other useful properties that giveinformation about the machine, OS, and currentlyrunning program. For example:

• Platform.isMacOS()
• Platform.numberOfProcessors
• Platform.script

Setting exit codes

The dart:io library defines a top-level property,exitCode, that you can change to set the exit code forthe current invocation of the Dart VM.An exit code is a number passed fromthe Dart program to the parent processto indicate the success, failure, or other state of theexecution of the program.

The dcat program sets the exit codein the _handleError() function to indicate that an errorocccurred during execution.

Future _handleError(String path) async {
  if (await FileSystemEntity.isDirectory(path)) {
    stderr.writeln('error: $path is a directory');
  } else {
    exitCode = 2;
  }
}

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 call exit(2)instead of setting exitCode to 2,but exit() would quit the programand it might not process all of the files on the command line.

Generally speaking, you’re 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,by convention, the codes in the table below have the following meanings:

Summary

This tutorial described some basic API found in these classes from the dart:io library:

In addition, this tutorial covers two classes that help with command-line arguments:ArgParser andArgResults.

For more classes, functions, and properties,consult to the API reference fordart:io,dart:convert,and the args package.

What next?

If you’re interested in server-side programming,check out the next tutorial, which coversHTTP clients and servers.

• ⟨ Get started: command-line & server apps
• Write HTTP clients & servers ⟩