Class: ArgumentStream

Constructors

new ArgumentStream()

new ArgumentStream(results: ParserResult): ArgumentStream

Parameters

Parameter	Type
results	ParserResult

Returns

ArgumentStream

Source

lib/ArgumentStream.ts:9

Properties

results

readonly results: ParserResult

Source

lib/ArgumentStream.ts:6

---

state

state: State

Source

lib/ArgumentStream.ts:7

Accessors

finished

get finished(): boolean

Whether or not all ordered parameters were used.

Returns

boolean

Source

lib/ArgumentStream.ts:17

---

length

get length(): number

The amount of ordered parameters.

Returns

number

Source

lib/ArgumentStream.ts:24

---

remaining

get remaining(): number

The remaining amount of ordered parameters.

Returns

number

Source

lib/ArgumentStream.ts:31

---

used

get used(): number

The amount of ordered parameters that have been used.

Returns

number

Source

lib/ArgumentStream.ts:38

Methods

filter()

filter(predicate: (value: string) => boolean, from: number): Option<string[]>

Parameters

Parameter	Type
predicate	(value: string) => boolean
from	number

Returns

Option<string[]>

Source

lib/ArgumentStream.ts:497

---

filterAsync()

filterAsync(predicate: (value: string) => Promise<boolean>, from: number): Promise<Option<string[]>>

Parameters

Parameter	Type
predicate	(value: string) => Promise<boolean>
from	number

Returns

Promise<Option<string[]>>

Source

lib/ArgumentStream.ts:514

---

filterMap()

filterMap<T>(predicate: (value: string) => Option<T>, from: number): Option<T[]>

Type parameters

Type parameter
T

Parameters

Parameter	Type
predicate	(value: string) => Option<T>
from	number

Returns

Option<T[]>

Source

lib/ArgumentStream.ts:531

---

filterMapAsync()

filterMapAsync<T>(predicate: (value: string) => Promise<Option<T>>, from: number): Promise<Option<T[]>>

Type parameters

Type parameter
T

Parameters

Parameter	Type
predicate	(value: string) => Promise<Option<T>>
from	number

Returns

Promise<Option<T[]>>

Source

lib/ArgumentStream.ts:549

---

find()

find(predicate: (value: string) => boolean, from: number): Option<string>

Returns the value of the first element in the array within Option.some where predicate returns true, and Option.none otherwise.

Parameters

Parameter	Type	Description
predicate	(value: string) => boolean	find calls predicate once for each unused ordered parameter, in ascending order, until it finds one where predicate returns true. If such an element is found, find immediately returns a Option.some with that element value. Otherwise, find returns Option.none.
from	number	The position where to start looking for unused parameters, defaults to current position.

Returns

Option<string>

The found parameter's value.

Note

This does not support asynchronous results, refer to findAsync.

Example

// Suppose args are from 'ba aa cc'.

console.log(args.find((value) => value.startsWith('a')));
// Some { value: 'aa' }

Source

lib/ArgumentStream.ts:248

---

findAsync()

findAsync(predicate: (value: string) => Promise<boolean>, from: number): Promise<Option<string>>

Returns the value of the first element in the array within Option.some where predicate returns true, and Option.none otherwise.

Parameters

Parameter	Type	Description
predicate	(value: string) => Promise<boolean>	find calls predicate once for each unused ordered parameter, in ascending order, until it finds one where predicate returns true. If such an element is found, find immediately returns a Option.some with that element value. Otherwise, find returns Option.none.
from	number	The position where to start looking for unused parameters, defaults to current position.

Returns

Promise<Option<string>>

The found parameter's value.

Note

This is an asynchronous variant of find.

Example

// Suppose args are from 'ba aa cc'.

console.log(args.find((value) => value.startsWith('a')));
// Some { value: 'aa' }

Source

lib/ArgumentStream.ts:282

---

findMap()

findMap<T>(predicate: (value: string) => Option<T>, from: number): Option<T>

Returns the value of the first element in the array within Option.some where predicate returns Some, and Option.none otherwise.

Type parameters

Type parameter
T

Parameters

Parameter	Type	Description
predicate	(value: string) => Option<T>	find calls predicate once for each unused ordered parameter, in ascending order, until it finds one where predicate returns Some. If such an element is found, find immediately returns the returned value. Otherwise, find returns Option.none.
from	number	The position where to start looking for unused parameters, defaults to current position.

Returns

Option<T>

The found parameter's value.

Note

This does not support asynchronous results, refer to findMapAsync.

Example

// Suppose args are from 'ba aa cc'.

console.log(args.find((value) => value.startsWith('a')));
// Some { value: 'aa' }

Typeparam

T The output type.

Source

lib/ArgumentStream.ts:317

---

findMapAsync()

findMapAsync<T>(predicate: (value: string) => Promise<Option<T>>, from: number): Promise<Option<T>>

Returns the value of the first element in the array within Option.some where predicate returns Some, and Option.none otherwise.

Type parameters

Type parameter
T

Parameters

Parameter	Type	Description
predicate	(value: string) => Promise<Option<T>>	find calls predicate once for each unused ordered parameter, in ascending order, until it finds one where predicate returns Some. If such an element is found, find immediately returns the returned value. Otherwise, find returns Option.none.
from	number	The position where to start looking for unused parameters, defaults to current position.

Returns

Promise<Option<T>>

The found parameter's value.

Note

This is an asynchronous variant of findMap.

Example

// Suppose args are from 'ba aa cc'.

console.log(args.find((value) => value.startsWith('a')));
// Some { value: 'aa' }

Typeparam

T The output type.

Source

lib/ArgumentStream.ts:353

---

findParse()

findParse<T, E>(predicate: (value: string) => Result<T, E>, from: number): Result<T, E[]>

Finds and retrieves the first unused parameter that could be transformed.

Type parameters

Type parameter
T
E

Parameters

Parameter	Type	Description
predicate	(value: string) => Result<T, E>	findParse calls predicate once for each unused ordered parameter, in ascending order, until it finds one where predicate returns Ok. If such an element is found, findParse immediately returns the returned value. Otherwise, findParse returns Result.Err with all the returned errors.
from	number	The position where to start looking for unused parameters, defaults to current position.

Returns

Result<T, E[]>

The found parameter's value.

Note

This is a variant of findMap that returns the errors on failure.

Note

This does not support asynchronous results, refer to findParseAsync.

Example

const parse = (value) => {
  const number = Number(value);
  return Number.isNaN(number)
    ? Result.err(`Could not parse ${value} to a number`)
    : Result.ok(number);
};

// Suppose args are from 'ba 1 cc'.

console.log(args.findParse(parse));
// Ok { value: 1 }

console.log(args.findParse(parse));
// Err {
//   error: [
//     'Could not parse ba to a number',
//     'Could not parse cc to a number'
//   ]
// }

Typeparam

T The output type.

Typeparam

E The error type.

Source

lib/ArgumentStream.ts:405

---

findParseAsync()

findParseAsync<T, E>(predicate: (value: string) => Promise<Result<T, E>>, from: number): Promise<Result<T, E[]>>

Finds and retrieves the first unused parameter that could be transformed.

Type parameters

Type parameter
T
E

Parameters

Parameter	Type	Description
predicate	(value: string) => Promise<Result<T, E>>	findParse calls predicate once for each unused ordered parameter, in ascending order, until it finds one where predicate returns Ok. If such an element is found, findParse immediately returns the returned value. Otherwise, findParse returns Result.Err with all the returned errors.
from	number	The position where to start looking for unused parameters, defaults to current position.

Returns

Promise<Result<T, E[]>>

The found parameter's value.

Note

This is a variant of findMapAsync that returns the errors on failure.

Note

This is an asynchronous variant of findParse.

Typeparam

T The output type.

Typeparam

E The error type.

Source

lib/ArgumentStream.ts:437

---

flag()

flag(...keys: readonly string[]): boolean

Checks whether any of the flags were given.

Parameters

Parameter	Type	Description
...keys	readonly string[]	The names of the flags to check.

Returns

boolean

Whether or not any of the flags were given.

Example

// Assume args are '--f --g':

console.log(args.flag('f'));
// true

console.log(args.flag('g', 'h'));
// true

console.log(args.flag('h'));
// false

Source

lib/ArgumentStream.ts:587

---

many()

many(limit: number, from: number): Option <Parameter[]>

Retrieves multiple unused parameters.

Parameters

Parameter	Type	Default value	Description
limit	number	Infinity	The maximum amount of parameters to retrieve, defaults to Infinity.
from	number	undefined	The position where to start looking for unused parameters, defaults to current position.

Returns

Option <Parameter[]>

The unused parameters within the range.

Examples

// Assume args are '1 2 3':

console.log(join(args.many().unwrap()));
// '1 2 3'

// Assume args are '1 2 3':

console.log(join(args.many(2).unwrap()));
// '1 2'

Source

lib/ArgumentStream.ts:478

---

option()

option(...keys: readonly string[]): Option<string>

Gets the last value of any option. When there are multiple names, the last value of the last found name is given.

Parameters

Parameter	Type	Description
...keys	readonly string[]	The names of the options to check.

Returns

Option<string>

The last value of the option, if any.

Example

// Assume args are '--a=1 --b=2 --c=3'.
console.log(args.option('a'));
// Some { value: '1' }

console.log(args.option('b', 'c'));
// Some { value: '3' }

console.log(args.option('d'));
// None {}

Source

lib/ArgumentStream.ts:610

---

options()

options(...keys: readonly string[]): Option<readonly string[]>

Gets all values from all options.

Parameters

Parameter	Type	Description
...keys	readonly string[]	The names of the options to check.

Returns

Option<readonly string[]>

The values from all the options concatenated, if any.

Example

// Assume args are '--a=1 --a=1 --b=2 --c=3'.
console.log(args.option('a'));
// Some { value: ['1', '1'] }

console.log(args.option('b', 'c'));
// Some { value: ['2', '3'] }

console.log(args.option('d'));
// None {}

Source

lib/ArgumentStream.ts:633

---

reset()

reset(): void

Returns

void

Source

lib/ArgumentStream.ts:654

---

restore()

restore(state: State): void

Parameters

Parameter	Type
state	State

Returns

void

Source

lib/ArgumentStream.ts:650

---

save()

save(): State

Returns

State

Source

lib/ArgumentStream.ts:643

---

single()

single(): Option<string>

Retrieves the value of the next unused ordered token.

Returns

Option<string>

The value, if any.

Example

// Assume args are '1 2 3':

console.log(args.single());
// Ok { value: '1' }

console.log(args.single());
// Ok { value: '2' }

console.log(args.single());
// Ok { value: '3' }

console.log(args.single());
// None

Source

lib/ArgumentStream.ts:64

---

singleMap()

singleMap<T>(predicate: (value: string) => Option<T>, useAnyways: boolean): Option<T>

Retrieves the value of the next unused ordered token, but only if it could be transformed.

Type parameters

Type parameter
T

Parameters

Parameter	Type	Default value	Description
predicate	(value: string) => Option<T>	undefined	The predicate that determines the parameter's mapped value, or nothing if failed.
useAnyways	boolean	false	Whether to consider the parameter used even if the mapping failed. Defaults to false.

Returns

Option<T>

The mapped value, if any.

Note

This does not support asynchronous results, refer to singleMapAsync.

Example

const parse = (value) => {
  const number = Number(value);
  return Number.isNaN(number) ? Option.none : Option.some(number);
};

// Assume args are '1 2 3':

console.log(args.singleMap(parse));
// Some { value: 1 }

console.log(args.singleMap(parse));
// Some { value: 2 }

console.log(args.singleMap(parse));
// Some { value: 3 }

console.log(args.singleMap(parse));
// None

Typeparam

T The output type.

Source

lib/ArgumentStream.ts:107

---

singleMapAsync()

singleMapAsync<T>(predicate: (value: string) => Promise<Option<T>>, useAnyways: boolean): Promise<Option<T>>

Retrieves the value of the next unused ordered token, but only if it could be transformed.

Type parameters

Type parameter
T

Parameters

Parameter	Type	Default value	Description
predicate	(value: string) => Promise<Option<T>>	undefined	The predicate that determines the parameter's mapped value, or nothing if failed.
useAnyways	boolean	false	Whether to consider the parameter used even if the mapping failed. Defaults to false.

Returns

Promise<Option<T>>

The mapped value, if any.

Note

This is an asynchronous variant of singleMap.

Typeparam

T The output type.

Source

lib/ArgumentStream.ts:133

---

singleParse()

singleParse<T, E>(predicate: (value: string) => Result<T, E>, useAnyways: boolean): Result<T, null | E>

Finds and retrieves the next unused parameter and transforms it.

Type parameters

Type parameter
T
E

Parameters

Parameter	Type	Default value	Description
predicate	(value: string) => Result<T, E>	undefined	The predicate that determines the parameter's transformed value, or nothing if failed.
useAnyways	boolean	false	Whether to consider the parameter used even if the transformation failed. Defaults to false.

Returns

Result<T, null | E>

The transformed value, if any.

Note

This is a variant of findMap that returns the errors on failure.

Note

This does not support asynchronous results, refer to singleParseAsync.

Example

const parse = (value) => {
  const number = Number(value);
  return Number.isNaN(number)
    ? Result.err(`Could not parse ${value} to a number`)
    : Result.ok(number);
};

// Assume args are '1 2 3':

console.log(args.singleParse(parse));
// Ok { value: 1 }

console.log(args.singleParse(parse));
// Ok { value: 2 }

console.log(args.singleParse(parse));
// Ok { value: 3 }

console.log(args.singleParse(parse));
// Err { error: null }

Typeparam

T The output type.

Typeparam

E The error type.

Source

lib/ArgumentStream.ts:185

---

singleParseAsync()

singleParseAsync<T, E>(predicate: (value: string) => Promise<Result<T, E>>, useAnyways: boolean): Promise<Result<T, null | E>>

Retrieves the value of the next unused ordered token, but only if it could be transformed.

Type parameters

Type parameter
T
E

Parameters

Parameter	Type	Default value	Description
predicate	(value: string) => Promise<Result<T, E>>	undefined	The predicate that determines the parameter's mapped value, or nothing if failed.
useAnyways	boolean	false	Whether to consider the parameter used even if the mapping failed. Defaults to false.

Returns

Promise<Result<T, null | E>>

The mapped value, if any.

Note

This is an asynchronous variant of singleParse.

Typeparam

T The output type.

Typeparam

E The error type.

Source

lib/ArgumentStream.ts:212