Spark.Builder.Section (spark v2.6.0)

Builder for constructing Spark.Dsl.Section structs.

This module provides an options-based API for creating DSL section definitions programmatically. Sections organize related configurations and can contain entities, nested sections, and schema options.

Examples

alias Spark.Builder.{Section, Entity}

section = Section.new(:attributes,
  describe: "Configure resource attributes",
  schema: [
    primary_key: [type: :boolean, default: true, doc: "Include primary key"]
  ],
  entities: [attribute_entity]
)
|> Section.build!()

Nested Sections

Sections can contain nested sections via the :sections option:

Section.new(:resource,
  sections: [
    Section.new(:attributes,
      entities: [attribute_entity]
    )
    |> Section.build!()
  ]
)
|> Section.build!()

Accepted Options

:schema - Schema for section-level options
:entities - List of entities in this section
:sections - List of nested sections
:top_level? - Whether the section can be used at module level without a do block
:patchable? - Whether other extensions can add entities via patches
:auto_set_fields - Fields automatically set on entities in this section
:after_define - Callback to run after the section is defined as {module, function}
:describe - Description for documentation
:examples - List of example strings
:snippet - IDE autocomplete snippet
:links - Documentation links
:deprecations - Deprecation warnings for specific options
:docs - Additional documentation
:imports - Modules to import in the section's DSL scope
:modules - Schema fields containing module references
:no_depend_modules - Module fields that should not create dependencies

Summary

Types

t()

Functions

build(builder)

Builds the %Spark.Dsl.Section{} struct.

build!(builder)

Builds the %Spark.Dsl.Section{} struct, raising on validation errors.

new(name, opts \\ [])

Creates a new section builder with the given name and options.

Types

t()

(since 2.5.0)

@type t() :: %Spark.Builder.Section{
  after_define: {module(), atom()} | nil,
  auto_set_fields: keyword(),
  deprecations: keyword(String.t()),
  describe: String.t(),
  docs: String.t(),
  entities: [Spark.Dsl.Entity.t()],
  examples: [String.t()],
  imports: [module()],
  links: keyword([String.t()]) | nil,
  modules: [atom()],
  name: atom() | nil,
  no_depend_modules: [atom()],
  patchable?: boolean(),
  schema: Spark.Options.schema(),
  sections: [Spark.Dsl.Section.t()],
  singleton_entity_keys: term(),
  snippet: String.t(),
  top_level?: boolean()
}

Functions

build(builder)

(since 2.5.0)

@spec build(t()) :: {:ok, Spark.Dsl.Section.t()} | {:error, String.t()}

Builds the %Spark.Dsl.Section{} struct.

Returns {:ok, section} on success or {:error, reason} on validation failure.

Examples

{:ok, section} = Section.new(:fields,
  entities: [field_entity]
)
|> Section.build()

build!(builder)

(since 2.5.0)

@spec build!(t()) :: Spark.Dsl.Section.t()

Builds the %Spark.Dsl.Section{} struct, raising on validation errors.

Examples

section = Section.new(:fields,
  entities: [field_entity]
)
|> Section.build!()

new(name, opts \\ [])

(since 2.5.0)

@spec new(
  atom(),
  keyword()
) :: t()

Creates a new section builder with the given name and options.

Parameters

name - The atom name for the DSL section (e.g., :attributes)
opts - Options to configure the section (see module docs for accepted options)

Examples

iex> Section.new(:attributes)
%Spark.Builder.Section{name: :attributes}

iex> Section.new(:attributes,
...>   describe: "Resource attributes",
...>   top_level?: true
...> )
%Spark.Builder.Section{name: :attributes, describe: "Resource attributes", top_level?: true}