summaryrefslogtreecommitdiff
path: root/argparse/README.rst
diff options
context:
space:
mode:
authorDaniel Mueller <deso@posteo.net>2020-04-04 14:39:19 -0700
committerDaniel Mueller <deso@posteo.net>2020-04-04 14:39:19 -0700
commitd0d9683df8398696147e7ee1fcffb2e4e957008c (patch)
tree4baa76712a76f4d072ee3936c07956580b230820 /argparse/README.rst
parent203e691f46d591a2cc8acdfd850fa9f5b0fb8a98 (diff)
downloadnitrocli-d0d9683df8398696147e7ee1fcffb2e4e957008c.tar.gz
nitrocli-d0d9683df8398696147e7ee1fcffb2e4e957008c.tar.bz2
Remove vendored dependencies
While it appears that by now we actually can get successful builds without Cargo insisting on Internet access by virtue of using the --frozen flag, maintaining vendored dependencies is somewhat of a pain point. This state will also get worse with upcoming changes that replace argparse in favor of structopt and pull in a slew of new dependencies by doing so. Then there is also the repository structure aspect, which is non-standard due to the way we vendor dependencies and a potential source of confusion. In order to fix these problems, this change removes all the vendored dependencies we have. Delete subrepo argparse/:argparse Delete subrepo base32/:base32 Delete subrepo cc/:cc Delete subrepo cfg-if/:cfg-if Delete subrepo getrandom/:getrandom Delete subrepo lazy-static/:lazy-static Delete subrepo libc/:libc Delete subrepo nitrokey-sys/:nitrokey-sys Delete subrepo nitrokey/:nitrokey Delete subrepo rand/:rand
Diffstat (limited to 'argparse/README.rst')
-rw-r--r--argparse/README.rst341
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");
-
-