@sapphire/lexure - npm Package Compare versions

Comparing version 1.0.2-next.a963396.0 to 1.0.2-next.b2486c2.0

dist/index.d.ts

@@ -1,13 +0,499 @@
-export * from './lib/ArgumentStream';
-export * from './lib/lexer/Lexer';
-export * from './lib/lexer/streams/parameters/BaseParameter';
-export * from './lib/lexer/streams/parameters/QuotedParameter';
-export * from './lib/lexer/streams/parameters/WordParameter';
-export * from './lib/lexer/streams/ParameterStream';
-export * from './lib/lexer/streams/raw/TokenStream';
-export * from './lib/parser/Parser';
-export * from './lib/parser/ParserResult';
-export * from './lib/parser/strategies/EmptyStrategy';
-export * from './lib/parser/strategies/IUnorderedStrategy';
-export * from './lib/parser/strategies/PrefixedStrategy';
-//# sourceMappingURL=index.d.ts.map
+import { Option, Result } from '@sapphire/result';
+
+declare class Lexer {
+    readonly quotes: readonly [open: string, close: string][];
+    readonly separator: string;
+    constructor(options?: Lexer.Options);
+    run(input: string): ParameterStream;
+    raw(input: string): TokenStream;
+}
+declare namespace Lexer {
+    interface Options {
+        separator?: string;
+        quotes?: readonly [open: string, close: string][];
+    }
+}
+
+declare class TokenStream implements Iterable<Token> {
+    private readonly input;
+    private readonly quotes;
+    private readonly separator;
+    private position;
+    constructor(lexer: Lexer, input: string);
+    get finished(): boolean;
+    [Symbol.iterator](): Iterator<Token>;
+    private getPossibleSeparator;
+    private getPossibleQuotedArgument;
+    private getParameter;
+}
+declare enum TokenType {
+    Parameter = 0,
+    Quoted = 1,
+    Separator = 2
+}
+declare type Token = WordToken | QuotedToken | SeparatorToken;
+interface WordToken {
+    readonly type: TokenType.Parameter;
+    readonly value: string;
+}
+interface QuotedToken {
+    readonly type: TokenType.Quoted;
+    readonly value: string;
+    readonly open: string;
+    readonly close: string;
+}
+interface SeparatorToken {
+    readonly type: TokenType.Separator;
+    readonly value: string;
+}
+
+declare abstract class BaseParameter {
+    readonly separators: readonly string[];
+    constructor(separators: readonly string[]);
+    get leading(): string;
+    abstract get raw(): string;
+}
+
+declare class QuotedParameter extends BaseParameter {
+    readonly value: string;
+    readonly open: string;
+    readonly close: string;
+    constructor(separators: readonly string[], part: Omit<QuotedToken, 'type'>);
+    get raw(): string;
+}
+
+declare class WordParameter extends BaseParameter {
+    readonly value: string;
+    constructor(separators: readonly string[], part: Omit<WordToken, 'type'>);
+    get raw(): string;
+}
+
+declare class ParameterStream {
+    private readonly stream;
+    private separators;
+    constructor(stream: Iterable<Token>);
+    [Symbol.iterator](): Iterator<Parameter, string[]>;
+}
+declare type Parameter = QuotedParameter | WordParameter;
+
+interface IUnorderedStrategy {
+    /**
+     * Matches a flag.
+     * @param input The string to match.
+     */
+    matchFlag(input: string): Option<string>;
+    /**
+     * Matches an option.
+     * @param input The string to match.
+     */
+    matchOption(input: string): Option<readonly [key: string, value: string]>;
+}
+
+declare class Parser {
+    strategy: IUnorderedStrategy;
+    constructor(strategy?: IUnorderedStrategy);
+    setUnorderedStrategy(strategy: IUnorderedStrategy): this;
+    run(input: Iterable<Parameter>): ParserResult;
+}
+
+declare class ParserResult {
+    readonly ordered: Parameter[];
+    readonly flags: Set<string>;
+    readonly options: Map<string, string[]>;
+    private readonly strategy;
+    constructor(parser: Parser);
+    parse(parameters: Iterable<Parameter>): this;
+    private parsePossibleFlag;
+    private parsePossibleOptions;
+    private parseOrdered;
+}
+
+declare class ArgumentStream {
+    readonly results: ParserResult;
+    state: ArgumentStream.State;
+    constructor(results: ParserResult);
+    /**
+     * Whether or not all ordered parameters were used.
+     */
+    get finished(): boolean;
+    /**
+     * The amount of ordered parameters.
+     */
+    get length(): number;
+    /**
+     * The remaining amount of ordered parameters.
+     */
+    get remaining(): number;
+    /**
+     * The amount of ordered parameters that have been used.
+     */
+    get used(): number;
+    /**
+     * Retrieves the value of the next unused ordered token.
+     *
+     * @example
+     * ```typescript
+     * // 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 The value, if any.
+     */
+    single(): Option<string>;
+    /**
+     * 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 {@link singleMapAsync}.
+     *
+     * @example
+     * ```typescript
+     * 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.
+     * @param predicate The predicate that determines the parameter's mapped value, or nothing if failed.
+     * @param useAnyways Whether to consider the parameter used even if the mapping failed. Defaults to `false`.
+     * @returns The mapped value, if any.
+     */
+    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.
+     *
+     * @note This is an asynchronous variant of {@link singleMap}.
+     *
+     * @typeparam T The output type.
+     * @param predicate The predicate that determines the parameter's mapped value, or nothing if failed.
+     * @param useAnyways Whether to consider the parameter used even if the mapping failed. Defaults to `false`.
+     * @returns The mapped value, if any.
+     */
+    singleMapAsync<T>(predicate: (value: string) => Promise<Option<T>>, useAnyways?: boolean): Promise<Option<T>>;
+    /**
+     * Finds and retrieves the next unused parameter and transforms it.
+     *
+     * @note This is a variant of {@link findMap} that returns the errors on failure.
+     * @note This does not support asynchronous results, refer to {@link singleParseAsync}.
+     *
+     * @example
+     * ```typescript
+     * 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.
+     * @param predicate The predicate that determines the parameter's transformed value, or nothing if failed.
+     * @param useAnyways Whether to consider the parameter used even if the transformation failed. Defaults to `false`.
+     * @returns The transformed value, if any.
+     */
+    singleParse<T, E>(predicate: (value: string) => Result<T, E>, useAnyways?: boolean): Result<T, E | null>;
+    /**
+     * Retrieves the value of the next unused ordered token, but only if it could be transformed.
+     *
+     * @note This is an asynchronous variant of {@link singleParse}.
+     *
+     * @typeparam T The output type.
+     * @typeparam E The error type.
+     * @param predicate The predicate that determines the parameter's mapped value, or nothing if failed.
+     * @param useAnyways Whether to consider the parameter used even if the mapping failed. Defaults to `false`.
+     * @returns The mapped value, if any.
+     */
+    singleParseAsync<T, E>(predicate: (value: string) => Promise<Result<T, E>>, useAnyways?: boolean): Promise<Result<T, E | null>>;
+    /**
+     * 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 {@link findAsync}.
+     *
+     * @example
+     * ```typescript
+     * // Suppose args are from 'ba aa cc'.
+     *
+     * console.log(args.find((value) => value.startsWith('a')));
+     * // Some { value: 'aa' }
+     * ```
+     *
+     * @param predicate 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`.
+     * @param from The position where to start looking for unused parameters, defaults to current position.
+     * @returns The found parameter's value.
+     */
+    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.
+     *
+     * @note This is an asynchronous variant of {@link find}.
+     *
+     * @example
+     * ```typescript
+     * // Suppose args are from 'ba aa cc'.
+     *
+     * console.log(args.find((value) => value.startsWith('a')));
+     * // Some { value: 'aa' }
+     * ```
+     *
+     * @param predicate 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`.
+     * @param from The position where to start looking for unused parameters, defaults to current position.
+     * @returns The found parameter's value.
+     */
+    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 `Some`, and
+     * `Option.none` otherwise.
+     *
+     * @note This does not support asynchronous results, refer to {@link findMapAsync}.
+     *
+     * @example
+     * ```typescript
+     * // Suppose args are from 'ba aa cc'.
+     *
+     * console.log(args.find((value) => value.startsWith('a')));
+     * // Some { value: 'aa' }
+     * ```
+     *
+     * @typeparam T The output type.
+     * @param predicate 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`.
+     * @param from The position where to start looking for unused parameters, defaults to current position.
+     * @returns The found parameter's value.
+     */
+    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.
+     *
+     * @note This is an asynchronous variant of {@link findMap}.
+     *
+     * @example
+     * ```typescript
+     * // Suppose args are from 'ba aa cc'.
+     *
+     * console.log(args.find((value) => value.startsWith('a')));
+     * // Some { value: 'aa' }
+     * ```
+     *
+     * @typeparam T The output type.
+     * @param predicate 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`.
+     * @param from The position where to start looking for unused parameters, defaults to current position.
+     * @returns The found parameter's value.
+     */
+    findMapAsync<T>(predicate: (value: string) => Promise<Option<T>>, from?: number): Promise<Option<T>>;
+    /**
+     * Finds and retrieves the first unused parameter that could be transformed.
+     *
+     * @note This is a variant of {@link findMap} that returns the errors on failure.
+     * @note This does not support asynchronous results, refer to {@link findParseAsync}.
+     *
+     * @example
+     * ```typescript
+     * 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.
+     * @param predicate `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.
+     * @param from The position where to start looking for unused parameters, defaults to current position.
+     * @returns The found parameter's value.
+     */
+    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.
+     *
+     * @note This is a variant of {@link findMapAsync} that returns the errors on failure.
+     * @note This is an asynchronous variant of {@link findParse}.
+     *
+     * @typeparam T The output type.
+     * @typeparam E The error type.
+     * @param predicate `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.
+     * @param from The position where to start looking for unused parameters, defaults to current position.
+     * @returns The found parameter's value.
+     */
+    findParseAsync<T, E>(predicate: (value: string) => Promise<Result<T, E>>, from?: number): Promise<Result<T, E[]>>;
+    /**
+     * Retrieves multiple unused parameters.
+     *
+     * @example
+     * ```typescript
+     * // Assume args are '1 2 3':
+     *
+     * console.log(join(args.many().unwrap()));
+     * // '1 2 3'
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Assume args are '1 2 3':
+     *
+     * console.log(join(args.many(2).unwrap()));
+     * // '1 2'
+     * ```
+     *
+     * @param limit The maximum amount of parameters to retrieve, defaults to `Infinity`.
+     * @param from The position where to start looking for unused parameters, defaults to current position.
+     * @returns The unused parameters within the range.
+     */
+    many(limit?: number, from?: number): Option<Parameter[]>;
+    filter(predicate: (value: string) => boolean, from?: number): Option<string[]>;
+    filterAsync(predicate: (value: string) => Promise<boolean>, from?: number): Promise<Option<string[]>>;
+    filterMap<T>(predicate: (value: string) => Option<T>, from?: number): Option<T[]>;
+    filterMapAsync<T>(predicate: (value: string) => Promise<Option<T>>, from?: number): Promise<Option<T[]>>;
+    /**
+     * Checks whether any of the flags were given.
+     *
+     * @example
+     * ```typescript
+     * // Assume args are '--f --g':
+     *
+     * console.log(args.flag('f'));
+     * // true
+     *
+     * console.log(args.flag('g', 'h'));
+     * // true
+     *
+     * console.log(args.flag('h'));
+     * // false
+     * ```
+     *
+     * @param keys The names of the flags to check.
+     * @returns Whether or not any of the flags were given.
+     */
+    flag(...keys: readonly string[]): boolean;
+    /**
+     * Gets the last value of any option. When there are multiple names, the last value of the last found name is given.
+     *
+     * @example
+     * ```typescript
+     * // 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 {}
+     * ```
+     *
+     * @param keys The names of the options to check.
+     * @returns The last value of the option, if any.
+     */
+    option(...keys: readonly string[]): Option<string>;
+    /**
+     * Gets all values from all options.
+     *
+     * @example
+     * ```typescript
+     * // 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 {}
+     * ```
+     *
+     * @param keys The names of the options to check.
+     * @returns The values from all the options concatenated, if any.
+     */
+    options(...keys: readonly string[]): Option<readonly string[]>;
+    save(): ArgumentStream.State;
+    restore(state: ArgumentStream.State): void;
+    reset(): void;
+}
+declare namespace ArgumentStream {
+    interface State {
+        used: Set<number>;
+        position: number;
+    }
+}
+
+declare class EmptyStrategy implements IUnorderedStrategy {
+    matchFlag(): Option<string>;
+    matchOption(): Option<readonly [key: string, value: string]>;
+}
+
+declare class PrefixedStrategy implements IUnorderedStrategy {
+    readonly prefixes: readonly string[];
+    readonly separators: readonly string[];
+    constructor(prefixes: readonly string[], separators: readonly string[]);
+    matchFlag(input: string): Option<string>;
+    matchOption(input: string): Option<readonly [key: string, value: string]>;
+}
+
+export { ArgumentStream, BaseParameter, EmptyStrategy, IUnorderedStrategy, Lexer, Parameter, ParameterStream, Parser, ParserResult, PrefixedStrategy, QuotedParameter, QuotedToken, SeparatorToken, Token, TokenStream, TokenType, WordParameter, WordToken };

package.json

 {
   "name": "@sapphire/lexure",
-  "version": "1.0.2-next.a963396.0",
+  "version": "1.0.2-next.b2486c2.0",
   "description": "Parser and utilities for non-technical user input",
@@ -22,3 +22,3 @@ "author": "@sapphire",
     "lint": "eslint src tests --ext ts --fix -c ../../.eslintrc",
-    "build": "tsup && tsc -b src",
+    "build": "tsup",
     "prepack": "yarn build",
@@ -61,3 +61,3 @@ "bump": "cliff-jumper",
   "dependencies": {
-    "@sapphire/result": "^2.3.1"
+    "@sapphire/result": "^2.3.3"
   },
@@ -64,0 +64,0 @@ "devDependencies": {

No alert changes

Worsened metrics

Total package byte prevSize

258646

decreased by-0.88%

Number of package files

10

decreased by-54.55%

Lines of code

2646

decreased by-1.23%

Dependency changes

• Updated@sapphire/result@^2.3.3