Catalyst.PluginOptionParser (Catalyst v1.0.0-beta.0)

Copy Markdown View Source

Parses and validates plugin options using OptionParser-like semantics.

This module supports two primary flows:

  • parse/4: non-raising parse that returns {parsed, rest, invalid}
  • validate!/3: raising validation helper used by runtime planner code

Parsing mode is selected in this order:

  1. :strict passed to parse/4
  2. :switches passed to parse/4
  3. plugin opts_schema/0 when available
  4. permissive :switches mode when no schema is declared

Return Shape

parse/4 always returns a tuple in the shape:

{parsed_opts, [], invalid_entries}

Where:

  • parsed_opts is a keyword list of accepted options
  • [] is the rest slot kept for OptionParser-style compatibility
  • invalid_entries is a list of maps with a :kind key, for example:
    • %{kind: :unknown_option, ...}
    • %{kind: :invalid_type, ...}
    • %{kind: :missing_required, ...}
    • %{kind: :invalid_opts_type, ...}

Duplicate Options

By default, repeated keys are overwritten (last value wins). Use :keep in a rule to preserve repeated entries.

Errors

validate!/3 raises Catalyst.Errors.PluginError with reason :invalid_plugin_opts when parsing or schema validation fails.

Summary

Types

invalid_entry()
invalid_kind()
parse_result()
parsed()
parser_options()

Functions

parse(plugin_mod, opts, config, parser_opts \\ [])

Parses plugin options without raising.

validate!(plugin_mod, opts, config)

Validates plugin options and returns parsed options or raises.

Types

invalid_entry()

@type invalid_entry() :: %{:kind => invalid_kind(), optional(atom()) => any()}

invalid_kind()

@type invalid_kind() ::
  :unknown_option | :invalid_type | :missing_required | :invalid_opts_type

parse_result()

@type parse_result() :: {parsed(), [], [invalid_entry()]}

parsed()

@type parsed() :: keyword()

parser_options()

@type parser_options() :: [strict: keyword(), switches: keyword(), aliases: keyword()]

Functions

parse(plugin_mod, opts, config, parser_opts \\ [])

@spec parse(module(), keyword(), map(), parser_options()) :: parse_result()

Parses plugin options without raising.

Accepts raw plugin options, runs plugin init/2 normalization, applies aliases, and validates against strict or switches rules.

Parameters

  • plugin_mod: plugin module implementing init/2
  • opts: input keyword options
  • config: project/runtime config passed through to init/2
  • parser_opts: parser overrides such as strict:, switches:, aliases:

Returns

{parsed_opts, [], invalid_entries}

This function does not raise for unknown/type/required-option parse failures; they are returned in invalid_entries.

It may still raise Catalyst.Errors.PluginError if init/2 returns an invalid shape or if schema declaration itself is malformed.

validate!(plugin_mod, opts, config)

@spec validate!(module(), keyword(), map()) :: keyword()

Validates plugin options and returns parsed options or raises.

This is a strict helper around parse/4 that converts the first invalid parse entry into a Catalyst.Errors.PluginError.

Returns

  • parsed keyword options when validation succeeds

Raises

  • Catalyst.Errors.PluginError when options are invalid, missing required keys, contain unknown keys in strict mode, have invalid types, or are not a keyword list