View Source Spark.Dsl.Section (spark v2.1.21)

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 you can learn more about in Spark.Options. 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

auto_set_fields()

describe()

User provided documentation.

docs()

Internal field. Not set by user.

entities()

examples()

imports()

links()

modules()

name()

no_depend_modules()

patchable?()

sections()

snippet()

t()

top_level?()

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

Types

auto_set_fields()

@type auto_set_fields() :: keyword(any())

describe()

@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.

docs()

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

Internal field. Not set by user.

entities()

@type entities() :: [Spark.Dsl.Entity.t()]

examples()

@type examples() :: [String.t()]

imports()

@type imports() :: [module()]

links()

@type links() :: nil | keyword([String.t()])

modules()

@type modules() :: [atom()]

name()

@type name() :: atom()

no_depend_modules()

@type no_depend_modules() :: [atom()]

patchable?()

@type patchable?() :: boolean()

sections()

@type sections() :: [t()]

snippet()

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

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.Options.schema(),
  sections: sections(),
  snippet: snippet(),
  top_level?: 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