1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

// License: see LICENSE file at root directory of `master` branch

//! # A command line parser
//!
//! # Project
//!
//! - Repository: <https://bitbucket.org/haibison/dia-args>
//! - License: [Free Public License 1.0.0](https://opensource.org/licenses/FPL-1.0.0)
//! - _This project follows [Semantic Versioning 2.0.0]_
//!
//! # Features
//!
//! - TODO
//!
//! # Specification `0.0.1`
//!
//! A program argument can be:
//!
//! - A command.
//! - An argument.
//! - An option.
//! - Two special phrases: `-` and `--`.
//!
//! 1. Commands
//!
//!    - Form: `[a-zA-Z][a-zA-Z0-9\-]*[^\-]?`
//!
//! 2. Arguments
//!
//!    - An argument can be anything which does not start with either `-` or `--`.
//!
//! 3. Options
//!
//!    An option starts with `-` or `--`.
//!
//!    - `-` supports either:
//!
//!        + A single short format option.
//!        + Or multiple short format _boolean_ options.
//!
//!    - `--` supports a single long format option.
//!    - Option values can be anything.
//!
//!    - An option's key and value can be separated by either:
//!
//!        + An equals sign `=`.
//!        + Or mutiple white spaces.
//!
//!    - A boolean option has 2 values: `true` and `false`. The value is optional. If absent, `true` will be assigned.
//!
//! 4. Special phrases
//!
//!    - `-` means: the program should process standard input.
//!    - `--` means: the program should process _all_ arguments after it as arguments.
//!
//! 5. Passing arguments to a program
//!
//!    Must be in this form:
//!
//!    ```shell
//!    program [command] [arguments...] [options...] [-] [-- [arguments...]]
//!    ```
//!
//!    in which:
//!
//!    - `[]` means optional.
//!    - `...` means multiple arguments.
//!
//! # Implementation
//!
//! The main technique is using macros to generate structs holding options, arguments...
//!
//! - <https://doc.rust-lang.org/book/first-edition/macros.html>
//! - <https://doc.rust-lang.org/book/second-edition/appendix-04-macros.html>
//!
//! ## Notes
//!
//! - [`Arg`] takes care of arguments and options.
//! - Commands should be handled by other functions/structs...
//! - In _code_ (not in _command line_), the user can provide mixed arguments/options in any arbitrary order. The parser(s) should re-arrange
//!   them to parse.
//!
//! - TODO
//!
//! [Semantic Versioning 2.0.0]: https://semver.org/spec/v2.0.0.html

// ╔═════════════════╗
// ║   IDENTIFIERS   ║
// ╚═════════════════╝

macro_rules! code_name  { () => { "dia-args" }}
macro_rules! version    { () => { "0.2.1" }}

/// # Crate name
pub const NAME: &'static str = "Dia-args";

/// # Crate code name
pub const CODE_NAME: &'static str = code_name!();

/// # Crate version
pub const VERSION: &'static str = version!();

/// # Crate release date (year/month/day)
pub const RELEASE_DATE: (u16, u8, u8) = (2018, 8, 25);

/// # Unique universally identifier of this crate
pub const UUID: &'static str = "ea808a86-0aef-4163-9964-8f25f727f06a";

/// # Tag, which can be used for logging...
pub const TAG: &'static str = concat!(code_name!(), "::ea808a86::", version!());

// ╔════════════════════╗
// ║   IMPLEMENTATION   ║
// ╚════════════════════╝

#[test]
fn test_crate_version() {
    assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
}

#[macro_use]
#[allow(unused_macros)]
mod __;
mod args;
pub use args::*;