@knaw-huc/text-annotation-segmenter 0.5.1 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@knaw-huc/text-annotation-segmenter.svg?color=green)](https://www.npmjs.com/package/@knaw-huc/text-annotation-segmenter)
 
-Utility functions to render annotations with character offsets in a text.
+Utility functions to render annotations with character position offsets in a text.
 
 Annotations on a text have a non-hierarchical nature, i.e., they can overlap:
 ```text
@@ -24,16 +24,16 @@ The `segment` function creates an array of segments: a flat, non-overlapping lis
 
 ### Functions
 
-- [`segment<T>(text, annotations, getOffsets, getMarkerPosition?): TextSegment<T>[]`](./src/segment.ts) <br /> Split a text into TextSegments with character offsets to the text and a list of applying annotations.
+- [`segment<T>(text, annotations, getOffsets, getMarkerPosition?): TextSegment<T>[]`](./src/segment.ts) <br /> Split a text into TextSegments with character positions and a list of applying annotations.
 - [`groupSegments<T>(segments, isGroup, getId): SegmentGroup<T>[]`](src/groupSegments.ts) <br /> Recursively group segments into higher-level units (e.g., words, paragraphs, divs) by collecting all segments that share a matching annotation.
 - [`collectGroupSegments<T>(group): TextSegment<T>[]`](src/groupSegments.ts) <br /> Recursively collect all TextSegments from a Group.
-- [`findSegmentOffsets<T>(segments): Map<T, SegmentOffsets>`](src/findSegmentOffsets.ts) <br /> For each annotation, collect the first and last segment index it appears in, keyed by object reference.
+- [`findSegmentRange<T>(segments): Map<T, SegmentRange>`](src/findSegmentRange.ts) <br /> For each annotation, collect the first and last segment index it appears in, keyed by object reference.
 
 ### Types
 
 - [`SegmentGroup<T>`](src/groupSegments.ts) <br /> A `Group<T>` (with annotation and recursive children) or `Ungrouped<T>` (with plain segments).
-- [`SegmentOffsets`](src/findSegmentOffsets.ts) <br /> Start and end segment index of an annotation (excluding end segment).
-- [`TextSegment<T>`](./src/Model.ts) <br /> Start and end offsets of text segment (excluding last character), plus the annotations that apply.
+- [`SegmentRange`](src/findSegmentRange.ts) <br /> Start and end segment index of an annotation (excluding last segment).
+- [`TextSegment<T>`](./src/Model.ts) <br /> Start and end positions of text segment (excluding last character), plus the annotations that apply.
 
 ## Examples
 
@@ -51,17 +51,17 @@ annotation bc:   __
 import {segment} from "@knaw-huc/text-annotation-segmenter";
 
 const text = 'abc';
-const ab = {id: 'ab', begin: 0, end: 2};
-const bc = {id: 'bc', begin: 1, end: 3};
+const ab = {id: 'ab', start: 0, end: 2};
+const bc = {id: 'bc', start: 1, end: 3};
 
 const getOffsets = annotation => annotation;
 
 const segments = segment(text, [ab, bc], getOffsets);
 
 expect(segments).toEqual([
-  {index: 0, begin: 0, end: 1, body: 'a', annotations: [ab]},
-  {index: 1, begin: 1, end: 2, body: 'b', annotations: [ab, bc]},
-  {index: 2, begin: 2, end: 3, body: 'c', annotations: [bc]},
+  {index: 0, start: 0, end: 1, value: 'a', annotations: [ab]},
+  {index: 1, start: 1, end: 2, value: 'b', annotations: [ab, bc]},
+  {index: 2, start: 2, end: 3, value: 'c', annotations: [bc]},
 ]);
 ```
 - More examples: [segment.spec.ts](./src/segment.spec.ts).
@@ -83,8 +83,8 @@ paragraph:  __
 import {segment, groupSegments} from "@knaw-huc/text-annotation-segmenter";
 
 const text = 'aabb';
-const section = {id: 'section', type: 'section', begin: 0, end: 4};
-const paragraph = {id: 'paragraph', type: 'paragraph', begin: 0, end: 2};
+const section = {id: 'section', type: 'section', start: 0, end: 4};
+const paragraph = {id: 'paragraph', type: 'paragraph', start: 0, end: 2};
 
 const getOffsets = annotation => annotation;
 const segments = segment(text, [section, paragraph], getOffsets);
@@ -125,19 +125,19 @@ annotation b:        _
 
 ```ts
 const text = 'ab';
-const marker: Annotation = {begin: 1, end: 1, id: 'm'};
-const a: Annotation = {begin: 0, end: 1, id: 'a'};
-const b: Annotation = {begin: 1, end: 2, id: 'b'};
+const marker: Annotation = {start: 1, end: 1, id: 'm'};
+const a: Annotation = {start: 0, end: 1, id: 'a'};
+const b: Annotation = {start: 1, end: 2, id: 'b'};
 
 const segments = segment(text, [marker, a, b], getOffsets);
 const markerSegment = segments[1];
 expect(markerSegment).toEqual(
-  {index: 1, begin: 1, end: 1, body: '', annotations: [marker, a]},
+  {index: 1, start: 1, end: 1, value: '', annotations: [marker, a]},
 );
 ```
-Notice how the marker is 'postfixed' to the previous annotation. When the marker shares its character index with the start and end offsets of annotations, by default the marker segment will only include the annotations that end at that offset (e.g: a note at the end of a paragraph).
+Notice how the marker is 'postfixed' to the previous annotation. When the marker shares its character index with the start and end positions of annotations, by default the marker segment will only include the annotations that end at that position (e.g: a note at the end of a paragraph).
 
-However, markers can also be prefixed to annotations that share their start offset with the marker, using the `getMarkerPosition` parameter of the `segment` function:
+However, markers can also be prefixed to annotations that share their start position with the marker, using the `getMarkerPosition` parameter of the `segment` function:
 
 ```ts
 const getMarkerPosition = a => a.id === 'm' ? 'prefix' : 'postfix'
@@ -145,7 +145,7 @@ const segments = segment(text, [marker, a, b], getOffsets, getMarkerPosition);
 
 const markerSegment = segments[1];
 expect(markerSegment).toEqual(
-  {index: 1, begin: 1, end: 1, body: '', annotations: [marker, b]},
+  {index: 1, start: 1, end: 1, value: '', annotations: [marker, b]},
 );
 ```
 More examples: [segment.spec.ts](./src/segment.spec.ts#L118).

package/dist/GetOffsets.d.ts

@@ -1,2 +1,2 @@
-import { Offsets } from './Model.ts';
-export type GetOffsets<T> = (annotation: T) => Offsets;
+import { TextPosition } from './Model.ts';
+export type GetOffsets<T> = (annotation: T) => TextPosition;

package/dist/Model.d.ts

@@ -1,17 +1,24 @@
 /**
  * Start and end character, end excluding last character
  */
-export type Offsets = {
-    begin: number;
+export type TextPosition = {
+    start: number;
     end: number;
 };
 /**
- * Output: start and end offsets of text segment (excluding last character), plus the annotations that apply.
+ * Output: the character range and sliced text of a text segment, plus all annotations that apply.
  */
-export type TextSegment<T> = Offsets & {
+export type TextSegment<T> = TextPosition & {
     index: SegmentIndex;
-    body: string;
+    value: string;
     annotations: T[];
 };
 export type SegmentIndex = number;
 export type MarkerPosition = 'prefix' | 'postfix';
+/**
+ * Start and end segment index of an annotation, excluding last segment
+ */
+export type SegmentRange = {
+    startSegment: number;
+    endSegment: number;
+};

package/dist/findSegmentRange.d.ts

@@ -0,0 +1,6 @@
+import { SegmentRange, TextSegment } from './Model';
+/**
+ * For each annotation, collect the first and last segment index it appears in,
+ * keyed by object reference.
+ */
+export declare function findSegmentRange<T>(segments: TextSegment<T>[]): Map<T, SegmentRange>;

package/dist/index.d.ts

@@ -1,10 +1,9 @@
 export { segment } from './segment.ts';
 export type { AnnotationSegmentsByChar } from './segment.ts';
-export { findSegmentOffsets } from './findSegmentOffsets.ts';
-export type { SegmentOffsets } from './findSegmentOffsets.ts';
+export { findSegmentRange } from './findSegmentRange.ts';
 export { groupSegments } from './groupSegments.ts';
 export { collectGroupSegments } from './collectGroupSegments.ts';
 export type { Group, SegmentGroup } from './groupSegments.ts';
-export type { Offsets, TextSegment, SegmentIndex, MarkerPosition, } from './Model.ts';
+export type { TextPosition, TextSegment, SegmentIndex, MarkerPosition, SegmentRange } from './Model.ts';
 export type { GetOffsets } from './GetOffsets.ts';
 export type { GetMarkerPosition } from './GetMarkerPosition.ts';

package/dist/index.js

@@ -6,17 +6,17 @@ function segment(text, annotations, getOffsets, getMarkerPosition = () => "postf
     return offset || (offset = { charIndex, starting: [], ending: [] }, offsetMap.set(charIndex, offset)), offset;
   }, createMarkerSegment = (markers, charIndex) => ({
     index: ++segmentCounter,
-    begin: charIndex,
+    start: charIndex,
     end: charIndex,
-    body: "",
+    value: "",
     annotations: [...markers, ...activeAnnotations]
   });
   getOrCreateOffset(0), getOrCreateOffset(text.length);
   for (const annotation of annotations) {
-    const offsets = getOffsets(annotation), isMarker = offsets.begin === offsets.end;
-    if (isMarker && (offsets.end < 0 || offsets.begin > text.length) || !isMarker && (offsets.end <= 0 || offsets.begin >= text.length))
+    const offsets = getOffsets(annotation), isMarker = offsets.start === offsets.end;
+    if (isMarker && (offsets.end < 0 || offsets.start > text.length) || !isMarker && (offsets.end <= 0 || offsets.start >= text.length))
       continue;
-    const begin = Math.max(0, offsets.begin), end = Math.min(text.length, offsets.end);
+    const begin = Math.max(0, offsets.start), end = Math.min(text.length, offsets.end);
     getOrCreateOffset(begin).starting.push(annotation), getOrCreateOffset(end).ending.push(annotation);
   }
   const sortedOffsets = [...offsetMap.values()].sort(
@@ -28,9 +28,9 @@ function segment(text, annotations, getOffsets, getMarkerPosition = () => "postf
       const index = ++segmentCounter;
       segments.push({
         index,
-        begin: lastOffset,
+        start: lastOffset,
         end: offset.charIndex,
-        body: text.slice(lastOffset, offset.charIndex),
+        value: text.slice(lastOffset, offset.charIndex),
         annotations: [...activeAnnotations]
       });
     }
@@ -47,12 +47,12 @@ function segment(text, annotations, getOffsets, getMarkerPosition = () => "postf
   }
   return segments;
 }
-function findSegmentOffsets(segments) {
+function findSegmentRange(segments) {
   const offsets = /* @__PURE__ */ new Map();
   for (let i = 0; i < segments.length; i++)
     for (const annotation of segments[i].annotations) {
       const existing = offsets.get(annotation);
-      existing ? existing.endSegment = i + 1 : offsets.set(annotation, { beginSegment: i, endSegment: i + 1 });
+      existing ? existing.endSegment = i + 1 : offsets.set(annotation, { startSegment: i, endSegment: i + 1 });
     }
   return offsets;
 }
@@ -102,7 +102,7 @@ function collectGroupSegments(group2) {
 }
 export {
   collectGroupSegments,
-  findSegmentOffsets,
+  findSegmentRange,
   groupSegments,
   segment
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knaw-huc/text-annotation-segmenter",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/knaw-huc/text-annotation-segmenter.git"

package/dist/findSegmentOffsets.d.ts

@@ -1,13 +0,0 @@
-import { TextSegment } from './Model';
-export type SegmentOffsets = {
-    beginSegment: number;
-    /**
-     * Excluding last segment
-     */
-    endSegment: number;
-};
-/**
- * For each annotation, collect the first and last segment index
- * it appears in, keyed by object reference.
- */
-export declare function findSegmentOffsets<T>(segments: TextSegment<T>[]): Map<T, SegmentOffsets>;