NimbleOptions

https://nimble-options.hexdocs.pm/
Admin
NimbleOptions provides a standard API to validate keyword-list-based options and maps against...
Tokens:11,056
Snippets:88
Trust Score:9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example schema with option_typespec

Source: https://nimble-options.hexdocs.pm/

Example schema definition and usage of option_typespec/1 to generate a typespec for it.

```elixir
schema = [
  int: [type: :integer],
  number: [type: {:or, [:integer, :float]}]
]

@type option() :: unquote(NimbleOptions.option_typespec(schema))
```

--------------------------------

### Specifying a whole schema with option_typespec

Source: https://nimble-options.hexdocs.pm/

Example of using option_typespec/1 to spec a whole schema as a list of options.

```elixir
@type options() :: [unquote(NimbleOptions.option_typespec(my_schema))]
```

--------------------------------

### Nested schema example

Source: https://nimble-options.hexdocs.pm/

Defines a nested schema used to demonstrate the :nest_level option of docs/2.

```elixir
nested_schema = [
  allowed_messages: [type: :pos_integer, doc: "Allowed messages."],
  interval: [type: :pos_integer, doc: "Interval."]
]
```

--------------------------------

### Using option_typespec in a typespec

Source: https://nimble-options.hexdocs.pm/

Usage example showing how to use the return value of option_typespec/1 in a typespec with unquote/1.

```elixir
@type option() :: unquote(NimbleOptions.option_typespec(my_schema))
```

--------------------------------

### Schema in module attribute

Source: https://nimble-options.hexdocs.pm/

Example of storing a schema in a module attribute, which can then be used with docs/1 to inject documentation.

```elixir
@options_schema [...]
```

--------------------------------

### Compiled typespec result

Source: https://nimble-options.hexdocs.pm/

The compiled result of the previous example, showing the generated typespec.

```elixir
@type option() :: {:int, integer()} | {:number, integer() | float()}
```

--------------------------------

### Combining option_typespec with custom types

Source: https://nimble-options.hexdocs.pm/

Example of combining option_typespec/1 with custom types in a typespec for partial validation.

```elixir
@type my_option() ::
        {:my_opt1, integer()}
        | {:my_opt2, boolean()}
        | unquote(NimbleOptions.option_typespec(my_schema))
```

--------------------------------

### docs(schema, options \\ [])

Source: https://nimble-options.hexdocs.pm/

Returns documentation for the given schema. You can use this to inject documentation in your docstrings.

```APIDOC
## docs(schema, options \\ [])

### Description
Returns documentation for the given schema. You can use this to inject documentation in your docstrings.

### Method
Function

### Signature
`docs(schema, options \\ [])`

### Parameters
- **schema** (schema() | t()) - Required - The schema or validated schema to generate documentation for.
- **options** (keyword()) - Optional - Options for generating documentation. Supported option: `:nest_level` (integer) - decides the "nest level" of the generated docs, useful for nested schemas.

### Return Value
String.t() - The generated documentation string.

### Example
```elixir
@doc "Supported options:\n#{NimbleOptions.docs(@options_schema)}"
```
```

--------------------------------

### Inject docs with @doc

Source: https://nimble-options.hexdocs.pm/

Shows how to use docs/1 to inject schema documentation into a module's @doc attribute.

```elixir
@doc "Supported options:\n#{NimbleOptions.docs(@options_schema)}"
```

--------------------------------

### Compile schema with NimbleOptions.new!/1 and validate options

Source: https://nimble-options.hexdocs.pm/

Validates a schema once with NimbleOptions.new!/1 and then uses the compiled schema in validate/2. This avoids re-validating the schema on every call and returns an :ok tuple when the options are valid.

```elixir
iex> raw_schema = [
...>   hostname: [
...>     required: true,
...>     type: :string
...>   ]
...> ]
...>
...> schema = NimbleOptions.new!(raw_schema)
...> NimbleOptions.validate([hostname: "elixir-lang.org"], schema)
{:ok, hostname: "elixir-lang.org"}
```

--------------------------------

### NimbleOptions.new!/1

Source: https://nimble-options.hexdocs.pm/

Validates a schema and returns a compiled schema. Raises on invalid schema. Can be used at compile time for efficiency.

```APIDOC
## [POST] /new

### Description
Validates a schema and returns a compiled schema. Raises on invalid schema. Can be used at compile time for efficiency.

### Method
POST

### Endpoint
/new

### Parameters
#### Request Body
- **schema** (keyword list) - Required - The schema to validate and compile.

### Request Example
```json
{
  "schema": {
    "hostname": {"required": true, "type": "string"}
  }
}
```

### Response
#### Success Response (200)
- **compiled_schema** (term) - The compiled schema.

#### Response Example
```json
{
  "compiled_schema": "%NimbleOptions.CompiledSchema{...}"
}
```
```

--------------------------------

### validate!(options, schema)

Source: https://nimble-options.hexdocs.pm/

Validates the given `options` with the given `schema` and raises if they're not valid.

```APIDOC
## validate!(options, schema)

### Description
Validates the given `options` with the given `schema` and raises if they're not valid.

### Method
Function

### Signature
`validate!(options, schema)`

### Parameters
- **options** (keyword()) - Required - The options to validate.
- **schema** (schema() | t()) - Required - The schema to validate against.

### Return Value
Validated options - The validated options, or raises an error if validation fails.
```

--------------------------------

### new!(schema)

Source: https://nimble-options.hexdocs.pm/

Validates the given `schema` and returns a wrapped schema to be used with `validate/2`.

```APIDOC
## new!(schema)

### Description
Validates the given `schema` and returns a wrapped schema to be used with `validate/2`.

### Method
Function

### Signature
`new!(schema)`

### Parameters
- **schema** (schema()) - Required - The schema to validate.

### Return Value
t() - The `NimbleOptions` struct embedding the validated schema.

### Example
```elixir
schema = NimbleOptions.new!(schema)
```
```

--------------------------------

### validate!(options, schema)

Source: https://nimble-options.hexdocs.pm/

Validates the given options with the given schema and raises an exception if validation fails.

```APIDOC
## validate!(options, schema)

### Description
Validates the given `options` with the given `schema` and raises if they're not valid. Returns the validated options directly on success.

### Method
Function

### Signature
`validate!(options, schema)`

### Parameters
- **options** (keyword() | map()) - Required - The options to validate.
- **schema** (schema() | t()) - Required - The schema to validate against.

### Returns
- `validated_options` (keyword() | map()) - The validated options.

### Raises
- `NimbleOptions.ValidationError` - If validation fails.

### Example
```elixir
validate!(options, schema)
```
```

--------------------------------

### Nested schema with nest_level

Source: https://nimble-options.hexdocs.pm/

Shows how to document a nested schema inside another schema using the :nest_level option of docs/2.

```elixir
schema = [
  producer: [
    type: {:or, [:string, keyword_list: nested_schema]},
    doc:
      "Either a string or a keyword list with the following keys:\n\n" <>
        NimbleOptions.docs(nested_schema, nest_level: 1)
  ],
  other_key: [type: :string]
]
```

--------------------------------

### validate(options, schema)

Source: https://nimble-options.hexdocs.pm/

Validates the given options with the given schema. Returns a tuple indicating success or failure.

```APIDOC
## validate(options, schema)

### Description
Validates the given `options` with the given `schema`. Returns `{:ok, validated_options}` on success or `{:error, validation_error}` on failure.

### Method
Function

### Signature
`validate(options, schema)`

### Parameters
- **options** (keyword() | map()) - Required - The options to validate.
- **schema** (schema() | t()) - Required - The schema to validate against.

### Returns
- `{:ok, validated_options}` - A tuple with `:ok` and the validated options as a keyword list.
- `{:error, NimbleOptions.ValidationError.t()}` - A tuple with `:error` and a `NimbleOptions.ValidationError` struct.

### Example
```elixir
validate(options, schema)
```
```

--------------------------------

### NimbleOptions.validate/2

Source: https://nimble-options.hexdocs.pm/

Validates a configuration against a schema. Returns {:ok, validated_config} or {:error, %NimbleOptions.ValidationError{}}.

```APIDOC
## [POST] /validate

### Description
Validates a configuration against a schema. Returns {:ok, validated_config} or {:error, %NimbleOptions.ValidationError{}}.

### Method
POST

### Endpoint
/validate

### Parameters
#### Request Body
- **config** (keyword list) - Required - The configuration to validate.
- **schema** (keyword list) - Required - The schema to validate against.

### Request Example
```json
{
  "config": {
    "producer": {
      "concurrency": 1
    }
  },
  "schema": {
    "producer": {
      "type": "non_empty_keyword_list",
      "required": true,
      "keys": {
        "module": {"required": true, "type": "mod_arg"},
        "concurrency": {"type": "pos_integer"}
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **result** (tuple) - {:ok, validated_config} or {:error, %NimbleOptions.ValidationError{}}

#### Response Example
```json
{
  "result": {"error": "required :module option not found, received options: [:concurrency] (in options [:producer])"}
}
```
```

--------------------------------

### new!(schema)

Source: https://nimble-options.hexdocs.pm/

Validates a given schema and returns a wrapped schema for use with validate/2. Raises an error if the schema is invalid.

```APIDOC
## new!(schema)

### Description
Validates the given `schema` and returns a wrapped schema to be used with `validate/2`. If the given schema is not valid, raises a `NimbleOptions.ValidationError`.

### Function Signature
```elixir
@spec new!(schema()) :: t()
```

### Parameters
- **schema** (schema()) - Required - The schema to validate.

### Returns
- **t()** - A wrapped schema to be used with `validate/2`.

### Errors
- Raises `NimbleOptions.ValidationError` if the schema is not valid.
```

--------------------------------

### validate(options, schema)

Source: https://nimble-options.hexdocs.pm/

Validates the given `options` with the given `schema`.

```APIDOC
## validate(options, schema)

### Description
Validates the given `options` with the given `schema`.

### Method
Function

### Signature
`validate(options, schema)`

### Parameters
- **options** (keyword()) - Required - The options to validate.
- **schema** (schema() | t()) - Required - The schema to validate against.

### Return Value
`{:ok, validated_options}` or `{:error, error}` - The result of validation.
```

--------------------------------

### %NimbleOptions.ValidationError{}

Source: https://nimble-options.hexdocs.pm/NimbleOptions.ValidationError.html

The error struct for validation errors. Only the documented fields :key, :keys_path, and :value are public and should be referenced.

```APIDOC
## %NimbleOptions.ValidationError{}

### Description
The error struct returned or raised when options are invalid. Only the documented fields are public; all other fields are private.

### Fields
- **:key** (atom() | [atom()]) - The key that did not successfully validate. When several keys are involved in the same error (e.g., unknown options reported as a group), this is the list of those keys.
- **:keys_path** ([atom()]) - If the key is nested, this is the path to the key.
- **:value** (term()) - The value that failed to validate. This field is `nil` if there was no value provided.

### Type Specification
```elixir
@type t() :: %NimbleOptions.ValidationError{
  __exception__: term(),
  key: atom() | [atom()],
  keys_path: [atom()],
  message: term(),
  redact: boolean(),
  value: term()
}
```

### Usage
This exception can be raised directly with `raise/1` or turned into a message string with `Exception.message/1`.
```

--------------------------------

### schema() type definition

Source: https://nimble-options.hexdocs.pm/

Defines the schema type as a keyword list. Used to represent a NimbleOptions schema.

```elixir
@type schema() :: keyword()
```

--------------------------------

### docs/2 spec

Source: https://nimble-options.hexdocs.pm/

Specifies the docs/2 function signature. It accepts a schema or a validated t() and returns documentation as a string.

```elixir
@spec docs(
  schema() | t(),
  keyword()
) :: String.t()
```

--------------------------------

### new!/1 spec

Source: https://nimble-options.hexdocs.pm/

Specification for the new!/1 function, which validates a schema and returns a wrapped schema for use with validate/2. Raises NimbleOptions.ValidationError for invalid schemas.

```elixir
@spec new!(schema()) :: t()
```

--------------------------------

### Validate required nested option with NimbleOptions.validate/2

Source: https://nimble-options.hexdocs.pm/

Validates a config against a schema with a required nested option. The schema requires a :module key inside :producer, but the config omits it, so validate/2 returns an error tuple and Exception.message/1 shows the validation message.

```elixir
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,
...>   ]
...> ]
...>
...> {:error, %NimbleOptions.ValidationError{} = error} = NimbleOptions.validate(config, schema)
...> Exception.message(error)
"required :module option not found, received options: [:concurrency] (in options [:producer])"
```

--------------------------------

### option_typespec(schema)

Source: https://nimble-options.hexdocs.pm/

Returns the quoted typespec for any option described by the given schema.

```APIDOC
## option_typespec(schema)

### Description
Returns the quoted typespec for any option described by the given schema.

### Method
Function

### Signature
`option_typespec(schema)`

### Parameters
- **schema** (schema()) - Required - The schema to generate the typespec for.

### Return Value
Quoted typespec (AST) - The quoted typespec for the options described by the schema.
```

--------------------------------

### option_typespec(schema)

Source: https://nimble-options.hexdocs.pm/

Returns the quoted typespec for any option described by the given schema. The returned quoted code represents the type union for all possible keys in the schema, alongside their type.

```APIDOC
## option_typespec(schema)

### Description
Returns the quoted typespec for any option described by the given schema. The returned quoted code represents the type union for all possible keys in the schema, alongside their type. Nested keyword lists are spec'ed as `keyword/0`.

### Function Signature
```elixir
@spec option_typespec(schema() | t()) :: Macro.t()
```

### Parameters
- **schema** (schema() | t()) - Required - The schema or wrapped schema to generate the typespec for.

### Returns
- **Macro.t()** - The quoted typespec representing the type union for all possible keys.

### Usage
Because of how typespecs are treated by the Elixir compiler, you have to use `unquote/1` on the return value of this function to use it in a typespec:

```elixir
@type option() :: unquote(NimbleOptions.option_typespec(my_schema))
```

This function returns the type union for a single option: to give you flexibility to combine it and use it in your own typespecs. For example, if you only validate part of the options through NimbleOptions, you could write a spec like this:

```elixir
@type my_option() ::
        {:my_opt1, integer()}
        | {:my_opt2, boolean()}
        | unquote(NimbleOptions.option_typespec(my_schema))
```

If you want to spec a whole schema, you could write something like this:

```elixir
@type options() :: [unquote(NimbleOptions.option_typespec(my_schema))]
```

### Example
```elixir
schema = [
  int: [type: :integer],
  number: [type: {:or, [:integer, :float]}]
]

@type option() :: unquote(NimbleOptions.option_typespec(schema))
```

The code above would essentially compile to:

```elixir
@type option() :: {:int, integer()} | {:number, integer() | float()}
```
```

--------------------------------

### Validate nested option items with NimbleOptions.validate/2

Source: https://nimble-options.hexdocs.pm/

Shows nested option validation: the schema defines a :rate_limiting key with a required :interval of type :pos_integer. The config provides an atom instead of an integer, so validate/2 returns an error and Exception.message/1 reports the invalid value.

```elixir
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!
...>     ]
...>   ]
...> ]
...>
...> {:error, %NimbleOptions.ValidationError{} = error} = NimbleOptions.validate(config, schema)
...> Exception.message(error)
"invalid value for :interval option: expected positive integer, got: :oops! (in options [:producer, :rate_limiting])"
```

--------------------------------

### Declare compiled schema as module attribute with @options_schema

Source: https://nimble-options.hexdocs.pm/

Declares a module attribute that holds a compiled schema. Because new!/1 is called at compile time, the schema is validated once when the module is compiled, avoiding runtime schema validation.

```elixir
@options_schema NimbleOptions.new!([...])
```

--------------------------------

### t() type definition

Source: https://nimble-options.hexdocs.pm/

Defines the t() type as a NimbleOptions struct embedding a validated schema. Used after validation with new!/1.

```elixir
@type t() :: %NimbleOptions{schema: schema()}
```

--------------------------------

### option_typespec/1 spec

Source: https://nimble-options.hexdocs.pm/

Specification for the option_typespec/1 function, which returns a quoted typespec representing the type union for all possible keys in a schema. Nested keyword lists are spec'ed as keyword/0.

```elixir
@spec option_typespec(schema() | t()) :: Macro.t()
```
Tokens:
Raw