Concepts

Data Operations

Data Operations

GPALConverter: Converting Between Formats

One Converter, Five Kinds of Input

GPAL.Converter accepts WithInput(...) for a GPALFile, a string of raw data, an IGPALGrid, 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

GPAL.Converter

.WithInput((GPALFile)"data.csv")

.WithFirstLineHasColumnNames(true)

.WithOutputType(DataFormat.JSON)

.SaveTo("data.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 overrides detection on the way in. Useful for a file with a non-standard extension, or a raw string that could plausibly be more than one format. On the way out, a file destination's extension decides the format. WithFirstLineHasColumnNames, WithIgnoreFirstLineColumnNames, and WithColumnsEnclosedInQuotes 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

GPAL.Converter

.WithInput(rawString)

.WithInputType(DataFormat.YAML)

.WithOutputType(DataFormat.JSON)

.SaveTo("result.json");


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

var grid = GPAL.Grid.ToGPALObject();

GPAL.Converter

.WithInput((GPALFile)"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 cast the path to GPALFile here, or use GPAL.FileFor(path).

Where the Result Goes

SaveTo writes the converted result to its destination as the chain's final step. A GPALFile, an IGPALGrid, an IGPALDatabase, or a typed class via SaveTo. AppendTo works the same way but adds to an existing file instead of overwriting it. DataFormat.CLASS combined with SaveTo 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((GPALFile)"customer.json")

.WithOutputType(DataFormat.CLASS)

.SaveTo<Customer>(ref customer);


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

GPAL.Converter

.WithInput((GPALFile)"new-rows.csv")

.WithFirstLineHasColumnNames(true)

.WithOutputType(DataFormat.CSV)

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

NOTE

YAML output writes an object referenced more than once as an anchor and aliases. At or above the alias limit, 5000 nodes by default, aliases are skipped for speed unless the graph has a cycle. Change the limit with GPAL.WithYamlAliasLimit or yamlAliasLimit in gpal.yaml; 0 always uses aliases.

On this page

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