Text Quote Anchor

Find and describe ranges of a document using text quotes.

This library is capable of searching for text content within a DOM node, utilizing optional context strings and/or offset hint to disambiguate matches.

Functions are provided for finding a quote within a DOM node and returning either the text offsets of the best match or a DOM Range instance, as well as functions to perform the inverse operations of describing a Range or a sub-string identified by text offsets in terms of the selected text and its surrounding context.

Searching is performed using the diff-match-patch library to support finding approximate matches.

Relevant specifications:

• Range
• Web Annotation TextPositionSelector
• Web Annotation TextQuoteSelector

Installation

To require('dom-anchor-text-quote'):

npm install dom-anchor-text-quote

Usage

API Documentation

fromRange(root, range)

This function is a short-hand for the following equivalent code:

import * as textPosition from 'dom-anchor-text-position'
import * as textQuote from 'dom-anchor-text-quote'

function fromRange(root, range) {
  let position = textPosition.fromRange(root, range)
  let selector = textQuote.fromTextPosition(root, position)
}

The return value is an Object with exact, prefix and suffix keys.

fromTextPosition(root, selector)

Given an Object containing start and end keys, returns an Object containing the sub-string [start, end) of the text content of root Node in the value of the exact key and surrounding context (up to thirty-two characters in either direction) in the prefix and suffix keys.

The resulting Object is a text position selector suitable for use with the dom-anchor-text-position library. See the documentation of dom-anchor-text-position for details.

toRange(root, selector, [options])

This function is a short-hand for the following equivalent code:

import * as textPosition from 'dom-anchor-text-position'
import * as textQuote from 'dom-anchor-text-quote'

function toRange(root, selector, options) {
  let position = textQuote.toTextPosition(root, selector, options)
  return textPosition.toRange(position)
}

The return value is a Range instance or null if the quote is not found.

toTextPosition(root, selector, [options])

Given an Object selector with an exact key, returns an Object with keys start and end. The sub-string [start, end) of the text content of the root Node is an approximate match for the value of the exact key. Optional selector keys prefix and suffix, if provided, are used to disambiguate between multiple matches. The return value is null if the quote is not found.

If the options argument is an Object with an integer valued hint key then the quote search will prioritize matches that are closer to this offset over equivalent matches that are farther away.