Skip to content

supported-fields.md

Latest commit

 

History

History
230 lines (158 loc) · 6.64 KB

supported-fields.md

File metadata and controls

230 lines (158 loc) · 6.64 KB

Supported Fields Compliance Checklist

This document tracks per-field compliance objectives for DocxportNet. Use it as a living checklist while iterating field-by-field. Mark items as done only when we have tests that demonstrate the behavior in a Word document (or a minimal synthetic document that mirrors Word output).

Legend:

  • Not done
  • Done
  • [~] Partial / in progress

Global objectives (apply to all fields)

  • End-to-end test in a Word document (or synthetic OpenXML body) that matches expected output.
  • Cached result handling (cache mode) covered by test when applicable.
  • CHARFORMAT and MERGEFORMAT behavior covered where relevant.
  • Nested-field behavior covered where relevant.
  • Regression test present (explicitly tracked).

IF

Status: feature-complete

  • Structured branch replay (runs + formatting).
  • Nested field evaluation inside expressions.
  • Wildcards and numeric/string comparisons.
  • Error propagation in comparisons (uses nested field text).
  • Regression test present.

SET

Status: feature-complete

  • Sets bookmark value; emits no output.
  • Nested-field value for SET.
  • Cache mode suppresses SET output.
  • Regression test present.

REF

Status: feature-complete (review multi-run bookmarks)

  • Resolves bookmark value.
  • REF switches: \d \f \h \n \p \r \t \w (via resolver).
  • CHARFORMAT/MERGEFORMAT for rendered output.
  • Multi-run/structured bookmark replay.
  • Regression test present.

DOCVARIABLE

Status: feature-complete (edge-case hardening optional)

  • Resolver path (delegate / value resolver).
  • Error text when missing.
  • CHARFORMAT/MERGEFORMAT for rendered output.
  • Regression test present.

DATE / TIME / CREATEDATE / SAVEDATE / PRINTDATE

Status: feature-complete

  • Uses NowProvider for DATE/TIME.
  • Uses document properties for CREATEDATE/SAVEDATE/PRINTDATE (with fallback).
  • @ formatting coverage.
  • Regression test present.

DOCPROPERTY

Status: feature-complete (custom props optional)

  • Built-in core properties resolve.
  • Custom properties resolve (includeCustomProperties = true).
  • * formatting coverage.
  • Regression test present.

MERGEFIELD

Status: feature-complete (mail-merge semantics implemented)

  • \b and \f behavior when result is non-blank.
  • \m alias mapping.
  • \v vertical rendering.
  • General format switches (*, #, @) applied.
  • Mail-merge record semantics (record cursor + NEXT/NEXTIF/SKIPIF integration).
  • Regression test present.

SEQ

Status: partial

  • Increment behavior.
  • \c repeat.
  • \r reset.
  • \s heading level reset.
  • \h hide (and interaction with *).
  • General format switches (*, #).
  • Regression test present.

COMPARE

Status: feature-complete

  • Returns 1/0 and applies formatting.
  • Nested field evaluation.
  • Regression test present.

ASK

Status: partial (delegate-backed)

  • Delegate prompt + default.
  • \o behavior (only-once semantics vs true merge behavior).
  • No output emitted.
  • Regression test present.

SKIPIF / NEXTIF

Status: feature-complete

  • Evaluates comparison correctly.
  • Suppresses output.
  • Record skipping / control-flow integration (merge cursor).
  • Regression test present.

Formula (=)

Status: partial

  • Core operators and comparisons.
  • Supported functions (current registry).
  • Table range resolution (A1, ABOVE/LEFT/RIGHT/BELOW) with TableResolver.
  • Error handling parity with Word (not yet implemented).
  • Additional Word functions (not yet implemented).
  • Regression test present.

NEXT

Status: feature-complete

  • Advances merge record cursor unconditionally.
  • No output emitted.
  • Regression test present.

MERGEREC / MERGESEQ

Status: feature-complete

  • MERGEREC returns current record number from data source.
  • MERGESEQ returns sequence number of merged records.
  • Regression test present.

Document Metrics (NUMPAGES / NUMWORDS / NUMCHARS)

Status: not tracked

  • Resolves from document stats.
  • Compute on the fly when stats missing.
  • Formatting switches apply where relevant.
  • Regression test present.

PAGEREF / NOTEREF

Status: out of scope (requires pagination/layout engine)

  • Resolves page number for bookmark (PAGEREF).
  • Resolves note reference mark for bookmark (NOTEREF).
  • Regression test present.

GREETINGLINE

Status: partial (locale-aware providers; simple templates)

  • Provider-based macro resolution (locale-aware registry).
  • Uses merge cursor values.
  • Regression test present.
  • [~] Locale-specific templates (may differ from Word labels; documented intentional divergence).

ADDRESSBLOCK

Status: partial (locale-aware providers; simple templates)

  • Provider-based macro resolution (locale-aware registry).
  • Uses merge cursor values.
  • Regression test present.
  • [~] Locale-specific templates (may differ from Word labels; documented intentional divergence).

DATABASE

Status: partial (pluggable provider; basic TSV rendering)

  • Pluggable database provider interface (optional external providers).
  • Default provider (e.g., SqlClient / T-SQL).
  • Optional providers (ODBC, PostgreSQL, MySQL).
  • External data query support (document-level or provider-driven).
  • Mapping to output rows/records.
  • Configurable rendering (table/HTML/Markdown).
  • Regression test present.

INCLUDETEXT / INCLUDEPICTURE

Status: not tracked

  • External content resolution (file/URL).
  • Security/sandbox policy for external loads.
  • Regression test present.

TOC / TC / INDEX / XE / RD

Status: out of scope (requires indexing + layout engine). Note: Full support needs a two-pass indexer (collect entries first, render later) plus pagination to compute page numbers. A possible interim “TOC-lite” would link to headings/bookmarks without page numbers.

  • TOC aggregation and rendering (with page numbers).
  • TC entry capture for TOC.
  • INDEX aggregation and rendering (with page numbers).
  • XE entry capture for index.
  • RD external document inclusion.
  • Optional TOC-lite (hyperlinks only, no page numbers).
  • Regression test present.

Field Error Semantics

Status: partial

  • Word-style error strings for REF/DOCVARIABLE/DOCPROPERTY missing values.
  • Formula error strings for divide-by-zero and syntax/unknown functions.
  • Word-style error strings for other field types (e.g., SEQ, MERGEFIELD, ASK).
  • [~] Nested field error propagation behavior (known divergence: missing REF inside IF).
  • [~] Regression tests for error strings across all fields.