Delimit.Field (delimit v0.2.0)

View Source

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 field configuration options.

Date field configuration options.

General field configuration options.

Supported field types.

t()

Field definition structure.

Functions

Creates a new field definition.

Parses a raw string value into the specified type.

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()}]

Date field configuration options.

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
  | {: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

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"