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
126
127
128
129
130
131
132
133
134
135
136

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

//! # A command line parser
//!
//! ## Project
//!
//! - Repository: <https://bitbucket.org/haibison/dia-args>
//! - License: Nice License 1.0.0 _(see LICENSE file at root directory of `master` branch)_
//! - _This project follows [Semantic Versioning 2.0.0]_
//!
//! ## Features
//!
//! - No debts: no dependencies. It's an argument parser, so standard Rust is enough.
//! - There's a specification (below). It has a ***separate*** version, not same as the library's.
//! - [`::parse_file()`][crate::parse_file()] can be useful: it helps you parse arguments stored in your file.
//!
//! ## Specification `0.0.1`
//!
//! A program argument can be:
//!
//! - A command.
//! - An argument.
//! - An option.
//! - Two special phrases: `-` and `--`.
//!
//! 1. Commands
//!
//!    - A command can be anything which does not start with either `-` or `--`.
//!
//! 2. Arguments
//!
//!    - Same as a command, 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. This is normally used to pass arguments to sub process.
//!
//! 5. Passing arguments to a program
//!
//!    Must be in this form:
//!
//!    ```shell
//!    program [command] [arguments...|options...|-] [-- [arguments...]]
//!    ```
//!
//!    in which:
//!
//!    - `[]` means optional.
//!    - `...` means multiple arguments.
//!
//! [Semantic Versioning 2.0.0]: https://semver.org/spec/v2.0.0.html
//! [crate::parse_file()]: fn.parse_file.html

#![warn(missing_docs)]

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

macro_rules! code_name  { () => { "dia-args" }}
macro_rules! version    { () => { "0.28.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) = (2019, 4, 7);

/// # 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 mod docs;
pub mod paths;
pub mod version_info;

pub use args::*;

/// # Default file name for storing arguments: `.dia-args`
///
/// The file must be placed within the directory of the program. Then you can use [`::parse_file()`][crate::parse_file()] to parse it. Refer to
/// that function for content syntax.
///
/// [crate::parse_file()]: fn.parse_file.html
pub const DIA_ARGS_FILE_NAME: &'static str = concat!('.', code_name!());

/// # Maximum size allowed for argument file to be parsed (3 MiB)
pub const MAX_DIA_ARGS_FILE_SIZE: u64 = 3 * 1024 * 1024;

#[test]
fn tests() {
    assert_eq!(DIA_ARGS_FILE_NAME, ".dia-args");
}