Concepts

Data Operations

Data Operations

GPALConverter: Converting Between Formats

GPALConverter reads data from one source and format and writes it to another, with one consistent fluent chain regardless of whether the source is a file, a database, an in-memory grid, a raw string, or a typed class.

One Converter, Six Kinds of Input

GPAL.Converter accepts WithInput(...) for a GPALFile, a string of raw data, an IGPALGrid<string>, an IGPALDatabase, or a dynamic class instance. The same chain continues identically afterward no matter which one you used. For files and strings, GPAL infers the format from the file extension or from the content itself (CSV, JSON, XML, YAML, and the rest of the DataFormat enum), so the common case needs no extra configuration at all.

// From a file - format inferred from the .csv extension

string json;

GPAL.Converter

.WithInput(GPAL.FileFor("data.csv"))

.WithFirstLineHasColumnNames(true)

.WithOutputType(DataFormat.JSON)

.SaveTo(ref json);

// From an in-memory grid built earlier in the workflow

GPAL.Converter

.WithInput(myGrid)

.WithOutputType(DataFormat.XML)

.SaveTo("output.xml");

When Format Detection Isn't Enough

WithInputType and WithOutputType override detection in either direction. Useful for a file with a non-standard extension, or a raw string that could plausibly be more than one format. WithFirstLineHasColumnNames, WithIgnoreFirstLineColumnNames, and WithFieldsEnclosedInQuotes apply to delimited formats (CSV, TAB, PIPE) on either side of the conversion.

// Force YAML parsing on a string that could be ambiguous, output as JSON

string result;

GPAL.Converter

.WithInput(rawString)

.WithInputType(DataFormat.YAML)

.WithOutputType(DataFormat.JSON)

.SaveTo(ref result);

// A .txt file that is actually CSV with a header row to skip

var grid = GPAL.Grid.ToGPALObject();

GPAL.Converter

.WithInput(GPAL.FileFor("export.txt"))

.WithInputType(DataFormat.CSV)

.WithIgnoreFirstLineColumnNames(true)

.SaveTo(ref grid);

WARNING

GPALFile normally has an implicit conversion from string, so a bare path works almost everywhere. WithInput is the one exception. It has its own overload for raw string content, and C# prefers that exact match over the implicit GPALFile conversion. A bare string passed to WithInput is treated as data, not a path, so use GPAL.FileFor(path) explicitly here.

Where the Result Goes

SaveTo writes the converted result to its destination as the chain's final step. A GPALFile, a string (out parameter), an IGPALGrid<string>, an IGPALDatabase, or a typed class via SaveTo<T>. AppendTo works the same way but adds to an existing file instead of overwriting it. DataFormat.CLASS combined with SaveTo<T> is the converter's most powerful pattern: it automaps source data onto your typed class with no manual mapping code at all.

// JSON file mapped directly onto a typed class - zero mapping code

var customer = new Customer();

GPAL.Converter

.WithInput(GPAL.FileFor("customer.json"))

.WithOutputType(DataFormat.CLASS)

.SaveTo<Customer>(ref customer);

// CSV file appended to an existing output file rather than overwriting

GPAL.Converter

.WithInput(GPAL.FileFor("new-rows.csv"))

.WithFirstLineHasColumnNames(true)

.WithOutputType(DataFormat.CSV)

.AppendTo("all-rows.csv");

On this page

Data Operations
GPALConverter: Converting Between Formats
  • One Converter, Six Kinds of Input
  • When Format Detection Isn't Enough
  • Where the Result Goes