# `MimeDescription`
[🔗](https://github.com/neilberkman/mime_description/blob/v0.12.0/lib/mime_description.ex#L1)

Human-friendly MIME type descriptions for Elixir.

This library provides embedded MIME type descriptions sourced from the 
freedesktop.org shared-mime-info database. The data is compiled directly
into the library, so no runtime fetching is required.

## Usage

    # Get description for a specific MIME type
    MimeDescription.get("application/pdf")
    #=> {:ok, "PDF document"}

    # Handle MIME types with parameters (charset, boundary, etc.)
    MimeDescription.get_from_header("text/plain; charset=utf-8")
    #=> {:ok, "Plain text document"}

    # Get description with fallback
    MimeDescription.get("unknown/type")
    #=> {:error, :not_found}

## Updating the MIME database

The MIME data is embedded at compile time. To update it with the latest
from freedesktop.org, run:

    mix mime_description.generate

This task will check if the remote database has changed and regenerate
the embedded data module if needed.

# `extract_mime_type`

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

Extract the base MIME type from a header value, removing any parameters.

## Examples

    iex> MimeDescription.extract_mime_type("text/plain; charset=utf-8")
    "text/plain"

    iex> MimeDescription.extract_mime_type("application/pdf;name=document.pdf")
    "application/pdf"

    iex> MimeDescription.extract_mime_type("  text/html ; charset=ISO-8859-1  ")
    "text/html"

# `get`

```elixir
@spec get(String.t()) :: {:ok, String.t()} | {:error, :not_found}
```

Get the human-friendly description for a MIME type.

Returns `{:ok, description}` if found, or `{:error, :not_found}` if not found.

## Examples

    iex> MimeDescription.get("application/pdf")
    {:ok, "PDF document"}

    iex> MimeDescription.get("text/plain")
    {:ok, "Plain text document"}

    iex> MimeDescription.get("unknown/type")
    {:error, :not_found}

# `get!`

```elixir
@spec get!(String.t()) :: String.t()
```

Get the human-friendly description for a MIME type, raising if not found.

## Examples

    iex> MimeDescription.get!("application/pdf")
    "PDF document"

    iex> MimeDescription.get!("unknown/type")
    ** (KeyError) MIME type not found: "unknown/type"

# `get_from_header`

```elixir
@spec get_from_header(String.t()) :: {:ok, String.t()} | {:error, :not_found}
```

Get the human-friendly description for a MIME type from a raw header value.

This function handles MIME types that may include parameters like charset,
boundary, etc. It extracts the base MIME type and looks up its description.

## Examples

    iex> MimeDescription.get_from_header("text/plain; charset=utf-8")
    {:ok, "Plain text document"}

    iex> MimeDescription.get_from_header("application/pdf; name=document.pdf")
    {:ok, "PDF document"}

    iex> MimeDescription.get_from_header("text/html;charset=ISO-8859-1")
    {:ok, "HTML document"}

    iex> MimeDescription.get_from_header("multipart/form-data; boundary=----WebKitFormBoundary")
    {:ok, "multipart message"}

    iex> MimeDescription.get_from_header("unknown/type; param=value")
    {:error, :not_found}

# `get_from_header_with_fallback`

```elixir
@spec get_from_header_with_fallback(String.t(), String.t() | nil) :: String.t()
```

Get the human-friendly description for a MIME type from a raw header value,
returning the cleaned MIME type as a fallback if not found.

This is useful when you want to display something reasonable even for unknown types.

## Examples

    iex> MimeDescription.get_from_header_with_fallback("text/plain; charset=utf-8")
    "Plain text document"

    iex> MimeDescription.get_from_header_with_fallback("application/x-custom; param=value")
    "application/x-custom"

    iex> MimeDescription.get_from_header_with_fallback("unknown/type; charset=utf-8", "Unknown file")
    "Unknown file"

# `get_with_default`

```elixir
@spec get_with_default(String.t(), String.t()) :: String.t()
```

Get the description for a MIME type with a default fallback.

## Examples

    iex> MimeDescription.get_with_default("application/pdf", "Unknown")
    "PDF document"

    iex> MimeDescription.get_with_default("unknown/type", "Unknown")
    "Unknown"

---

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