Skip to main content

Class: ArgumentStream

@sapphire/lexure.ArgumentStream

Constructors

constructor

new ArgumentStream(results)

Parameters

NameType
resultsParserResult

Defined in

lib/ArgumentStream.ts:9

Properties

results

Readonly results: ParserResult

Defined in

lib/ArgumentStream.ts:6


state

state: State

Defined in

lib/ArgumentStream.ts:7

Accessors

finished

get finished(): boolean

Whether or not all ordered parameters were used.

Returns

boolean

Defined in

lib/ArgumentStream.ts:17


length

get length(): number

The amount of ordered parameters.

Returns

number

Defined in

lib/ArgumentStream.ts:24


remaining

get remaining(): number

The remaining amount of ordered parameters.

Returns

number

Defined in

lib/ArgumentStream.ts:31


used

get used(): number

The amount of ordered parameters that have been used.

Returns

number

Defined in

lib/ArgumentStream.ts:38

Methods

filter

filter(predicate, from?): Option<string[]>

Parameters

NameType
predicate(value: string) => boolean
fromnumber

Returns

Option<string[]>

Defined in

lib/ArgumentStream.ts:497


filterAsync

filterAsync(predicate, from?): Promise<Option<string[]>>

Parameters

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

Returns

Promise<Option<string[]>>

Defined in

lib/ArgumentStream.ts:514


filterMap

filterMap<T>(predicate, from?): Option<T[]>

Type parameters

Name
T

Parameters

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

Returns

Option<T[]>

Defined in

lib/ArgumentStream.ts:531


filterMapAsync

filterMapAsync<T>(predicate, from?): Promise<Option<T[]>>

Type parameters

Name
T

Parameters

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

Returns

Promise<Option<T[]>>

Defined in

lib/ArgumentStream.ts:549


find

find(predicate, from?): Option<string>

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

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' }

Parameters

NameTypeDescription
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.

Defined in

lib/ArgumentStream.ts:248


findAsync

findAsync(predicate, from?): Promise<Option<string>>

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

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' }

Parameters

NameTypeDescription
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.

Defined in

lib/ArgumentStream.ts:282


findMap

findMap<T>(predicate, from?): Option<T>

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

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.

Type parameters

Name
T

Parameters

NameTypeDescription
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.

Defined in

lib/ArgumentStream.ts:317


findMapAsync

findMapAsync<T>(predicate, from?): Promise<Option<T>>

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

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.

Type parameters

Name
T

Parameters

NameTypeDescription
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.

Defined in

lib/ArgumentStream.ts:353


findParse

findParse<T, E>(predicate, from?): Result<T, E[]>

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

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.

Type parameters

Name
T
E

Parameters

NameTypeDescription
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.

Defined in

lib/ArgumentStream.ts:405


findParseAsync

findParseAsync<T, E>(predicate, from?): Promise<Result<T, E[]>>

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

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.

Type parameters

Name
T
E

Parameters

NameTypeDescription
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.

Defined in

lib/ArgumentStream.ts:437


flag

flag(...keys): boolean

Checks whether 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

Parameters

NameTypeDescription
...keysreadonly string[]The names of the flags to check.

Returns

boolean

Whether or not any of the flags were given.

Defined in

lib/ArgumentStream.ts:587


many

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

Retrieves multiple unused parameters.

Example

// Assume args are '1 2 3':

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

Example

// Assume args are '1 2 3':

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

Parameters

NameTypeDefault 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.

Defined in

lib/ArgumentStream.ts:478


option

option(...keys): Option<string>

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

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 {}

Parameters

NameTypeDescription
...keysreadonly string[]The names of the options to check.

Returns

Option<string>

The last value of the option, if any.

Defined in

lib/ArgumentStream.ts:610


options

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

Gets all values from all options.

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 {}

Parameters

NameTypeDescription
...keysreadonly string[]The names of the options to check.

Returns

Option<readonly string[]>

The values from all the options concatenated, if any.

Defined in

lib/ArgumentStream.ts:633


reset

reset(): void

Returns

void

Defined in

lib/ArgumentStream.ts:654


restore

restore(state): void

Parameters

NameType
stateState

Returns

void

Defined in

lib/ArgumentStream.ts:650


save

save(): State

Returns

State

Defined in

lib/ArgumentStream.ts:643


single

single(): Option<string>

Retrieves the value of the next unused ordered token.

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

Returns

Option<string>

The value, if any.

Defined in

lib/ArgumentStream.ts:64


singleMap

singleMap<T>(predicate, useAnyways?): Option<T>

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

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.

Type parameters

Name
T

Parameters

NameTypeDefault 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.

Defined in

lib/ArgumentStream.ts:107


singleMapAsync

singleMapAsync<T>(predicate, useAnyways?): Promise<Option<T>>

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

Note

This is an asynchronous variant of singleMap.

Typeparam

T The output type.

Type parameters

Name
T

Parameters

NameTypeDefault 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.

Defined in

lib/ArgumentStream.ts:133


singleParse

singleParse<T, E>(predicate, useAnyways?): Result<T, null | E>

Finds and retrieves the next unused parameter and transforms it.

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.

Type parameters

Name
T
E

Parameters

NameTypeDefault 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.

Defined in

lib/ArgumentStream.ts:185


singleParseAsync

singleParseAsync<T, E>(predicate, useAnyways?): Promise<Result<T, null | E>>

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

Note

This is an asynchronous variant of singleParse.

Typeparam

T The output type.

Typeparam

E The error type.

Type parameters

Name
T
E

Parameters

NameTypeDefault 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.

Defined in

lib/ArgumentStream.ts:212