Add Feature object

Add Feature object with toString()/fromString() and use it in shape()
instead of passing comma-separated feature string.

Fixes #201

Author: khaledhosny

MIGRATING.md

@@ -68,6 +68,7 @@ When you need the raw HarfBuzz JSON output (e.g. to capture all fields including
 Affected APIs:
 
 - `Buffer.serialize` now takes a single options object: `{ font, start, end, format, flags }` (all optional). The previous positional signature is gone.
+- `shape` and `shapeWithTrace` now take `Feature[]` instead of a comma-separated string. Use the new `Feature` class (e.g. `new Feature("liga", 0)` or `Feature.fromString("-liga")`).
 - `Buffer.addText` / `Buffer.addCodePoints`: `itemLength` accepts `undefined` (or omission), instead of `null`.
 - `Face.getFeatureNameIds`: returns `undefined` on failure, instead of `null`.
 - `Font.glyphHOrigin` / `glyphVOrigin` / `glyphExtents` / `glyphFromName`: return `undefined` on failure, instead of `null`.

examples/harfbuzz.example.js

@@ -10,7 +10,7 @@ function example(hb, fontBlob, text) {
   buffer.addText(text || "abc");
   buffer.guessSegmentProperties();
   // buffer.setDirection(hb.Direction.LTR); // optional as can be set by guessSegmentProperties also
-  hb.shape(font, buffer); // features are not supported yet
+  hb.shape(font, buffer);
   var result = buffer.getGlyphInfosAndPositions();
 
   // returns glyphs paths, totally optional

harfbuzz.symbols

@@ -84,6 +84,7 @@ _hb_ot_tag_to_script
 _hb_ot_var_get_axis_infos
 _hb_script_from_string
 _hb_feature_from_string
+_hb_feature_to_string
 _hb_language_from_string
 _hb_language_to_string
 _hb_set_create

src/feature.ts

@@ -0,0 +1,135 @@
+import {
+  Module,
+  exports,
+  hb_tag,
+  hb_untag,
+  string_to_ascii_ptr,
+  utf8_ptr_to_string,
+} from "./helpers";
+
+/**
+ * A {@link https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-t | HarfBuzz feature}.
+ *
+ * The structure that holds information about requested feature application.
+ * The feature will be applied with the given value to all glyphs which are in
+ * clusters between {@link Feature.start} (inclusive) and {@link Feature.end}
+ * (exclusive). Setting `start` to `0` and `end` to `0xffffffff` specifies that
+ * the feature always applies to the entire buffer.
+ */
+export class Feature {
+  /**
+   * Special setting for {@link Feature.start} to apply the feature from the
+   * start of the buffer.
+   */
+  static readonly GLOBAL_START = 0;
+
+  /**
+   * Special setting for {@link Feature.end} to apply the feature from to the
+   * end of the buffer.
+   */
+  static readonly GLOBAL_END = 0xffffffff;
+
+  /** The tag of the feature. */
+  tag: string;
+  /**
+   * The value of the feature. `0` disables the feature, non-zero (usually `1`)
+   * enables the feature. For features implemented as lookup type 3 (like
+   * `salt`) the value is a one-based index into the alternates.
+   */
+  value: number;
+  /** The cluster to start applying this feature setting (inclusive). */
+  start: number;
+  /** The cluster to end applying this feature setting (exclusive). */
+  end: number;
+
+  constructor(
+    tag: string,
+    value: number = 1,
+    start: number = Feature.GLOBAL_START,
+    end: number = Feature.GLOBAL_END,
+  ) {
+    this.tag = tag;
+    this.value = value;
+    this.start = start;
+    this.end = end;
+  }
+
+  /**
+   * Parses a string into a Feature.
+   *
+   * The format for specifying feature strings follows. All valid CSS
+   * font-feature-settings values other than `normal` and the global values are
+   * also accepted, though not documented below. CSS string escapes are not
+   * supported.
+   *
+   * The range indices refer to the positions between Unicode characters. The
+   * position before the first character is always 0.
+   *
+   * The format is Python-esque. Here is how it all works:
+   *
+   * | Syntax        | Value | Start | End | Meaning                          |
+   * | ------------- | ----- | ----- | --- | -------------------------------- |
+   * | `kern`        | 1     | 0     | ∞   | Turn feature on                  |
+   * | `+kern`       | 1     | 0     | ∞   | Turn feature on                  |
+   * | `-kern`       | 0     | 0     | ∞   | Turn feature off                 |
+   * | `kern=0`      | 0     | 0     | ∞   | Turn feature off                 |
+   * | `kern=1`      | 1     | 0     | ∞   | Turn feature on                  |
+   * | `aalt=2`      | 2     | 0     | ∞   | Choose 2nd alternate             |
+   * | `kern[]`      | 1     | 0     | ∞   | Turn feature on                  |
+   * | `kern[:]`     | 1     | 0     | ∞   | Turn feature on                  |
+   * | `kern[5:]`    | 1     | 5     | ∞   | Turn feature on, partial         |
+   * | `kern[:5]`    | 1     | 0     | 5   | Turn feature on, partial         |
+   * | `kern[3:5]`   | 1     | 3     | 5   | Turn feature on, range           |
+   * | `kern[3]`     | 1     | 3     | 3+1 | Turn feature on, single char     |
+   * | `aalt[3:5]=2` | 2     | 3     | 5   | Turn 2nd alternate on for range  |
+   *
+   * @param str The string to parse.
+   * @returns A Feature, or undefined if the string is not a valid feature.
+   */
+  static fromString(str: string): Feature | undefined {
+    const sp = Module.stackSave();
+    const featurePtr = Module.stackAlloc(16);
+    const strPtr = string_to_ascii_ptr(str);
+    let feature: Feature | undefined;
+    if (exports.hb_feature_from_string(strPtr.ptr, -1, featurePtr)) {
+      feature = new Feature(
+        hb_untag(Module.HEAPU32[featurePtr / 4]),
+        Module.HEAPU32[featurePtr / 4 + 1],
+        Module.HEAPU32[featurePtr / 4 + 2],
+        Module.HEAPU32[featurePtr / 4 + 3],
+      );
+    }
+    strPtr.free();
+    Module.stackRestore(sp);
+    return feature;
+  }
+
+  /**
+   * Converts the feature to a string in the format understood by
+   * {@link Feature.fromString}.
+   *
+   * Note that the feature value will be omitted if it is `1`, but the string
+   * won't include any whitespace.
+   *
+   * @returns The feature string.
+   */
+  toString(): string {
+    const sp = Module.stackSave();
+    const featurePtr = Module.stackAlloc(16);
+    this.writeTo(featurePtr);
+    const bufLen = 128;
+    const bufPtr = Module.stackAlloc(bufLen);
+    exports.hb_feature_to_string(featurePtr, bufPtr, bufLen);
+    const result = utf8_ptr_to_string(bufPtr);
+    Module.stackRestore(sp);
+    return result;
+  }
+
+  /** @internal Write this feature into the given hb_feature_t pointer. */
+  writeTo(ptr: number): void {
+    Module.HEAPU32[ptr / 4] = hb_tag(this.tag);
+    Module.HEAPU32[ptr / 4 + 1] = this.value;
+    Module.HEAPU32[ptr / 4 + 2] = this.start;
+    Module.HEAPU32[ptr / 4 + 3] = this.end;
+  }
+}

src/index.ts

@@ -7,6 +7,7 @@ export * from "./face";
 export * from "./font";
 export * from "./font-funcs";
 export * from "./buffer";
+export * from "./feature";
 export * from "./shape";
 
 init(await createHarfBuzz());

src/shape.ts

@@ -4,12 +4,12 @@ import {
   hb_tag,
   hb_untag,
   utf8_ptr_to_string,
-  string_to_ascii_ptr,
   language_to_string,
   type ValueOf,
 } from "./helpers";
 import type { TraceEntry } from "./types";
 import type { Font } from "./font";
+import type { Feature } from "./feature";
 import {
   Buffer,
   BufferContentType,
@@ -33,30 +33,20 @@ export type TracePhase = ValueOf<typeof TracePhase>;
  * @param font The Font to shape with.
  * @param buffer The Buffer containing text to shape, suitably prepared
  *   (text added, segment properties set).
- * @param features A string of comma-separated OpenType features to apply.
+ * @param features An array of {@link Feature} values to apply.
  */
-export function shape(font: Font, buffer: Buffer, features?: string): void {
+export function shape(font: Font, buffer: Buffer, features?: Feature[]): void {
+  const featuresLen = features?.length ?? 0;
+  const sp = Module.stackSave();
   let featuresPtr = 0;
-  let featuresLen = 0;
-  if (features) {
-    const featureList = features.split(",");
-    featuresPtr = exports.malloc(16 * featureList.length);
-    featureList.forEach((feature) => {
-      const str = string_to_ascii_ptr(feature);
-      if (
-        exports.hb_feature_from_string(
-          str.ptr,
-          -1,
-          featuresPtr + featuresLen * 16,
-        )
-      )
-        featuresLen++;
-      str.free();
+  if (featuresLen) {
+    featuresPtr = Module.stackAlloc(16 * featuresLen);
+    features!.forEach((feature, i) => {
+      feature.writeTo(featuresPtr + i * 16);
     });
   }
-
   exports.hb_shape(font.ptr, buffer.ptr, featuresPtr, featuresLen);
-  if (featuresPtr) exports.free(featuresPtr);
+  Module.stackRestore(sp);
 }
 
 /**
@@ -67,15 +57,15 @@ export function shape(font: Font, buffer: Buffer, features?: string): void {
  *
  * @param font The Font to shape with.
  * @param buffer The Buffer containing text to shape, suitably prepared.
- * @param features A string of comma-separated OpenType features to apply.
+ * @param features An array of {@link Feature} values to apply.
  * @param stop_at A lookup ID at which to terminate shaping.
  * @param stop_phase The {@link TracePhase} at which to stop shaping.
  * @returns An array of trace entries, each with a message, serialized glyphs, and phase info.
  */
 export function shapeWithTrace(
   font: Font,
   buffer: Buffer,
-  features: string,
+  features: Feature[],
   stop_at: number,
   stop_phase: TracePhase,
 ): TraceEntry[] {

test/index.test.js

@@ -1080,6 +1080,42 @@ describe("Buffer", function () {
   });
 });
 
+describe("Feature", function () {
+  it("fromString parses simple tags", function () {
+    expect(hb.Feature.fromString("liga")).to.deep.equal(
+      new hb.Feature("liga", 1, 0, 0xffffffff),
+    );
+    expect(hb.Feature.fromString("-kern")).to.deep.equal(
+      new hb.Feature("kern", 0, 0, 0xffffffff),
+    );
+  });
+
+  it("fromString parses values and ranges", function () {
+    expect(hb.Feature.fromString("salt=2")).to.deep.equal(
+      new hb.Feature("salt", 2, 0, 0xffffffff),
+    );
+    expect(hb.Feature.fromString("aalt[3:5]=2")).to.deep.equal(
+      new hb.Feature("aalt", 2, 3, 5),
+    );
+  });
+
+  it("fromString returns undefined for invalid input", function () {
+    expect(hb.Feature.fromString("not a feature")).to.equal(undefined);
+  });
+
+  it("toString round-trips canonical forms", function () {
+    for (const str of ["liga", "-kern", "salt=2", "aalt[3:5]=2"]) {
+      expect(hb.Feature.fromString(str).toString()).to.equal(str);
+    }
+  });
+
+  it("toString uses default range and value", function () {
+    expect(new hb.Feature("liga").toString()).to.equal("liga");
+    expect(new hb.Feature("kern", 0).toString()).to.equal("-kern");
+    expect(new hb.Feature("salt", 2).toString()).to.equal("salt=2");
+  });
+});
+
 describe("shape", function () {
   it("shape Latin string", function () {
     let blob = new hb.Blob(
@@ -1267,7 +1303,7 @@ describe("shape", function () {
     const result = hb.shapeWithTrace(
       font,
       buffer,
-      "",
+      [],
       0,
       hb.TracePhase.DONT_STOP,
     );
@@ -1304,7 +1340,7 @@ describe("shape", function () {
     const result = hb.shapeWithTrace(
       font,
       buffer,
-      "-liga,-kern",
+      [new hb.Feature("liga", 0), new hb.Feature("kern", 0)],
       0,
       hb.TracePhase.DONT_STOP,
     );