build_cli 0.2.3

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

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.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: "^0.2.3"

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
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
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 Jun 19, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.63.0
  • pana: 0.11.3

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
8 / 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]
54
Learn more about scoring.

Platforms

Detected platforms: other

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

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.32.0 0.32.1
build >=0.9.0 <0.13.0 0.12.6
build_cli_annotations >=0.1.2 <0.1.3 0.1.2
build_config ^0.2.6 0.2.6+2 0.3.0
meta ^1.1.0 1.1.5
pub_semver ^1.3.0 1.4.1
source_gen >=0.8.1 <0.9.0 0.8.2
yaml ^2.1.0 2.1.14
Transitive dependencies
args 1.4.3
async 2.0.7
charcode 1.1.1
collection 1.14.10
convert 2.0.1
crypto 2.0.5
csslib 0.14.4
front_end 0.1.1
glob 1.1.5
html 0.13.3+1
kernel 0.3.1
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+8
Dev dependencies
build_runner ^0.8.2
dart_style 1.1.0
io ^0.3.2
path ^1.5.1 1.6.1
test ^0.12.0