docs(args): update readme

packages/args/README.md

@@ -84,13 +84,28 @@ Package sizes (brotli'd, pre-treeshake): ESM: 2.29 KB
 
 ### Basic usage
 
-```ts
+```ts tangle:export/readme.ts
+import {
+    flag,
+    hex,
+    json,
+    kvPairs,
+    oneOf,
+    parse,
+    size,
+    string,
+    vec,
+    type Args,
+    type KVDict,
+    type Tuple,
+} from "@thi.ng/args";
+
 type ImgType = "png" | "jpg" | "gif" | "tiff";
 
 // CLI args will be validated against this interface
 interface TestArgs {
     configPath?: string;
-    force: boolean;
+    force?: boolean;
     bg: number;
     type: ImgType;
     size?: Tuple<number>;
@@ -120,6 +135,7 @@ const specs: Args<TestArgs> = {
         desc: "Background color",
         // mandatory args require a `default` value and/or `optional: false`
         default: 0xffffff,
+        defaultHint: "ffffff",
     }),
     // enum value (mandatory)
     type: oneOf(["png", "jpg", "gif", "tiff"], {
@@ -134,24 +150,76 @@ const specs: Args<TestArgs> = {
     size: size(2, { hint: "WxH", desc: "Target size" }),
     // another version for tuples of floating point values
     // pos: tuple(coerceFloat, 2, { desc: "Lat/Lon" }, ","),
-    pos: vec(2, { desc: "Lat/Lon" }),
+    pos: vec(2, { desc: "Lat/Lon coordinates" }),
     // JSON string arg
     xtra: json({
         alias: "x",
         desc: "Extra options",
+        group: "extra",
     }),
     // key-value pairs parsed into an object
-    define: kvPairs({ alias: "D", desc: "Define dict entry" }),
+    define: kvPairs({
+        alias: "D",
+        desc: "Define dict entry",
+        group: "extra"
+    }),
 };
 
 try {
     // parse argv w/ above argument specs & default options
     // (by default usage is shown if error occurs)
-    const args = parse(specs, process.argv);
+    const args = parse(specs, process.argv, {
+        usageOpts: {
+            prefix: `
+ █ █   █           │
+██ █               │
+ █ █ █ █   █ █ █ █ │ @thi.ng/args demo app
+ █ █ █ █ █ █ █ █ █ │ v1.0.0
+                 █ │
+               █ █ │\n\n`,
+            showGroupNames: true,
+            groups: ["flags", "main", "extra"],
+            lineWidth: 72,
+        },
+    });
     console.log(args);
 } catch (_) {}
 ```
 
+Invoking this as CLI script without arguments will generate an error about a
+missing `--type` arg and output the generated usage info (by default with ANSI
+color highlights):
+
+```text
+illegal argument(s): missing arg: --type
+
+ █ █   █           │
+██ █               │
+ █ █ █ █   █ █ █ █ │ @thi.ng/args demo app
+ █ █ █ █ █ █ █ █ █ │ v1.0.0
+                 █ │
+               █ █ │
+
+Flags:
+
+-f, --force                     Force operation
+
+Main:
+
+--bg HEX                        Background color (default: "ffffff")
+-c PATH, --config-path PATH     Config file path (CLI args always take
+                                precedence over those settings)
+--pos N,N                       Lat/Lon coordinates
+--size WxH                      Target size
+-t ID, --type ID                [required] Image type: "png", "jpg",
+                                "gif", "tiff"
+
+Extra:
+
+-D key=val, --define key=val    [multiple] Define dict entry
+-x JSON, --xtra JSON            Extra options
+```
+
 #### Generate & display help
 
 Usage information can be generated via `usage()` and is automatically triggered

packages/args/tpl.readme.md

@@ -50,13 +50,28 @@ individual values, e.g. `-a 1,2,3` equals `-a 1 -a 2 -a 3`
 
 ### Basic usage
 
-```ts
+```ts tangle:export/readme.ts
+import {
+    flag,
+    hex,
+    json,
+    kvPairs,
+    oneOf,
+    parse,
+    size,
+    string,
+    vec,
+    type Args,
+    type KVDict,
+    type Tuple,
+} from "@thi.ng/args";
+
 type ImgType = "png" | "jpg" | "gif" | "tiff";
 
 // CLI args will be validated against this interface
 interface TestArgs {
     configPath?: string;
-    force: boolean;
+    force?: boolean;
     bg: number;
     type: ImgType;
     size?: Tuple<number>;
@@ -86,6 +101,7 @@ const specs: Args<TestArgs> = {
         desc: "Background color",
         // mandatory args require a `default` value and/or `optional: false`
         default: 0xffffff,
+        defaultHint: "ffffff",
     }),
     // enum value (mandatory)
     type: oneOf(["png", "jpg", "gif", "tiff"], {
@@ -100,24 +116,77 @@ const specs: Args<TestArgs> = {
     size: size(2, { hint: "WxH", desc: "Target size" }),
     // another version for tuples of floating point values
     // pos: tuple(coerceFloat, 2, { desc: "Lat/Lon" }, ","),
-    pos: vec(2, { desc: "Lat/Lon" }),
+    pos: vec(2, { desc: "Lat/Lon coordinates" }),
     // JSON string arg
     xtra: json({
         alias: "x",
         desc: "Extra options",
+        group: "extra",
     }),
     // key-value pairs parsed into an object
-    define: kvPairs({ alias: "D", desc: "Define dict entry" }),
+    define: kvPairs({
+        alias: "D",
+        desc: "Define dict entry",
+        group: "extra"
+    }),
 };
 
 try {
     // parse argv w/ above argument specs & default options
     // (by default usage is shown if error occurs)
-    const args = parse(specs, process.argv);
+    const args = parse(specs, process.argv, {
+        usageOpts: {
+            prefix: `
+ █ █   █           │
+██ █               │
+ █ █ █ █   █ █ █ █ │ @thi.ng/args demo app
+ █ █ █ █ █ █ █ █ █ │ v1.0.0
+                 █ │
+               █ █ │\n\n`,
+            showGroupNames: true,
+            groups: ["flags", "main", "extra"],
+            lineWidth: 72,
+        },
+    });
     console.log(args);
 } catch (_) {}
 ```
 
+Invoking this as CLI script without arguments will generate an error about a
+missing `--type` arg and output the generated usage info (by default with ANSI
+color highlights):
+
+```text
+illegal argument(s): missing arg: --type
+
+
+ █ █   █           │
+██ █               │
+ █ █ █ █   █ █ █ █ │ @thi.ng/args demo app
+ █ █ █ █ █ █ █ █ █ │ v1.0.0
+                 █ │
+               █ █ │
+
+Flags:
+
+-f, --force                     Force operation
+
+Main:
+
+--bg HEX                        Background color (default: "ffffff")
+-c PATH, --config-path PATH     Config file path (CLI args always take
+                                precedence over those settings)
+--pos N,N                       Lat/Lon coordinates
+--size WxH                      Target size
+-t ID, --type ID                [required] Image type: "png", "jpg",
+                                "gif", "tiff"
+
+Extra:
+
+-D key=val, --define key=val    [multiple] Define dict entry
+-x JSON, --xtra JSON            Extra options
+```
+
 #### Generate & display help
 
 Usage information can be generated via `usage()` and is automatically triggered