diff options
Diffstat (limited to 'argparse/README.rst')
| -rw-r--r-- | argparse/README.rst | 341 |
1 files changed, 0 insertions, 341 deletions
diff --git a/argparse/README.rst b/argparse/README.rst deleted file mode 100644 index 8a3fca0..0000000 --- a/argparse/README.rst +++ /dev/null @@ -1,341 +0,0 @@ -======== -Argparse -======== - -The ``rust-argparse`` is command-line parsing module for rust. It's inspired -by python's ``argparse`` module. - -Features: - -* Supports standard (GNU) option conventions -* Properly typed values -* Automatically generated help and usage messages - -Importing -========= -Edit your Cargo.toml to add ``rust-argparse`` to your project. - -.. code-block:: rust - - [dependencies] - argparse = "0.2.2" - - -Example -======= - -The following code is a simple Rust program with command-line arguments: - -.. code-block:: rust - - extern crate argparse; - - use argparse::{ArgumentParser, StoreTrue, Store}; - - fn main() { - let mut verbose = false; - let mut name = "World".to_string(); - { // this block limits scope of borrows by ap.refer() method - let mut ap = ArgumentParser::new(); - ap.set_description("Greet somebody."); - ap.refer(&mut verbose) - .add_option(&["-v", "--verbose"], StoreTrue, - "Be verbose"); - ap.refer(&mut name) - .add_option(&["--name"], Store, - "Name for the greeting"); - ap.parse_args_or_exit(); - } - - if verbose { - println!("name is {}", name); - } - println!("Hello {}!", name); - } - -Assuming the Rust code above is saved into a file ``greeting.rs``, let's see -what we have now:: - - $ rustc greeting.rs - $ ./greeting -h - Usage: - ./greeting [OPTIONS] - - Greet somebody. - - Optional arguments: - -h, --help Show this help message and exit - -v, --verbose - Be verbose - --name NAME Name for the greeting - $ ./greeting - Hello World! - $ ./greeting --name Bob - Hello Bob! - $ ./greeting -v --name Alice - name is Alice - Hello Alice! - - -Basic Workflow -============== - - -Create ArgumentParser ---------------------- - -The argument parser is created empty and is built incrementally. So we create -a mutable variable:: - - extern crate argparse; - use argparse::ArgumentParser; - - let mut parser = ArgumentParser::new(); - - -Customize ---------- - -There are optional customization methods. The most important one is:: - - parser.set_description("My command-line utility") - -The descripion is rewrapped to fit 80 column string nicely. Just like option -descriptions. - -Add Options ------------ - -The ``refer`` method creates a cell variable, which the result will be written -to:: - - let mut verbose = false; - parser.refer(&mut verbose); - -Next we add an options which control the variable: -For example:: - - parser.refer(&mut verbose) - .add_option(&["-v", "--verbose"], StoreTrue, - "Be verbose"); - -You may add multiple options for the same variable:: - - parser.refer(&mut verbose) - .add_option(&["-v", "--verbose"], StoreTrue, - "Be verbose") - .add_option(&["-q", "--quiet"], StoreFalse, - "Be verbose"); - -Similarly positional arguments are added:: - - let mut command = String; - parser.refer(&mut command) - .add_argument("command", Store, - "Command to run"); - - - -Organizing Options ------------------- - -It's often useful to organize options into some kind of structure. You can -easily borrow variables from the structure into option parser. For example:: - - struct Options { - verbose: bool, - } - ... - let mut options = Options { verbose: false }; - parser.refer(&mut options.verbose) - .add_option(&["-v"], StoreTrue, - "Be verbose"); - - -Parsing Arguments ------------------ - -All the complex work is done in ``parser.parse_args()``. But there is -a simpler option:: - - parser.parse_args_or_exit() - -In case you don't want argparse to exit itself, you might use the -``parse_args`` function directly:: - - use std::process::exit; - - match parser.parse_args() { - Ok(()) => {} - Err(x) => { - std::process::exit(x); - } - } - - -ArgumentParser Methods -====================== - -``parser.refer<T>(var: &mut T) -> Ref`` - Attach the variable to argument parser. The options are added to the - returned ``Ref`` object and modify a variable passed to the method. - -``parser.add_option(names: &[&str], action: TypedAction, help: &str)`` - Add a single option which has no parameters. Most options must be added - by ``refer(..)`` and methods on ``Ref`` object (see below). - - Example:: - - ap.add_option(&["-V", "--version"], - Print(env!("CARGO_PKG_VERSION").to_string()), "Show version"); - -``parser.set_description(descr: &str)`` - Set description that is at the top of help message. - -``parser.stop_on_first_argument(val: bool)`` - If called with ``true``, parser will stop searching for options when first - non-option (the one doesn't start with ``-``) argument is encountered. This - is useful if you want to parse following options with another argparser or - external program. - -``parser.silence_double_dash(val: bool)`` - If called with ``true`` (default), parser will not treat *first* double - dash ``--`` as positional argument. Use ``false`` if you need to add some - meaning to the ``--`` marker. - -``parser.print_usage(name: &str, writer: &mut Write)`` - Prints usage string to stderr. - -``parser.print_help(name: &str, writer: &mut Write)`` - Writes help to ``writer``, used by ``--help`` option internally. - -``parser.parse_args()`` - Method that does all the dirty work. And returns ``Result`` - -``parser.parse_args_or_exit()`` - Method that does all the dirty work. And in case of failure just ``exit()`` - - -Variable Reference Methods -========================== - -The ``argparse::Ref`` object is returned from ``parser.refer()``. -The following methods are used to add and customize arguments: - -``option.add_option(names: &[&str], action: TypedAction, help: &str)`` - Add an option. All items in names should be either in format ``-X`` or - ``--long-option`` (i.e. one dash and one char or two dashes and long name). - How this option will be interpreted and whether it will have an argument - dependes on the action. See below list of actions. - -``option.add_argument(name: &str, action: TypedAction, help: &str)`` - Add a positional argument - -``option.metavar(var: &str)`` - A name of the argument in usage messages (for options having argument). - -``option.envvar(var: &str)`` - A name of the environment variable to get option value from. The value - would be parsed with ``FromStr::from_str``, just like an option having - ``Store`` action. - -``option.required()`` - The option or argument is required (it's optional by default). If multiple - options or multiple arguments are defined for this reference at least one - of them is required. - - -Actions -======= - -The following actions are available out of the box. They may be used in either -``add_option`` or ``add_argument``: - -``Store`` - An option has single argument. Stores a value from command-line in a - variable. Any type that has the ``FromStr`` and ``Clone`` traits implemented - may be used. - -``StoreOption`` - As ``Store``, but wrap value with ``Some`` for use with ``Option``. For - example: - - let mut x: Option<i32> = None; - ap.refer(&mut x).add_option(&["-x"], StoreOption, "Set var x"); - -``StoreConst(value)`` - An option has no arguments. Store a hard-coded ``value`` into variable, - when specified. Any type with the ``Clone`` trait implemented may be used. - -``PushConst(value)`` - An option has no arguments. Push a hard-coded ``value`` into variable, - when specified. Any type which has the ``Clone`` type implemented may be - used. Option might used for a list of operations to perform, when ``required`` - is set for this variable, at least one operation is required. - -``StoreTrue`` - Stores boolean ``true`` value in a variable. - (shortcut for ``StoreConst(true)``) - -``StoreFalse`` - Stores boolean ``false`` value in a variable. - (shortcut for ``StoreConst(false)``) - - -``IncrBy(num)`` - An option has no arguments. Increments the value stored in a variable by a - value ``num``. Any type which has the ``Add`` and ``Clone`` traits may be used. - -``DecrBy(nym)`` - Decrements the value stored in a variable by a value ``num``. Any type - which has the ``Add`` and ``Clone`` traits may be used. - -``Collect`` - When used for an ``--option``, requires single argument. When used for a - positional argument consumes all remaining arguments. Parsed options are - added to the list. I.e. a ``Collect`` action requires a - ``Vec<int>`` variable. Parses arguments using ``FromStr`` trait. - -``List`` - When used for positional argument, works the same as ``List``. When used - as an option, consumes all remaining arguments. - - Note the usage of ``List`` is strongly discouraged, because of complex - rules below. Use ``Collect`` and positional options if possible. But usage - of ``List`` action may be useful if you need shell expansion of anything - other than last positional argument. - - Let's learn rules by example. For the next options:: - - ap.refer(&mut lst1).add_option(&["-X", "--xx"], List, "List1"); - ap.refer(&mut lst2).add_argument("yy", List, "List2"); - - The following command line:: - - ./run 1 2 3 -X 4 5 6 - - Will return ``[1, 2, 3]`` in the ``lst1`` and the ``[4,5,6]`` in the - ``lst2``. - - Note that using when using ``=`` or equivalent short option mode, the - 'consume all' mode is not enabled. I.e. in the following command-line:: - - ./run 1 2 -X3 4 --xx=5 6 - - The ``lst1`` has ``[3, 5]`` and ``lst2`` has ``[1, 2, 4, 6]``. - The argument consuming also stops on ``--`` or the next option:: - - ./run: -X 1 2 3 -- 4 5 6 - ./run: -X 1 2 --xx=3 4 5 6 - - Both of the above parse ``[4, 5, 6]`` as ``lst1`` and - the ``[1, 2, 3]`` as the ``lst2``. - -``Print(value)`` - Print the text and exit (with status ``0``). Useful for ``--version`` - option:: - - ap.add_option(&["-V", "--version"], - Print(env!("CARGO_PKG_VERSION").to_string()), "Show version"); - - |