@clerc/parser 1.2.1 → 1.3.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +50 -46
- package/dist/index.mjs +1 -1
- package/package.json +2 -4
package/dist/index.d.mts
CHANGED
|
@@ -19,9 +19,9 @@ type FlagDefaultValue<T = unknown> = T | FlagDefaultValueFunction<T>;
|
|
|
19
19
|
interface TypeFunction<T = unknown> {
|
|
20
20
|
(value: string): T;
|
|
21
21
|
/**
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
22
|
+
* Optional display name for the type, useful in help output. If provided,
|
|
23
|
+
* this will be shown instead of the function name.
|
|
24
|
+
*/
|
|
25
25
|
display?: string;
|
|
26
26
|
}
|
|
27
27
|
/**
|
|
@@ -37,35 +37,35 @@ type IgnoreFunction = (type: typeof KNOWN_FLAG | typeof UNKNOWN_FLAG | typeof PA
|
|
|
37
37
|
type TypeValue<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
|
|
38
38
|
type FlagRequiredOrDefault = RequireExactlyOneOrNone<{
|
|
39
39
|
/**
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
* The default value of the flag.
|
|
41
|
+
*/
|
|
42
42
|
default?: unknown;
|
|
43
43
|
/**
|
|
44
|
-
|
|
45
|
-
|
|
44
|
+
* Whether the flag is required.
|
|
45
|
+
*/
|
|
46
46
|
required?: boolean;
|
|
47
47
|
}, "default" | "required">;
|
|
48
48
|
type BaseFlagOptions<T extends TypeValue = TypeValue> = FlagRequiredOrDefault & {
|
|
49
49
|
/**
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
50
|
+
* The type constructor or a function to convert the string value. To
|
|
51
|
+
* support multiple occurrences of a flag (e.g., --file a --file b), wrap
|
|
52
|
+
* the type in an array: [String], [Number]. e.g., String, Number, [String],
|
|
53
|
+
* (val) => val.split(',')
|
|
54
|
+
*/
|
|
55
55
|
type: T;
|
|
56
56
|
/**
|
|
57
|
-
|
|
58
|
-
|
|
57
|
+
* Short flag alias (single character).
|
|
58
|
+
*/
|
|
59
59
|
short?: string;
|
|
60
60
|
};
|
|
61
61
|
type FlagOptions = (BaseFlagOptions<BooleanConstructor> & {
|
|
62
62
|
/**
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
63
|
+
* Whether to enable the `--no-<flag>` syntax to set the value to false.
|
|
64
|
+
* Only useful for boolean flags. When set on a non-boolean flag, a type
|
|
65
|
+
* error will be shown.
|
|
66
|
+
*
|
|
67
|
+
* @default true
|
|
68
|
+
*/
|
|
69
69
|
negatable?: boolean;
|
|
70
70
|
}) | (BaseFlagOptions & {
|
|
71
71
|
negatable?: never;
|
|
@@ -77,21 +77,21 @@ type FlagsDefinition = Record<string, FlagDefinitionValue>;
|
|
|
77
77
|
*/
|
|
78
78
|
interface ParserOptions<T extends FlagsDefinition = {}> {
|
|
79
79
|
/**
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
80
|
+
* Detailed configuration for flags. Supports the full object syntax or a type
|
|
81
|
+
* constructor as a shorthand. The key is the flag name (e.g., "file" for
|
|
82
|
+
* "--file").
|
|
83
|
+
*/
|
|
84
84
|
flags?: T;
|
|
85
85
|
/**
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
86
|
+
* Delimiters to split flag names and values.
|
|
87
|
+
*
|
|
88
|
+
* @default ["=", ":"]
|
|
89
|
+
*/
|
|
90
90
|
delimiters?: string[];
|
|
91
91
|
/**
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
92
|
+
* A callback function to conditionally stop parsing. When it returns true,
|
|
93
|
+
* parsing stops and remaining arguments are preserved in `ignored`.
|
|
94
|
+
*/
|
|
95
95
|
ignore?: IgnoreFunction;
|
|
96
96
|
}
|
|
97
97
|
type RawInputType = string | boolean;
|
|
@@ -105,33 +105,37 @@ interface ObjectInputType {
|
|
|
105
105
|
*/
|
|
106
106
|
interface ParsedResult<TFlags extends Record<string, any>> {
|
|
107
107
|
/**
|
|
108
|
-
|
|
109
|
-
|
|
108
|
+
* Positional arguments or commands.
|
|
109
|
+
*/
|
|
110
110
|
parameters: string[];
|
|
111
111
|
/**
|
|
112
|
-
|
|
113
|
-
|
|
112
|
+
* Arguments after the `--` delimiter.
|
|
113
|
+
*/
|
|
114
114
|
doubleDash: string[];
|
|
115
115
|
/**
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
116
|
+
* The parsed flags. This is a strongly-typed object whose structure is
|
|
117
|
+
* inferred from the `flags` configuration in ParserOptions.
|
|
118
|
+
*/
|
|
119
119
|
flags: TFlags;
|
|
120
120
|
/**
|
|
121
|
-
|
|
122
|
-
|
|
121
|
+
* The raw command-line arguments.
|
|
122
|
+
*/
|
|
123
123
|
raw: string[];
|
|
124
124
|
/**
|
|
125
|
-
|
|
126
|
-
|
|
125
|
+
* Unknown flags encountered during parsing.
|
|
126
|
+
*/
|
|
127
127
|
unknown: Record<string, RawInputType>;
|
|
128
128
|
/**
|
|
129
|
-
|
|
130
|
-
|
|
129
|
+
* Raw arguments for unknown flags (original string form).
|
|
130
|
+
*/
|
|
131
|
+
rawUnknown: string[];
|
|
132
|
+
/**
|
|
133
|
+
* Arguments that were not parsed due to ignore callback.
|
|
134
|
+
*/
|
|
131
135
|
ignored: string[];
|
|
132
136
|
/**
|
|
133
|
-
|
|
134
|
-
|
|
137
|
+
* List of required flags that were not provided.
|
|
138
|
+
*/
|
|
135
139
|
missingRequiredFlags: string[];
|
|
136
140
|
}
|
|
137
141
|
type InferFlagDefault<T extends FlagDefinitionValue, Fallback> = T extends {
|
package/dist/index.mjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{camelCase as e,hasOwn as t,looseIsArray as n,resolveValue as r}from"@clerc/utils";var i=class extends Error{constructor(e){super(`Invalid schema: ${e}`),this.name=`InvalidSchemaError`}};const a=`known-flag`,o=`unknown-flag`,s=`parameter`;function c(e,t,n,r,i,c){let l=0,u=!1,d=e.length,f={current:``,index:0,hasNext:!1,next:``,shouldIgnore:e=>i?i(n(e)?r(e)?a:o:s,e):!1,
|
|
1
|
+
import{camelCase as e,hasOwn as t,looseIsArray as n,resolveValue as r}from"@clerc/utils";var i=class extends Error{constructor(e){super(`Invalid schema: ${e}`),this.name=`InvalidSchemaError`}};const a=`known-flag`,o=`unknown-flag`,s=`parameter`;function c(e,t,n,r,i,c){let l=0,u=!1,d=e.length,f={current:``,index:0,hasNext:!1,next:``,shouldIgnore:e=>i?i(n(e)?r(e)?a:o:s,e):!1,advance:()=>f.shouldIgnore(f.next)?(f.exit(),``):(l++,p(),e[l]),advanceUnknown:()=>{let e=f.advance();return e&&t.rawUnknown.push(e),e},markUnknown:()=>{t.rawUnknown.push(f.current)},exit:(n=!0)=>{u||=(n&&t.ignored.push(...e.slice(l+1)),!0)}};function p(){f.current=e[l],f.index=l,f.hasNext=l+1<d,f.next=f.hasNext?e[l+1]:``}for(l=0;l<d&&!u;l++)p(),c(f)}const l={delimiters:[`=`,`:`]},u=(e={})=>({...l,...e}),d=e=>typeof e==`function`||n(e)?{type:e}:e;function f(t,n){let r=new Map,a=new Map,o=e=>t.some(t=>e.includes(t))||e.includes(` `)||e.includes(`.`);function s(e,t){let n=`Flag "${e}"`;if(Array.isArray(t.type)&&t.type.length>1)throw new i(`${n} has an invalid type array. Only single-element arrays are allowed to denote multiple occurrences.`);if(e.length<2)throw new i(`${n} name must be at least 2 characters long.`);let r=[e];if(t.short){if(t.short.length!==1)throw new i(`${n} short flag must be exactly 1 character long.`);r.push(t.short)}if(r.some(o))throw new i(`${n} contains reserved characters, which are used as delimiters.`);if(t.required&&t.default!==void 0)throw new i(`${n} cannot be both required and have a default value.`)}for(let[t,i]of Object.entries(n)){let n=d(i);s(t,n),r.set(t,n),a.set(t,t),a.set(e(t),t),n.short&&a.set(n.short,t)}return{configs:r,aliases:a}}const p=(e,t)=>Array.isArray(e)&&e[0]===t;function m(e){if(n(e))return p(e,Boolean)?0:[];if(e===Boolean)return!1;if(e===Object)return{}}const h=e=>e>=65&&e<=90||e>=97&&e<=122,g=e=>e>=48&&e<=57;function _(e,t,r,i){let{type:a}=i;n(a)?p(a,Boolean)?e[t]=(e[t]??0)+1:(e[t]??=[]).push(a[0](r)):e[t]=a(r)}function v(e){return e===`true`||e===``?!0:e===`false`?!1:e}function y(e,t,n){let r=t.split(`.`),i=e;for(let e=0;e<r.length-1;e++){let t=r[e];i[t]??={},i=i[t]}let a=r[r.length-1];i[a]=n}function b(e,n,r){let i=n.split(`.`),a=e;for(let e=0;e<i.length-1;e++){let n=i[e];if(t(a,n)&&(typeof a[n]!=`object`||a[n]===null))return;a[n]??={},a=a[n]}let o=i[i.length-1];if(t(a,o)){let e=a[o];Array.isArray(e)?e.push(r):a[o]=[e,r]}else a[o]=r}function x(e,t){let n=-1,r=0;for(let i of t){let t=e.indexOf(i);t!==-1&&(n===-1||t<n)&&(n=t,r=i.length)}return n===-1?{rawName:e,rawValue:void 0,hasSep:!1}:{rawName:e.slice(0,n),rawValue:e.slice(n+r),hasSep:!0}}const S=`--`;function C(t={}){let{flags:n={},delimiters:i,ignore:a}=u(t),{configs:o,aliases:s}=f(i,n);function l(t,n=!1){let r=t.indexOf(`.`),i=r===-1?t:t.slice(0,r),a=s.get(i);if(!a&&(a=s.get(e(i)),!a))return;let c=o.get(a);if(!(!n&&c.short===i))return{key:a,config:c,path:r===-1?void 0:t.slice(r+1)}}function d(e){if(!e.startsWith(`no`))return;let t=e[2]===`-`?e.slice(3):e.length>2&&e.charCodeAt(2)>=65&&e.charCodeAt(2)<=90?e[2].toLowerCase()+e.slice(3):``;if(t){let e=l(t);if(e?.config.type===Boolean&&e.config.negatable!==!1)return e}}function y(e){if(e.charCodeAt(0)!==45)return!1;let t=e.length;if(t<2)return!1;let n=e.charCodeAt(1);if(h(n))return!0;if(g(n)){let t=n!==45;return!!l(t?e[1]:e.slice(2),t)}return n===45&&t>2?h(e.charCodeAt(2)):!1}function S(e){if(e.charCodeAt(1)===45){let{rawName:t}=x(e.slice(2),i);return!!(l(t,!1)||d(t))}let t=e.slice(1);for(let e of t)if(!l(e,!0))return!1;return!0}return{parse:t=>{let n={parameters:[],doubleDash:[],flags:{},raw:t,unknown:{},rawUnknown:[],ignored:[],missingRequiredFlags:[]};c(t,n,y,S,a,({advance:r,advanceUnknown:a,current:o,exit:s,hasNext:c,index:u,markUnknown:f,next:m,shouldIgnore:h})=>{if(o===`--`){n.doubleDash.push(...t.slice(u+1)),s(!1);return}if(h(o)){n.ignored.push(o),s();return}if(!y(o)){n.parameters.push(o);return}let g=!o.startsWith(`--`),S=o.slice(g?1:2);if(g){let e=S.length,t=!1;for(let i=0;i<e;i++){let a=S[i],o=l(a,!0);if(!o){n.unknown[a]=!0,t||=(f(),!0);continue}let{key:s,config:u}=o,d=u.type;if(d===Boolean||p(d,Boolean))_(n.flags,s,`true`,u);else if(i+1<e){_(n.flags,s,S.slice(i+1),u);break}else{let e=c&&!y(m)?r():``;_(n.flags,s,e,u)}}}else{let{rawName:t,rawValue:o,hasSep:s}=x(S,i),u=l(t),p=!1;if(!u){let e=d(t);e&&(u=e,p=!0)}if(!u){let r=e(t);if(f(),s)n.unknown[r]=o;else if(c&&!y(m)){let e=a();n.unknown[r]=e||!0}else n.unknown[r]=!0;return}let{key:h,config:g,path:C}=u;if(C){if(g.type===Object){n.flags[h]??={};let e=s?o:c&&!y(m)?r():``;b(n.flags[h],C,v(e))}}else if(g.type===Boolean){let e=s?o!==`false`:!0;n.flags[h]=p?!e:e}else{let e=s?o:c&&!y(m)?r():``;_(n.flags,h,e,g)}}});for(let[e,t]of o.entries())n.flags[e]===void 0&&(t.default===void 0?t.required?n.missingRequiredFlags.push(e):n.flags[e]=m(t.type):n.flags[e]=r(t.default));return n}}}const w=(e,t={})=>C(t).parse(e);export{S as DOUBLE_DASH,i as InvalidSchemaError,a as KNOWN_FLAG,s as PARAMETER,o as UNKNOWN_FLAG,b as appendDotValues,v as coerceObjectValue,C as createParser,m as inferDefault,w as parse,y as setDotValues};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clerc/parser",
|
|
3
|
-
"version": "1.2
|
|
3
|
+
"version": "1.3.0-beta.2",
|
|
4
4
|
"author": "Ray <i@mk1.io> (https://github.com/so1ve)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Clerc parser",
|
|
@@ -30,8 +30,6 @@
|
|
|
30
30
|
".": "./dist/index.mjs",
|
|
31
31
|
"./package.json": "./package.json"
|
|
32
32
|
},
|
|
33
|
-
"main": "./dist/index.mjs",
|
|
34
|
-
"module": "./dist/index.mjs",
|
|
35
33
|
"types": "./dist/index.d.mts",
|
|
36
34
|
"files": [
|
|
37
35
|
"dist"
|
|
@@ -40,7 +38,7 @@
|
|
|
40
38
|
"access": "public"
|
|
41
39
|
},
|
|
42
40
|
"dependencies": {
|
|
43
|
-
"@clerc/utils": "1.2
|
|
41
|
+
"@clerc/utils": "1.3.0-beta.2"
|
|
44
42
|
},
|
|
45
43
|
"devDependencies": {
|
|
46
44
|
"@types/minimist": "^1.2.5",
|