unscripted 0.3.4 unscripted: ^0.3.4 copied to clipboard
Declarative command-line interface programming.
unscripted #
Unscripted is a pub package for declarative command-line interface
programming in dart. Command-line interfaces are defined using ordinary method
and class declarations, minimally annotated with command-line metadata.
Reflection is used to derive the command-line interface from the declarations.
Command-line arguments are automatically injected into the method or
class (constructor). This removes the need for boilerplate logic to define,
parse, validate and assign variables for command-line arguments. Since the
interface is defined in code, standard refactoring, testing, etc. tools can
be used.
##Demo
cat.dart is a complete implementation of the *nix cat
utility using unscripted.
##Usage
(For more detailed usage, see the API docs)
A simple script to output a greeting:
import 'package:unscripted/unscripted.dart';
main(arguments) => declare(greet).execute(arguments);
@Command(help: 'Outputs a greeting')
@ArgExample('--salutation Welcome --exclaim Bob', help: 'enthusiastic')
greet(
@Rest(help: "Name(s) to greet")
List<String> who, // A rest parameter, must be last positional.
{String salutation : 'Hello', // An option, use `@Option(...)` for metadata.
bool exclaim : false}) { // A flag, use `@Flag(...)` for metadata.
print('$salutation ${who.join(' ')}${exclaim ? '!' : ''}');
}
(Compare to a traditiional version of this script.)
We can call this script as follows:
$ dart greet.dart Bob
Hello Bob
$ dart greet.dart --salutation Welcome --exclaim Bob
Welcome Bob!
###Automatic --help
Unscripted automatically defines and handles a --help/-h option, allowing for:
$ dart greet.dart --help
Outputs a greeting
Usage:
dart greet.dart [options] WHO...
Options:
-h, --help Print this usage information.
--salutation (defaults to "Hello")
--[no-]exclaim
Examples:
dart greet.dart --salutation Welcome --exclaim Bob # enthusiastic
###Sub-Commands
Sub-commands are also supported. In this case the script is defined as a class, whose instance methods can be annotated as sub-commands. Assume we have the following 'server.dart':
import 'package:unscripted/unscripted.dart';
main(arguments) => declare(Server).execute(arguments);
class Server {
final String configPath;
@Command(help: 'Manages a server')
Server({this.configPath: 'config.xml'});
@SubCommand(help: 'Start the server')
start({bool clean}) {
print('''
Starting the server.
Config path: $configPath''');
}
@SubCommand(help: 'Stop the server')
stop() {
print('Stopping the server.');
}
}
We can call this script as follows:
$ dart server.dart start --config-path my-config.xml --clean
Starting the server.
Config path: my-config.xml
A 'help' sub-command is also added, which can be used as a synonym for '--help', which outputs all the basic help info plus a list of available commands:
$ dart server.dart help
Available commands:
start
help
stop
Use "dart server.dart help [command]" for more information about a command.
and as indicated there, sub-command help is also available:
$ dart server.dart help stop
Stop the server
Usage:
dart server.dart stop [options]
Options:
-h, --help Print this usage information.