build_cli 1.0.0

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 65

Build Status

Parse command line arguments directly into an annotation class using the Dart Build System.

Example

Annotate a class with @CliOptions() from package:build_cli_annotations.

import 'package:build_cli_annotations/build_cli_annotations.dart';

part 'example.g.dart';

@CliOptions()
class Options {
  @CliOption(abbr: 'n', help: 'Required. The name to use in the greeting.')
  final String name;

  final bool nameWasParsed;

  bool yell;

  @CliOption(defaultsTo: Language.en, abbr: 'l')
  Language displayLanguage;

  @CliOption(negatable: false, help: 'Prints usage information.')
  bool help;

  Options(this.name, {this.nameWasParsed});
}

enum Language { en, es }

Configure and run the Dart Build System and a set of helpers is created to parse the corresponding command line arguments and populate your class.

void main(List<String> args) {
  var options = parseOptions(args);
  if (!options.nameWasParsed) {
    throw new ArgumentError('You must set `name`.');
  }
  print(options.name);
}

Setup

Add three packages to pubspec.yaml:

dependencies:
  build_cli_annotations: ^0.1.0

dev_dependencies:
  build_cli: ^0.2.0
  build_runner: '>=0.7.10 <0.9.0'
  • build_cli_annotations is a separate package containing the annotations you add to classes and members to tell build_cli what to do.
    • If the code you're annotating is in a published directory – lib, bin – put it in the dependencies section.
  • build_cli contains the logic to generate the code.
    • It should almost always be put in dev_dependencies.
  • build_runner contains the logic to run a build and generate code.
    • It should almost always be put in dev_dependencies.

Details

Uses package:args under the covers.

More examples:

1.0.0

  • Support package:build_cli_annotations v1.

0.2.6

  • Helper methods that were previously generated inline within functions are now generated as top-level functions and shared.

0.2.5

  • Require package:source_gen ^0.9.0.

  • The header configuration option is no longer supported. (It's ignored.)

0.2.4+1

  • Support Dart 2 stable.

0.2.4

  • Support the latest version of package:build_config.

0.2.3

  • Require the latest package:analyzer.
  • Support convert functions with optional parameters.

0.2.2

  • Added support for populating ArgResults command if the field is not annotated.
  • Improved error output, including in cases where a bug may be found.

0.2.1

  • Added support for covert to CliOption.
  • Throw many more errors during build that would create invalid code at runtime.

0.2.0

  • Fail unless the minimum SDK constraint on the target package is at least 2.0.0-dev.48.

  • Added for support valueHelp to CliOption.

0.1.2

  • Support int, double, and num for options.
  • Improve error messages for some failures.
  • Support defaultsTo for flags.
  • Generate another private method _$populate[OptionClassName]Parser. Allows usage for already existing ArgParser instances, such as with package:args CommandRunner.

0.1.1+1

  • Fix link to package:peanut usage example.

0.1.1

  • Add setup instructions to README.md.
  • Use the logger built into pkg:build.
  • Don't generate CLI entries for unassignable fields.
  • Support latest pkg:source_gen.
  • Properly escape String literals.

0.1.0

  • First release

example/example.dart

import 'dart:io';

import 'package:io/ansi.dart';
import 'package:io/io.dart';

import 'package:build_cli_annotations/build_cli_annotations.dart';

part 'example.g.dart';

/// Annotation your option class with [CliOptions].
@CliOptions()
class Options {
  /// Customize options and flags by annotating fields with [CliOption].
  @CliOption(abbr: 'n', help: 'Required. The name to use in the greeting.')
  final String name;

  /// Name a field `[name]WasParsed` without a [CliOption] annotation and it
  /// will be populated with `ArgResult.wasParsed('name')`.
  final bool nameWasParsed;

  /// [bool] fields are turned into flags.
  ///
  /// Fields without the [CliOption] annotation are picked up with simple
  /// defaults.
  bool yell;

  /// Field names are also "kebab cased" automatically.
  ///
  /// This becomes `--display-language`.
  @CliOption(defaultsTo: Language.en, abbr: 'l')
  Language displayLanguage;

  @CliOption(negatable: false, help: 'Prints usage information.')
  bool help;

  /// Populates final fields as long as there are matching constructor
  /// parameters.
  Options(this.name, {this.nameWasParsed});
}

/// Enums are a great way to specify options with a fixed set of allowed
/// values.
enum Language { en, es }

void main(List<String> args) {
  Options options;
  try {
    options = parseOptions(args);
    if (!options.nameWasParsed) {
      throw new FormatException('You must provide a name.');
    }
  } on FormatException catch (e) {
    print(red.wrap(e.message));
    print('');
    _printUsage();
    exitCode = ExitCode.usage.code;
    return;
  }

  if (options.help) {
    _printUsage();
    return;
  }

  var buffer = new StringBuffer();

  switch (options.displayLanguage) {
    case Language.en:
      buffer.write('Hello, ');
      break;
    case Language.es:
      buffer.write('¡Hola, ');
      break;
  }

  buffer.write(options.name);
  buffer.write('!');

  if (options.yell) {
    print(buffer.toString().toUpperCase());
  } else {
    print(buffer);
  }
}

void _printUsage() {
  print('Usage: example/example.dart [arguments]');
  print(_$parserForOptions.usage);
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  build_cli: ^1.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:build_cli/build_cli.dart';
  
Version Uploaded Documentation Archive
1.0.0 Aug 3, 2018 Go to the documentation of build_cli 1.0.0 Download build_cli 1.0.0 archive
0.2.5 Jul 25, 2018 Go to the documentation of build_cli 0.2.5 Download build_cli 0.2.5 archive
0.2.4+1 Jul 23, 2018 Go to the documentation of build_cli 0.2.4+1 Download build_cli 0.2.4+1 archive
0.2.4 Jun 21, 2018 Go to the documentation of build_cli 0.2.4 Download build_cli 0.2.4 archive
0.2.3 May 15, 2018 Go to the documentation of build_cli 0.2.3 Download build_cli 0.2.3 archive
0.2.2 Apr 21, 2018 Go to the documentation of build_cli 0.2.2 Download build_cli 0.2.2 archive
0.2.1 Apr 19, 2018 Go to the documentation of build_cli 0.2.1 Download build_cli 0.2.1 archive
0.2.0 Apr 17, 2018 Go to the documentation of build_cli 0.2.0 Download build_cli 0.2.0 archive
0.1.2 Apr 13, 2018 Go to the documentation of build_cli 0.1.2 Download build_cli 0.1.2 archive
0.1.1+1 Apr 6, 2018 Go to the documentation of build_cli 0.1.1+1 Download build_cli 0.1.1+1 archive

All 12 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
31
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
65
Learn more about scoring.

We analyzed this package on Aug 10, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0
  • pana: 0.11.8

Platforms

Detected platforms: other

Primary library: package:build_cli/build_cli.dart with components: io, isolate, build, mirrors.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.48 <3.0.0
analyzer ^0.32.0 0.32.4
build >=0.9.0 <0.13.0 0.12.7+3
build_cli_annotations >=0.1.2 <1.1.0 1.0.0
build_config >=0.2.6 <0.4.0 0.3.1+2
meta ^1.1.0 1.1.6
pub_semver ^1.3.0 1.4.2
source_gen ^0.9.0 0.9.0+1
yaml ^2.1.0 2.1.15
Transitive dependencies
async 2.0.8
charcode 1.1.2
collection 1.14.11
convert 2.0.2
crypto 2.0.6
csslib 0.14.4+1
front_end 0.1.4
glob 1.1.7
html 0.13.3+2
json_annotation 1.1.0
kernel 0.3.4
logging 0.11.3+2
package_config 1.0.5
plugin 0.2.0+3
pubspec_parse 0.1.2+2
source_span 1.4.1
string_scanner 1.0.3
typed_data 1.1.6
utf 0.9.0+5
watcher 0.9.7+10
Dev dependencies
args ^1.5.0 1.5.0
build_runner ^0.10.0
dart_style any 1.1.3
io ^0.3.2
path ^1.5.1 1.6.2
test ^1.0.0