@sapphire/lexure 1.0.0

package/dist/lib/ArgumentStream.d.ts

@@ -0,0 +1,378 @@
+import { Option, Result } from '@sapphire/result';
+import type { Parameter } from './lexer/streams/ParameterStream';
+import type { ParserResult } from './parser/ParserResult';
+export 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;
+}
+export declare namespace ArgumentStream {
+    interface State {
+        used: Set<number>;
+        position: number;
+    }
+}
+//# sourceMappingURL=ArgumentStream.d.ts.map

package/dist/lib/lexer/Lexer.d.ts

@@ -0,0 +1,16 @@
+import { ParameterStream } from './streams/ParameterStream';
+import { TokenStream } from './streams/raw/TokenStream';
+export 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;
+}
+export declare namespace Lexer {
+    interface Options {
+        separator?: string;
+        quotes?: readonly [open: string, close: string][];
+    }
+}
+//# sourceMappingURL=Lexer.d.ts.map

package/dist/lib/lexer/streams/ParameterStream.d.ts

@@ -0,0 +1,11 @@
+import { QuotedParameter } from './parameters/QuotedParameter';
+import { WordParameter } from './parameters/WordParameter';
+import { type Token } from './raw/TokenStream';
+export declare class ParameterStream {
+    private readonly stream;
+    private separators;
+    constructor(stream: Iterable<Token>);
+    [Symbol.iterator](): Iterator<Parameter, string[]>;
+}
+export declare type Parameter = QuotedParameter | WordParameter;
+//# sourceMappingURL=ParameterStream.d.ts.map

package/dist/lib/lexer/streams/parameters/BaseParameter.d.ts

@@ -0,0 +1,7 @@
+export declare abstract class BaseParameter {
+    readonly separators: readonly string[];
+    constructor(separators: readonly string[]);
+    get leading(): string;
+    abstract get raw(): string;
+}
+//# sourceMappingURL=BaseParameter.d.ts.map

package/dist/lib/lexer/streams/parameters/QuotedParameter.d.ts

@@ -0,0 +1,10 @@
+import type { QuotedToken } from '../raw/TokenStream';
+import { BaseParameter } from './BaseParameter';
+export 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;
+}
+//# sourceMappingURL=QuotedParameter.d.ts.map

package/dist/lib/lexer/streams/parameters/WordParameter.d.ts

@@ -0,0 +1,8 @@
+import type { WordToken } from '../raw/TokenStream';
+import { BaseParameter } from './BaseParameter';
+export declare class WordParameter extends BaseParameter {
+    readonly value: string;
+    constructor(separators: readonly string[], part: Omit<WordToken, 'type'>);
+    get raw(): string;
+}
+//# sourceMappingURL=WordParameter.d.ts.map

package/dist/lib/lexer/streams/raw/TokenStream.d.ts

@@ -0,0 +1,34 @@
+import type { Lexer } from '../../Lexer';
+export 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;
+}
+export declare enum TokenType {
+    Parameter = 0,
+    Quoted = 1,
+    Separator = 2
+}
+export declare type Token = WordToken | QuotedToken | SeparatorToken;
+export interface WordToken {
+    readonly type: TokenType.Parameter;
+    readonly value: string;
+}
+export interface QuotedToken {
+    readonly type: TokenType.Quoted;
+    readonly value: string;
+    readonly open: string;
+    readonly close: string;
+}
+export interface SeparatorToken {
+    readonly type: TokenType.Separator;
+    readonly value: string;
+}
+//# sourceMappingURL=TokenStream.d.ts.map

package/dist/lib/parser/Parser.d.ts

@@ -0,0 +1,10 @@
+import type { Parameter } from '../lexer/streams/ParameterStream';
+import type { IUnorderedStrategy } from './strategies/IUnorderedStrategy';
+import { ParserResult } from './ParserResult';
+export declare class Parser {
+    strategy: IUnorderedStrategy;
+    constructor(strategy?: IUnorderedStrategy);
+    setUnorderedStrategy(strategy: IUnorderedStrategy): this;
+    run(input: Iterable<Parameter>): ParserResult;
+}
+//# sourceMappingURL=Parser.d.ts.map

package/dist/lib/parser/ParserResult.d.ts

@@ -0,0 +1,14 @@
+import type { Parameter } from '../lexer/streams/ParameterStream';
+import type { Parser } from './Parser';
+export 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;
+}
+//# sourceMappingURL=ParserResult.d.ts.map

package/dist/lib/parser/strategies/EmptyStrategy.d.ts

@@ -0,0 +1,7 @@
+import { Option } from '@sapphire/result';
+import type { IUnorderedStrategy } from './IUnorderedStrategy';
+export declare class EmptyStrategy implements IUnorderedStrategy {
+    matchFlag(): Option<string>;
+    matchOption(): Option<readonly [key: string, value: string]>;
+}
+//# sourceMappingURL=EmptyStrategy.d.ts.map

package/dist/lib/parser/strategies/IUnorderedStrategy.d.ts

@@ -0,0 +1,14 @@
+import type { Option } from '@sapphire/result';
+export 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]>;
+}
+//# sourceMappingURL=IUnorderedStrategy.d.ts.map

package/dist/lib/parser/strategies/PrefixedStrategy.d.ts

@@ -0,0 +1,10 @@
+import { Option } from '@sapphire/result';
+import type { IUnorderedStrategy } from './IUnorderedStrategy';
+export 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]>;
+}
+//# sourceMappingURL=PrefixedStrategy.d.ts.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@sapphire/lexure",
+  "version": "1.0.0",
+  "description": "Parser and utilities for non-technical user input",
+  "author": "@sapphire",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "browser": "dist/index.global.js",
+  "unpkg": "dist/index.global.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "sideEffects": false,
+  "homepage": "https://github.com/sapphiredev/utilities/tree/main/packages/lexure",
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint src tests --ext ts --fix -c ../../.eslintrc",
+    "build": "tsup && tsc -b src",
+    "prepack": "yarn build",
+    "bump": "cliff-jumper",
+    "check-update": "cliff-jumper --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sapphiredev/utilities.git",
+    "directory": "packages/lexure"
+  },
+  "files": [
+    "dist/**/*.js*",
+    "dist/**/*.mjs*",
+    "dist/**/*.d*"
+  ],
+  "engines": {
+    "node": ">=v14.0.0",
+    "npm": ">=7.0.0"
+  },
+  "keywords": [
+    "@sapphire/lexure",
+    "bot",
+    "discord",
+    "lexure",
+    "promise",
+    "sapphire",
+    "standalone",
+    "ts",
+    "typescript",
+    "yarn"
+  ],
+  "bugs": {
+    "url": "https://github.com/sapphiredev/utilities/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sapphire/result": "^2.0.1"
+  },
+  "devDependencies": {
+    "@favware/cliff-jumper": "^1.8.5",
+    "tsup": "^6.1.3",
+    "typescript": "^4.7.4"
+  }
+}