From ae7c12ad62d1282b3769ad8e537829b82ad8bd0b Mon Sep 17 00:00:00 2001
From: a dinosaur <dino@a-dinosaur.com>
Date: Sun, 2 Nov 2025 22:55:00 +1100
Subject: [PATCH] Add example from README.md as basic.rs

---
 README.md         | 12 ++++++++----
 examples/basic.rs | 48 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 4 deletions(-)
 create mode 100644 examples/basic.rs

diff --git a/README.md b/README.md
index 1ea2621..16f607a 100644
--- a/README.md
+++ b/README.md
@@ -22,12 +22,15 @@ let mut number = 0;
 enum Arg { Help, Number, File, Out }
 const OPTIONS: Opts<Arg> = Opts::new(&[
   Opt::help_flag(Arg::Help, &["-h", "--help"]).help_text("Show this help and exit."),
-  Opt::value(Arg::Number, &["-n", "--number"], "value").help_text("Optionally specify a number (default: 0)"),
-  Opt::positional(Arg::File, "file").required().help_text("Input file."),
-  Opt::positional(Arg::Out, "out").help_text("Output destination (optional).")
+  Opt::value(Arg::Number, &["-n", "--number"], "value")
+    .help_text("Optionally specify a number (default: 0)"),
+  Opt::positional(Arg::File, "file").required()
+    .help_text("Input file."),
+  Opt::positional(Arg::Out, "out")
+    .help_text("Output destination (optional).")
 ]).with_description("My simple utility.");
 
-// Parse the arguments
+// Parse command-line arguments from `std::env::args()`
 match OPTIONS.parse_easy(|program_name, id, _opt, _name, arg| {
   match id {
     Arg::Help => {
@@ -54,6 +57,7 @@ println!("{file:?} -> {out:?} (number: {number:?})",
 
 main:
  * Fixed incorrect error message format for coerced parsing errors.
+ * Added basic example.
 
 v0.1.0:
  * Initial release.
diff --git a/examples/basic.rs b/examples/basic.rs
new file mode 100644
index 0000000..c3c84b0
--- /dev/null
+++ b/examples/basic.rs
@@ -0,0 +1,48 @@
+/* basic - jaarg example program using parse_easy
+ * SPDX-FileCopyrightText: (C) 2025 Gay Pizza Specifications
+ * SPDX-License-Identifier: MIT
+ */
+
+use jaarg::{Opt, Opts, ParseControl, ParseResult};
+use std::path::PathBuf;
+
+fn main() {
+  // Variables for arguments to fill
+  let mut file = PathBuf::new();
+  let mut out: Option<PathBuf> = None;
+  let mut number = 0;
+
+  // Set up arguments table
+  enum Arg { Help, Number, File, Out }
+  const OPTIONS: Opts<Arg> = Opts::new(&[
+    Opt::help_flag(Arg::Help, &["-h", "--help"]).help_text("Show this help and exit."),
+    Opt::value(Arg::Number, &["-n", "--number"], "value")
+      .help_text("Optionally specify a number (default: 0)"),
+    Opt::positional(Arg::File, "file").required()
+      .help_text("Input file."),
+    Opt::positional(Arg::Out, "out")
+      .help_text("Output destination (optional).")
+  ]).with_description("My simple utility.");
+
+  // Parse command-line arguments from `std::env::args()`
+  match OPTIONS.parse_easy(|program_name, id, _opt, _name, arg| {
+    match id {
+      Arg::Help => {
+        OPTIONS.print_full_help(program_name);
+        return Ok(ParseControl::Quit);
+      }
+      Arg::Number => { number = str::parse(arg)?; }
+      Arg::File   => { file = arg.into(); }
+      Arg::Out    => { out = Some(arg.into()); }
+    }
+    Ok(ParseControl::Continue)
+  }) {
+    ParseResult::ContinueSuccess => (),
+    ParseResult::ExitSuccess     => std::process::exit(0),
+    ParseResult::ExitError       => std::process::exit(1),
+  }
+
+  // Print the result variables
+  println!("{file:?} -> {out:?} (number: {number:?})",
+    out = out.unwrap_or(file.with_extension("out")));
+}