# `OCSF.EventCodeFormat`
[🔗](https://github.com/docjerem/ocsf/blob/v0.1.0/lib/ocsf/event_code_format.ex#L1)

Format-driven `metadata.event_code` generation.

Derives a human-readable event code from existing OCSF field values.
No parallel taxonomy is introduced — `event_code` is a convenience
projection for SIEM search, log grep, and dashboards.

## Example

    format = OCSF.EventCodeFormat.get(:default)
    OCSF.EventCodeFormat.generate(format, event)
    #=> "authentication:magic_link:logon"

See `EVENT_CODE_FORMAT_CONFIG_SPEC.md` for the full specification.

See `OCSF.Events.Authentication` for how builders integrate with
event code generation.

# `t`

```elixir
@type t() :: %OCSF.EventCodeFormat{fields: [[atom()]], separator: String.t()}
```

# `default_format`

```elixir
@spec default_format() :: atom() | nil
```

Return the configured default format name, or `nil`.

# `generate`

```elixir
@spec generate(t(), OCSF.Event.t()) :: String.t() | nil
```

Generate an event code from a format and an event.

Returns `nil` if all field paths resolve to nil/empty.

## Examples

    iex> format = %OCSF.EventCodeFormat{
    ...>   fields: [[:class_name], [:activity_name]],
    ...>   separator: ":"
    ...> }
    iex> event = %OCSF.Event{class_uid: 3002, activity_id: 1,
    ...>   category_uid: 3, type_uid: 300201, severity_id: 1, status_id: 1,
    ...>   time: ~U[2026-04-15 10:00:00Z],
    ...>   metadata: %OCSF.Metadata{uid: "x", version: "1.8.0",
    ...>     product: %OCSF.Product{name: "T"}},
    ...>   user: %OCSF.User{uid: "u"}}
    iex> OCSF.EventCodeFormat.generate(format, event)
    "authentication:logon"

# `get`

```elixir
@spec get(atom()) :: t() | nil
```

Retrieve a named format from application config.

Reads from `config :ocsf, event_code: [formats: %{name => opts}]`.
Returns `nil` if the format is not configured.

## Examples

    iex> OCSF.EventCodeFormat.get(:nonexistent)
    nil

# `normalize`

```elixir
@spec normalize(String.t()) :: String.t()
```

Normalize a string value for use in an event code.

Trims whitespace, lowercases, replaces non-alphanumeric characters
with `_`, collapses consecutive `_`, and strips leading/trailing `_`.

## Examples

    iex> OCSF.EventCodeFormat.normalize("Authentication")
    "authentication"

    iex> OCSF.EventCodeFormat.normalize("Magic Link")
    "magic_link"

    iex> OCSF.EventCodeFormat.normalize("User-Login!")
    "user_login"

---

*Consult [api-reference.md](api-reference.md) for complete listing*