NimbleOptions v0.1.0 NimbleOptions View Source

Provides a standard API to handle keyword list based options.

NimbleOptions allows developers to create schemas using a pre-defined set of options and types. The main benefits are:

  • A single unified way to define simple static options
  • Config validation against schemas
  • Automatic doc generation

Options

  • :type - The type of the option item. The default value is :any.

  • :required - Defines if the option item is required. The default value is false.

  • :default - The default value for option item if not specified.

  • :keys - Available for types :keyword_list and :non_empty_keyword_list, it defines which set of keys are accepted for the option item. Use :* as the key to allow multiple arbitrary keys.

  • :deprecated - Defines a message to indicate that the option item is deprecated. The message will be displayed as a warning when passing the item.

  • :rename_to - Renames a option item allowing one to use a normalized name internally, e.g. rename a deprecated item to the currently accepted name.

  • :doc - The documentation for the option item.

  • :subsection - The title of separate subsection of the options' documentation

Types

  • :any - Any type.

  • :keyword_list - A keyword list.

  • :non_empty_keyword_list - A non-empty keyword list.

  • :atom - An atom.

  • :string - A string.

  • :boolean - A boolean.

  • :non_neg_integer - A non-negative integer.

  • :pos_integer - A positive integer.

  • :timeout - A non-negative integer or the atom :infinity.

  • :mfa - A named function in the format {module, function, arity}

  • :mod_arg - A module along with arguments, e.g. {MyModule, [arg1, arg2]}. Usually used for process initialization using start_link and friends.

  • {:fun, arity} - Any function with the specified arity.

  • {:one_of, choices} - A value that is a member of one of the choices.

  • {:custom, mod, fun, args} - A custom type. The related value must be validated by mod.fun(values, ...args). The function should return {:ok, value} or {:error, message}.

Example

iex> schema = [
...>   producer: [
...>     type: :non_empty_keyword_list,
...>     required: true,
...>     keys: [
...>       module: [required: true, type: :mod_arg],
...>       concurrency: [
...>         type: :pos_integer,
...>       ]
...>     ]
...>   ]
...> ]
...>
...> config = [
...>   producer: [
...>     concurrency: 1,
...>   ]
...> ]
...>
...> NimbleOptions.validate(config, schema)
{:error, "(in options [:producer]) required option :module not found, received options: [:concurrency]"}

Nested option items

NimbleOptions allows option items to be nested so you can recursively validate any item down the options tree.

Example

iex> schema = [
...>   producer: [
...>     required: true,
...>     type: :non_empty_keyword_list,
...>     keys: [
...>       rate_limiting: [
...>         type: :non_empty_keyword_list,
...>         keys: [
...>           interval: [required: true, type: :pos_integer]
...>         ]
...>       ]
...>     ]
...>   ]
...> ]
...>
...> config = [
...>   producer: [
...>     rate_limiting: [
...>       interval: :oops!
...>     ]
...>   ]
...> ]
...>
...> NimbleOptions.validate(config, schema)
{:error, "(in options [:producer, :rate_limiting]) expected :interval to be a positive integer, got: :oops!"}

Link to this section Summary

Functions

Returns documentation for the given schema.

Validate the given options with the given schema.

Link to this section Types

Link to this section Functions

Returns documentation for the given schema.

You can use this to inject documentation in your docstrings. For example, say you have your schema in a module attribute:

@options_schema [...]

With this, you can use docs/1 to inject documentation:

@doc "Supported options:\n#{NimbleOptions.docs(@options_schema)}"
Link to this function

validate(options, schema)

View Source
validate(keyword(), schema()) ::
  {:ok, validated_options :: keyword()} | {:error, reason :: String.t()}

Validate the given options with the given schema.

See the module documentation for what a schema is.

If the validation is successful, this function returns {:ok, validated_options} where validated_options is a keyword list. If the validation fails, this function returns {:error, reason} where reason is an error message (a string) telling what's wrong with the given options.