@blackglory/match 0.3.5 → 0.4.0

package/src/matchers/css.ts

@@ -0,0 +1,24 @@
+import { concat } from '@utils/concat.js'
+import { ITerminalMatcher } from '@src/types.js'
+import { isString } from '@blackglory/prelude'
+
+export function css(
+  strings: TemplateStringsArray
+, ...values: string[]
+): ITerminalMatcher<Element>
+export function css(selector: string): ITerminalMatcher<Element>
+export function css(...args:
+| [selector: string]
+| [strings: TemplateStringsArray, ...values: string[]]
+): ITerminalMatcher<Element> {
+  if (isString(args[0])) {
+    const [selector] = args
+
+    return (element: Element) => element.matches(selector)
+  } else {
+    const [strings, ...values] = args
+    const selector = concat(strings, values).join('')
+
+    return css(selector)
+  }
+}

package/src/matchers/element.ts

@@ -0,0 +1,49 @@
+import { isntElement } from 'extra-dom'
+import { INestedMatcher, ITerminalMatcher, IReadonlyContext } from '@src/types.js'
+import { isArray, isString } from '@blackglory/prelude'
+import { concat } from '@utils/concat.js'
+import { mergeInPlace } from '@utils/merge-in-place.js'
+
+export function element(
+  strings: TemplateStringsArray
+, ...values: string[]
+): (...matchers: Array<INestedMatcher<Element> | ITerminalMatcher<Element>>) => INestedMatcher<Node>
+export function element(name: string, ...matchers: Array<INestedMatcher<Element>>):
+  INestedMatcher<Node>
+export function element(...matchers: Array<INestedMatcher<Element>>):
+  INestedMatcher<Node>
+export function element(...args:
+| [strings: TemplateStringsArray, ...values: string[]]
+| [name: string, ...matchers: Array<INestedMatcher<Element> | ITerminalMatcher<Element>>]
+| [...matchers: Array<INestedMatcher<Element> | ITerminalMatcher<Element>>]
+) {
+  if (isArray(args[0])) {
+    const [strings, ...values] =
+      args as [strings: TemplateStringsArray, ...values: string[]]
+    const name = concat(strings, values).join('')
+
+    return (...matchers: Array<INestedMatcher<Element> | ITerminalMatcher<Element>>) => element(name, ...matchers)
+  }
+
+  if (isString(args[0])) {
+    const [name, ...matchers] =
+      args as [name: string, ...matchers: Array<INestedMatcher<Element> | ITerminalMatcher<Element>>]
+
+    return function (this: IReadonlyContext, _element: Element) {
+      const result = element(...matchers).call(this, _element)
+      if (result) {
+        mergeInPlace(this.collection, { [name]: _element })
+      }
+      return result
+    }
+  }
+
+  const [...matchers] = args as [...matchers: Array<INestedMatcher<Element> | ITerminalMatcher<Element>>]
+
+  return function (this: IReadonlyContext, element: Element) {
+    if (isntElement(element)) return false
+    if (matchers.length === 0) return true
+
+    return matchers.every(match => match.call(this, element))
+  }
+}

package/src/matchers/multiple.ts

@@ -0,0 +1,59 @@
+import { INestedMatcher, ITerminalMatcher, ISkipMatcher, IReadonlyContext } from '@src/types.js'
+import { countup } from 'extra-generator'
+import { assert } from '@blackglory/prelude'
+import { matchMultiple } from '@utils/match-multiple.js'
+
+export enum Range {
+  Min = 0
+, Max = 1
+}
+
+interface IMultipleOptions {
+  // 当开启贪婪模式时, 应该优先匹配最长的情况
+  greedy: boolean // = true, 默认启用贪婪模式
+}
+
+export function multiple<T extends Node>(
+  [min, max]: [min: number, max: number]
+, matcher: INestedMatcher<T> | ITerminalMatcher<T>
+, options: IMultipleOptions = { greedy: true }
+): ISkipMatcher<T> {
+  assert(Number.isInteger(min), 'parameter min must be an integer')
+  assert(Number.isInteger(max) || max === Infinity, 'parameter max must be an integer or Infinity')
+  assert(min >= 0, 'parameter min must be greater than or equal to 0')
+  assert(min <= max, 'parameter max must be greater than or equal to min')
+
+  return function* (this: IReadonlyContext, node: T) {
+    if (options.greedy) {
+      let ubound = max
+      while (true) {
+        const round = matchMultiple.call(
+          this
+        , node
+        , ubound
+        , matcher as INestedMatcher<Node> | ITerminalMatcher<Node>
+        )
+
+        if (round < min) break
+        yield round
+
+        ubound = round - 1
+        if (ubound < min) break
+      }
+    } else {
+      for (const ubound of countup(min, max)) {
+        const result = matchMultiple.call(
+          this
+        , node
+        , ubound
+        , matcher as INestedMatcher<Node> | INestedMatcher<Node>
+        )
+
+        // 如果匹配的节点数量少于ubound, 说明匹配失败, 即使尝试更长的匹配也不会成功.
+        if (result < ubound) break
+
+        if (result === ubound) yield ubound
+      }
+    }
+  }
+}

package/src/matchers/node.ts

@@ -0,0 +1,50 @@
+import { INestedMatcher, ITerminalMatcher, IReadonlyContext } from '@src/types.js'
+import { isArray, isString } from '@blackglory/prelude'
+import { concat } from '@utils/concat.js'
+import { mergeInPlace } from '@utils/merge-in-place.js'
+
+export function node(
+  strings: TemplateStringsArray
+, ...values: string[]
+): (...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>) => INestedMatcher<Node>
+export function node(
+  name: string
+, ...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>
+): INestedMatcher<Node>
+export function node(
+  ...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>
+): INestedMatcher<Node>
+export function node(...args:
+| [strings: TemplateStringsArray, ...values: string[]]
+| [name: string, ...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>]
+| [...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>]
+) {
+  if (isArray(args[0])) {
+    const [strings, ...values] =
+      args as [strings: TemplateStringsArray, ...values: string[]]
+    const name = concat(strings, values).join('')
+
+    return (...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>) => node(name, ...matchers)
+  }
+
+  if (isString(args[0])) {
+    const [name, ...matchers] =
+      args as [name: string, ...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>]
+
+    return function (this: IReadonlyContext, _node: Node) {
+      const result = node(...matchers).call(this, _node)
+      if (result) {
+        mergeInPlace(this.collection, { [name]: _node })
+      }
+      return result
+    }
+  }
+
+  const [...matchers] = args as [...matchers: Array<INestedMatcher<Node> | ITerminalMatcher<Node>>]
+
+  return function (this: IReadonlyContext, node: Node) {
+    if (matchers.length === 0) return true
+
+    return matchers.every(match => match.call(this, node))
+  }
+}

package/src/matchers/optional.ts

@@ -0,0 +1,6 @@
+import { INestedMatcher, ITerminalMatcher, ISkipMatcher } from '@src/types.js'
+import { multiple } from './multiple.js'
+
+export function optional<T extends Node>(matcher: INestedMatcher<T> | ITerminalMatcher<T>): ISkipMatcher<T> {
+  return multiple([0, 1], matcher, { greedy: true })
+}

package/src/matchers/repeat.ts

@@ -0,0 +1,25 @@
+import { INestedMatcher, ITerminalMatcher, ISkipMatcher, IReadonlyContext } from '@src/types.js'
+import { assert } from '@blackglory/prelude'
+import { matchMultiple } from '@utils/match-multiple.js'
+
+export function repeat<T extends Node>(
+  times: number
+, matcher: INestedMatcher<T> | ITerminalMatcher<T>
+): ISkipMatcher<T> {
+  assert(Number.isInteger(times), 'parameter times must be an integer')
+  assert(times >= 0, 'parameter number must be greater than or equal to 0')
+
+  return function (this: IReadonlyContext, node: T) {
+    const result = matchMultiple.call(
+      this
+    , node
+    , times
+    , matcher as INestedMatcher<Node> | ITerminalMatcher<Node>
+    )
+    if (result === times) {
+      return times
+    } else {
+      return false
+    }
+  }
+}

package/src/matchers/tap.ts

@@ -0,0 +1,12 @@
+import { IReadonlyContext, IMatcher } from '@src/types.js'
+
+export function tap<T extends Node, U extends ReturnType<IMatcher<any>>>(
+  matcher: (this: IReadonlyContext, node: T) => U
+, callback: (value: U) => void
+): (this: IReadonlyContext, node: T) => U {
+  return function (this: IReadonlyContext, node: T) {
+    const result = matcher.call(this, node)
+    callback(result)
+    return result
+  }
+}

package/src/matchers/text-content-equals.ts

@@ -0,0 +1,28 @@
+import { ITerminalMatcher } from '@src/types.js'
+import { isNull } from '@blackglory/prelude'
+
+interface ITextContentEqualsOptions {
+  caseSensitive?: boolean
+  trim?: boolean
+}
+
+export function textContentEquals(
+  text: string
+, {
+    caseSensitive = true
+  , trim = false
+  }: ITextContentEqualsOptions = {}
+): ITerminalMatcher<Node> {
+  return (node: Node) => {
+    if (isNull(node.textContent)) return false
+
+    let textContent = node.textContent
+    if (!caseSensitive) {
+      textContent = textContent.toLowerCase()
+      text = text.toLowerCase()
+    }
+    if (trim) textContent = textContent.trim()
+
+    return textContent === text
+  }
+}

package/src/matchers/text-content-includes.ts

@@ -0,0 +1,28 @@
+import { ITerminalMatcher } from '@src/types.js'
+import { isNull } from '@blackglory/prelude'
+
+interface ITextContentIncludesOptions {
+  caseSensitive?: boolean
+  trim?: boolean
+}
+
+export function textContentIncludes(
+  searchString: string
+, {
+    caseSensitive = true
+  , trim = false
+  }: ITextContentIncludesOptions = {}
+): ITerminalMatcher<Node> {
+  return (node: Node) => {
+    if (isNull(node.textContent)) return false
+
+    let textContent = node.textContent
+    if (!caseSensitive) {
+      textContent = textContent.toLowerCase()
+      searchString = searchString.toLowerCase()
+    }
+    if (trim) textContent = textContent.trim()
+
+    return textContent.includes(searchString)
+  }
+}

package/src/matchers/text-content-matches.ts

@@ -0,0 +1,20 @@
+import { ITerminalMatcher } from '@src/types.js'
+import { isNull } from '@blackglory/prelude'
+
+interface ITextContentMatchesOptions {
+  trim?: boolean
+}
+
+export function textContentMatches(
+  pattern: RegExp
+, { trim = false }: ITextContentMatchesOptions = {}
+): ITerminalMatcher<Node> {
+  return (node: Node) => {
+    if (isNull(node.textContent)) return false
+
+    let textContent = node.textContent
+    if (trim) textContent = textContent.trim()
+
+    return pattern.test(textContent)
+  }
+}

package/src/matchers/text-node.ts

@@ -0,0 +1,52 @@
+import { INestedMatcher, ITerminalMatcher, IReadonlyContext } from '@src/types.js'
+import { isArray, isString } from '@blackglory/prelude'
+import { concat } from '@utils/concat.js'
+import { isntTextNode } from 'extra-dom'
+import { mergeInPlace } from '@utils/merge-in-place.js'
+
+export function textNode(
+  strings: TemplateStringsArray
+, ...values: string[]
+): (...matchers: Array<ITerminalMatcher<Node>>) => INestedMatcher<Node>
+export function textNode(
+  name: string
+, ...matchers: Array<ITerminalMatcher<Node>>
+): INestedMatcher<Node>
+export function textNode(
+  ...matchers: Array<ITerminalMatcher<Node>>
+): INestedMatcher<Node>
+export function textNode(...args:
+| [strings: TemplateStringsArray, ...values: string[]]
+| [name: string, ...matchers: Array<ITerminalMatcher<Node>>]
+| [...matchers: Array<ITerminalMatcher<Node>>]
+) {
+  if (isArray(args[0])) {
+    const [strings, ...values] =
+      args as [strings: TemplateStringsArray, ...values: string[]]
+    const name = concat(strings, values).join('')
+
+    return (...matchers: Array<ITerminalMatcher<Node>>) => textNode(name, ...matchers)
+  }
+
+  if (isString(args[0])) {
+    const [name, ...matchers] =
+      args as [name: string, ...matchers: Array<ITerminalMatcher<Node>>]
+
+    return function (this: IReadonlyContext, node: Node) {
+      const result = textNode(...matchers).call(this, node)
+      if (result) {
+        mergeInPlace(this.collection, { [name]: node })
+      }
+      return result
+    }
+  }
+
+  const [...matchers] = args as [...matchers: Array<ITerminalMatcher<Node>>]
+
+  return function (this: IReadonlyContext, node: Node) {
+    if (isntTextNode(node)) return false
+    if (matchers.length === 0) return true
+
+    return matchers.every(match => match.call(this, node))
+  }
+}

package/src/matchers/xpath.ts

@@ -0,0 +1,54 @@
+import { ITerminalMatcher, IReadonlyContext } from '@src/types.js'
+import { isString } from '@blackglory/prelude'
+import { concat } from '@utils/concat.js'
+import { assert } from '@blackglory/prelude'
+
+const UNORDERED_NODE_ITERATOR_TYPE =
+  'XPathResult' in globalThis
+  ? XPathResult.UNORDERED_NODE_ITERATOR_TYPE
+  : 4
+
+export function xpath(
+  strings: TemplateStringsArray
+, ...values: string[]
+): ITerminalMatcher<Node>
+export function xpath(
+  experssion: string
+): ITerminalMatcher<Node>
+export function xpath(...args:
+| [expression: string]
+| [strings: TemplateStringsArray, ...values: string[]]
+): ITerminalMatcher<Node> {
+  if (isString(args[0])) {
+    const [expression] = args
+    assert(expression.startsWith('//*'), 'XPath expressions must start with "//*"')
+
+    return function (
+      this: Pick<IReadonlyContext, 'document'>
+    , node: Node
+    ): boolean {
+      return xpathMatches(this.document, expression, node)
+    }
+  } else {
+    const [strings, ...values] = args
+    const expression = concat(strings, values).join('')
+
+    return xpath(expression)
+  }
+}
+
+function xpathMatches(document: Document, expression: string, node: Node): boolean {
+  const iterator = document.evaluate(
+    expression
+  , node
+  , null
+  , UNORDERED_NODE_ITERATOR_TYPE
+  , null
+  )
+
+  let value
+  while ((value = iterator.iterateNext()) !== null) {
+    if (value === node) return true
+  }
+  return false
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+export interface IContext {
+  readonly document: Document
+  readonly next: (node: Node, distance?: number) => Node | undefined
+  readonly collection: {
+    [name: string]: Node | Node[]
+  }
+}
+
+export interface IReadonlyContext {
+  readonly document: Document
+  readonly next: (node: Node, distance?: number) => Node | undefined
+  readonly collection: {
+    readonly [name: string]: Node | Node[]
+  }
+}
+
+export type IMatcher<T extends Node> =
+| ITerminalMatcher<T>
+| INestedMatcher<T>
+| ISkipMatcher<T>
+| (
+    <T extends Node>(this: IReadonlyContext, node: T) =>
+      boolean | number | Iterable<number>
+  )
+
+export type INestedMatcher<T extends Node> = (
+  this: IReadonlyContext
+, node: T
+) => boolean
+
+export type ISkipMatcher<T extends Node> = (
+  this: IReadonlyContext
+, node: T
+) => number | Iterable<number> | false
+
+export type ITerminalMatcher<T extends Node> = (
+  this: IReadonlyContext
+, node: T
+) => boolean

package/src/utils/concat.ts

@@ -0,0 +1,9 @@
+export function concat(strings: TemplateStringsArray, values: string[]): string[] {
+  const result = []
+  for (let i = 0, len = values.length; i < len; i++) {
+    result.push(strings[i])
+    result.push(values[i])
+  }
+  result.push(strings[strings.length - 1])
+  return result
+}

package/src/utils/match-multiple.ts

@@ -0,0 +1,27 @@
+import { countup } from 'extra-generator'
+import { INestedMatcher, ITerminalMatcher, IReadonlyContext } from '@src/types.js'
+
+/**
+ * @returns {number} 返回值为成功匹配的元素个数, 当此值等于ubound时, 代表匹配成功.
+ */
+export function matchMultiple<T extends Node>(
+  this: IReadonlyContext
+, node: T
+, ubound: number
+, matcher: INestedMatcher<T> | ITerminalMatcher<T>
+): number {
+  let currentNode: T | null = node
+
+  for (const round of countup(1, ubound)) {
+    if (!currentNode) return round - 1
+
+    const result = matcher.call(this, currentNode)
+    if (result) {
+      currentNode = this.next(currentNode) as T | null
+    } else {
+      return round - 1
+    }
+  }
+
+  return ubound
+}

package/src/utils/match-one-by-one.ts

@@ -0,0 +1,47 @@
+import { IMatcher, IReadonlyContext } from '@src/types.js'
+import { isBoolean, isNumber, isIterable } from '@blackglory/prelude'
+
+export function matchOneByOne<T extends Node>(
+  context: IReadonlyContext
+, source: T | null
+, ...matchers: Array<IMatcher<T>>
+): boolean {
+  if (matchers.length === 0) return true
+  if (!source) return false
+
+  const [matcher, ...otherMatchers] = matchers
+
+  const result = Reflect.apply(matcher, context, [source]) as ReturnType<typeof matcher>
+
+  // TerminalMatcher
+  if (isBoolean(result)) {
+    if (result) {
+      const nextNode = context.next(source) as T | null
+      return matchOneByOne(context, nextNode, ...otherMatchers)
+    } else {
+      return false
+    }
+  }
+
+  // 此处一定是成功匹配, 因为SkipMatcher在失败时会返回false.
+  if (isNumber(result)) {
+    const distance = result
+    const nextNode = context.next(source, distance) as T | null
+    return matchOneByOne(context, nextNode, ...otherMatchers)
+  }
+
+  // SkipMatcher返回Iterable意味着存在多种可能性, 可能出现失败回溯.
+  if (isIterable(result)) {
+    for (const distance of result) {
+      const nextNode = context.next(source, distance) as T | null
+      if (matchOneByOne(context, nextNode, ...otherMatchers)) {
+        return true
+      }
+    }
+
+    // 尝试了所有可能性, 未发现可以匹配的结果
+    return false
+  }
+
+  throw new Error('Unknown return value')
+}

package/src/utils/merge-in-place.ts

@@ -0,0 +1,26 @@
+import { isArray } from '@blackglory/prelude'
+
+export function mergeInPlace<T>(
+  target: Record<string, T | T[]>
+, source: Record<string, T | T[]>
+): void {
+  for (const [key, value] of Object.entries(source)) {
+    if (target[key]) {
+      if (isArray(target[key])) {
+        if (isArray(value)) {
+          target[key] = [...target[key] as T[], ...value]
+        } else {
+          target[key] = [...target[key] as T[], value]
+        }
+      } else {
+        if (isArray(value)) {
+          target[key] = [target[key] as T, ...value]
+        } else {
+          target[key] = [target[key] as T, value]
+        }
+      }
+    } else {
+      target[key] = value
+    }
+  }
+}

package/src/utils/next-element-sibling.ts

@@ -0,0 +1,10 @@
+import * as ExtraDOM from 'extra-dom'
+
+export function nextElementSibling(
+  node: Node
+, distance: number = 1
+): Node | undefined {
+  if (distance === 0) return node
+
+  return ExtraDOM.nextElementSibling(node, distance)
+}

package/src/utils/next-sibling.ts

@@ -0,0 +1,7 @@
+import * as ExtraDOM from 'extra-dom'
+
+export function nextSibling(node: Node, distance: number = 1): Node | undefined {
+  if (distance === 0) return node
+
+  return ExtraDOM.nextSibling(node, distance)
+}