@witchcraft/expressit 0.0.2

package/src/ast/handlers.ts

@@ -0,0 +1,190 @@
+/* eslint-disable @typescript-eslint/no-shadow */
+
+import { ArrayNode } from "./classes/ArrayNode.js"
+import { ConditionNode } from "./classes/ConditionNode.js"
+import { ErrorToken } from "./classes/ErrorToken.js"
+import { ExpressionNode } from "./classes/ExpressionNode.js"
+import { GroupNode } from "./classes/GroupNode.js"
+import { ValidToken } from "./classes/ValidToken.js"
+import { VariableNode } from "./classes/VariableNode.js"
+
+import { type AnyToken, type FirstConstructorParam, type Position, TOKEN_TYPE, type TokenBooleanTypes, type TokenDelimiterTypes, type TokenOperatorTypes, type TokenQuoteTypes } from "../types/ast.js"
+
+
+/* #region HELPERS */
+function error<T extends TOKEN_TYPE>(pos: number, expected: T[]): ErrorToken<T> {
+	if (pos === undefined) throw new Error("should never happen, passed undefined position for error token")
+	return new ErrorToken({ expected, start: pos, end: pos })
+}
+/* #regionend */
+
+/* #region TOKENS */
+const operators = <T extends TokenOperatorTypes>
+(type: T) =>
+	(value: string, pos: Position): ValidToken<T> => new ValidToken({ value, type, ...pos })
+
+const delimiters = <T extends TokenDelimiterTypes>
+(type: T) =>
+	(value: string | undefined, pos: Position): ValidToken<T> | undefined =>
+		// check must be falsy, we want to return undefined when given ""
+		value ? new ValidToken({ value, type, ...pos }) : undefined
+
+const maybeToken = <T extends TOKEN_TYPE>(type: T) => (value: string | undefined, pos: Position,): AnyToken<T> => {
+	if (value === undefined) {
+		return error(pos.end, [type])
+	} else {
+		return new ValidToken({ value, type, ...pos })
+	}
+}
+
+export const token = {
+	value: maybeToken(TOKEN_TYPE.VALUE),
+	custom: maybeToken(TOKEN_TYPE.OP_CUSTOM),
+	sep: maybeToken(TOKEN_TYPE.OP_EXPANDED_SEP),
+}
+
+/** We want to handle all the types outside the grammar file. This makes it easier without trying to check the value. */
+export const delimiter = {
+	parenL: delimiters(TOKEN_TYPE.PARENL),
+	parenR: delimiters(TOKEN_TYPE.PARENR),
+	bracketL: delimiters(TOKEN_TYPE.BRACKETL),
+	bracketR: delimiters(TOKEN_TYPE.BRACKETR),
+	double: delimiters(TOKEN_TYPE.DOUBLEQUOTE),
+	single: delimiters(TOKEN_TYPE.SINGLEQUOTE),
+	regex: delimiters(TOKEN_TYPE.REGEX),
+	tick: delimiters(TOKEN_TYPE.BACKTICK),
+	tokenError: error,
+}
+export const operator = {
+	and: operators(TOKEN_TYPE.AND),
+	or: operators(TOKEN_TYPE.OR),
+	not: operators(TOKEN_TYPE.NOT),
+}
+/* #regionend */
+
+/* #region AST NODES */
+export function variable(
+	prefix: ValidToken<TOKEN_TYPE.VALUE> | null | undefined,
+	quoteL: AnyToken<TokenQuoteTypes> | null | undefined,
+	value: AnyToken<TOKEN_TYPE.VALUE> | null | undefined,
+	quoteR: AnyToken<TokenQuoteTypes> | null | undefined,
+	flags?: ValidToken<TOKEN_TYPE.VALUE>
+): VariableNode {
+	const node: FirstConstructorParam<typeof VariableNode> = {
+		prefix: prefix ?? undefined,
+		value: value ?? error((prefix?.end ?? quoteL?.end ?? quoteR?.start)!, [TOKEN_TYPE.VALUE]),
+		start: (prefix?.start ?? quoteL?.start ?? value?.start ?? quoteR?.start)!,
+		end: (quoteR?.end ?? value?.end ?? quoteL?.end ?? prefix?.end)!,
+	}
+
+	if (quoteL || quoteR) {
+		node.quote = {
+			left: quoteL ?? error(node.value.start, [(quoteR!.type)]),
+			right: quoteR ?? error(node.value.end, [(quoteL!.type)]),
+		}
+		if (flags) {
+			node.quote.flags = flags
+			node.end = node.quote?.flags.end
+		}
+	}
+
+	const instance = new VariableNode(node as any)
+	return instance
+}
+
+
+export function condition(
+	not: ValidToken<TOKEN_TYPE.NOT> | null | undefined,
+	property: VariableNode | null | undefined,
+	{ propertyOperator, sepL, sepR }: {
+		propertyOperator?: ConditionNode["propertyOperator"] | null
+		sepL?: ValidToken<TOKEN_TYPE.OP_EXPANDED_SEP> | null
+		sepR?: ValidToken<TOKEN_TYPE.OP_EXPANDED_SEP> | null
+	} = {},
+	value?: VariableNode | GroupNode | ArrayNode | null,
+): ConditionNode {
+	const start = (not?.start ?? property?.start ?? sepL?.start ?? propertyOperator?.start ?? sepR?.start ?? value?.start)!
+	const end = (value?.end ?? sepR?.end ?? propertyOperator?.end ?? sepL?.end ?? property?.end ?? not?.end)!
+	const node: FirstConstructorParam<typeof ConditionNode> = {
+		value: value ? value : error(end, [TOKEN_TYPE.VALUE]),
+		start,
+		end,
+	}
+	if (not) { node.operator = not }
+	if (property) node.property = property
+	if (propertyOperator) node.propertyOperator = propertyOperator
+	if (sepL || sepR) {
+		node.sep = {}
+		if (sepL) {
+			node.sep.left = sepL
+			node.property ||= error(sepL.start, [TOKEN_TYPE.VALUE])
+			node.propertyOperator ||= error(sepL?.end ?? sepR?.start, [TOKEN_TYPE.VALUE])
+		}
+		if (sepR) node.sep.right = sepR
+		else if (!node.value || node.value instanceof VariableNode) {
+			node.sep.right = error(node.value?.start ?? end, [TOKEN_TYPE.OP_EXPANDED_SEP])
+		}
+	} else if (propertyOperator) {
+		node.property ||= error(propertyOperator.start, [TOKEN_TYPE.VALUE])
+	}
+
+	const instance = new ConditionNode(node as any)
+	return instance
+}
+
+export function expression(
+	left: ConditionNode | GroupNode | null | undefined,
+	operator: ValidToken<TokenBooleanTypes> | null | undefined,
+	right: ConditionNode | GroupNode | null | undefined,
+): ExpressionNode {
+	const instance = new ExpressionNode({
+		left: left ?? error((operator?.start ?? right?.start)!, [TOKEN_TYPE.VALUE]),
+		operator: operator ?? error((left?.end ?? right?.start)!, [TOKEN_TYPE.AND, TOKEN_TYPE.OR]),
+		right: right ?? error((operator?.end ?? left?.end)!, [TOKEN_TYPE.VALUE]),
+		start: (left?.start ?? operator?.start ?? right?.start)!,
+		end: (right?.end ?? operator?.end ?? left?.end)!,
+	})
+	return instance
+}
+
+export function group(
+	operator: ValidToken<TOKEN_TYPE.NOT> | null | undefined,
+	prefix: ConditionNode | null | undefined,
+	parenL: ValidToken<TOKEN_TYPE.PARENL> | null | undefined,
+	condition: GroupNode["expression"],
+	parenR: ValidToken<TOKEN_TYPE.PARENR> | null | undefined
+): GroupNode {
+	const node: FirstConstructorParam<typeof GroupNode> = {
+		prefix: prefix ?? operator ?? undefined,
+		expression: condition ?? error((parenL?.end ?? parenR?.start)!, [TOKEN_TYPE.VALUE]),
+		paren: {
+			left: parenL ?? error((prefix?.end ?? operator?.end ?? condition?.start ?? parenR?.start)!, [TOKEN_TYPE.PARENL]),
+			right: parenR ?? error((condition?.end ?? parenL?.end)!, [TOKEN_TYPE.PARENR]),
+		},
+		start: (prefix?.start ?? operator?.start ?? parenL?.start ?? condition?.start ?? parenR?.start)!,
+		end: (parenR?.end ?? condition?.end ?? parenL?.end ?? operator?.end ?? prefix?.end)!,
+	}
+
+	const instance = new GroupNode(node as any)
+	return instance
+}
+
+export function array(
+	bracketL: ValidToken<TOKEN_TYPE.BRACKETL>,
+	values: VariableNode[],
+	bracketR: ValidToken<TOKEN_TYPE.BRACKETR> | null | undefined
+): ArrayNode {
+	const node: FirstConstructorParam<typeof ArrayNode> = {
+		values,
+		bracket: {
+			left: bracketL, // always valid for now
+			right: bracketR ?? error((values[values.length - 1]?.end ?? bracketL?.end)!, [TOKEN_TYPE.BRACKETR]),
+		},
+		start: bracketL.start,
+		end: (bracketR?.end ?? values[values.length - 1]?.end ?? bracketL.end)!,
+	}
+
+	const instance = new ArrayNode(node as any)
+	return instance
+}
+/* #regionend */

package/src/ast/index.ts

@@ -0,0 +1,5 @@
+/* Autogenerated Index */
+
+export * as builders from "./builders/index.js"
+export * as classes from "./classes/index.js"
+export { token } from "./handlers.js"

package/src/examples/advancedValueComparer.ts

@@ -0,0 +1,31 @@
+import type { ValueQuery } from "../types/parser.js"
+
+/* TODO TOUPDATE */
+type Operators = ">" | "contains"
+type Prefixes = "num"
+export function valueComparer(contextValue: string, { operator, prefix, value, isRegex, regexFlags }: ValueQuery): boolean {
+	let finalValue: any = value
+	if (prefix) {
+		const val = value as string // it's always a string if prefixed
+		switch (prefix as Prefixes) {
+			case "num": finalValue = parseInt(val, 2); break
+			// ...
+		}
+	}
+	if (isRegex) {
+		const val = value as string // it's always a string and never prefixed if it's a regex
+		const regex = new RegExp(val, regexFlags)
+		return contextValue.match(regex) !== null
+	}
+	if (operator) {
+		switch (operator as Operators) {
+			// custom operators
+			case ">": return contextValue > finalValue
+			// ...
+			// custom expanded operators
+			case "contains": return contextValue.includes(finalValue)
+			// ...
+		}
+	}
+	return contextValue === finalValue
+}

package/src/examples/shortcutContextParser.ts

@@ -0,0 +1,140 @@
+/* TODO TOUPDATE */
+/**
+ * A pre-configured parser for parsing shortcut contexts (similar to VSCode's [when clause contexts](https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts)).
+ *
+ * The only difference is that it does not have a regex operator since you can just do `prop == /regex/`, and because of how it has `prefixableGroups` turned on and how the parser allows groups as values, user's can use shorter queries.
+ *
+ * It also automatically implements a prefixApplier (variables are joined with `.`) and a value validator (which is why it requires a dummy context and a list of valid regex flags be passed). The value of the dummy context should be true to indicate the key is regexable, otherwise just false or a nested object. Any nested keys found are joined with a `.` and added to a list of valid keys. The prefixApplier is loose and allows things like `a.(b.(c))` and `a(b(c))` to both be parsed as `a.b.c`.
+ *
+ * The validate function will return a list of positions with a list of errors which includes handling invalid or duplicate regex flags.
+ */
+
+import { Parser } from "../parser.js"
+import type { Position } from "../types/ast.js"
+import type { ValueQuery } from "../types/parser.js"
+
+
+export class ShortcutContextParser<T extends
+	Position & { type: ("invalidKey" | "unregexableKey" | "invalidRegexFlag" | "duplicateRegexFlag") } =
+	Position & { type: ("invalidKey" | "unregexableKey" | "invalidRegexFlag" | "duplicateRegexFlag") },
+> extends Parser<T> {
+	validKeys: string[] = []
+
+	regexablekeys: string[] = []
+
+	constructor(
+		dummyContext: Record<string, any>,
+		validRegexFlags: string[] = ["i", "u", "m"]
+	) {
+		super({
+			arrayValues: false,
+			keyParser: (key: string) => key.split(/\.+/),
+			keywords: {
+				and: [{ isSymbol: true, value: "&&" }],
+				or: [{ isSymbol: true, value: "||" }],
+				not: [{ isSymbol: true, value: "!" }],
+			},
+			regexValues: (property, operator) => property !== undefined && operator !== undefined,
+			customPropertyOperators: ["!=", "=="],
+			prefixableGroups: true,
+			prefixApplier: (prefix: string, variable: string) => {
+				if (!prefix.endsWith(".")) {
+					return `${prefix}.${variable}`
+				}
+				return prefix + variable
+			},
+			valueComparer: (_condition, contextValue, query) => {
+				if (query.isRegex) {
+					return contextValue.match(new RegExp(query.value as string, query.regexFlags ?? "")) !== null
+				}
+				return contextValue === query.value
+			},
+			valueValidator: (_contextValue, query): T[] | void => {
+				let tokens: T[] = []
+				if (!this.validKeys.includes(query.propertyName!)) {
+					tokens = tokens.concat(query.property.map(token => ({
+						start: token.start,
+						end: token.end,
+						type: "invalidKey",
+					})) as T[])
+				}
+				if (query.isRegex && !this.regexablekeys.includes(query.propertyName!)) {
+					tokens = tokens.concat(query.property.map(token => ({
+						start: token.start,
+						end: token.end,
+						type: "unregexableKey",
+					})) as T[])
+				}
+				if (query.regexFlags) {
+					const chars = query.regexFlags.value.split("")
+					const start = query.regexFlags.start
+					for (let i = 0; i < chars.length; i++) {
+						const char = chars[i]
+						if (chars.slice(0, i).includes(char)) {
+							tokens.push({
+								start: start + i,
+								end: start + i + 1,
+								type: "duplicateRegexFlag",
+							} as T)
+						}
+						if (!validRegexFlags.includes(char)) {
+							tokens.push({
+								start: start + i,
+								end: start + i + 1,
+								type: "invalidRegexFlag",
+							} as T)
+						}
+					}
+				}
+				if (tokens.length > 0) return tokens
+			},
+			conditionNormalizer({ operator, value, regexFlags, isRegex, isNegated, isQuoted }: ValueQuery) {
+				let finalValue: any = value
+				let finalOperator: any = operator
+				// another way to allow special unquoted value types is something like this:
+				if (typeof value === "string" && !isQuoted) {
+					const asNum = parseInt(value, 2)
+					if (!isNaN(asNum)) finalValue = asNum
+					if (["true", "false"].includes(value)) {
+						finalValue = value === "true"
+					}
+				}
+				if (isRegex) {
+					const val = value as string // it's always a string and never prefixed if it's a regex
+					const regex = new RegExp(val, regexFlags) // this can throw if the user passes invalid flags
+					finalValue = regex
+				}
+				if (operator) {
+					switch (operator as any) {
+						case "==": {
+							finalOperator = "equals"
+							break
+						}
+						case "!=": {
+							finalOperator = "equals"
+							isNegated = !isNegated
+							break
+						}
+					}
+				}
+				return { value: finalValue, operator: finalOperator, negate: isNegated }
+			},
+		})
+		this._extractKeysFromContext(dummyContext)
+	}
+
+	private _extractKeysFromContext(context: Record<string, any>, prev?: string): void {
+		for (const key of Object.keys(context)) {
+			if (typeof context[key] === "boolean") {
+				this.validKeys.push(prev ? `${prev}.${key}` : key)
+				if (context[key] === true) {
+					this.regexablekeys.push(prev ? `${prev}.${key}` : key)
+				}
+			} else {
+				if (typeof context[key] !== "object") throw new Error("A dummy context value must be a boolean or an object.")
+				this._extractKeysFromContext(context[key], prev ? `${prev}.${key}` : key)
+			}
+		}
+	}
+}
+

package/src/global.d.ts

@@ -0,0 +1,4 @@
+declare module "./package.js" {
+	export const version: string
+	export const repository: string
+}