build_cli 0.2.2

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

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:

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);
}

1. Depend on it

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


dependencies:
  build_cli: "^0.2.2"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages 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
0.2.2 Apr 21, 2018 failed Download build_cli 0.2.2 archive
0.2.1 Apr 19, 2018 failed Download build_cli 0.2.1 archive
0.2.0 Apr 17, 2018 failed 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
0.1.1 Apr 5, 2018 Go to the documentation of build_cli 0.1.1 Download build_cli 0.1.1 archive
0.1.0 Mar 29, 2018 Go to the documentation of build_cli 0.1.0 Download build_cli 0.1.0 archive

Analysis

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

  • Dart: 2.0.0-dev.49.0
  • pana: 0.10.6

Scores

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

Platforms

Detected platforms: Flutter, other

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

Suggestions

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.48 <2.0.0
analyzer >=0.29.10 <0.32.0 0.31.1 0.31.2-alpha.1
build >=0.9.0 <0.13.0 0.12.2
build_cli_annotations >=0.1.2 <0.1.3 0.1.2
build_config ^0.2.6 0.2.6+1
meta ^1.1.0 1.1.2
pub_semver ^1.3.0 1.3.7
source_gen >=0.8.1 <0.9.0 0.8.1
yaml ^2.1.0 2.1.13
Transitive dependencies
args 1.4.2
async 2.0.6
charcode 1.1.1
cli_util 0.1.2+1
collection 1.14.9
convert 2.0.1
crypto 2.0.2+1
csslib 0.14.1
front_end 0.1.0-alpha.9 0.1.0-alpha.11
glob 1.1.5
html 0.13.3
isolate 1.1.0 2.0.0
kernel 0.3.0-alpha.9 0.3.0-alpha.11
logging 0.11.3+1
package_config 1.0.3
plugin 0.2.0+2
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
utf 0.9.0+4
watcher 0.9.7+7
Dev dependencies
build_runner ^0.8.2
dart_style 1.0.9+1 1.0.10
io ^0.3.2
path ^1.5.1 1.5.1
test ^0.12.0