release: 0.10.1

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 
 
+## [0.10.1](https://github.com/Blobfolio/argyle/releases/tag/v0.10.1) - 2024-11-28
+
+### Changes
+
+* Miscellaneous code changes and lints
+* Miscellaneous doc changes
+
+
+
 ## [0.10.0](https://github.com/Blobfolio/argyle/releases/tag/v0.10.0) - 2024-10-17
 
 This release finishes the work of the last one. The streaming version of `Argue` is now stable and all there is; the old methods and structs have been removed.

CREDITS.md

@@ -1,6 +1,6 @@
 # Project Dependencies
     Package:   argyle
-    Version:   0.10.0
-    Generated: 2024-10-17 19:06:19 UTC
+    Version:   0.10.1
+    Generated: 2024-11-28 18:44:05 UTC
 
-This package has no dependencies.
+This project has no dependencies.

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "argyle"
-version = "0.10.0"
-authors = ["Blobfolio, LLC. <hello@blobfolio.com>"]
+version = "0.10.1"
+authors = ["Josh Stoik <josh@blobfolio.com>"]
 edition = "2021"
 rust-version = "1.81"
 description = "A lightweight, agnostic CLI argument parser."
@@ -25,6 +25,3 @@ default-target = "x86_64-unknown-linux-gnu"
 
 [package.metadata.bashman]
 name = "Argyle"
-bash-dir = "./"
-man-dir = "./"
-credits-dir = "./"

README.md

@@ -89,27 +89,3 @@ for arg in args {
 
 // Now that you're set up, do stuff…
 ```
-
-
-
-## License
-
-See also: [CREDITS.md](CREDITS.md)
-
-Copyright © 2024 [Blobfolio, LLC](https://blobfolio.com) <[email protected]>
-
-This work is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2.
-
-    DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-    Version 2, December 2004
-
-    Copyright (C) 2004 Sam Hocevar <[email protected]>
-
-    Everyone is permitted to copy and distribute verbatim or modified
-    copies of this license document, and changing it is allowed as long
-    as the name is changed.
-
-    DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-    0. You just DO WHAT THE FUCK YOU WANT TO.

src/stream/mod.rs → src/argue.rs

@@ -2,12 +2,7 @@
 # Argyle: Streaming Argument Iterator.
 */
 
-mod key;
-
-pub use key::{
-	KeyWord,
-	KeyWordsBuilder,
-};
+use crate::KeyWord;
 use std::{
 	collections::BTreeSet,
 	env::ArgsOs,
@@ -27,16 +22,13 @@ pub type ArgueEnv = Argue<Skip<ArgsOs>>;
 
 /// # Streaming Argument Iterator.
 ///
-/// `Argue` occupies the middle ground between [`std::env::args`] and full-service
-/// crates like `clap`.
+/// `Argue` occupies the middle ground between the standard library's barebones
+/// [`std::env::args_os`] helper and full-service crates like [clap](https://crates.io/crates/clap).
 ///
-/// It performs some basic normalization — and won't crash if an [`OsString`]
-/// contains invalid UTF-8! — and can help identify any reserved subcommands
-/// and keys expected by your app, but leaves any subsequent validation- and
-/// handling-related particulars _to you_.
-///
-/// That said, it does have a few _opinions_. Refer to [`KeyWord`] for
-/// formatting constraints.
+/// It performs some basic normalization — it handles string conversion in a
+/// non-panicking way, recognizes shorthand value assignments like `-kval`,
+/// `-k=val`, `--key=val`, and handles end-of-command (`--`) arguments — and
+/// will help identify any special keys/values expected by your app.
 ///
 /// `Argue` supports both combined and consecutive key/value association. For
 /// example, the following are equivalent:
@@ -47,14 +39,17 @@ pub type ArgueEnv = Argue<Skip<ArgsOs>>;
 /// instead collected and returned as-are in case you want to do anything with
 /// them. See [`Argument::End`] for more details.
 ///
+/// In general, `Argue` tries hard not to get in your way or make too many
+/// assumptions — handling and validation are left up to you! — but it does
+/// require that commands and keys follow certain basic formatting rules. Check
+/// out the [`KeyWord`] documentation for more details.
+///
 /// ## Examples
 ///
 /// ```
 /// use argyle::{Argument, KeyWord};
 ///
-/// // Most of the time you'll probably want to parse env args, which the
-/// // helper method [`args`] sets up. Add switches, options, etc, then loop to
-/// // see what all comes in!
+/// // To parse arguments from env, just use the `args` helper method.
 /// let args = argyle::args()
 ///     .with_keywords([
 ///         KeyWord::key("--version").unwrap(),

src/stream/key.rs → src/key.rs

@@ -201,12 +201,14 @@ impl KeyWord {
 /// words.save(out_dir.join("keyz.rs"));
 /// ```
 ///
-/// Having done that, just `include!` it where needed:
+/// Having done that, just `include!` it within your library where needed:
 ///
 /// ```ignore
 /// let ags = argyle::args()
 ///     .with_keywords(include!(concat!(env!("OUT_DIR"), "/keyz.rs")));
 /// ```
+///
+/// For a real-world example, check out the build script for [adbyss](https://github.com/Blobfolio/adbyss/blob/master/adbyss/build.rs).
 pub struct KeyWordsBuilder(BTreeMap<String, String>);
 
 impl fmt::Display for KeyWordsBuilder {
@@ -235,13 +237,35 @@ impl KeyWordsBuilder {
 	/// # Is Empty?
 	///
 	/// Returns `true` if there are no keywords.
+	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// // Duh.
+	/// assert!(KeyWordsBuilder::default().is_empty());
+	/// ```
 	pub fn is_empty(&self) -> bool { self.0.is_empty() }
 
 	#[inline]
 	#[must_use]
 	/// # Length.
 	///
 	/// Returns the number of keywords currently in the set.
+	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// let mut builder = KeyWordsBuilder::default();
+	/// builder.push_keys([
+	///     "-h", "--help",
+	///     "-V", "--version",
+	/// ]);
+	/// assert_eq!(builder.len(), 4);
+	/// ```
 	pub fn len(&self) -> usize { self.0.len() }
 }
 
@@ -262,6 +286,15 @@ impl KeyWordsBuilder {
 	///
 	/// Use this to add a [`KeyWord::Command`] to the list.
 	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// let mut builder = KeyWordsBuilder::default();
+	/// builder.push_command("make");
+	/// ```
+	///
 	/// ## Panics
 	///
 	/// This will panic if the command is invalid or repeated;
@@ -276,6 +309,19 @@ impl KeyWordsBuilder {
 	///
 	/// Use this to add one or more [`KeyWord::Command`] to the list.
 	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// let mut builder = KeyWordsBuilder::default();
+	/// builder.push_commands([
+	///     "check",
+	///     "make",
+	///     "test",
+	/// ]);
+	/// ```
+	///
 	/// ## Panics
 	///
 	/// This will panic if any commands are invalid or repeated;
@@ -287,6 +333,15 @@ impl KeyWordsBuilder {
 	///
 	/// Use this to add a [`KeyWord::Key`] to the list.
 	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// let mut builder = KeyWordsBuilder::default();
+	/// builder.push_key("--help");
+	/// ```
+	///
 	/// ## Panics
 	///
 	/// This will panic if the key is invalid or repeated.
@@ -301,6 +356,18 @@ impl KeyWordsBuilder {
 	///
 	/// Use this to add one or more [`KeyWord::Key`] to the list.
 	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// let mut builder = KeyWordsBuilder::default();
+	/// builder.push_keys([
+	///     "-h", "--help",
+	///     "-V", "--version",
+	/// ]);
+	/// ```
+	///
 	/// ## Panics
 	///
 	/// This will panic if any keys are invalid or repeated.
@@ -312,6 +379,15 @@ impl KeyWordsBuilder {
 	///
 	/// Use this to add a [`KeyWord::KeyWithValue`] to the list.
 	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// let mut builder = KeyWordsBuilder::default();
+	/// builder.push_key_with_value("--output");
+	/// ```
+	///
 	/// ## Panics
 	///
 	/// This will panic if the key is invalid or repeated.
@@ -326,6 +402,18 @@ impl KeyWordsBuilder {
 	///
 	/// Use this to add one or more [`KeyWord::KeyWithValue`] to the list.
 	///
+	/// ## Examples
+	///
+	/// ```
+	/// use argyle::KeyWordsBuilder;
+	///
+	/// let mut builder = KeyWordsBuilder::default();
+	/// builder.push_keys_with_values([
+	///     "-i", "--input",
+	///     "-o", "--output",
+	/// ]);
+	/// ```
+	///
 	/// ## Panics
 	///
 	/// This will panic if any keys are invalid or repeated.

src/lib.rs

@@ -134,12 +134,16 @@ for arg in args {
 
 
 
-mod stream;
-pub use stream::{
+mod argue;
+mod key;
+
+pub use argue::{
 	args,
 	Argue,
 	ArgueEnv,
 	Argument,
+};
+pub use key::{
 	KeyWord,
 	KeyWordsBuilder,
 };