Concepts

Data Operations

Data Operations

GPALFile: Files as Objects

GPALFile turns a path, a wildcard pattern, or a list of files into a single object that the rest of GPAL can read from, write to, and act on. With implicit string conversion so most of the time it doesn't look like an object at all.

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(GPAL.FileFor("data.csv"))

.WithOutputType(DataFormat.JSON)

.SaveTo("data.json");

TIP

GPAL.FileFor(path) and GPAL.File.WithFileName(path).ToGPALObject() both just wrap a string in a GPALFile -- useful when WithInput's string overload would otherwise intercept a plain string (see the GPALConverter page), but otherwise no better than the string itself. Reach for the full GPAL.File... ToGPALObject() chain when you need to configure the file (wildcards, column names, delimiters) or reuse the resulting object (.Next, Filenames, CopyTo/MoveTo/Delete) -- covered next.

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

}

TIP

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();

TIP

Filenames is the list of inputs. What was supplied or matched by a wildcard. ReturnFilenames is populated as outputs are actually written, so after a loop using .Next, ReturnFilenames tells you exactly which files were produced, even when most of them were generated rather than supplied.

On this page

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