Add Language class wrapping hb_language_t

Similar Feature.

Author: khaledhosny

MIGRATING.md

@@ -69,6 +69,7 @@ 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.setLanguage`, `Face.getName`, `Face.listNames`, and `otTagToLanguage` now use the new `Language` class instead of plain BCP 47 strings (e.g. `buffer.setLanguage(new Language("en"))`).
 - `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`.

src/buffer.ts

@@ -10,6 +10,7 @@ import {
 } from "./helpers";
 import type { GlyphInfo, GlyphPosition } from "./types";
 import { Font } from "./font";
+import type { Language } from "./language";
 
 export const BufferContentType = {
   INVALID: 0,
@@ -177,15 +178,10 @@ export class Buffer {
 
   /**
    * Set buffer language explicitly.
-   * @param language The buffer language
+   * @param language The buffer language.
    */
-  setLanguage(language: string): void {
-    const str = string_to_ascii_ptr(language);
-    exports.hb_buffer_set_language(
-      this.ptr,
-      exports.hb_language_from_string(str.ptr, -1),
-    );
-    str.free();
+  setLanguage(language: Language): void {
+    exports.hb_buffer_set_language(this.ptr, language.ptr);
   }
 
   /**

src/face.ts

@@ -6,13 +6,12 @@ import {
   hb_tag,
   hb_untag,
   utf16_ptr_to_string,
-  language_to_string,
-  language_from_string,
   typed_array_from_set,
   type ValueOf,
 } from "./helpers";
 import type { AxisInfo, NameEntry, FeatureNameIds } from "./types";
 import type { Blob } from "./blob";
+import { Language } from "./language";
 
 const HB_OT_NAME_ID_INVALID = 0xffff;
 
@@ -266,9 +265,7 @@ export class Face {
     for (let i = 0; i < numEntries; i++) {
       entries.push({
         nameId: Module.HEAPU32[entriesPtr / 4 + i * 3],
-        language: language_to_string(
-          Module.HEAPU32[entriesPtr / 4 + i * 3 + 2],
-        ),
+        language: new Language(Module.HEAPU32[entriesPtr / 4 + i * 3 + 2]),
       });
     }
     Module.stackRestore(sp);
@@ -281,18 +278,17 @@ export class Face {
    * @param language The language of the name to get.
    * @returns The name string.
    */
-  getName(nameId: number, language: string): string {
+  getName(nameId: number, language: Language): string {
     const sp = Module.stackSave();
-    const languagePtr = language_from_string(language);
     const nameLen =
-      exports.hb_ot_name_get_utf16(this.ptr, nameId, languagePtr, 0, 0) + 1;
+      exports.hb_ot_name_get_utf16(this.ptr, nameId, language.ptr, 0, 0) + 1;
     const textSizePtr = Module.stackAlloc(4);
     const textPtr = exports.malloc(nameLen * 2);
     Module.HEAPU32[textSizePtr / 4] = nameLen;
     exports.hb_ot_name_get_utf16(
       this.ptr,
       nameId,
-      languagePtr,
+      language.ptr,
       textSizePtr,
       textPtr,
     );

src/helpers.ts

@@ -119,18 +119,6 @@ export function string_to_utf16_ptr(text: string): StringPtr {
   };
 }
 
-export function language_to_string(language: number): string {
-  const ptr = exports.hb_language_to_string(language);
-  return utf8_ptr_to_string(ptr);
-}
-
-export function language_from_string(str: string): number {
-  const languageStr = string_to_ascii_ptr(str);
-  const languagePtr = exports.hb_language_from_string(languageStr.ptr, -1);
-  languageStr.free();
-  return languagePtr;
-}
-
 /**
  * Return the typed array of HarfBuzz set contents.
  * @param setPtr Pointer of set

src/index.ts

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

src/language.ts

@@ -0,0 +1,36 @@
+import { exports, string_to_ascii_ptr, utf8_ptr_to_string } from "./helpers";
+
+/**
+ * A {@link https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-language-t | HarfBuzz language}.
+ *
+ * Data type for languages. Each Language corresponds to a BCP 47 language tag.
+ */
+export class Language {
+  readonly ptr: number;
+
+  /**
+   * Converts `tag` representing a BCP 47 language tag to the corresponding
+   * Language.
+   * @param tag A string representing a BCP 47 language tag.
+   */
+  constructor(tag: string);
+  /** @internal Wrap an existing hb_language_t. */
+  constructor(existingPtr: number);
+  constructor(arg: string | number) {
+    if (typeof arg === "number") {
+      this.ptr = arg;
+    } else {
+      const strPtr = string_to_ascii_ptr(arg);
+      this.ptr = exports.hb_language_from_string(strPtr.ptr, -1);
+      strPtr.free();
+    }
+  }
+
+  /**
+   * Converts the language to a string.
+   * @returns A string representing the language.
+   */
+  toString(): string {
+    return utf8_ptr_to_string(exports.hb_language_to_string(this.ptr));
+  }
+}

src/shape.ts

@@ -4,12 +4,12 @@ import {
   hb_tag,
   hb_untag,
   utf8_ptr_to_string,
-  language_to_string,
   type ValueOf,
 } from "./helpers";
 import type { TraceEntry } from "./types";
 import type { Font } from "./font";
 import type { Feature } from "./feature";
+import { Language } from "./language";
 import {
   Buffer,
   BufferContentType,
@@ -150,8 +150,6 @@ export function otTagToScript(tag: string): string {
  * @param tag The tag to convert.
  * @returns The language.
  */
-export function otTagToLanguage(tag: string): string {
-  const hbTag = hb_tag(tag);
-  const language = exports.hb_ot_tag_to_language(hbTag);
-  return language_to_string(language);
+export function otTagToLanguage(tag: string): Language {
+  return new Language(exports.hb_ot_tag_to_language(hb_tag(tag)));
 }

src/types.ts

@@ -1,4 +1,5 @@
 import type { ValueOf } from "./helpers";
+import type { Language } from "./language";
 
 // Data shape types
 export interface FontExtents {
@@ -47,7 +48,7 @@ export interface AxisInfo {
 
 export interface NameEntry {
   nameId: number;
-  language: string;
+  language: Language;
 }
 
 export interface FeatureNameIds {

test/index.test.js

@@ -271,17 +271,19 @@ describe("Face", function () {
     let face = new hb.Face(blob);
     let names = face.listNames();
     expect(names.length).to.equal(38);
-    expect(names[0]).to.deep.equal({ nameId: 0, language: "en" });
-    expect(names[37]).to.deep.equal({ nameId: 278, language: "en" });
+    expect(names[0].nameId).to.equal(0);
+    expect(names[0].language.toString()).to.equal("en");
+    expect(names[37].nameId).to.equal(278);
+    expect(names[37].language.toString()).to.equal("en");
   });
 
   it("getName fetches a name", function () {
     let blob = new hb.Blob(
       fs.readFileSync(path.join(__dirname, "fonts/noto/NotoSans-Regular.ttf")),
     );
     let face = new hb.Face(blob);
-    expect(face.getName(1, "en")).to.equal("Noto Sans");
-    expect(face.getName(256, "en")).to.equal("florin symbol");
+    expect(face.getName(1, new hb.Language("en"))).to.equal("Noto Sans");
+    expect(face.getName(256, new hb.Language("en"))).to.equal("florin symbol");
   });
 
   it("getFeatureNameIds returns valid name Ids for ssNN features", function () {
@@ -311,7 +313,7 @@ describe("Face", function () {
           "GSUB",
           face.getTableFeatureTags("GSUB").indexOf("ss03"),
         ).uiLabelNameId,
-        "en",
+        new hb.Language("en"),
       ),
     ).to.equal("florin symbol");
   });
@@ -1080,6 +1082,18 @@ describe("Buffer", function () {
   });
 });
 
+describe("Language", function () {
+  it("toString returns the BCP 47 tag", function () {
+    expect(new hb.Language("en").toString()).to.equal("en");
+    expect(new hb.Language("fa-IR").toString()).to.equal("fa-ir");
+  });
+
+  it("interns by tag", function () {
+    expect(new hb.Language("en").ptr).to.equal(new hb.Language("en").ptr);
+    expect(new hb.Language("en").ptr).to.not.equal(new hb.Language("fr").ptr);
+  });
+});
+
 describe("Feature", function () {
   it("fromString parses simple tags", function () {
     expect(hb.Feature.fromString("liga")).to.deep.equal(
@@ -1387,7 +1401,7 @@ describe("shape", function () {
 
     buffer.clearContents();
     buffer.addText("५ल");
-    buffer.setLanguage("dty");
+    buffer.setLanguage(new hb.Language("dty"));
     buffer.guessSegmentProperties();
     hb.shape(font, buffer);
     var infos = buffer.getGlyphInfos();
@@ -1413,7 +1427,7 @@ describe("shape", function () {
 
     buffer.clearContents();
     buffer.addText("५ल");
-    buffer.setLanguage("x-hbot-4e455020"); // 'NEP '
+    buffer.setLanguage(new hb.Language("x-hbot-4e455020")); // 'NEP '
     buffer.guessSegmentProperties();
     hb.shape(font, buffer);
     var infos = buffer.getGlyphInfos();
@@ -1445,10 +1459,10 @@ describe("misc", function () {
   });
 
   it("convert OpenType tag to language", function () {
-    expect(hb.otTagToLanguage("ARA ")).to.equal("ar");
-    expect(hb.otTagToLanguage("ENG ")).to.equal("en");
-    expect(hb.otTagToLanguage("BAD0")).to.equal("bad");
-    expect(hb.otTagToLanguage("SYRE")).to.equal("und-syre");
+    expect(hb.otTagToLanguage("ARA ").toString()).to.equal("ar");
+    expect(hb.otTagToLanguage("ENG ").toString()).to.equal("en");
+    expect(hb.otTagToLanguage("BAD0").toString()).to.equal("bad");
+    expect(hb.otTagToLanguage("SYRE").toString()).to.equal("und-syre");
   });
 
   it("test that calling functions repeatedly doesn't exhaust memory", function () {
@@ -1459,7 +1473,7 @@ describe("misc", function () {
     let font = new hb.Font(face);
     for (let i = 0; i < 10000; i++) {
       expect(face.listNames()).to.not.be.undefined;
-      expect(face.getName(0, "en")).to.not.be.undefined;
+      expect(face.getName(0, new hb.Language("en"))).to.not.be.undefined;
       expect(font.hExtents()).to.not.be.undefined;
       expect(font.vExtents()).to.not.be.undefined;
       expect(font.glyphHOrigin(0)).to.not.be.undefined;