Delimit.Field (delimit v0.4.1)

Defines field types, options, and conversion functions for Delimit schemas.

This module handles field definitions, data type conversions, and validation for delimited data format parsing and generation.

Summary

Types

boolean_opts()

Boolean field configuration options.

date_opts()

Date field configuration options.

field_opts()

General field configuration options.

field_type()

Supported field types.

t()

Field definition structure.

Functions

derived?(field)

Returns true if the field is a derived/computed type whose value comes from the parsing pipeline rather than from a column in the input file.

new(name, type, opts \\ [])

Creates a new field definition.

parse_value(value, field)

Parses a raw string value into the specified type.

to_string(value, field)

Converts a value to a string representation for writing to a delimited file.

Types

boolean_opts()

@type boolean_opts() :: [true_values: [String.t()], false_values: [String.t()]]

Boolean field configuration options.

date_opts()

@type date_opts() :: [format: String.t(), formats: [String.t()]]

Date field configuration options.

:format - A single Timex/ISO format string for parsing and writing
:formats - A list of format strings to try in order on read (mutually exclusive with :format). The first format that successfully parses wins. Useful for files that contain mixed date formats (e.g. mostly M/D/YYYY with occasional YYYY-MM-DD). Writing always uses the first format in the list.

field_opts()

@type field_opts() :: [
  optional: boolean(),
  default: any(),
  read_fn: (String.t() -> any()),
  write_fn: (any() -> String.t()),
  nil_on_empty: boolean(),
  label: String.t(),
  struct_type: field_type() | boolean_opts() | date_opts()
]

General field configuration options.

:optional - Whether the field is optional (default: false)
:default - Default value if the field is missing
:read_fn - Custom function to parse the raw field value
:write_fn - Custom function to convert the field value to string
:nil_on_empty - If true, empty strings become nil (default: true)
:label - Custom header label for this field (instead of the field name)
:struct_type - The type to use in the struct (different from file type)

field_type()

@type field_type() ::
  :string
  | :integer
  | :float
  | :boolean
  | :date
  | :datetime
  | :embed
  | :row_hash
  | :raw_row
  | {:list, field_type()}
  | {:map, field_type()}
  | {:map, field_type(), field_type()}

Supported field types.

Basic field types:

:string - String values
:integer - Integer values
:float - Floating point values
:boolean - Boolean values
:date - Date values
:datetime - DateTime values
:embed - Embedded struct

Complex type annotations (for struct_type option):

{:list, inner_type} - A list where each element is of type inner_type
{:map, key_type, value_type} - A map with keys of key_type and values of value_type
{:map, value_type} - A map with atom keys and values of value_type

t()

@type t() :: %Delimit.Field{name: atom(), opts: Keyword.t(), type: atom()}

Field definition structure.

:name - The name of the field
:type - The data type of the field
:opts - Additional options for the field

Functions

derived?(field)

@spec derived?(t()) :: boolean()

Returns true if the field is a derived/computed type whose value comes from the parsing pipeline rather than from a column in the input file.

Derived fields are skipped during write, do not consume input columns on read, and do not contribute to canonical encoding.

new(name, type, opts \\ [])

@spec new(atom(), field_type(), field_opts()) :: t()

Creates a new field definition.

Parameters

name - The name of the field as an atom
type - The type of the field (:string, :integer, etc.)
opts - A keyword list of options for the field

Example

iex> Delimit.Field.new(:first_name, :string, [])
%Delimit.Field{name: :first_name, type: :string, opts: []}

iex> Delimit.Field.new(:age, :integer, [default: 0])
%Delimit.Field{name: :age, type: :integer, opts: [default: 0]}

parse_value(value, field)

@spec parse_value(String.t() | nil, t()) :: any()

Parses a raw string value into the specified type.

Parameters

value - The raw string value from the delimited file
field - The field definition

Returns

The parsed value or nil if the value is empty and nil_on_empty is true

Example

iex> field = Delimit.Field.new(:age, :integer)
iex> Delimit.Field.parse_value("42", field)
42

iex> field = Delimit.Field.new(:active, :boolean)
iex> Delimit.Field.parse_value("Yes", field)
true

to_string(value, field)

@spec to_string(any(), t()) :: String.t()

Converts a value to a string representation for writing to a delimited file.

Parameters

value - The value to convert
field - The field definition

Returns

The string representation of the value

Example

iex> field = Delimit.Field.new(:age, :integer)
iex> Delimit.Field.to_string(42, field)
"42"

iex> field = Delimit.Field.new(:active, :boolean)
iex> Delimit.Field.to_string(true, field)
"true"