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 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. A zip, 7z, rar or tar in the path opens like a folder, export.zip*.csv being the csv files inside it. See Archives Are Folders.

Wildcards and Multi-File Settings

A filename pattern like *.csv adds every matching file in the directory to the GPALFile, sorted by name, or by a FileSortOrder set before the pattern is added. 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, in name order, all sharing one header

var exports = GPAL.File

.WithFileName("exports/*.csv")

.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 name 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. The order applies to a wildcard added after it is set, so set it before a later WithFileName.

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 last supplied filename's pattern, so the sequence keeps going indefinitely. A name whose file already exists is not reused; .Next gives the next free one.

WithOverwriteFile(true) changes only the first .Next for a single-file GPALFile: it returns that filename and deletes the file already there, so the first write replaces it. Every .Next after that generates a new filename.

// One output file per row, auto-numbered: report.csv, report_0001.csv, report_0002.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 carries on from the highest number already in the folder while a timestamp is unique by itself, 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