Spark.Builder.Field (spark v2.6.0)

Builder for individual schema field specifications.

This module provides an option-based API for constructing field definitions used in Spark.Options schemas. Each field can have type, validation, documentation, and DSL-specific attributes.

Examples

iex> alias Spark.Builder.Field
iex> Field.new(:name, :atom, required: true, doc: "The field name")
...> |> Field.to_spec()
{:name, [type: :atom, required: true, doc: "The field name"]}

iex> alias Spark.Builder.Field
iex> Field.new(:status, {:one_of, [:pending, :active]}, default: :pending)
...> |> Field.to_spec()
{:status, [type: {:one_of, [:pending, :active]}, default: :pending]}

Nested Keys

The :keys option accepts raw keyword lists, Field structs, or a zero-arity function returning a schema, allowing composable nested schemas:

alias Spark.Builder.Field

Field.new(:config, :keyword_list,
  keys: [
    Field.new(:host, :string, required: true, doc: "Server hostname"),
    Field.new(:port, :integer, default: 4000, doc: "Server port"),
    Field.new(:ssl, :boolean, default: false, doc: "Enable SSL")
  ],
  doc: "Server configuration"
)

Lazy schemas are supported:

Field.new(:config, :keyword_list,
  keys: &__MODULE__.options_schema/0
)

Summary

Types

t()

Functions

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

Creates a new field builder with the given name and type.

to_schema(field)

Builds a complete schema from a list of field builders or raw schema tuples.

to_spec(field)

Converts the field builder to a schema specification tuple.

Types

t()

(since 2.5.0)

@type t() :: %Spark.Builder.Field{
  as: atom() | nil,
  default: any(),
  deprecated: String.t() | nil,
  doc: String.t() | false | nil,
  has_default: boolean(),
  hide: [atom()],
  keys: Spark.Options.schema() | (-> Spark.Options.schema()) | nil,
  links: keyword() | nil,
  name: atom() | nil,
  private?: boolean(),
  required: boolean(),
  snippet: String.t() | nil,
  subsection: String.t() | nil,
  type: Spark.Options.type(),
  type_doc: String.t() | false | nil,
  type_spec: Macro.t() | nil
}

Functions

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

(since 2.5.0)

@spec new(atom(), Spark.Options.type(), keyword()) :: t()

Creates a new field builder with the given name and type.

Options can set common attributes like :required and :default.

:keys accepts a raw schema keyword list, a list of Field structs, or a zero-arity function that returns a schema.

Options

:required, :default, :keys, :doc, :type_doc, :subsection, :as, :snippet, :links, :deprecated, :private?, :hide, :type_spec

Examples

iex> Spark.Builder.Field.new(:my_field, :any)
%Spark.Builder.Field{name: :my_field, type: :any}

iex> Spark.Builder.Field.new(:type, :atom, required: true)
...> |> Spark.Builder.Field.to_spec()
{:type, [type: :atom, required: true]}

to_schema(field)

(since 2.5.0)

@spec to_schema([t() | {atom(), keyword()}] | t()) :: Spark.Options.schema()

Builds a complete schema from a list of field builders or raw schema tuples.

Examples

iex> [
...>   Field.new(:name, :atom, required: true),
...>   Field.new(:count, :integer, default: 0)
...> ]
...> |> Field.to_schema()
[name: [type: :atom, required: true], count: [type: :integer, default: 0]]

iex> Field.to_schema([name: [type: :atom, required: true]])
[name: [type: :atom, required: true]]

to_spec(field)

(since 2.5.0)

@spec to_spec(t()) :: {atom(), keyword()}

Converts the field builder to a schema specification tuple.

Returns {name, opts} suitable for use in a Spark.Options schema.

Examples

iex> Field.new(:name, :atom, required: true)
...> |> Field.to_spec()
{:name, [type: :atom, required: true]}