@tripley-kit/xfs-form-parser 1.0.0

package/README.md

@@ -0,0 +1,323 @@
+# @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
+
+```bash
+pnpm add @tripley-kit/xfs-form-parser
+```
+
+## Quick Start
+
+### Parsing a Form Definition
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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
+
+```bash
+pnpm build
+```
+
+### Testing
+
+```bash
+pnpm test
+```
+
+### Regenerating Parser
+
+If you modify the grammar file (`grammar/XFSForm.g4`), regenerate the parser:
+
+```bash
+java -jar doc/antlr-4.13.2-complete.jar -Dlanguage=TypeScript -visitor -no-listener -o src/generated grammar/XFSForm.g4
+```
+
+## License
+
+ISC
+
+## Author
+
+orichyy@hotmail.com