glost-plugins
Core extension system for GLOST document processing.
Installation
pnpm add @glotblocks/glost-pluginsOverview
@glotblocks/glost-plugins provides the core extension infrastructure:
- Extension processing functions
- Extension registry for managing extensions
- Built-in extensions for common transformations
- Type definitions for creating custom extensions
Individual data-enrichment extensions (frequency, difficulty, POS, etc.) are in separate packages.
Processing with Extensions
import { processGLOST, type GLOSTExtension } from '@glotblocks/glost-plugins';
// Define a custom extension
const myExtension: GLOSTExtension = {
id: 'my-extension',
name: 'My Extension',
visit: {
word: (node) => ({
...node,
extras: { ...node.extras, processed: true }
})
}
};
// Process document
const result = processGLOST(document, [myExtension]);Async Processing
import { processGLOSTWithExtensionsAsync } from '@glotblocks/glost-plugins';
const result = await processGLOSTWithExtensionsAsync(document, [
asyncExtension1,
asyncExtension2
]);Extension Registry
Global Registry
import {
extensionRegistry,
registerExtension,
registerExtensions,
getExtension,
getAllExtensions
} from '@glotblocks/glost-plugins';
// Register extensions
registerExtension(myExtension);
registerExtensions([ext1, ext2]);
// Get extensions
const ext = getExtension('my-extension');
const all = getAllExtensions();Using Registered Extensions
import { processGLOSTWithExtensionIds } from '@glotblocks/glost-plugins';
// Process using extension IDs from registry
const result = processGLOSTWithExtensionIds(document, [
'cultural-notes',
'gender-transformer'
]);Built-in Extensions
CulturalNotesExtension
Formats cultural notes for display.
import {
CulturalNotesExtension,
createCulturalNotesExtension
} from '@glotblocks/glost-plugins';
// Use default
const result = processGLOST(document, [CulturalNotesExtension]);
// Or create with options
const customExtension = createCulturalNotesExtension({
// options
});Expects: extras.metadata.culturalNotes on words
Adds: Formatted cultural notes display data
GenderTransformerExtension
Transforms text with gender variants.
import { createGenderTransformerExtension } from '@glotblocks/glost-plugins';
const transformer = createGenderTransformerExtension({
targetGender: 'female', // 'male' | 'female'
displayFormat: 'replace' // 'replace' | 'show-both' | 'inline-toggle'
});Input format: "{masculine|feminine}" in text
Output: Based on targetGender and displayFormat
NegationTransformerExtension
Marks clauses containing negation.
import { NegationTransformerExtension } from '@glotblocks/glost-plugins';Dependencies: Clause analysis (must run first) Adds: Negation metadata to clauses
ReadingScoreExtension
Computes reading difficulty scores.
import { createReadingScoreExtension } from '@glotblocks/glost-plugins';
const scorer = createReadingScoreExtension({
// options
});LearnerHintsExtension
Generates learner hints based on word metadata.
import { createLearnerHintsExtension } from '@glotblocks/glost-plugins';
const hints = createLearnerHintsExtension({
// options
});ClauseAnalysisExtension
Analyzes clause structure in sentences.
import { createClauseAnalysisExtension } from '@glotblocks/glost-plugins';
const analyzer = createClauseAnalysisExtension({
// options
});Separate Extension Packages
Data-enrichment extensions are in separate packages:
| Package | Description | Install |
|---|---|---|
@glotblocks/glost-frequency | Word frequency data | pnpm add @glotblocks/glost-frequency |
@glotblocks/glost-difficulty | Difficulty assessment | pnpm add @glotblocks/glost-difficulty |
@glotblocks/glost-pos | Part-of-speech tagging | pnpm add @glotblocks/glost-pos |
@glotblocks/glost-gender | Grammatical gender | pnpm add @glotblocks/glost-gender |
@glotblocks/glost-transcription | Transcription/romanization | pnpm add @glotblocks/glost-transcription |
@glotblocks/glost-translation | Translation data | pnpm add @glotblocks/glost-translation |
@glotblocks/glost-clause-segmenter | Clause segmentation | pnpm add @glotblocks/glost-clause-segmenter |
Example using separate packages:
import { processGLOSTWithExtensionsAsync } from '@glotblocks/glost-plugins';
import { createFrequencyExtension } from '@glotblocks/glost-frequency';
import { createDifficultyExtension } from '@glotblocks/glost-difficulty';
const [freqGen, freqEnh] = createFrequencyExtension({
targetLanguage: 'th',
provider: myFrequencyProvider
});
const [diffGen, diffEnh] = createDifficultyExtension({
targetLanguage: 'th',
provider: myDifficultyProvider
});
const result = await processGLOSTWithExtensionsAsync(document, [
freqGen, freqEnh,
diffGen, diffEnh
]);Extension Interface
interface GLOSTExtension {
id: string;
name: string;
description?: string;
// Tree transformation (runs once)
transform?: (tree: GLOSTRoot) => GLOSTRoot | Promise<GLOSTRoot>;
// Node visitors (runs for each matching node)
visit?: {
word?: (node: GLOSTWord) => GLOSTWord | void | Promise<GLOSTWord | void>;
sentence?: (node: GLOSTSentence) => GLOSTSentence | void | Promise<GLOSTSentence | void>;
paragraph?: (node: GLOSTParagraph) => GLOSTParagraph | void | Promise<GLOSTParagraph | void>;
clause?: (node: GLOSTClause) => GLOSTClause | void | Promise<GLOSTClause | void>;
phrase?: (node: GLOSTPhrase) => GLOSTPhrase | void | Promise<GLOSTPhrase | void>;
};
// Extension dependencies (IDs of extensions that must run first)
dependencies?: string[];
// Extension options
options?: Record<string, unknown>;
}Creating Custom Extensions
Visitor Pattern
import type { GLOSTExtension } from '@glotblocks/glost-plugins';
const MyVisitorExtension: GLOSTExtension = {
id: 'my-visitor',
name: 'My Visitor Extension',
visit: {
word: (node) => {
// Return modified node or void
return {
...node,
extras: {
...node.extras,
processed: true
}
};
},
sentence: (node) => {
// Process sentences
}
}
};Transform Pattern
const MyTransformExtension: GLOSTExtension = {
id: 'my-transform',
name: 'My Transform Extension',
transform: (tree) => {
// Return completely new tree structure
return modifyTree(tree);
}
};Async Pattern
const MyAsyncExtension: GLOSTExtension = {
id: 'my-async',
name: 'My Async Extension',
visit: {
word: async (node) => {
const data = await fetchExternalData(node);
return {
...node,
extras: { ...node.extras, externalData: data }
};
}
}
};With Dependencies
const MyDependentExtension: GLOSTExtension = {
id: 'my-dependent',
name: 'My Dependent Extension',
dependencies: ['clause-analysis'], // Runs after clause-analysis
visit: {
clause: (node) => {
// Process clauses created by clause-analysis
}
}
};Exports
Types
export type {
GLOSTExtension,
ExtensionContext,
ExtensionResult,
ProcessorOptions,
} from '@glotblocks/glost-plugins';Processor Functions
export {
processGLOSTWithExtensions,
processGLOSTWithExtensionsAsync,
processGLOSTWithExtensionIds,
processGLOST,
processGLOSTWithMeta,
} from '@glotblocks/glost-plugins';Registry
export {
extensionRegistry,
registerExtension,
registerExtensions,
getExtension,
getAllExtensions,
} from '@glotblocks/glost-plugins';Utilities
export {
deepMerge,
findConflicts,
type DeepMergeOptions
} from '@glotblocks/glost-plugins';Errors
export {
ExtensionDependencyError,
ExtensionConflictError,
MissingNodeTypeError,
} from '@glotblocks/glost-plugins';