@pbkware/fielded-text-web 0.1.0

package/src/serialization/declaration-parser.ts

@@ -0,0 +1,203 @@
+import { FtUnreachableCaseError } from '../types/errors/ft-internal-error.js';
+import { CharReader } from './char-reader.js';
+import { FtDeclaredParameters } from './ft-declared-parameters.js';
+
+const State = {
+  CommentChar: 'CommentChar',
+  Signature: 'Signature',
+  WaitingParameter: 'WaitingParameter',
+  ParameterName: 'ParameterName',
+  WaitingValue: 'WaitingValue',
+  Value: 'Value',
+  ValueStuffedQuote: 'ValueStuffedQuote',
+} as const;
+
+type State = (typeof State)[keyof typeof State];
+
+/**
+ * Parser for .ftx file declaration headers.
+ * Parses lines like: |!Fielded Text^| Version="1.1" MetaFile="myfile.ftm"
+ * @internal
+ */
+export class DeclarationParser {
+  private static readonly NAME_VALUE_SEPARATOR_CHAR = '=';
+  private static readonly VALUE_QUOTE_CHAR = '"';
+
+  private readonly _charReader: CharReader;
+  private readonly _parameters: FtDeclaredParameters;
+
+  private _nameBuilder: string[] = [];
+  private _valueBuilder: string[] = [];
+
+  private _state: State = State.CommentChar;
+  private _linePosition = -1;
+  private _signature = '';
+
+  constructor(charReader: CharReader, parameters: FtDeclaredParameters) {
+    this._charReader = charReader;
+    this._parameters = parameters;
+  }
+
+  get signature(): string {
+    return this._signature;
+  }
+
+  set signature(value: string) {
+    this._signature = value;
+  }
+
+  /**
+   * Start parsing a new line.
+   */
+  startLine(): void {
+    this._linePosition = -1;
+    this._state = State.CommentChar;
+  }
+
+  /**
+   * Parse a character from the signature line (first declaration line).
+   */
+  parseSignatureLineChar(aChar: string): void {
+    this._linePosition++;
+
+    switch (this._state) {
+      case State.CommentChar:
+        // Ignore character (line comment char)
+        this._state = State.Signature;
+        break;
+      case State.Signature:
+        // Ignore signature characters
+        if (this._linePosition >= this._signature.length) {
+          this._state = State.WaitingParameter;
+        }
+        break;
+      default:
+        this.parseChar(aChar);
+        break;
+    }
+  }
+
+  /**
+   * Parse a character from the second declaration line (if exists).
+   */
+  parseDeclaration2LineChar(aChar: string): void {
+    this._linePosition++;
+
+    if (this._state === State.CommentChar) {
+      // Ignore character (line comment char)
+      this._state = State.WaitingParameter;
+    } else {
+      this.parseChar(aChar);
+    }
+  }
+
+  /**
+   * Finish parsing the signature line.
+   */
+  finishSignatureLine(): void {
+    this.finishLine();
+  }
+
+  /**
+   * Finish parsing all declaration lines and validate.
+   */
+  finish(): void {
+    this.finishLine();
+
+    const versionIdx = this._parameters.indexOfVersion();
+    if (versionIdx < 0) {
+      throw new Error('Declared parameters missing version');
+    }
+
+    if (versionIdx !== 0) {
+      throw new Error('Declared parameters version is not first');
+    }
+
+    const versionResult = this._parameters.tryGetVersion();
+    if (versionResult.isErr()) {
+      throw new Error(`Declared parameters invalid version value: ${this._parameters.getValue(versionIdx)}`);
+    }
+  }
+
+  private parseChar(aChar: string): void {
+    switch (this._state) {
+      case State.WaitingParameter:
+        // Ignore whitespace
+        if (!/\s/.test(aChar)) {
+          if (aChar === DeclarationParser.NAME_VALUE_SEPARATOR_CHAR) {
+            throw new Error(`Declaration parameter name is zero length at parameter ${this._parameters.count}`);
+          } else {
+            this._nameBuilder = [aChar];
+            this._state = State.ParameterName;
+          }
+        }
+        break;
+
+      case State.ParameterName:
+        if (aChar !== DeclarationParser.NAME_VALUE_SEPARATOR_CHAR) {
+          this._nameBuilder.push(aChar);
+        } else {
+          this._state = State.WaitingValue;
+        }
+        break;
+
+      case State.WaitingValue:
+        // Ignore initial whitespace
+        if (!/\s/.test(aChar)) {
+          if (aChar !== DeclarationParser.VALUE_QUOTE_CHAR) {
+            throw new Error(`Declaration parameter value not quoted: ${this._nameBuilder.join('')}`);
+          } else {
+            this._valueBuilder = [];
+            this._state = State.Value;
+          }
+        }
+        break;
+
+      case State.Value:
+        if (aChar !== DeclarationParser.VALUE_QUOTE_CHAR) {
+          this._valueBuilder.push(aChar);
+        } else {
+          if (this._charReader.peek() === DeclarationParser.VALUE_QUOTE_CHAR.charCodeAt(0)) {
+            this._state = State.ValueStuffedQuote;
+          } else {
+            this._parameters.add(this._nameBuilder.join('').trim(), this._valueBuilder.join(''));
+            this._state = State.WaitingParameter;
+          }
+        }
+        break;
+
+      case State.ValueStuffedQuote:
+        this._valueBuilder.push(DeclarationParser.VALUE_QUOTE_CHAR);
+        this._state = State.Value;
+        break;
+
+      default:
+        throw new Error(`Unsupported state: ${this._state}`);
+    }
+  }
+
+  private finishLine(): void {
+    switch (this._state) {
+      case State.CommentChar:
+      case State.Signature:
+      case State.ValueStuffedQuote:
+        throw new Error(`Unexpected state at end of line: ${this._state}`);
+
+      case State.ParameterName:
+        throw new Error(`Declaration parameter name not terminated: ${this._nameBuilder.join('')}`);
+
+      case State.WaitingValue:
+        throw new Error(`Declaration parameter missing value: ${this._nameBuilder.join('')}`);
+
+      case State.Value:
+        throw new Error(`Declaration parameter value not terminated: ${this._nameBuilder.join('')}`);
+
+      case State.WaitingParameter:
+        // All good
+        break;
+
+      default:
+        throw new FtUnreachableCaseError('DPFL54482', this._state);
+    }
+  }
+}

package/src/serialization/delimited-field-parser.ts

@@ -0,0 +1,296 @@
+import { FtField } from '../fields/instances/ft-field.js';
+import { FtQuotedType } from '../types/enums/ft-quoted-type.js';
+import { CharReader } from './char-reader.js';
+import { SerializationCore } from './serialization-core.js';
+
+const QuotedState = {
+  NeverOpen: 'NeverOpen',
+  CanOpen: 'CanOpen',
+  MustOpen: 'MustOpen',
+  Opened: 'Opened',
+  Open: 'Open',
+  Stuffed: 'Stuffed',
+  Closed: 'Closed',
+} as const;
+
+type QuotedState = (typeof QuotedState)[keyof typeof QuotedState];
+
+/**
+ * Parser for delimited (CSV-like) fields.
+ * Handles quote characters, substitutions, and delimiter detection.
+ * @internal
+ */
+export class DelimitedFieldParser {
+  private readonly _headings: boolean;
+  private readonly _charReader: CharReader;
+  private readonly _core: SerializationCore;
+  private _textBuilder: string[] = [];
+
+  private _field: FtField | undefined = undefined;
+  private _fieldQuotedType: FtQuotedType = FtQuotedType.Optional;
+  private _fieldSubstitutionsEnabled = false;
+  private _fieldSubstitutionChar = '';
+  private _fieldDelimiterChar = '';
+  private _fieldQuoteChar = '';
+
+  private _quotedState: QuotedState = QuotedState.CanOpen;
+  private _substitutionActive = false;
+  private _position = -1;
+  private _rawOffset = -1;
+  private _rawLength = 0;
+
+  constructor(core: SerializationCore, charReader: CharReader, forHeadings: boolean) {
+    this._headings = forHeadings;
+    this._charReader = charReader;
+    this._core = core;
+  }
+
+  /**
+   * Check if end-of-line should be embedded (not treated as line break).
+   */
+  isEndOfLineToBeEmbedded(): boolean {
+    switch (this._quotedState) {
+      case QuotedState.Opened:
+      case QuotedState.Open:
+      case QuotedState.Stuffed:
+        return this._core.allowEndOfLineCharInQuotes;
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Enter a new field for parsing.
+   */
+  enterField(field: FtField): void {
+    this._field = field;
+
+    // Cache field values
+    this._fieldSubstitutionsEnabled = this._core.substitutionsEnabled;
+    this._fieldSubstitutionChar = this._core.substitutionChar;
+    this._fieldDelimiterChar = this._core.delimiterChar;
+    this._fieldQuoteChar = this._core.quoteChar;
+
+    if (this._headings) {
+      this._fieldQuotedType = field.headingQuotedType;
+    } else {
+      this._fieldQuotedType = field.valueQuotedType;
+    }
+
+    switch (this._fieldQuotedType) {
+      case FtQuotedType.Never:
+        this._quotedState = QuotedState.NeverOpen;
+        break;
+      case FtQuotedType.Optional:
+        this._quotedState = QuotedState.CanOpen;
+        break;
+      case FtQuotedType.Always:
+        this._quotedState = QuotedState.MustOpen;
+        break;
+      default:
+        throw new Error(`Unsupported quoted type: ${String(this._fieldQuotedType)}`);
+    }
+
+    this._textBuilder = [];
+    this._position = this._charReader.position;
+    this._rawOffset = -1;
+    this._rawLength = 0;
+    this._substitutionActive = false;
+  }
+
+  /**
+   * Exit the current field.
+   */
+  exitField(): void {
+    this._textBuilder = [];
+    this._field = undefined;
+  }
+
+  /**
+   * Parse a single character.
+   * @param aChar The character to parse.
+   * @returns True if the field is finished, false otherwise.
+   */
+  parseChar(aChar: string): boolean {
+    if (this._substitutionActive) {
+      this.appendSubstitution(aChar);
+      this._substitutionActive = false;
+      this._rawLength++;
+      return false;
+    } else {
+      if (this._fieldSubstitutionsEnabled && aChar === this._fieldSubstitutionChar) {
+        this._substitutionActive = true;
+        this._rawLength++;
+        return false;
+      } else {
+        switch (this._quotedState) {
+          case QuotedState.NeverOpen:
+            if (aChar === this._fieldDelimiterChar) {
+              return true;
+            } else {
+              this.appendValueChar(aChar);
+              return false;
+            }
+
+          case QuotedState.CanOpen:
+            if (aChar === this._fieldQuoteChar) {
+              this._quotedState = QuotedState.Opened;
+              return false;
+            } else {
+              if (this.isWhiteSpace(aChar)) {
+                this._rawLength++;
+                this._textBuilder.push(aChar);
+                return false;
+              } else {
+                this._quotedState = QuotedState.NeverOpen;
+                return this.parseChar(aChar);
+              }
+            }
+
+          case QuotedState.MustOpen:
+            if (this.isWhiteSpace(aChar)) {
+              return false; // Ignore white space before quote is opened
+            } else {
+              if (aChar === this._fieldDelimiterChar) {
+                return true; // null
+              } else {
+                if (aChar === this._fieldQuoteChar) {
+                  this._quotedState = QuotedState.Opened;
+                  return false;
+                } else {
+                  const errorType = this._headings ? 'HeadingNonWhiteSpaceCharBeforeQuotesOpened' : 'ValueNonWhiteSpaceCharBeforeQuotesOpened';
+                  throw new Error(`${errorType}: Non-whitespace character before quotes opened in field ${this._field?.name ?? 'unknown'}`);
+                }
+              }
+            }
+
+          case QuotedState.Opened:
+            this._rawOffset = this._charReader.position - this._position;
+            this._rawLength = 0;
+            this._quotedState = QuotedState.Open;
+            return this.parseChar(aChar);
+
+          case QuotedState.Open:
+            if (aChar !== this._fieldQuoteChar) {
+              this.appendValueChar(aChar);
+              return false;
+            } else {
+              if (this._charReader.peek() === this._fieldQuoteChar.charCodeAt(0)) {
+                this._rawLength++;
+                this._quotedState = QuotedState.Stuffed;
+                return false;
+              } else {
+                this._rawLength = this._charReader.position - this._position + this._rawOffset;
+                this._quotedState = QuotedState.Closed;
+                return false;
+              }
+            }
+
+          case QuotedState.Stuffed:
+            this.appendValueChar(this._fieldQuoteChar);
+            this._quotedState = QuotedState.Open;
+            return false;
+
+          case QuotedState.Closed:
+            if (aChar === this._fieldDelimiterChar) {
+              return true;
+            } else {
+              if (this.isWhiteSpace(aChar)) {
+                return false;
+              } else {
+                const errorType = this._headings ? 'HeadingNonWhiteSpaceCharAfterQuotesClosed' : 'ValueNonWhiteSpaceCharAfterQuotesClosed';
+                throw new Error(`${errorType}: Non-whitespace character after quotes closed in field ${this._field?.name ?? 'unknown'}`);
+              }
+            }
+
+          default:
+            throw new Error(`Unsupported quoted state: ${String(this._quotedState)}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Load the parsed heading into the field.
+   */
+  loadFieldHeading(headingLineIndex: number): void {
+    if (!this._field) {
+      throw new Error('No field to load heading into');
+    }
+    const headingText = this.finishText();
+    this._field.loadPosition(this._position, this._charReader.position - this._position, this._rawOffset, this._rawLength);
+    this._field.loadHeading(headingLineIndex, headingText);
+  }
+
+  /**
+   * Load the parsed value into the field.
+   */
+  loadFieldValue(): void {
+    if (!this._field) {
+      throw new Error('No field to load value into');
+    }
+    const valueText = this.finishText();
+    this._field.loadPosition(this._position, this._charReader.position - this._position, this._rawOffset, this._rawLength);
+    this._field.loadDelimitedValue(valueText, this._quotedState === QuotedState.Closed);
+  }
+
+  private appendValueChar(aChar: string): void {
+    this._rawLength++;
+    if (this._fieldSubstitutionsEnabled && aChar === this._fieldSubstitutionChar) {
+      this._substitutionActive = true;
+    } else {
+      this._textBuilder.push(aChar);
+    }
+  }
+
+  private appendSubstitution(tokenChar: string): void {
+    const substitutionValue = this._core.tryGetSubstitutionValue(tokenChar);
+    if (substitutionValue.found) {
+      this._textBuilder.push(substitutionValue.value);
+    } else {
+      this._textBuilder.push(tokenChar);
+    }
+  }
+
+  private isWhiteSpace(aChar: string): boolean {
+    return /\s/.test(aChar);
+  }
+
+  private finishText(): string {
+    let text: string;
+
+    switch (this._quotedState) {
+      case QuotedState.MustOpen:
+        text = ''; // is null
+        break;
+
+      case QuotedState.Opened:
+        if (this._fieldQuotedType === FtQuotedType.Always) {
+          const errorType = this._headings ? 'HeadingQuotedFieldMissingEndQuoteChar' : 'ValueQuotedFieldMissingEndQuoteChar';
+          throw new Error(`${errorType}: Quoted field missing end quote in field ${this._field?.name ?? 'unknown'}`);
+        } else {
+          text = this._fieldQuoteChar;
+          this._rawOffset--;
+          this._rawLength++;
+        }
+        break;
+
+      case QuotedState.Open:
+        if (this._fieldQuotedType === FtQuotedType.Always) {
+          const errorType = this._headings ? 'HeadingQuotedFieldMissingEndQuoteChar' : 'ValueQuotedFieldMissingEndQuoteChar';
+          throw new Error(`${errorType}: Quoted field missing end quote in field ${this._field?.name ?? 'unknown'}`);
+        } else {
+          text = this._fieldQuoteChar + this._textBuilder.join('');
+          this._rawOffset--;
+          this._rawLength++;
+        }
+        break;
+
+      default:
+        text = this._textBuilder.join('');
+        break;
+    }
+
+    return text;
+  }
+}

package/src/serialization/embedded-meta-parser.ts

@@ -0,0 +1,147 @@
+/**
+ * Parser for extracting embedded XML metadata from .ftx file headers.
+ * Detects <?xml or <FieldedText and accumulates until </FieldedText>.
+ * @internal
+ */
+export class EmbeddedMetaParser {
+  private static readonly FIELDED_TEXT_ELEMENT_NAME = 'FieldedText';
+  private static readonly XML_STARTING_TEXT = '<?xml ';
+  private static readonly FIELDED_TEXT_STARTING_TEXT = '<' + EmbeddedMetaParser.FIELDED_TEXT_ELEMENT_NAME;
+  private static readonly TERMINATING_TEXT = '</' + EmbeddedMetaParser.FIELDED_TEXT_ELEMENT_NAME + '>';
+  private static readonly INVALID_BUILDER_INDEX = -1;
+
+  private _builder: string[] = [];
+  private _detected = false;
+  private _nextCharIsComment = false;
+  private _ready = false;
+
+  private _xmlStartingPosition = 0;
+  private _fieldedTextStartingPosition = 0;
+  private _terminatingPosition = 0;
+
+  private _fieldedTextStartingBuilderIndex = EmbeddedMetaParser.INVALID_BUILDER_INDEX;
+  private _xmlStartingBuilderIndex = EmbeddedMetaParser.INVALID_BUILDER_INDEX;
+
+  get ready(): boolean {
+    return this._ready;
+  }
+
+  /**
+   * Reset parser state for new parsing session.
+   */
+  reset(): void {
+    this._detected = false;
+    this._nextCharIsComment = false;
+    this._ready = false;
+
+    this._xmlStartingPosition = 0;
+    this._fieldedTextStartingPosition = 0;
+    this._terminatingPosition = 0;
+
+    this._xmlStartingBuilderIndex = EmbeddedMetaParser.INVALID_BUILDER_INDEX;
+    this._fieldedTextStartingBuilderIndex = EmbeddedMetaParser.INVALID_BUILDER_INDEX;
+
+    this._builder = [];
+  }
+
+  /**
+   * Parse a character before detection. Returns true if embedded meta detected.
+   */
+  parseNotYetDetectedChar(aChar: string): boolean {
+    if (this._nextCharIsComment) {
+      // Ignore start of line comment characters
+      this._nextCharIsComment = false;
+    } else {
+      this._builder.push(aChar);
+
+      // If XmlStartingText not yet match, see if char is part of match
+      if (this._xmlStartingPosition < EmbeddedMetaParser.XML_STARTING_TEXT.length) {
+        if (aChar === EmbeddedMetaParser.XML_STARTING_TEXT[this._xmlStartingPosition]) {
+          if (this._xmlStartingPosition === 0) {
+            this._xmlStartingBuilderIndex = this._builder.length - 1;
+          }
+          this._xmlStartingPosition++;
+        }
+      }
+
+      // If FieldedTextStartingText not yet match, see if char is part of match
+      if (aChar === EmbeddedMetaParser.FIELDED_TEXT_STARTING_TEXT[this._fieldedTextStartingPosition]) {
+        if (this._fieldedTextStartingPosition === 0) {
+          this._fieldedTextStartingBuilderIndex = this._builder.length;
+        }
+
+        this._fieldedTextStartingPosition++;
+
+        if (this._fieldedTextStartingPosition >= EmbeddedMetaParser.FIELDED_TEXT_STARTING_TEXT.length) {
+          const builderIndex =
+            this._xmlStartingPosition >= EmbeddedMetaParser.XML_STARTING_TEXT.length
+              ? this._xmlStartingBuilderIndex
+              : this._fieldedTextStartingBuilderIndex;
+          this._builder.splice(0, builderIndex);
+
+          this._detected = true;
+        }
+      }
+    }
+
+    return this._detected;
+  }
+
+  /**
+   * Called at the start of each line.
+   */
+  startLine(): void {
+    // Matches cannot carry over line except for fully matched XmlStartingText
+    if (!this._detected) {
+      this._fieldedTextStartingPosition = 0;
+
+      if (this._xmlStartingPosition >= EmbeddedMetaParser.XML_STARTING_TEXT.length) {
+        this.appendLine();
+      } else {
+        this._xmlStartingPosition = 0;
+        this._builder = [];
+      }
+    }
+
+    this._nextCharIsComment = true;
+    this._terminatingPosition = 0;
+  }
+
+  /**
+   * Parse a character after detection (accumulating XML).
+   */
+  parseChar(aChar: string): void {
+    if (!this._ready) {
+      if (this._nextCharIsComment) {
+        this._nextCharIsComment = false;
+      } else {
+        this._builder.push(aChar);
+
+        if (aChar !== EmbeddedMetaParser.TERMINATING_TEXT[this._terminatingPosition]) {
+          this._terminatingPosition = 0;
+        } else {
+          this._terminatingPosition++;
+          if (this._terminatingPosition >= EmbeddedMetaParser.TERMINATING_TEXT.length) {
+            this._ready = true;
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Append a newline to the builder.
+   */
+  appendLine(): void {
+    this._builder.push('\n');
+  }
+
+  /**
+   * Take the accumulated XML metadata as a string and clear the builder.
+   */
+  takeMetaAsString(): string {
+    const result = this._builder.join('');
+    this._builder = [];
+    return result;
+  }
+}