@thi.ng/args 2.2.33 → 2.2.35

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-08-27T11:20:58Z
+- **Last updated**: 2023-09-06T13:36:28Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/args",
-  "version": "2.2.33",
+  "version": "2.2.35",
   "description": "Declarative, functional & typechecked CLI argument/options parser, value coercions etc.",
   "type": "module",
   "module": "./index.js",
@@ -37,7 +37,7 @@
     "@thi.ng/api": "^8.9.5",
     "@thi.ng/checks": "^3.4.5",
     "@thi.ng/errors": "^2.3.5",
-    "@thi.ng/strings": "^3.4.13"
+    "@thi.ng/strings": "^3.5.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.36.4",
@@ -96,5 +96,5 @@
   "thi.ng": {
     "year": 2018
   },
-  "gitHead": "5929dd20497668496af13415cdf784a4d6f69aa3\n"
+  "gitHead": "b2ef5a1b8932d067af4ec2fc7da03d59d6868dc7\n"
 }