View Source Spark.Dsl.Section (spark v1.1.53)

Declares a DSL section.

A dsl section allows you to organize related configurations. All extensions configure sections, they cannot add DSL builders to the top level. This keeps things organized, and concerns separated.

A section may have nested sections, which will be configured the same as other sections. Getting the options/entities of a section is done by providing a path, so you would use the nested path to retrieve that configuration. See Spark.Dsl.Extension.get_entities/2 and Spark.Dsl.Extension.get_opt/4.

A section may have entities, which are constructors that produce instances of structs. For more on entities, see Spark.Dsl.Entity.

A section may also have a schema, which is a NimbleOptions schema. Spark will produce builders for those options, so that they may be configured. They are retrieved with Spark.Dsl.Extension.get_opt/4.

To create a section that is available at the top level (i.e not nested inside of its own name), use top_level?: true. Remember, however, that this has no effect on sections nested inside of other sections.

For a full example, see Spark.Dsl.Extension.

Summary

Types

User provided documentation.

Internal field. Not set by user.

t()

Determines whether a section can be declared directly in a module.

Types

@type auto_set_fields() :: Keyword.t(any())
@type describe() :: String.t()

User provided documentation.

Documentation provided in a Section's describe field will be included by Spark in any generated documentation that includes the Section.

@type docs() :: String.t()

Internal field. Not set by user.

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

Determines whether a section can be declared directly in a module.

When top_level?: true, that Section's DSL can be declared outside of a do block in a module.

Example

A Section declared with top_level?: true:

@my_section %Spark.Dsl.Section{
  top_level?: true,
  name: :my_section,
  schema: [my_field: [type: :atom, required: true]]
}

Can be declared like this:

defmodule MyDslModule do
  my_field :value
end

With top_level?: false, the DSL section would need to be declared explicitly/:

defmodule MyDslModule do
  my_section do
    my_field :value
  end
end