### NimbleOptions Validation Example

Source: https://hexdocs.pm/nimble_options/index.html

Demonstrates how NimbleOptions.validate/2 works by providing a configuration and a schema, and showing the resulting validation error.

```APIDOC
## NimbleOptions.validate/2 Example

### Description
This example shows how to use `NimbleOptions.validate/2` to validate a configuration against a defined schema. It highlights the error handling when the provided configuration does not match the schema.

### Method
`validate/2`

### Endpoint
N/A (Elixir function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**config** (keyword list) - The configuration options to validate.
**schema** (keyword list) - The schema defining the expected structure and types of the options.

### Request Example
```elixir
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)
```

### Response
#### Success Response (200)
`{:ok, validated_options}` - If the configuration is valid.

#### Error Response
`{:error, %NimbleOptions.ValidationError{}}` - If the configuration is invalid.

#### Response Example
```elixir
"invalid value for :interval option: expected positive integer, got: :oops! (in options [:producer, :rate_limiting])"
```
```

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

### Validate Configuration with Schema

Source: https://hexdocs.pm/nimble_options/index.html

Demonstrates validating a configuration against a defined schema. This example shows an invalid configuration that results in a validation error.

```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])"copy
```

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

### Validate Configuration with Schema

Source: https://hexdocs.pm/nimble_options/index.html

Demonstrates validating a configuration against a defined schema using NimbleOptions.validate. This example shows how a missing required option results in a validation error.

```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])"copy
```

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

### Generate Option Typespec

Source: https://hexdocs.pm/nimble_options/index.html

Use `option_typespec/1` to get a quoted typespec for an option schema. You must use `unquote/1` to embed this in your own typespecs.

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

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

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

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

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

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

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

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

### Injecting Schema Documentation into Docstrings

Source: https://hexdocs.pm/nimble_options/index.html

Shows how to use `NimbleOptions.docs/1` to dynamically generate documentation for an option schema and embed it within a module's docstring.

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

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

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

### NimbleOptions Schema Compilation

Source: https://hexdocs.pm/nimble_options/index.html

Illustrates how to pre-compile a schema using `NimbleOptions.new!/1` for compile-time validation and runtime efficiency.

```APIDOC
## NimbleOptions.new!/1 Example

### Description
This example demonstrates the use of `NimbleOptions.new!/1` to validate a schema at compile time. This pre-compiled schema can then be used with `NimbleOptions.validate/2` for more efficient runtime validation.

### Method
`new!/1`

### Endpoint
N/A (Elixir function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**schema** (keyword list) - The raw schema definition.

### Request Example
```elixir
raw_schema = [
  hostname: [
    required: true,
    type: :string
  ]
]

schema = NimbleOptions.new!(raw_schema)
NimbleOptions.validate([hostname: "elixir-lang.org"], schema)
```

### Response
#### Success Response (200)
`t()` - A compiled schema struct (`%NimbleOptions{}`) that can be used with `validate/2`.

#### Response Example
```elixir
{:ok, hostname: "elixir-lang.org"}
```
```

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

### Documenting Nested Schemas with Nesting Level

Source: https://hexdocs.pm/nimble_options/index.html

Illustrates how to document nested schemas by increasing the nesting level using the `nest_level` option in `NimbleOptions.docs/2`. This is useful for organizing documentation of complex configurations.

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

```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]
]copy
```

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

### NimbleOptions Functions

Source: https://hexdocs.pm/nimble_options/index.html

Provides an overview of the main functions available in the NimbleOptions module.

```APIDOC
## NimbleOptions Functions

### Description
This section outlines the primary functions provided by the `NimbleOptions` module for schema validation and documentation generation.

### Functions

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

*   **Description**: Returns documentation for the given schema. Useful for generating docstrings.
*   **Parameters**: 
    *   `schema` (schema() | t()) - The schema or compiled schema struct.
    *   `options` (keyword list) - Options to control documentation generation, such as `:nest_level`.
*   **Returns**: `String.t()` - The generated documentation string.

#### `new!(schema)`

*   **Description**: Validates the given `schema` and returns a compiled schema struct (`t()`) for efficient use with `validate/2`. Raises `NimbleOptions.ValidationError` if the schema is invalid.
*   **Parameters**: 
    *   `schema` (schema()) - The raw schema definition.
*   **Returns**: `t()` - A compiled schema struct.

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

*   **Description**: Validates the given `options` against the provided `schema`. Returns `{:ok, validated_options}` on success or `{:error, %NimbleOptions.ValidationError{}}` on failure.
*   **Parameters**: 
    *   `options` (keyword list) - The options to validate.
    *   `schema` (schema() | t()) - The schema or compiled schema struct.
*   **Returns**: `{:ok, keyword_list()} | {:error, %NimbleOptions.ValidationError{}}`

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

*   **Description**: Validates the given `options` against the provided `schema`. Raises `NimbleOptions.ValidationError` if the options are invalid.
*   **Parameters**: 
    *   `options` (keyword list) - The options to validate.
    *   `schema` (schema() | t()) - The schema or compiled schema struct.
*   **Returns**: `keyword_list()`
```

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

### Validate Options with Schema

Source: https://hexdocs.pm/nimble_options/index.html

Use `validate/2` to check if options conform to a schema. It returns `{:ok, validated_options}` on success or `{:error, validation_error}` on failure.

```elixir
@spec validate(keyword() | map(), schema() | t()) ::
  {:ok, validated_options :: keyword() | map()}
  | {:error, NimbleOptions.ValidationError.t()}
```

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

### Compile-Time Schema Validation with NimbleOptions.new!

Source: https://hexdocs.pm/nimble_options/index.html

Validates a schema once at compile time using `NimbleOptions.new!/1` for efficiency. The returned compiled schema can then be used for runtime validation.

```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"}copy
```

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

### Validate Options and Raise on Error

Source: https://hexdocs.pm/nimble_options/index.html

Use `validate!/2` to validate options against a schema. It returns the validated options directly or raises a `NimbleOptions.ValidationError` if validation fails.

```elixir
@spec validate!(keyword() | map(), schema() | t()) ::
  validated_options :: keyword() | map()
```

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

### validate!(options, schema)

Source: https://hexdocs.pm/nimble_options/index.html

Validates options against a schema and raises a `NimbleOptions.ValidationError` if validation fails. Returns the validated options directly on success.

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

### Description
Validates the given `options` with the given `schema` and raises if they're not valid. This function behaves exactly like `validate/2`, but returns the options directly if they're valid or raises a `NimbleOptions.ValidationError` exception otherwise.

### Method
Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
schema = [...
options = [...] # keyword() or map()
NimbleOptions.validate!(options, schema)
```

### Response
#### Success Response (200)
- **validated_options** (keyword() | map()) - The validated options.

#### Error Response
Raises `NimbleOptions.ValidationError` if validation fails.

#### Response Example
```elixir
validated_options
```

#### Error Example
```elixir
# Raises NimbleOptions.ValidationError
```
```

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

### validate(options, schema)

Source: https://hexdocs.pm/nimble_options/index.html

Validates a given set of options against a defined schema. Returns `{:ok, validated_options}` on success or `{:error, validation_error}` on failure.

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

### Description
Validates the given `options` with the given `schema`. 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, validation_error}` where `validation_error` is a `NimbleOptions.ValidationError` struct explaining what's wrong with the options.

### Method
Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
schema = [...
options = [...] # keyword() or map()
NimbleOptions.validate(options, schema)
```

### Response
#### Success Response (200)
- **validated_options** (keyword() | map()) - The validated options.

#### Error Response
- **validation_error** (NimbleOptions.ValidationError.t()) - A struct explaining the validation error.

#### Response Example
```elixir
{:ok, validated_options}
```

#### Error Example
```elixir
{:error, %NimbleOptions.ValidationError{...}}
```
```

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

### option_typespec(schema)

Source: https://hexdocs.pm/nimble_options/index.html

Generates a quoted typespec for options based on a given schema. This is useful for defining Elixir typespecs that accurately reflect the structure and types of your options.

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

### Method
Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

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

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

### Response
#### Success Response (200)
Returns a quoted Elixir typespec representing the option types.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.