Update readme with some example for using key/values

doc/readme.md

@@ -192,7 +192,10 @@ Random other tidbits:
   ```csharp
   var app = new CommandApp()
   {
-      { "D:", "Add a marco {0:NAME} and optional {1:VALUE}", (k, v) => Console.WriteLin($"Macro:    {k}` => `{v}`") },
+      { "D:", "Add a macro {0:NAME} and optional {1:VALUE}", (k, v) => {
+        if (k is null) throw new OptionException("Missing macro name", "D");
+        Console.WriteLine($"Macro:    {k}` => `{v}`"); 
+      }},
       { "I|macro=", "Add a marco {0:NAME} and required {1:VALUE}", (k, v) => Console.WriteLine  ($"Required Macro: `{k}` => `{v}`") },
   };
   await app.RunAsync(["-DA=B", "-DHello=World", "-DG", "-IG=F", "--macro", "X=Y"]);

readme.md

@@ -36,11 +36,17 @@ using XenoAtom.CommandLine;
 const string _ = "";
 string? name = null;
 int age = 0;
+List<(string, string?)> keyValues = new List<(string, string?)>();
 List<string> messages = new List<string>();
 
 var commandApp = new CommandApp("myexe")
 {
     _,
+    {"D:", "Defines a {0:name} and optional {1:value}", (key, value) =>
+    {
+        if (key is null) throw new OptionException("The key is mandatory for a define", "D");
+        keyValues.Add((key, value));
+    }},
     {"n|name=", "Your {NAME}", v => name = v},
     {"a|age=", "Your {AGE}", (int v) => age = v},
     new HelpOption(),
@@ -53,20 +59,28 @@ var commandApp = new CommandApp("myexe")
         new HelpOption(),
 
         // Action for the commit command
-        (arguments) =>
+        (ctx, arguments) =>
         {
-            Console.Out.WriteLine($"Committing with name={name}, age={age}");
+            ctx.Out.WriteLine($"Committing with name={name}, age={age}");
             foreach (var message in messages)
             {
-                Console.Out.WriteLine($"Commit message: {message}");
+                ctx.Out.WriteLine($"Commit message: {message}");
             }
             return ValueTask.FromResult(0);
         }
     },
     // Default action if no command is specified
-    (_) =>
+    (ctx, _) =>
     {
-        Console.Out.WriteLine($"Hello {name}! You are {age} years old.");
+        ctx.Out.WriteLine($"Hello {name}! You are {age} years old.");
+        if (keyValues.Count > 0)
+        {
+            foreach (var keyValue in keyValues)
+            {
+                ctx.Out.WriteLine($"Define: {keyValue.Item1} => {keyValue.Item2}");
+            }
+        }
+
         return ValueTask.FromResult(0);
     }
 };
@@ -79,12 +93,13 @@ Running `myexe --help` will output:
 ```
 Usage: myexe [Options] COMMAND
 
+  -D[=name:value]            Defines a name and optional value
   -n, --name=NAME            Your NAME
   -a, --age=AGE              Your AGE
   -h, -?, --help             Show this message and exit
 
 Available commands:
-  commit    
+  commit
 ```
 
 Running `myexe --name John -a50` will output:
@@ -93,6 +108,15 @@ Running `myexe --name John -a50` will output:
 Hello John! You are 50 years old.
 ```
 
+
+Running `myexe --name John -a50 -DHello -DWorld=121` will output:
+
+```
+Hello John! You are 50 years old.
+Define: Hello =>
+Define: World => 121
+```
+
 Running `myexe commit --help` will output:
 
 ```

samples/AdvancedApp/Program.cs

@@ -29,7 +29,12 @@
     _,
     "Options:",
     // gcc-like options
-    { "D:", "Add a marco {0:NAME} and optional {1:VALUE}", (k, v) => keyValues.Add((k, v)) },
+    { "D:", "Add a marco {0:NAME} and optional {1:VALUE}", (k, v) =>
+        {
+            if (k is null) throw new OptionException("Name is required", "D");
+            keyValues.Add((k, v));
+        }
+    },
 
     // tar-like options
     { "f=", "The input {FILE}", files },

src/XenoAtom.CommandLine.Tests/CommandLineTests.cs

@@ -8,18 +8,25 @@ public class CommandLineTests : VerifyBase
     [TestMethod]
     [DataRow(0, "--help")]
     [DataRow(0, "--name", "John", "-a50" )]
+    [DataRow(0, "--name", "John", "-a50", "-DHello", "-DWorld=126")]
     [DataRow(0, "commit", "--help")]
     [DataRow(0, "--name", "John", "-a50", "commit", "--message", "Hello!", "--message", "World!")]
     public async Task TestHelloWorld(int result, params string[] args)
     {
         const string _ = "";
         string? name = null;
         int age = 0;
+        List<(string, string?)> keyValues = new List<(string, string?)>();
         List<string> messages = new List<string>();
 
         var commandApp = new CommandApp("myexe")
         {
             _,
+            {"D:", "Defines a {0:name} and optional {1:value}", (key, value) =>
+            {
+                if (key is null) throw new OptionException("The key is mandatory for a define", "D");
+                keyValues.Add((key, value));
+            }},
             {"n|name=", "Your {NAME}", v => name = v},
             {"a|age=", "Your {AGE}", (int v) => age = v},
             new HelpOption(),
@@ -46,6 +53,14 @@ public async Task TestHelloWorld(int result, params string[] args)
             (ctx, _) =>
             {
                 ctx.Out.WriteLine($"Hello {name}! You are {age} years old.");
+                if (keyValues.Count > 0)
+                {
+                    foreach (var keyValue in keyValues)
+                    {
+                        ctx.Out.WriteLine($"Define: {keyValue.Item1} => {keyValue.Item2}");
+                    }
+                }
+
                 return ValueTask.FromResult(0);
             }
         };

src/XenoAtom.CommandLine.Tests/Verified/CommandLineTests.TestHelloWorld_result=0,--help.verified.txt

@@ -1,5 +1,6 @@
 Usage: myexe [Options] COMMAND
 
+  -D[=name:value]            Defines a name and optional value
   -n, --name=NAME            Your NAME
   -a, --age=AGE              Your AGE
   -h, -?, --help             Show this message and exit

src/XenoAtom.CommandLine.Tests/Verified/CommandLineTests.TestHelloWorld_result=0,--name,John,-a50,-DHello,-DWorld=126.verified.txt

@@ -0,0 +1,3 @@
+Hello John! You are 50 years old.
+Define: Hello => 
+Define: World => 126