Struct DelimitedFile 

#[non_exhaustive]
pub struct DelimitedFile<'a> {
    pub path_literal: &'a str,
    pub directory_literal: &'a str,
    pub name: &'a str,
    pub columns: &'a [String],
    pub line_ending: LineEnding,
    pub delimiter: FileDelimiter,
    pub quote: char,
    pub header: bool,
    pub encoding: Option<&'a str>,
}

One delimited source file, in every spelling an engine’s file relation may ask for it in — what SqlRenderer::delimited_file_relation_for is handed.

One struct rather than several arguments, because a slot that grows an argument is a slot every dialect has to be recompiled for; one that grows a field is not. Each is composed once, by the caller that knows the answer, so no dialect has to take a path apart to find a file name in it.

A dialect reads the fields. One that builds a value, in its own tests, starts from DelimitedFile::new and the with_ methods, which is also why it cannot be written out field by field outside this crate: the next thing Razeri learns to say about a file arrives as a field with a default, and no dialect’s tests break for it.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

path_literal: &'a str

The whole path to the file, already a single-quoted SQL string literal and already escaped. Put it where the relation takes a path, and do not quote it again.

directory_literal: &'a str

The directory the file sits in, already a single-quoted SQL string literal — for an engine that resolves a file name against a directory rather than opening a path.

name: &'a str

The file’s own name inside that directory, bare: no quotes and no path in front of it.

columns: &'a [String]

The file’s columns, in the order the file writes them, spelled exactly as its header row spells them and with no quoting applied.

Empty where the caller measured no header — a bundle assembled by hand. An engine that cannot read a file without its columns declared answers None to an empty list rather than guessing at one.

A file with no header line (header false) has no names of its own, and its columns arrive as column0, column1 and on, counted from zero: the names DuckDB gives such a file, and the names a header cell with no name is read under everywhere.

line_ending: LineEnding

How the file’s lines end, as Razeri measured it when it read the file: LineEnding::CrLf for a carriage return and a newline, LineEnding::Lf for a newline alone.

Put it wherever the engine’s read names a record delimiter. An engine told \n for a file whose lines end \r\n either keeps the carriage return on the last field, so a name is stored one character too long and a number cannot be read, or, where the last field is quoted, reads past the closing quote into the next line. An engine whose read finds the ending itself can leave this alone, and should say so where it states its read.

delimiter: FileDelimiter

The character between the file’s fields, as the design declares it. Never a guess: an engine whose reader would otherwise sniff the delimiter is told this one.

The four ASCII separators (FileDelimiter::is_control) are bytes no text editor shows, and engines differ in how a statement may name them: an escape, a hexadecimal literal, a function call, or not at all. Spell the one your engine was measured to take. Where it takes none, answer None: Razeri then declines the file by name and says which delimiter your engine does read.

quote: char

The character a field is quoted with: " unless the design declares another. A field inside two of them may hold the delimiter and a line break, and two of them together inside it stand for one.

header: bool

Whether the file’s first line names its columns. true unless the design declares header: false; a file without one has its first row of values on its first line, and its columns are named by position.

encoding: Option<&'a str>

The encoding to read the bytes as, where they are not UTF-8: the one name the encoding standard files it under (windows-1252, shift_jis). None on the ordinary day, which means UTF-8.

Razeri asks delimited_file_relation_in_encoding whether your engine has a word for the encoding before it hands one over here, so a dialect that answers that one None never meets an encoding in this field. One that answers it, and also overrides delimited_file_relation_for, reads this field there.

Implementations

impl<'a> DelimitedFile<'a>

pub const fn new( path_literal: &'a str, directory_literal: &'a str, name: &'a str, ) -> Self

A file at path_literal, read the way every engine reads a file by default: no columns measured, lines ending \n, split on commas, quoted with ", a header on its first line, and UTF-8.

path_literal and directory_literal are finished single-quoted SQL string literals; name is the file’s own name, bare.

pub const fn with_columns(self, columns: &'a [String]) -> Self

The same file, with its columns in the order the file writes them.

pub const fn with_line_ending(self, line_ending: LineEnding) -> Self

The same file, its lines ending as line_ending says.

pub const fn with_delimiter(self, delimiter: FileDelimiter) -> Self

The same file, its fields split by delimiter.

pub const fn with_quote(self, quote: char) -> Self

The same file, its fields quoted with quote.

pub const fn with_header(self, header: bool) -> Self

The same file, with a header line or without one.

pub const fn with_encoding(self, encoding: Option<&'a str>) -> Self

The same file, its bytes read as encoding, or as UTF-8 for None.

pub fn is_plain(&self) -> bool

Whether the file is written the way a read that is told nothing reads it: split on commas, quoted with ", and headed.

The default delimited_file_relation_for answers only for such a file, because the path-only delimited_file_relation it hands over to has no way to be told anything else.

Trait Implementations

impl<'a> Clone for DelimitedFile<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for DelimitedFile<'a>

impl<'a> Debug for DelimitedFile<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.