@tripley-kit/xfs-form-parser

A TypeScript library for parsing and validating XFS (eXtensions for Financial Services) Form and Media definition files.

Features

• 🎯 Full XFS Support: Parse both XFSFORM and XFSMEDIA definitions
• 📝 Type-Safe: Complete TypeScript type definitions
• ✅ Validation: Built-in validation for XFS documents
• 🚀 ANTLR-Based: Uses ANTLR 4 for robust parsing
• 🔍 Error Reporting: Detailed error messages with line and column information
• 📦 Zero Config: Works out of the box with ESM and CommonJS

Installation

pnpm add @tripley-kit/xfs-form-parser

Quick Start

Parsing a Form Definition

import { parseXFSForm } from "@tripley-kit/xfs-form-parser";

const formDef = `
XFSFORM "Receipt"
BEGIN
  UNIT MM, 1, 1
  SIZE 75, 85
  ORIENTATION PORTRAIT
  
  XFSFIELD "CustomerName"
  BEGIN
    POSITION 10, 10
    SIZE 50, 5
    FONT "Arial"
    POINTSIZE 12
    HORIZONTAL LEFT
    VERTICAL TOP
  END
END
`;

const result = parseXFSForm(formDef);

if (result.success) {
  console.log("Parsed forms:", result.data);
  result.data.forEach((form) => {
    console.log(`Form: ${form.name}`);
    console.log(`Fields: ${form.fields.length}`);
  });
} else {
  console.error("Parse errors:", result.errors);
}

Parsing a Media Definition

import { parseXFSMedia } from "@tripley-kit/xfs-form-parser";

const mediaDef = `
XFSMEDIA "Receipt1"
BEGIN
  TYPE GENERIC
  UNIT MM, 1, 1
  SIZE 75, 85
END
`;

const result = parseXFSMedia(mediaDef);

if (result.success) {
  console.log("Parsed media:", result.data);
}

Parsing Mixed Documents

import { parseXFS } from "@tripley-kit/xfs-form-parser";

const xfsDef = `
XFSFORM "MyForm"
BEGIN
  SIZE 75, 85
END

XFSMEDIA "MyMedia"
BEGIN
  TYPE GENERIC
  SIZE 75, 85
END
`;

const result = parseXFS(xfsDef);

if (result.success) {
  console.log("Forms:", result.data.forms);
  console.log("Medias:", result.data.medias);
}

Validating Documents

import { parseXFS, validateXFS } from "@tripley-kit/xfs-form-parser";

const result = parseXFS(xfsDefinition);

if (result.success) {
  const validation = validateXFS(result.data);

  if (validation.valid) {
    console.log("Document is valid!");
  } else {
    console.error("Validation errors:", validation.errors);
    console.warn("Validation warnings:", validation.warnings);
  }
}

API Reference

Parser Functions

parseXFS(input: string): ParseResult<XFSDocument>

Parse a complete XFS document containing forms and/or medias.

parseXFSForm(input: string): ParseResult<Form[]>

Parse only form definitions from the input.

parseXFSMedia(input: string): ParseResult<Media[]>

Parse only media definitions from the input.

Validator Functions

validateXFS(document: XFSDocument): ValidationResult

Validate an XFS document and return validation results.

Classes

XFSParser

Main parser class with methods:

• parse(input: string): ParseResult<XFSDocument>
• parseFile(content: string): ParseResult<XFSDocument>
• parseForms(input: string): ParseResult<Form[]>
• parseMedias(input: string): ParseResult<Media[]>
• validateSyntax(input: string): boolean
• getErrors(): ParseError[]

XFSValidator

Validator class with methods:

• validate(document: XFSDocument): ValidationResult
• validateForm(form: Form): ValidationResult

Type Definitions

Form Structure

interface Form {
  name: string;
  properties: FormProperties;
  frames: Frame[];
  fields: Field[];
}

interface FormProperties {
  unit?: { type: Unit; xResolution?: number; yResolution?: number };
  size?: Size;
  alignment?: { type: Alignment; xOffset?: number; yOffset?: number };
  orientation?: Orientation;
  version?: { major: number; minor: number; revision: string; vendor: string };
  language?: number;
  copyright?: string;
}

Field Structure

interface Field {
  name: string;
  properties: FieldProperties;
}

interface FieldProperties {
  position?: Position;
  size?: Size;
  initialValue?: string;
  horizontal?: HorizontalAlign;
  vertical?: VerticalAlign;
  style?: Style;
  pointSize?: number;
  font?: string;
  overflow?: Overflow;
  color?: Color;
  rgbColor?: RGBColor;
  // ... and more
}

Media Structure

interface Media {
  name: string;
  properties: MediaProperties;
}

interface MediaProperties {
  type?: MediaType;
  unit?: { type: Unit; xResolution?: number; yResolution?: number };
  size?: Size;
  printArea?: Rectangle;
  restricted?: Rectangle;
  paperType?: PaperType;
  // ... and more
}

File Encoding

The parser automatically handles Unicode files with BOM (Byte Order Mark), as required by the XFS specification:

import { readFileSync } from "fs";
import { parseXFSForm } from "@tripley-kit/xfs-form-parser";

// Read UTF-16LE file (common for XFS files)
const content = readFileSync("form.def", "utf16le");
const result = parseXFSForm(content);
// BOM is automatically removed by the parser

Note: According to the XFS specification, Unicode-encoded form files must include a BOM marker. The parser automatically detects and removes the BOM (U+FEFF) before parsing.

Supported XFS Features

Form Properties

• UNIT (MM, INCH, ROWCOLUMN)
• SIZE
• ALIGNMENT (TOPLEFT, TOPRIGHT, BOTTOMLEFT, BOTTOMRIGHT)
• ORIENTATION (PORTRAIT, LANDSCAPE)
• VERSION
• LANGUAGE
• COPYRIGHT

Frame/Field Properties

• POSITION
• SIZE
• CLASS (STATIC, STATICTEXT, STATICGRAPHIC)
• TYPE (TEXT, MICR, OCR, MSF, BARCODE, GRAPHIC, PAGEMARK, RECTANGLE)
• STYLE (SINGLE_THIN, DOUBLE_THIN, BOLD, ITALIC, etc.)
• HORIZONTAL (LEFT, RIGHT, CENTER, JUSTIFY)
• VERTICAL (TOP, BOTTOM, CENTER)
• COLOR / RGBCOLOR
• FONT
• POINTSIZE
• INITIALVALUE
• OVERFLOW (TERMINATE, TRUNCATE, BESTFIT, OVERWRITE, WORDWRAP)
• And many more...

Media Properties

• TYPE (GENERIC, PASSBOOK, MULTIPART)
• UNIT
• SIZE
• PRINTAREA
• RESTRICTED
• PAPERTYPE (PLAIN, THERMAL, SECURITY_PAPER)
• SECURITY (NONE, LEVEL1, LEVEL2, LEVEL3)

Examples

See the doc/ directory for real-world XFS definition files:

• TW_Receipt_Balance.def - Complex receipt form with multiple frames and fields
• TW_Receipt_GeneralPay.def - General payment receipt form
• rmedia.def - Simple media definition

Development

Building

pnpm build

Testing

pnpm test

Regenerating Parser

If you modify the grammar file (grammar/XFSForm.g4), regenerate the parser:

java -jar doc/antlr-4.13.2-complete.jar -Dlanguage=TypeScript -visitor -no-listener -o src/generated grammar/XFSForm.g4

License

ISC

Author

[email protected]