{"id":27842571,"url":"https://github.com/dart-lang/args","last_synced_at":"2025-05-03T06:01:13.188Z","repository":{"id":24832764,"uuid":"28247433","full_name":"dart-archive/args","owner":"dart-archive","description":"A command-line argument parsing library for Dart.","archived":true,"fork":false,"pushed_at":"2024-10-16T06:56:07.000Z","size":521,"stargazers_count":216,"open_issues_count":0,"forks_count":61,"subscribers_count":39,"default_branch":"main","last_synced_at":"2025-04-28T16:02:14.787Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/args","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dart-archive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-19T21:42:56.000Z","updated_at":"2025-03-30T13:32:43.000Z","dependencies_parsed_at":"2023-01-14T01:41:22.857Z","dependency_job_id":"e6bdbd1d-d88b-455e-bba3-36a802f3d28a","html_url":"https://github.com/dart-archive/args","commit_stats":{"total_commits":258,"total_committers":62,"mean_commits":4.161290322580645,"dds":0.8178294573643411,"last_synced_commit":"7a2dfb528768f0a2e5680f711dbfb948f1d6c255"},"previous_names":["dart-archive/args","dart-lang/args"],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fargs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fargs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fargs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fargs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dart-archive","download_url":"https://codeload.github.com/dart-archive/args/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252149191,"owners_count":21702083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-03T06:00:37.331Z","updated_at":"2025-05-03T06:01:13.172Z","avatar_url":"https://github.com/dart-archive.png","language":"Dart","funding_links":[],"categories":["[Dart](https://dart.dev/)","Libraries"],"sub_categories":["Parsers"],"readme":"\u003e [!IMPORTANT]  \n\u003e This repo has moved to https://github.com/dart-lang/core/tree/main/pkgs/args\n\n[![Dart CI](https://github.com/dart-lang/args/actions/workflows/test-package.yml/badge.svg)](https://github.com/dart-lang/args/actions/workflows/test-package.yml)\n[![pub package](https://img.shields.io/pub/v/args.svg)](https://pub.dev/packages/args)\n[![package publisher](https://img.shields.io/pub/publisher/args.svg)](https://pub.dev/packages/args/publisher)\n\nParses raw command-line arguments into a set of options and values.\n\nThis library supports [GNU][] and [POSIX][] style options, and it works in both\nserver-side and client-side apps.\n\n## Defining options\n\nFirst create an [ArgParser][]:\n\n    var parser = ArgParser();\n\nThen define a set of options on that parser using [addOption()][addOption] and\n[addFlag()][addFlag]. Here's the minimal way to create an option named \"name\":\n\n    parser.addOption('name');\n\nWhen an option can only be set or unset (as opposed to taking a string value),\nuse a flag:\n\n```dart\nparser.addFlag('name');\n```\n\nFlag options, by default, accept a 'no-' prefix to negate the option. You can\ndisable the 'no-' prefix using the `negatable` parameter:\n\n```dart\nparser.addFlag('name', negatable: false);\n```\n\n*Note:* From here on out, \"option\" refers to both regular options and flags. In\ncases where the distinction matters, we'll use \"non-flag option.\"\n\nOptions can have an optional single-character abbreviation, specified with the\n`abbr` parameter:\n\n```dart\nparser.addOption('mode', abbr: 'm');\nparser.addFlag('verbose', abbr: 'v');\n```\n\nOptions can also have a default value, specified with the `defaultsTo`\nparameter. The default value is used when arguments don't specify the option.\n\n```dart\nparser.addOption('mode', defaultsTo: 'debug');\nparser.addFlag('verbose', defaultsTo: false);\n```\n\nThe default value for non-flag options can be any string. For flags, it must\nbe a `bool`.\n\nTo validate a non-flag option, you can use the `allowed` parameter to provide an\nallowed set of values. When you do, the parser throws an\n[`ArgParserException`][ArgParserException] if the value for an option is not in\nthe allowed set. Here's an example of specifying allowed values:\n\n```dart\nparser.addOption('mode', allowed: ['debug', 'release']);\n```\n\nYou can use the `callback` parameter to associate a function with an option.\nLater, when parsing occurs, the callback function is invoked with the value of\nthe option:\n\n```dart\nparser.addOption('mode', callback: (mode) =\u003e print('Got mode $mode'));\nparser.addFlag('verbose', callback: (verbose) {\n  if (verbose) print('Verbose');\n});\n```\n\nThe callbacks for all options are called whenever a set of arguments is parsed.\nIf an option isn't provided in the args, its callback is passed the default\nvalue, or `null` if no default value is set.\n\nIf an option is `mandatory` but not provided, the results object throws an\n[`ArgumentError`][ArgumentError] on retrieval.\n\n```dart\nparser.addOption('mode', mandatory: true);\n```\n\n## Parsing arguments\n\nOnce you have an [ArgParser][] set up with some options and flags, you use it by\ncalling [ArgParser.parse()][parse] with a set of arguments:\n\n```dart\nvar results = parser.parse(['some', 'command', 'line', 'args']);\n```\n\nThese arguments usually come from the arguments to `main()`. For example:\n\n    main(List\u003cString\u003e args) {\n      // ...\n      var results = parser.parse(args);\n    }\n\nHowever, you can pass in any list of strings. The `parse()` method returns an\ninstance of [ArgResults][], a map-like object that contains the values of the\nparsed options.\n\n```dart\nvar parser = ArgParser();\nparser.addOption('mode');\nparser.addFlag('verbose', defaultsTo: true);\nvar results = parser.parse(['--mode', 'debug', 'something', 'else']);\n\nprint(results.option('mode')); // debug\nprint(results.flag('verbose')); // true\n```\n\nBy default, the `parse()` method allows additional flags and options to be\npassed after positional parameters unless `--` is used to indicate that all\nfurther parameters will be positional. The positional arguments go into\n[ArgResults.rest][rest].\n\n```dart\nprint(results.rest); // ['something', 'else']\n```\n\nTo stop parsing options as soon as a positional argument is found,\n`allowTrailingOptions: false` when creating the [ArgParser][].\n\n## Specifying options\n\nTo actually pass in options and flags on the command line, use GNU or POSIX\nstyle. Consider this option:\n\n```dart\nparser.addOption('name', abbr: 'n');\n```\n\nYou can specify its value on the command line using any of the following:\n\n```\n--name=somevalue\n--name somevalue\n-nsomevalue\n-n somevalue\n```\n\nConsider this flag:\n\n```dart\nparser.addFlag('name', abbr: 'n');\n```\n\nYou can set it to true using one of the following:\n\n```\n--name\n-n\n```\n\nYou can set it to false using the following:\n\n```\n--no-name\n```\n\nMultiple flag abbreviations can be collapsed into a single argument. Say you\ndefine these flags:\n\n```dart\nparser\n  ..addFlag('verbose', abbr: 'v')\n  ..addFlag('french', abbr: 'f')\n  ..addFlag('iambic-pentameter', abbr: 'i');\n```\n\nYou can set all three flags at once:\n\n```\n-vfi\n```\n\nBy default, an option has only a single value, with later option values\noverriding earlier ones; for example:\n\n```dart\nvar parser = ArgParser();\nparser.addOption('mode');\nvar results = parser.parse(['--mode', 'on', '--mode', 'off']);\nprint(results.option('mode')); // prints 'off'\n```\n\nMultiple values can be parsed with `addMultiOption()`. With this method, an\noption can occur multiple times, and the `parse()` method returns a list of\nvalues:\n\n```dart\nvar parser = ArgParser();\nparser.addMultiOption('mode');\nvar results = parser.parse(['--mode', 'on', '--mode', 'off']);\nprint(results.multiOption('mode')); // prints '[on, off]'\n```\n\nBy default, values for a multi-valued option may also be separated with commas:\n\n```dart\nvar parser = ArgParser();\nparser.addMultiOption('mode');\nvar results = parser.parse(['--mode', 'on,off']);\nprint(results.multiOption('mode')); // prints '[on, off]'\n```\n\nThis can be disabled by passing `splitCommas: false`.\n\n## Defining commands\n\nIn addition to *options*, you can also define *commands*. A command is a named\nargument that has its own set of options. For example, consider this shell\ncommand:\n\n```\n$ git commit -a\n```\n\nThe executable is `git`, the command is `commit`, and the `-a` option is an\noption passed to the command. You can add a command using the [addCommand][]\nmethod:\n\n```dart\nvar parser = ArgParser();\nvar command = parser.addCommand('commit');\n```\n\nIt returns another [ArgParser][], which you can then use to define options\nspecific to that command. If you already have an [ArgParser][] for the command's\noptions, you can pass it in:\n\n```dart\nvar parser = ArgParser();\nvar command = ArgParser();\nparser.addCommand('commit', command);\n```\n\nThe [ArgParser][] for a command can then define options or flags:\n\n```dart\ncommand.addFlag('all', abbr: 'a');\n```\n\nYou can add multiple commands to the same parser so that a user can select one\nfrom a range of possible commands. When parsing an argument list, you can then\ndetermine which command was entered and what options were provided for it.\n\n```dart\nvar results = parser.parse(['commit', '-a']);\nprint(results.command.name);   // \"commit\"\nprint(results.command['all']); // true\n```\n\nOptions for a command must appear after the command in the argument list. For\nexample, given the above parser, `\"git -a commit\"` is *not* valid. The parser\ntries to find the right-most command that accepts an option. For example:\n\n```dart\nvar parser = ArgParser();\nparser.addFlag('all', abbr: 'a');\nvar command = parser.addCommand('commit');\ncommand.addFlag('all', abbr: 'a');\n\nvar results = parser.parse(['commit', '-a']);\nprint(results.command['all']); // true\n```\n\nHere, both the top-level parser and the `\"commit\"` command can accept a `\"-a\"`\n(which is probably a bad command line interface, admittedly). In that case, when\n`\"-a\"` appears after `\"commit\"`, it is applied to that command. If it appears to\nthe left of `\"commit\"`, it is given to the top-level parser.\n\n## Dispatching Commands\n\nIf you're writing a command-based application, you can use the [CommandRunner][]\nand [Command][] classes to help structure it. [CommandRunner][] has built-in\nsupport for dispatching to [Command][]s based on command-line arguments, as well\nas handling `--help` flags and invalid arguments.\n\nWhen using the [CommandRunner][] it replaces the [ArgParser][].\n\nIn the following example we build a dart application called `dgit` that takes commands `commit` and `stash`.\n\nThe [CommandRunner][] takes an `executableName` which is used to generate the help message.\n\ne.g.\n`dgit commit -a`\n\nFile `dgit.dart`\n\n```dart\nvoid main(List\u003cString\u003e args) {\n  var runner = CommandRunner(\"dgit\", \"A dart implementation of distributed version control.\")\n    ..addCommand(CommitCommand())\n    ..addCommand(StashCommand())\n    ..run(args);\n}\n```\n\nWhen the above `run(args)` line executes it parses the command line args looking for one of the commands (`commit` or `stash`).\n\nIf the [CommandRunner][] finds a matching command then the [CommandRunner][] calls the overridden `run()` method on the matching command (e.g. CommitCommand().run).\n\nCommands are defined by extending the [Command][] class. For example:\n\n```dart\nclass CommitCommand extends Command {\n  // The [name] and [description] properties must be defined by every\n  // subclass.\n  final name = \"commit\";\n  final description = \"Record changes to the repository.\";\n\n  CommitCommand() {\n    // we can add command specific arguments here.\n    // [argParser] is automatically created by the parent class.\n    argParser.addFlag('all', abbr: 'a');\n  }\n\n  // [run] may also return a Future.\n  void run() {\n    // [argResults] is set before [run()] is called and contains the flags/options\n    // passed to this command.\n    print(argResults.flag('all'));\n  }\n}\n```\n\n### CommandRunner Arguments\nThe [CommandRunner][] allows you to specify both global args as well as command specific arguments (and even sub-command specific arguments).\n\n#### Global Arguments\nAdd argments directly to the [CommandRunner] to specify global arguments:\n\nAdding global arguments\n\n```dart\nvar runner = CommandRunner('dgit',  \"A dart implementation of distributed version control.\");\n// add global flag\nrunner.argParser.addFlag('verbose', abbr: 'v', help: 'increase logging');\n```\n\n#### Command specific Arguments\nAdd arguments to each [Command][] to specify [Command][] specific arguments.\n\n```dart\n  CommitCommand() {\n    // we can add command specific arguments here.\n    // [argParser] is automatically created by the parent class.\n    argParser.addFlag('all', abbr: 'a');\n  }\n```\n\n### SubCommands\n\nCommands can also have subcommands, which are added with [addSubcommand][]. A\ncommand with subcommands can't run its own code, so [run][] doesn't need to be\nimplemented. For example:\n\n```dart\nclass StashCommand extends Command {\n  final String name = \"stash\";\n  final String description = \"Stash changes in the working directory.\";\n\n  StashCommand() {\n    addSubcommand(StashSaveCommand());\n    addSubcommand(StashListCommand());\n  }\n}\n```\n\n### Default Help Command\n\n[CommandRunner][] automatically adds a `help` command that displays usage\ninformation for commands, as well as support for the `--help` flag for all\ncommands. If it encounters an error parsing the arguments or processing a\ncommand, it throws a [UsageException][]; your `main()` method should catch these and\nprint them appropriately. For example:\n\n```dart\nrunner.run(arguments).catchError((error) {\n  if (error is! UsageException) throw error;\n  print(error);\n  exit(64); // Exit code 64 indicates a usage error.\n});\n```\n\n## Displaying usage\n\nYou can automatically generate nice help text, suitable for use as the output of\n`--help`. To display good usage information, you should provide some help text\nwhen you create your options.\n\nTo define help text for an entire option, use the `help:` parameter:\n\n```dart\nparser.addOption('mode', help: 'The compiler configuration',\n    allowed: ['debug', 'release']);\nparser.addFlag('verbose', help: 'Show additional diagnostic info');\n```\n\nFor non-flag options, you can also provide a help string for the parameter:\n\n```dart\nparser.addOption('out', help: 'The output path', valueHelp: 'path',\n    allowed: ['debug', 'release']);\n```\n\nFor non-flag options, you can also provide detailed help for each expected value\nby using the `allowedHelp:` parameter:\n\n```dart\nparser.addOption('arch', help: 'The architecture to compile for',\n    allowedHelp: {\n      'ia32': 'Intel x86',\n      'arm': 'ARM Holding 32-bit chip'\n    });\n```\n\nTo display the help, use the [usage][usage] getter:\n\n```dart\nprint(parser.usage);\n```\n\nThe resulting string looks something like this:\n\n```\n--mode            The compiler configuration\n                  [debug, release]\n\n--out=\u003cpath\u003e      The output path\n--[no-]verbose    Show additional diagnostic info\n--arch            The architecture to compile for\n      [arm]       ARM Holding 32-bit chip\n      [ia32]      Intel x86\n```\n\n[posix]: https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_02\n[gnu]: https://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces\n[ArgParser]: https://pub.dev/documentation/args/latest/args/ArgParser/ArgParser.html\n[ArgParserException]: https://pub.dev/documentation/args/latest/args/ArgParserException-class.html\n[ArgResults]: https://pub.dev/documentation/args/latest/args/ArgResults-class.html\n[CommandRunner]: https://pub.dev/documentation/args/latest/command_runner/CommandRunner-class.html\n[Command]: https://pub.dev/documentation/args/latest/command_runner/Command-class.html\n[UsageException]: https://pub.dev/documentation/args/latest/command_runner/UsageException-class.html\n[addOption]: https://pub.dev/documentation/args/latest/args/ArgParser/addOption.html\n[addFlag]: https://pub.dev/documentation/args/latest/args/ArgParser/addFlag.html\n[parse]: https://pub.dev/documentation/args/latest/args/ArgParser/parse.html\n[rest]: https://pub.dev/documentation/args/latest/args/ArgResults/rest.html\n[addCommand]: https://pub.dev/documentation/args/latest/args/ArgParser/addCommand.html\n[usage]: https://pub.dev/documentation/args/latest/args/ArgParser/usage.html\n[addSubcommand]: https://pub.dev/documentation/args/latest/command_runner/Command/addSubcommand.html\n[run]: https://pub.dev/documentation/args/latest/command_runner/CommandRunner/run.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdart-lang%2Fargs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdart-lang%2Fargs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdart-lang%2Fargs/lists"}