Write Comments Example

This example demonstrates how to add comment lines to fielded text output for documentation, metadata, and organization.

What it does

1. Deserializes metadata from an XML string with LineCommentChar="#"
2. Uses writeComment() to add comment lines throughout the file
3. Writes heading and data records interspersed with comments
4. Shows different comment use cases (header, section markers, footer)

Running the example

npx tsx examples/write-comments/index.ts
Copy

Expected output

Writing CSV with comments:
=========================

Generated CSV:
==============
# ====================================
# Customer Data Export
# ====================================
#
# Generated: 2024-01-01T12:00:00.000Z
# Generator: FieldedText TypeScript Library
# Format: CSV (Comma-Separated Values)
#
# --- Active Customers ---
Customer Name,Age
John Doe,30
Jane Smith,25
#
# --- Inactive Customers ---
Bob Johnson,45
#
# End of customer data
# Total records: 3

Key observations:
- Comments start with # (defined by lineCommentChar)
- Comments can appear anywhere in the file
- Comments are ignored when reading
- Comments are useful for documentation and metadata
Copy

Key concepts

• Meta deserialization: Load metadata from XML text with FtXmlMetaSerialization.deserialize()
• Line Comment Character: Set via meta.lineCommentChar (e.g., "#", "//", ";")
• writeComment(): Adds a comment line prefixed with the comment character
• Comment Placement: Comments can appear before, between, or after data records
• Reading: Comments are automatically skipped during reading
• Documentation: Comments help explain file contents and format

Use Cases

File headers:

• Generation timestamp
• Tool/version information
• Data source
• Copyright notices

Section markers:

• Separate logical sections
• Mark data boundaries
• Add structure to long files

Data annotations:

• Notes about specific records
• Warnings or special conditions
• Metadata about following records

Footer information:

• Record counts
• Checksums
• Processing notes

Comment Characters

Common comment characters by format:

• CSV: # or //
• Configuration files: #, ;, or //
• SQL-style: --
• C-style: // (single-line comments only)

Set your comment character based on your file format and reader compatibility.

Code

// Write Comments Example
// Demonstrates adding comment lines to output

import {
  FtStringWriter,
  FtWriter,
  FtXmlMetaSerialization,
} from "@pbkware/fielded-text-web";

// Load metadata from XML string
const metaXml = `<?xml version="1.0" encoding="utf-8"?>
<FieldedText LineCommentChar="#" HeadingLineCount="1">
  <Field Name="Name" Headings="Customer Name" />
  <Field DataType="Integer" Name="Age" Format="G" Headings="Age" />
</FieldedText>`;

const meta = FtXmlMetaSerialization.deserialize(metaXml);

// Create writer
const stringWriter = new FtStringWriter();
const writer = new FtWriter(meta, stringWriter);

console.log("Writing CSV with comments:");
console.log("=========================\n");

// Write file header comments
writer.writeComment("====================================");
writer.writeComment("Customer Data Export");
writer.writeComment("====================================");
writer.writeComment("");
writer.writeComment(`Generated: ${new Date().toISOString()}`);
writer.writeComment("Generator: FieldedText TypeScript Library");
writer.writeComment("Format: CSV (Comma-Separated Values)");
writer.writeComment("");

// Write section comment
writer.writeComment("--- Active Customers ---");

// Write header
writer.writeHeader(); // Write header manually. Otherwise cannot include comments between header and first record

// Write section comment
writer.writeComment("--- Data Records ---");

// Write data records
writer.fieldList.get(0).asString = "John Doe";
writer.fieldList.get(1).asBigInt = BigInt(30);
writer.write();

writer.fieldList.get(0).asString = "Jane Smith";
writer.fieldList.get(1).asBigInt = BigInt(25);
writer.write();

// Write another section comment
writer.writeComment("");
writer.writeComment("--- Inactive Customers ---");

writer.fieldList.get(0).asString = "Bob Johnson";
writer.fieldList.get(1).asBigInt = BigInt(45);
writer.write();

// Write footer comments
writer.writeComment("");
writer.writeComment("End of customer data");
writer.writeComment("Total records: 3");

console.log("Generated CSV:");
console.log("==============");
console.log(stringWriter.toString());

console.log("\nKey observations:");
console.log("- Comments start with # (defined by lineCommentChar)");
console.log("- Comments can appear anywhere in the file");
console.log("- Comments are ignored when reading");
console.log("- Comments are useful for documentation and metadata");
Copy