Skip to main content

Class: ArgumentStream

Constructors

new ArgumentStream()

new ArgumentStream(results: ParserResult): ArgumentStream

Parameters

ParameterType
resultsParserResult

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

ParameterType
predicate(value: string) => boolean
fromnumber

Returns

Option<string[]>

Source

lib/ArgumentStream.ts:497


filterAsync()

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

Parameters

ParameterType
predicate(value: string) => Promise<boolean>
fromnumber

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

ParameterType
predicate(value: string) => Option<T>
fromnumber

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

ParameterType
predicate(value: string) => Promise<Option<T>>
fromnumber

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

ParameterTypeDescription
predicate(value: string) => booleanfind 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.
fromnumberThe 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

ParameterTypeDescription
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.
fromnumberThe 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

ParameterTypeDescription
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.
fromnumberThe 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

ParameterTypeDescription
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.
fromnumberThe 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

ParameterTypeDescription
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.
fromnumberThe 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

ParameterTypeDescription
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.
fromnumberThe 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

ParameterTypeDescription
...keysreadonly 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

ParameterTypeDefault valueDescription
limitnumberInfinityThe maximum amount of parameters to retrieve, defaults to Infinity.
fromnumberundefinedThe 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

ParameterTypeDescription
...keysreadonly 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

ParameterTypeDescription
...keysreadonly 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

ParameterType
stateState

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

ParameterTypeDefault valueDescription
predicate(value: string) => Option<T>undefinedThe predicate that determines the parameter's mapped value, or nothing if failed.
useAnywaysbooleanfalseWhether 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

ParameterTypeDefault valueDescription
predicate(value: string) => Promise<Option<T>>undefinedThe predicate that determines the parameter's mapped value, or nothing if failed.
useAnywaysbooleanfalseWhether 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

ParameterTypeDefault valueDescription
predicate(value: string) => Result<T, E>undefinedThe predicate that determines the parameter's transformed value, or nothing if failed.
useAnywaysbooleanfalseWhether 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

ParameterTypeDefault valueDescription
predicate(value: string) => Promise<Result<T, E>>undefinedThe predicate that determines the parameter's mapped value, or nothing if failed.
useAnywaysbooleanfalseWhether 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