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

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 -- after a .Next loop, it tells you exactly which files were produced, including auto-generated names.

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