Concepts

Data Operations

Data Operations

GPALFile: Files as Objects

Not Just a Path

GPALFile has an implicit conversion from string, so a plain path is a GPALFile wherever one is expected. Most workflows never need to write the word GPALFile at all. The object form exists for when a 'file' stops being just a path: GPAL.File.WithFileName(...).ToGPALObject() starts a fluent chain that can add more filenames, set column names, configure delimiters, and more. Filename returns the single path when there is exactly one, and Filenames returns the full List<string> for everything that was added or matched.

// A plain string is a GPALFile wherever one is expected

GPAL.Converter

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

.WithOutputType(DataFormat.JSON)

.SaveTo("data.json");

NOTE

GPAL.FileFor(path) wraps a string in a GPALFile when WithInput would otherwise intercept it as raw text. Use the full GPAL.File chain when you need wildcards, column names, or file-level operations like .Next or CopyTo. WithFileName also accepts an http or https url, in which case the file is fetched to disk right there and everything after it works on the local copy. See Files From a URL.

Wildcards and Multi-File Settings

A filename pattern like *.csv adds every matching file in the directory to the GPALFile, sorted in whatever order you configure. For flat files, you can describe the format -- the delimiter, whether the first line is column names, and whether fields are quoted -- so every matched file is parsed the same way. When a file has no header row, you supply column names once and optionally share them across all matched files.

// Every CSV in the directory, oldest first, all sharing one header

var exports = GPAL.File

.WithFileName("exports/*.csv")

.WithFileSortOrder(FileSortOrder.DateCreatedAscending)

.WithFirstLineIsColumnNames(false)

.WithColumnNames("Id,Name,Total")

.WithUseSameColumnNamesForAllFiles(true)

.ToGPALObject();


foreach (var path in exports.Filenames)

{

// path is a plain string - one per matched file, in the configured order

}

NOTE

FileSortOrder controls how wildcard matches are ordered in Filenames: NameAscending/Descending and NaturalAscending/Descending sort alphabetically (Natural treats embedded numbers as numbers, so file2 comes before file10), and DateModified/DateCreated Ascending/Descending sort by file timestamp. The default is NameAscending.

Generating Output Filenames with .Next

When a GPALFile is used as an output destination across a loop -- saving one file per page, per record, or per iteration -- calling .Next returns the filename to write to this time and advances an internal cursor. If user-supplied filenames remain (from a wildcard match, for example), those are returned first, in order. Once they're exhausted, .Next generates a new filename from the first filename's pattern, so the sequence keeps going indefinitely. WithOverwriteFile(true) changes this for a single-file GPALFile: instead of generating new filenames, .Next keeps returning the same filename every time, so each iteration overwrites the last.

// One output file per row, auto-numbered: report.csv, report (1).csv, report (2).csv, ...

var output = GPAL.FileFor("report.csv");


foreach (var row in rows)

{

GPAL.Converter

.WithInput(row)

.WithOutputType(DataFormat.CSV)

.SaveTo(output.Next);

}


// File-level actions need the object, not just the path

var archive = GPAL.FileFor("report.csv");

archive.CopyTo("archive/report.csv");

archive.Delete();

NOTE

Filenames lists what was supplied or matched by wildcard. ReturnFilenames is populated as outputs are written, so after a .Next loop it tells you exactly which files were produced, including the generated names. WithNextFilePattern chooses the shape of those generated names. CounterPadded is the default and gives report_0001.csv, report_0002.csv and on. Counter is the same without the padding, DateStamp gives report_20260723.csv, DateTimeStamp gives report_20260723_141530.csv, and Timestamp gives report20260723141530777.csv. A counter starts again with the workflow while a timestamp does not, so reach for a timestamp when runs can overlap and a padded counter when the files want to sort in order.

On this page

Data Operations
GPALFile: Files as Objects
  • Not Just a Path
  • Wildcards and Multi-File Settings
  • Generating Output Filenames with .Next
    • 💬 Ask GPAL