Tutorials

Tutorials

GPALConverter: Moving Data Between CSV, JSON, XML, YAML, and Classes

GPALConverter is GPAL's "anything in, anything out" data pipeline. WithInput accepts a file, a class instance, or a collection, and SaveTo writes it out as CSV, JSON, XML, YAML, HTML, or back into a typed object - all without writing format-specific parsing code yourself.

Complete Program

This is a trimmed version of the actual test program. It sets up input and output GPALFile objects for several formats, then runs three representative conversions: CSV to several formats, a custom class out to multiple files, and a JSON file fanned out to CSV, XML, and YAML.

using System.Collections.Generic;

using GenerallyPositive;

GPAL.WithPublishToConsole().WithPublishStackTrace(false);

IGPALConverter converter = GPAL.Converter.ToGPALObject();

GPALFile inCsvFile = GPAL.File

.WithFileName(@"c:sdisample.csv")

.WithFirstLineIsColumnNames()

.WithDelimiter(',')

.ToGPALObject();

GPALFile inJsonFile = @"c:sdisample.json";

GPALFile outCsvFile = GPAL.File

.WithFileName(@"c:sdioutsample.csv")

.WithOverwriteFile(false)

.WithFirstLineIsColumnNames()

.ToGPALObject();

GPALFile outJsonFile = GPAL.File

.WithFileName(@"c:sdioutsample.json")

.WithOverwriteFile(false)

.ToGPALObject();

GPALFile outXmlFile = GPAL.File

.WithFileName(@"c:sdioutsample.xml")

.WithOverwriteFile(false)

.ToGPALObject();

GPALFile outYamlFile = GPAL.File

.WithFileName(@"c:sdioutsample.yaml")

.WithOverwriteFile(false)

.ToGPALObject();

GPALFile outHtmlFile = GPAL.File

.WithFileName(@"c:sdioutsample.html")

.WithOverwriteFile(false)

.ToGPALObject();

// CSV -> CSV, JSON, HTML, XML, YAML

converter

.WithInput(inCsvFile)

.WithFirstLineHasColumnNames(true)

.SaveTo(outCsvFile.Next)

.SaveTo(outJsonFile.Next)

.AppendTo(outXmlFile.Next)

.SaveTo(outYamlFile.Next)

.SaveTo(outHtmlFile.Next);

// A custom class out to CSV, XML, JSON, YAML, HTML

var myObject = new MyClass();

converter

.WithInput(myObject)

.WithFirstLineHasColumnNames(true)

.SaveTo(outCsvFile.Next)

.SaveTo(outXmlFile.Next)

.SaveTo(outJsonFile.Next)

.SaveTo(outYamlFile.Next)

.SaveTo(outHtmlFile.Next);

// JSON -> CSV, JSON, HTML, XML, YAML

converter

.WithInput(inJsonFile)

.SaveTo(outCsvFile.Next)

.SaveTo(outJsonFile.Next)

.SaveTo(outHtmlFile.Next)

.SaveTo(outXmlFile.Next)

.SaveTo(outYamlFile.Next);

class MyClass

{

public int IntProperty { get; set; } = 666;

public string StringProperty { get; set; } = "hello world";

}

One Converter, Many Output Files

GPAL.Converter.ToGPALObject() gives you one converter instance that you reuse for every conversion in the workflow. Output files are set up once with WithFileName and WithOverwriteFile(false) - the false means each .Next call generates the next available filename instead of overwriting the same file repeatedly.

IGPALConverter converter = GPAL.Converter.ToGPALObject();

GPALFile outCsvFile = GPAL.File

.WithFileName(@"c:sdioutsample.csv")

.WithOverwriteFile(false)

.WithFirstLineIsColumnNames()

.ToGPALObject();

TIP

Because WithOverwriteFile(false) is set, calling .Next on an output GPALFile (e.g. outCsvFile.Next) returns a GPALFile pointing at the next numbered filename, so repeated SaveTo calls in the same run don't clobber each other's results.

CSV In, Five Formats Out

WithInput(inCsvFile) reads the CSV using the column definitions and delimiter configured on that GPALFile. From there, a chain of SaveTo (and AppendTo for XML) writes the same data out as CSV, JSON, XML, YAML, and HTML - GPALConverter handles the format-specific serialization for each target.

converter

.WithInput(inCsvFile)

.WithFirstLineHasColumnNames(true)

.SaveTo(outCsvFile.Next)

.SaveTo(outJsonFile.Next)

.AppendTo(outXmlFile.Next)

.SaveTo(outYamlFile.Next)

.SaveTo(outHtmlFile.Next);

A Plain C# Class Is Just Another Input

WithInput isn't limited to files - pass in any object and GPALConverter reflects over its public properties to build rows or fields for each output format. A simple class with an int property and a string property converts to CSV columns, JSON fields, XML elements, and so on, with no extra mapping code.

var myObject = new MyClass();

converter

.WithInput(myObject)

.WithFirstLineHasColumnNames(true)

.SaveTo(outCsvFile.Next)

.SaveTo(outXmlFile.Next)

.SaveTo(outJsonFile.Next)

.SaveTo(outYamlFile.Next)

.SaveTo(outHtmlFile.Next);

class MyClass

{

public int IntProperty { get; set; } = 666;

public string StringProperty { get; set; } = "hello world";

}

JSON In, Same Fan-Out Pattern

Pointing WithInput at a GPALFile that holds JSON works the same way as the CSV example - GPALConverter detects the source format from the file and runs the same SaveTo chain to fan it out to CSV, JSON, HTML, XML, and YAML. The conversion logic doesn't change based on what format you started with.

GPALFile inJsonFile = @"c:sdisample.json";

converter

.WithInput(inJsonFile)

.SaveTo(outCsvFile.Next)

.SaveTo(outJsonFile.Next)

.SaveTo(outHtmlFile.Next)

.SaveTo(outXmlFile.Next)

.SaveTo(outYamlFile.Next);

TIP

GPALFile inJsonFile = "c:\sdi\sample.json"; works because GPALFile has an implicit conversion from string - you only need the fuller GPAL.File...ToGPALObject() builder when you need to set extra options like column names or a delimiter.

On this page

Tutorials
GPALConverter: Moving Data Between CSV, JSON, XML, YAML, and Classes
  • Complete Program
  • One Converter, Many Output Files
  • CSV In, Five Formats Out
  • A Plain C# Class Is Just Another Input
  • JSON In, Same Fan-Out Pattern