2.3.63 • Published 4 months ago

@thi.ng/args v2.3.63

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
4 months ago

args

npm version npm downloads Twitter Follow

This project is part of the @thi.ng/umbrella monorepo.

About

Declarative, functional & typechecked CLI argument/options parser, value coercions etc..

Includes built-in support for the following argument types (of course custom arg types are supported too):

Argument typeMultipleExampleResult
Flag--force, -fforce: true
String--foo barfoo: "bar"
Float/int/hex--bg ff997fbg: 16750975
Enum--type pngtype: "png"
KV pairs--define foo=bardefine: { foo: "bar" }
KV multi pairs-D foo=bar -D foo=bazdefine: { foo: ["bar", "baz"] }
JSON--config '{"foo": [23]}'config: { foo: [23] }
Fixed size tuple--size 640x480size: { value: [640, 480] }

If multiple values/repetitions are allowed for an argument, the values will be collected into an array (apart from KV pairs, which will yield an object). Furthermore, for multi-args, an optional delimiter can be specified to extract individual values, e.g. -a 1,2,3 equals -a 1 -a 2 -a 3

Status

STABLE - used in production

Search or submit any issues for this package

Installation

yarn add @thi.ng/args

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/args"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const args = await import("@thi.ng/args");

Package sizes (gzipped, pre-treeshake): ESM: 2.44 KB

Dependencies

API

Generated API docs

Basic usage

type ImgType = "png" | "jpg" | "gif" | "tiff";

// CLI args will be validated against this interface
interface TestArgs {
    configPath?: string;
    force: boolean;
    bg: number;
    type: ImgType;
    size?: Tuple<number>;
    pos?: Tuple<number>;
    xtra?: { a: number; b: string };
    define?: KVDict;
}

// arg specifications
const specs: Args<TestArgs> = {
    // string arg
    configPath: string({
        alias: "c",
        hint: "PATH",
        desc: "Config file path (CLI args always take precedence over those settings)",
    }),
    // boolean flag (default: false)
    force: flag({
        alias: "f",
        desc: "Force operation",
        // side effect & predicate
        // parsing only continues if fn returns true
        fn: (_) => (console.log("force mode enabled"), true),
    }),
    // hex int value
    bg: hex({
        desc: "Background color",
        // mandatory args require a `default` value and/or `optional: false`
        default: 0xffffff,
    }),
    // enum value (mandatory)
    type: oneOf(["png", "jpg", "gif", "tiff"], {
        alias: "t",
        desc: "Image type",
        // mandatory args require a `default` value and/or `optional: false`
        optional: false,
    }),
    // fixed size numeric tuple w/ `x` as delimiter
    // size: tuple(coerceInt, 2, { hint: "WxH", desc: "Target size" }, "x"),
    // syntax sugar for above:
    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" }),
    // JSON string arg
    xtra: json({
        alias: "x",
        desc: "Extra options",
    }),
    // key-value pairs parsed into an object
    define: kvPairs({ alias: "D", desc: "Define dict entry" }),
};

try {
    // parse argv w/ above argument specs & default options
    // (by default usage is shown if error occurs)
    const args = parse(specs, process.argv);
    console.log(args);
} catch (_) {}

Generate & display help

Usage information can be generated via usage() and is automatically triggered via the special --help option (configurable, see ParseOpts).

Each arg can be associated with arbitrary group IDs, which are then used to segment usage output. By default, flag() args are assigned to a "flags" group, all others to "main". The default output order too is ["flags", "main"], but can be configured via a group option given an arg spec or factory function.

By default, ANSI colors are used to format the result string of usage(), but can be disabled (see UsageOpts).

ts-node index.ts --help

-f, --force                     Force operation

--bg HEX                        Background color
-c PATH, --config-path PATH     Config file path (CLI args always take
                                precedence over those settings)
-D key=val, --define key=val    [multiple] Define dict entry
--pos N,N                       Lat/Lon
--size WxH                      Target size
-t ID, --type ID                [required] Image type: 'png', 'jpg', 'gif',
                                'tiff'
-x JSON, --xtra JSON            Extra options

Parsing, value coercions & side effects

The below invocation demonstrates how the various argument types are handled & represented in the result. Parsing stops with the first non-argument value (here sourcefile.png) and the remaining values are made available via rest in the result object.

ts-node index.ts \
    -f -t png --bg ff00ff --size 640x480 \
    -D author=toxi -D date=2018-03-24 \
    --xtra '{"foo": [23]}' \
    sourcefile.png

# force mode enabled
# {
#   result: {
#     force: true,
#     type: 'png',
#     bg: 16711935,
#     size: Tuple { value: [640, 480] }
#     define: { author: 'toxi', date: '2018-03-24' },
#     xtra: { foo: [23] },
#   },
#   index: 15,
#   rest: [ 'sourcefile.png' ],
#   done: false
# }

Authors

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-args,
  title = "@thi.ng/args",
  author = "Karsten Schmidt",
  note = "https://thi.ng/args",
  year = 2018
}

License

© 2018 - 2021 Karsten Schmidt // Apache Software License 2.0

2.3.63

4 months ago

2.3.62

4 months ago

2.3.60

4 months ago

2.3.61

4 months ago

2.3.57

5 months ago

2.3.56

5 months ago

2.3.59

5 months ago

2.3.58

5 months ago

2.3.55

5 months ago

2.3.54

5 months ago

2.3.53

6 months ago

2.3.52

6 months ago

2.3.51

6 months ago

2.3.50

7 months ago

2.3.49

7 months ago

2.3.48

8 months ago

2.3.47

8 months ago

2.3.46

8 months ago

2.3.45

8 months ago

2.3.39

12 months ago

2.3.38

12 months ago

2.3.35

1 year ago

2.3.34

1 year ago

2.3.37

12 months ago

2.3.36

12 months ago

2.3.42

11 months ago

2.3.41

11 months ago

2.3.44

9 months ago

2.3.43

10 months ago

2.3.40

11 months ago

2.3.33

1 year ago

2.3.32

1 year ago

2.3.31

1 year ago

2.3.30

1 year ago

2.3.29

1 year ago

2.3.28

1 year ago

2.3.27

1 year ago

2.3.26

1 year ago

2.3.25

1 year ago

2.3.24

1 year ago

2.3.23

1 year ago

2.3.22

1 year ago

2.3.21

1 year ago

2.3.20

1 year ago

2.3.19

1 year ago

2.3.18

1 year ago

2.3.17

1 year ago

2.3.16

1 year ago

2.3.15

1 year ago

2.3.14

1 year ago

2.3.13

1 year ago

2.3.12

1 year ago

2.3.11

1 year ago

2.3.8

1 year ago

2.3.7

1 year ago

2.3.9

1 year ago

2.3.10

1 year ago

2.3.6

1 year ago

2.3.5

1 year ago

2.3.4

2 years ago

2.3.3

2 years ago

2.3.2

2 years ago

2.3.0

2 years ago

2.3.1

2 years ago

2.2.46

2 years ago

2.2.45

2 years ago

2.2.44

2 years ago

2.2.28

2 years ago

2.2.29

2 years ago

2.2.39

2 years ago

2.2.37

2 years ago

2.2.38

2 years ago

2.2.35

2 years ago

2.2.36

2 years ago

2.2.33

2 years ago

2.2.34

2 years ago

2.2.31

2 years ago

2.2.32

2 years ago

2.2.30

2 years ago

2.2.42

2 years ago

2.2.43

2 years ago

2.2.40

2 years ago

2.2.27

2 years ago

2.2.26

2 years ago

2.2.25

2 years ago

2.2.24

2 years ago

2.2.22

2 years ago

2.2.23

2 years ago

2.2.20

2 years ago

2.2.21

2 years ago

2.2.17

2 years ago

2.2.19

2 years ago

2.2.15

3 years ago

2.2.16

2 years ago

2.2.13

3 years ago

2.2.14

3 years ago

2.2.12

3 years ago

2.2.3

3 years ago

2.2.5

3 years ago

2.2.4

3 years ago

2.2.11

3 years ago

2.2.7

3 years ago

2.2.6

3 years ago

2.2.10

3 years ago

2.2.9

3 years ago

2.2.8

3 years ago

2.2.2

3 years ago

2.2.1

3 years ago

2.2.0

3 years ago

2.1.14

3 years ago

2.1.12

3 years ago

2.1.13

3 years ago

2.1.10

3 years ago

2.1.11

3 years ago

2.1.8

3 years ago

2.1.7

3 years ago

2.1.9

3 years ago

2.1.6

3 years ago

2.1.5

3 years ago

2.1.2

4 years ago

2.1.1

4 years ago

2.1.4

4 years ago

2.1.3

4 years ago

2.0.8

4 years ago

2.1.0

4 years ago

2.0.7

4 years ago

2.0.4

4 years ago

2.0.6

4 years ago

2.0.3

4 years ago

2.0.1

4 years ago

2.0.0

4 years ago

1.1.1

4 years ago

1.1.0

4 years ago

1.0.4

4 years ago

1.0.2

4 years ago

1.0.1

4 years ago

1.0.3

4 years ago

0.7.2

4 years ago

0.7.1

4 years ago

0.7.0

4 years ago

0.6.0

4 years ago

0.5.1

4 years ago

0.5.0

4 years ago

0.4.2

4 years ago

0.4.1

4 years ago

0.4.0

4 years ago

0.3.1

4 years ago

0.3.0

4 years ago

0.2.7

4 years ago

0.2.6

4 years ago

0.2.5

4 years ago

0.2.1

4 years ago

0.2.0

4 years ago

0.1.0

4 years ago