feat: update docstrings for commands/args, replace --dry-run with --o…

…utput for whiskerify

Cargo.toml

@@ -11,6 +11,10 @@ keywords = ["cli"]
 categories = ["command-line-utilities"]
 edition = "2021"
 
+[[bin]]
+name = "purr"
+path = "src/main.rs"
+
 [dependencies]
 catppuccin = { version = "2.4.0", features = ["css-colors"] }
 clap = { version = "4.5.4", features = ["derive", "env"] }

src/cli.rs

@@ -7,114 +7,144 @@ use url::Url;
 use crate::models::shared::CATEGORIES;
 
 #[derive(Parser)]
-#[command(version, arg_required_else_help(true))]
+#[command(name = "purr", version, arg_required_else_help(true))]
 pub struct Cli {
 	#[command(subcommand)]
 	pub command: Commands,
 }
 
 #[derive(Subcommand)]
 pub enum Commands {
+	/// Query about the ports.yml data source
 	Query {
 		#[command(subcommand)]
 		command: Option<Query>,
 
+		/// Query data for a specific port
 		#[arg(long, name = "PORT", conflicts_with = "count", requires = "get")]
 		r#for: Option<String>,
 
+		/// Count the number of results
 		#[arg(short, long)]
 		count: bool,
 
+		/// Extract a specific property each result
 		#[arg(short, long, value_enum, default_value_t)]
 		get: Key,
 	},
+	/// Initialize a new port from catppuccin/template
 	Init {
+		/// Name of the application
 		#[arg(long)]
 		name: Option<String>,
 
+		/// URL to the application
 		#[arg(long, value_parser = valid_url)]
 		url: Option<String>,
 	},
+	/// Userstyles-related subcommands
 	Userstyles {
 		#[command(subcommand)]
 		command: Userstyles,
 	},
+	/// Convert a theme file to a Whiskers template
 	Whiskerify {
-		path: PathBuf,
+		input: PathBuf,
 
 		#[arg(short, long)]
-		dry_run: bool,
+		output: Option<PathBuf>,
 	},
 }
 
 #[derive(Subcommand)]
 pub enum Userstyles {
+	/// Query about the userstyles.yml data source
 	Query {
 		#[command(subcommand)]
 		command: Option<UserstylesQuery>,
 
+		/// Query data for a specific userstyle
 		#[arg(long, name = "USERSTYLE", conflicts_with = "count", requires = "get")]
 		r#for: Option<String>,
 
+		/// Count the number of results
 		#[arg(short, long)]
 		count: bool,
 
+		/// Extract a specific property each result
 		#[arg(short, long, value_enum, default_value_t)]
 		get: UserstyleKey,
 	},
+	/// Initialize a new userstyle from the template
 	Init {
+		/// Name of the application
 		#[arg(long)]
 		name: Option<String>,
 
+		/// Categories that represent the application
 		#[arg(long = "category", value_delimiter = ',', value_parser = valid_category)]
 		categories: Option<Vec<String>>,
 
+		/// Icon for the application (from simpleicons.org)
 		#[arg(long)]
 		icon: Option<String>,
 
+		/// Name of a Catppuccin color that matches the application's brand color
 		#[arg(long)]
 		color: Option<String>,
 
+		/// URL to the application
 		#[arg(long, value_parser = valid_url)]
 		url: Option<String>,
 	},
 }
 
 #[derive(Subcommand)]
 pub enum Query {
+	/// Query maintained ports and who maintains them
 	Maintained {
+		/// Name of the maintainer to search for
 		#[arg(long, name = "NAME")]
 		by: Option<String>,
 
 		#[command(flatten)]
 		options: ExtraOptions<Key>,
 	},
+	/// Query about the Whiskers migration
 	Whiskers {
+		/// Name of the repository to query
 		#[arg(long, name = "REPOSITORY", conflicts_with_all = ["count"])]
 		r#for: Option<String>,
 
+		/// Whiskers state to check for
 		#[arg(short, long, name = "STATE")]
 		is: Option<WhiskersCustomProperty>,
 
+		/// Invert matched results
 		#[arg(short, long)]
 		not: bool,
 
+		/// Count the number of results
 		#[arg(short, long)]
 		count: bool,
 
 		#[arg(long, env = "GITHUB_TOKEN")]
 		token: String,
 	},
+	/// Query star counts of the whole organization or per-repository
 	Stars {
+		/// Name of the repository to query
 		#[arg(long, name = "REPOSITORY", conflicts_with = "archived")]
 		r#for: Option<String>,
 
+		/// Whether to include archived repositories in the total count
 		#[arg(long)]
 		archived: bool,
 
 		#[arg(long, env = "GITHUB_TOKEN")]
 		token: String,
 	},
+	/// Query ports with matching fields
 	Has {
 		#[arg(long)]
 		name: Option<String>,
@@ -147,13 +177,15 @@ pub enum Query {
 
 #[derive(Subcommand)]
 pub enum UserstylesQuery {
+	/// Query maintained userstyles and who maintains them
 	Maintained {
 		#[arg(long, name = "NAME")]
 		by: Option<String>,
 
 		#[command(flatten)]
 		options: ExtraOptions<UserstyleKey>,
 	},
+	/// Query ports with matching fields
 	Has {
 		#[arg(long)]
 		name: Option<String>,
@@ -177,12 +209,15 @@ pub enum UserstylesQuery {
 
 #[derive(Args)]
 pub struct ExtraOptions<K: Send + Sync + Default + ValueEnum + 'static> {
+	/// Invert matched results
 	#[arg(short, long)]
 	pub not: bool,
 
+	/// Count the number of results
 	#[arg(short, long)]
 	pub count: bool,
 
+	/// Extract a specific property each result
 	#[arg(short, long, value_enum, default_value_t)]
 	pub get: K,
 }

src/main.rs

@@ -36,7 +36,7 @@ fn main() -> Result<()> {
 				url,
 			} => userstyles::init(name, categories, icon, color, url)?,
 		},
-		Commands::Whiskerify { path, dry_run } => whiskerify::convert(path, dry_run)?,
+		Commands::Whiskerify { input, output } => whiskerify::convert(input, output)?,
 	}
 
 	Ok(())

src/whiskerify.rs

@@ -5,8 +5,8 @@ use log::warn;
 
 use fancy_regex::Regex;
 
-pub fn convert(path: PathBuf, dry_run: bool) -> Result<()> {
-	let mut contents = fs::read_to_string(&path)?;
+pub fn convert(input: PathBuf, output: Option<PathBuf>) -> Result<()> {
+	let mut contents = fs::read_to_string(&input)?;
 
 	let mut color_matches = Regex::new("rgba?\\(.*\\)")
 		.unwrap()
@@ -63,15 +63,15 @@ pub fn convert(path: PathBuf, dry_run: bool) -> Result<()> {
 		warn!(
 			"could not replace non-Catppuccin color '{}' at {}:{}",
 			text.yellow(),
-			path.to_string_lossy(),
+			input.to_string_lossy(),
 			&get_location_in_text(&text, &contents)
 		);
 	}
 
-	if dry_run {
-		println!("{contents}");
-	} else {
+	if let Some(path) = output {
 		fs::write(path, contents)?;
+	} else {
+		println!("{contents}");
 	}
 
 	Ok(())