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
// Copyright 2017 Lyndon Brown // // This file is part of the `gong` command-line argument processing library. // // Licensed under the MIT license or the Apache license (version 2.0), at your option. You may not // copy, modify, or distribute this file except in compliance with said license. You can find copies // of these licenses either in the LICENSE-MIT and LICENSE-APACHE files, or alternatively at // <http://opensource.org/licenses/MIT> and <http://www.apache.org/licenses/LICENSE-2.0> // respectively. //! Analysis components /// Analysis of processing arguments against an option set #[derive(Debug, Clone, PartialEq, Eq)] pub struct Analysis<'a> { /// Set of items describing what was found pub items: Vec<ItemClass<'a>>, /// Quick indication of error level issues (e.g. ambiguous match, or missing arg data) pub error: bool, /// Quick indication of warning level issues (e.g. unknown option, or unexpected data) pub warn: bool, } /// The possible classes of items identified and extracted from command line arguments. /// /// This breaks down items to three classes - okay/warn/error - with each variant holding an /// [`Item`], [`ItemW`] or [`ItemE`] variant which more specifically represents what was found. /// /// We use a class wrapper rather than grouping items into separate vectors because a single vector /// preserves order more simply. We break up item variants into groups for the advantages in /// matching. /// /// All sub-variants hold a `usize` value to be used for indicating the index of the argument at /// which the item was found. /// /// Most sub-variants also hold additional data. Long option sub-variants hold a string slice /// reference to the matched option. Short option sub-variants hold the `char` matched. Options with /// data arguments additionally hold a string slice reference to the data string matched, and in /// some cases also a [`DataLocation`] variant. The [`NonOption`] sub-variant holds a string slice /// reference to the matched string. /// /// [`Item`]: enum.Item.html /// [`ItemW`]: enum.ItemW.html /// [`ItemE`]: enum.ItemE.html /// [`DataLocation`]: enum.DataLocation.html /// [`NonOption`]: enum.Item.html#variant.NonOption #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ItemClass<'a> { /// Non-problematic item Ok(Item<'a>), /// Warn-level item Warn(ItemW<'a>), /// Error-level item Err(ItemE<'a>), } /// Non-problematic items. See [`ItemClass`](enum.ItemClass.html) documentation for details. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Item<'a> { /// Argument not considered an option. NonOption(usize, &'a str), /// Early terminator (`--`) encountered. EarlyTerminator(usize), /// Long option match. Long(usize, &'a str), /// Long option match, with expected data argument. LongWithData{ i: usize, n: &'a str, d: &'a str, l: DataLocation }, /// Short option match. Short(usize, char), /// Short option match, with expected data argument. ShortWithData{ i: usize, c: char, d: &'a str, l: DataLocation }, } /// Error-level items. See [`ItemClass`](enum.ItemClass.html) documentation for details. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ItemE<'a> { /// Long option match, but data argument missing [ERROR] LongMissingData(usize, &'a str), /// Short option match, but data argument missing [ERROR] ShortMissingData(usize, char), /// Ambiguous match with multiple long options. This only occurs when an exact match was not /// found, but multiple abbreviated possible matches were found. [ERROR] AmbiguousLong(usize, &'a str), } /// Warn-level items. See [`ItemClass`](enum.ItemClass.html) documentation for details. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ItemW<'a> { /// Looked like a long option, but no match [WARN] UnknownLong(usize, &'a str), /// Unknown short option `char` [WARN] UnknownShort(usize, char), /// Looked like a long option, but a name was not actually specified. This only occurs for /// arguments starting with `--=` (in standard mode, `-=` in alternate mode). Because the first /// `=` in a long option argument is interpreted as indication that any subsequent characters /// are a data sub-argument, an `=` immediately following the long option prefix thus gives an /// empty option name. The data (if any) is ignored. [WARN] LongWithNoName(usize), /// Long option match, but came with unexpected data. For example `--foo=bar` when `--foo` takes /// no data. [WARN] LongWithUnexpectedData{ i: usize, n: &'a str, d: &'a str }, } /// Used to describe where data was located, for options that require data. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum DataLocation { /// Found in the same argument (after an `=` for long options, or the remaining characters for a /// short option). SameArg, /// Found in the next argument. NextArg, } impl<'a> Analysis<'a> { /// Create a new result set (mostly only useful internally) pub fn new(size_guess: usize) -> Self { Self { items: Vec::with_capacity(size_guess), error: false, warn: false, } } /// Add a new item to the analysis (mostly only useful internally) pub fn add(&mut self, item: ItemClass<'a>) { self.items.push(item); } }