conform

v2.5.2

conform v2.5.2 Conform.Schema

A schema is a keyword list which represents how to map, transform, and validate configuration values parsed from the .conf file. The following is an explanation of each key in the schema definition in order of appearance, and how to use them.

Import

A list of application names (as atoms), which represent apps to load modules from which you can then reference in your schema definition. This is how you import your own custom Validator/Transform modules, or general utility modules for use in validator/transform functions in the schema. For example, if you have an application :foo which contains a custom Transform module, you would add it to your schema like so:

[ import: [:foo], ..., transforms: ["myapp.some.setting": MyApp.SomeTransform]]

Extends

A list of application names (as atoms), which contain schemas that you want to extend with this schema. By extending a schema, you effectively re-use definitions in the extended schema. You may also override definitions from the extended schema by redefining them in the extending schema. You use :extends like so:

[ extends: [:foo], ... ]

Mappings

Mappings define how to interpret settings in the .conf when they are translated to runtime configuration. They also define how the .conf will be generated, things like documention, @see references, example values, etc.

See the moduledoc for Conform.Schema.Mapping for more details.

Transforms

Transforms are custom functions which are executed to build the value which will be stored at the path defined by the key. Transforms have access to the current config state via the Conform.Conf module, and can use that to build complex configuration from a combination of other config values.

See the moduledoc for Conform.Schema.Transform for more details and examples.

Validators

Validators are simple functions which take two arguments, the value to be validated, and arguments provided to the validator (used only by custom validators). A validator checks the value, and returns :ok if it is valid, {:warn, message} if it is valid, but should be brought to the users attention, or {:error, message} if it is invalid.

See the moduledoc for Conform.Schema.Validator for more details and examples.

Summary

Types

schema()

Functions

coalesce()

Load the schemas for all dependencies of the current project, and merge them into a single schema. Schemas are returned in their quoted form

coalesce(schemas)

Given a collection of schemas, merge them into a single schema

empty()
extract_datatype(v)
from_config(config)

Convert standard configuration to quoted schema format

load(path)

Loads a schema from the provided path. Returns {:ok, schema} | {:error, message}

load!(path)

Load a schema from the provided path. Throws on error. Used for schema evaluation only

merge(x, y)

Merges two schemas. Conflicts are resolved by taking the value from y. Expects the schema to be provided in it’s quoted form

parse(binary)

Parses the schema at the provided path as quoted terms. Returns {:ok, quoted} | {:error, {line, error, details}}

parse!(binary)

Parses the schema at the provided path as quoted terms. Returns the quoted terms or raises SchemaError on failure

schema_filename(app)

get the current app’s schema filename

schema_path()

Get the current app’s schema path

schema_path(app)
stringify(schema, with_moduledoc \\ true)

Converts a schema to a prettified string. Expects the schema to be in it’s quoted form

write(schema, path)

Saves a schema to the provided path

write_quoted(schema, path)

Converts a schema in it’s quoted form and writes it to the provided path

Types

schema() 
schema() :: Conform.Schema

Functions

coalesce() 
coalesce() :: schema

Load the schemas for all dependencies of the current project, and merge them into a single schema. Schemas are returned in their quoted form.

coalesce(schemas) 
coalesce([schema]) :: schema

Given a collection of schemas, merge them into a single schema

empty()
extract_datatype(v)
from_config(config) 
from_config([] | [{atom, term}]) :: [{atom, term}]

Convert standard configuration to quoted schema format

load(path) 
load(binary | atom) :: {:ok, schema} | {:error, term}

Loads a schema from the provided path. Returns {:ok, schema} | {:error, message}

load!(path) 
load!(binary | atom) :: schema

Load a schema from the provided path. Throws on error. Used for schema evaluation only.

merge(x, y) 
merge(schema, schema) :: schema

Merges two schemas. Conflicts are resolved by taking the value from y. Expects the schema to be provided in it’s quoted form.

parse(binary) 
parse(String.t) ::
  {:ok, term} |
  {:error, {integer, binary, binary}}

Parses the schema at the provided path as quoted terms. Returns {:ok, quoted} | {:error, {line, error, details}}

parse!(binary) 
parse!(String.t) :: term | no_return

Parses the schema at the provided path as quoted terms. Returns the quoted terms or raises SchemaError on failure.

schema_filename(app)

get the current app’s schema filename

schema_path() 
schema_path() :: binary

Get the current app’s schema path

schema_path(app)
stringify(schema, with_moduledoc \\ true)

Converts a schema to a prettified string. Expects the schema to be in it’s quoted form.

write(schema, path) 
write(schema, binary) :: :ok | {:error, term}

Saves a schema to the provided path

write_quoted(schema, path) 
write_quoted(schema, binary) :: :ok | {:error, term}

Converts a schema in it’s quoted form and writes it to the provided path