Skip to content

Commit

Permalink
feat(app): add support for building args from usage strings
Browse files Browse the repository at this point in the history
  • Loading branch information
kbknapp committed Apr 13, 2015
1 parent ab409a8 commit d5d48bc
Show file tree
Hide file tree
Showing 2 changed files with 82 additions and 0 deletions.
37 changes: 37 additions & 0 deletions src/app.rs
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,43 @@ impl<'a, 'v, 'ab, 'u, 'ar> App<'a, 'v, 'ab, 'u, 'ar>{
self
}

/// Adds an argument from a usage string. See Arg::from_usage() for details
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let app = App::new("myprog")
/// .arg_from_usage("-c --conf=<config> 'Sets a configuration file to use'")
/// # .get_matches();
/// ```
pub fn arg_from_usage(mut self, usage: &'ar str) -> App<'a, 'v, 'ab, 'u, 'ar> {
self = self.arg(Arg::from_usage(usage));
self
}

/// Adds multiple arguments from a usage string, one per line. See Arg::from_usage() for
/// details
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let app = App::new("myprog")
/// .args_from_usage(
/// "-c --conf=[config] 'Sets a configuration file to use'
/// [debug]... -d 'Sets the debugging level'
/// <input> 'The input file to use'")
/// # .get_matches();
/// ```
pub fn args_from_usage(mut self, usage: &'ar str) -> App<'a, 'v, 'ab, 'u, 'ar> {
for l in usage.lines() {
self = self.arg(Arg::from_usage(l));
}
self
}


/// Adds a subcommand to the list of valid possibilties. Subcommands are effectively sub apps,
/// because they can contain their own arguments, subcommands, version, usage, etc. They also
/// function just like apps, in that they get their own auto generated help and version
Expand Down
45 changes: 45 additions & 0 deletions src/args/arg.rs
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,51 @@ impl<'n, 'l, 'h, 'b, 'p, 'r> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
}
}

/// Creates a new instace of `Arg` using a usage string. Allows creation of basic settings
/// for Arg (i.e. everything except relational rules). The syntax is flexible, but there are
/// some rules to follow.
///
/// The syntax should be as follows (only properties which you wish to set must be present):
///
/// 1. Name (arguments with a `long` or that take a value can ommit this if desired),
/// use `[]` for non-required arguments, or `<>` for required arguments.
/// 2. Short preceded by a `-`
/// 3. Long preceded by a `--` (this may be used as the name, if the name is omitted. If the
/// name is *not* omittied, the name takes precedence)
/// 4. Value (this can be used as the name, if the name is not manually specified. If the name
/// is manually specified, it takes precence. If this value is used as the name, it uses the
/// same `[]` and `<>` requirement rules. If it is *not* used as the name, it still needs to
/// be surrounded by either `[]` or `<>` but the effect is the same, as the requirement rule
/// is determined by the name. The value may follow the `short` or `long`. If it
/// follows the `long`, it may follow either a `=` or ` ` with the same effect, personal
/// preference only, but may only follow a ` ` after a `short`)
/// 5. Multiple specifier `...` (for flags or positional arguments the `...` may follow the
/// name or `short` or `long`)
/// 6. The help info surrounded by `'`
/// 7. The index of a positional argument will be the next available index (you don't need to
/// specify one)
///
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// .args(vec![
/// // A option argument with a long, named "conf" (note: because the name was specified
/// // the portion after the long can be called anything, only the first name will be displayed
/// // to the user. Also, requirement is set with the *name*, so the portion after the long could
/// // be either <> or [] and it wouldn't matter, so long as it's one of them. Had the name been
/// // omitted, the name would have been derived from the portion after the long and those rules
/// // would have mattered)
/// Arg::from_usage("[conf] --config=[c] 'a required file for the configuration'"),
/// // A flag with a short, a long, named "debug", and accepts multiple values
/// Arg::from_usage("-d --debug... 'turns on debugging information"),
/// // A required positional argument named "input"
/// Arg::from_usage("<input> 'the input file to use'")
/// ])
/// # .short("c")
/// # ).get_matches();
pub fn from_usage(u: &'n str) -> Arg<'n, 'n, 'n, 'b, 'p, 'r> {
assert!(u.len() > 0, "Arg::from_usage() requires a non-zero-length usage string but none was provided");

Expand Down

0 comments on commit d5d48bc

Please sign in to comment.