glost-utils
Framework-agnostic utilities for GLOST manipulation, conversion, and merging.
Installation
pnpm add @glotblocks/glost-utilsExports
// Main entry
import { ... } from '@glotblocks/glost-utils';
// Subpath exports
import { convertTextToGLOST } from '@glotblocks/glost-utils/text-to-glost';
import { mergeTranscriptionData } from '@glotblocks/glost-utils/merger';
import { getAllWordsFromDocument } from '@glotblocks/glost-utils/document';
import { convertScriptToString } from '@glotblocks/glost-utils/script';Text-to-GLOST Conversion
convertTextToGLOST
Convert plain text to a GLOST document.
function convertTextToGLOST(
text: string,
options: ConvertTextToGLOSTOptions
): GLOSTRoot;
interface ConvertTextToGLOSTOptions {
language: GlostLanguage;
script?: string;
languageStrategy?: LanguageStrategy;
transcriptionProvider?: TranscriptionProvider;
}Example:
import { convertTextToGLOST } from '@glotblocks/glost-utils';
const document = convertTextToGLOST("Hello world!", {
language: "en",
script: "latin"
});Custom Word Segmentation
For languages without spaces (Thai, Japanese, Chinese):
const document = convertTextToGLOST("สวัสดีครับ", {
language: "th",
languageStrategy: {
segmentWords: (text) => {
// Custom Thai word segmentation
return ["สวัสดี", "ครับ"];
}
}
});Custom Transcription
const document = convertTextToGLOST("สวัสดี", {
language: "th",
transcriptionProvider: async (word, lang) => {
// Fetch transcription from dictionary
return { rtgs: "sawatdi", ipa: "sa.wàt.diː" };
}
});GLOST Merging
mergeTranscriptionData
Merge transcription data from multiple sources.
function mergeTranscriptionData(
base: TransliterationData,
additions: TransliterationData
): TransliterationData;Example:
const merged = mergeTranscriptionData(
{ rtgs: { text: "sawatdi", system: "rtgs" } },
{ ipa: { text: "sa.wàt.diː", system: "ipa" } }
);
// { rtgs: {...}, ipa: {...} }mergeTranscriptionDataIntoDocument
Apply transcription data to all matching words.
function mergeTranscriptionDataIntoDocument(
document: GLOSTRoot,
transcriptionMap: Record<string, TransliterationData>
): GLOSTRoot;extendGLOSTWithMetadata
Add metadata to a word.
function extendGLOSTWithMetadata(
word: GLOSTWord,
metadata: Partial<ExtendedMetadata>
): GLOSTWord;extendGLOSTDocumentWithMetadata
Add metadata to all matching words in a document.
function extendGLOSTDocumentWithMetadata(
document: GLOSTRoot,
metadataMap: Record<string, Partial<ExtendedMetadata>>
): GLOSTRoot;hydrateGLOSTDocument
Hydrate a document with external data.
function hydrateGLOSTDocument(
document: GLOSTRoot,
data: Record<string, any>
): GLOSTRoot;filterGLOSTByGender
Filter document content by grammatical gender.
function filterGLOSTByGender(
document: GLOSTRoot,
gender: "male" | "female"
): GLOSTRoot;Document Utilities
getAllWordsFromDocument
Get all words from a document.
function getAllWordsFromDocument(doc: GLOSTRoot): GLOSTWord[];getFirstSentenceFromDocument
Get the first sentence.
function getFirstSentenceFromDocument(doc: GLOSTRoot): GLOSTSentence | null;getWordsFromFirstSentence
Get words from the first sentence.
function getWordsFromFirstSentence(doc: GLOSTRoot): GLOSTWord[];getDocumentTranscriptionSystems
Get all transcription systems used in a document.
function getDocumentTranscriptionSystems(doc: GLOSTRoot): string[];hasTranscriptionData
Check if document has a specific transcription system.
function hasTranscriptionData(doc: GLOSTRoot, system: string): boolean;getDocumentMetadata
Get document metadata.
function getDocumentMetadata(doc: GLOSTRoot): Record<string, any>;getSentenceTranslation
Get translation for a sentence.
function getSentenceTranslation(
sentence: GLOSTSentence,
lang: GlostLanguage
): string | undefined;Script Conversion
RubySegment
For languages with ruby/furigana annotations.
type RubySegment = { base: string; ruby: string };convertScriptToString
Convert script (string or ruby) to plain string.
function convertScriptToString(script: string | RubySegment[]): string;isRubySegment
Check if item is a ruby segment.
function isRubySegment(item: unknown): item is RubySegment;isRubyScript
Check if script contains ruby annotations.
function isRubyScript(script: string | RubySegment[]): boolean;getPlainText
Extract plain text from any script format.
function getPlainText(script: string | RubySegment[]): string;ensureArrayFormat
Convert script to ruby segment array.
function ensureArrayFormat(script: string | RubySegment[]): RubySegment[];ensureStringFormat
Convert script to string.
function ensureStringFormat(script: string | RubySegment[]): string;