MagicMime (magic_mime v0.1.0)

Fast and secure MIME type detection using the system's file command.

This library provides a safe interface to detect MIME types for files without requiring NIFs or external dependencies (other than the system's file command).

Examples

iex> {:ok, mime_type} = MagicMime.detect("mix.exs")
iex> String.starts_with?(mime_type, "text/")
true

iex> mime_type = MagicMime.detect!("mix.exs")
iex> String.starts_with?(mime_type, "text/")
true

iex> results = MagicMime.detect_many(["mix.exs", "README.md"])
iex> Enum.all?(results, fn {_path, {:ok, mime_type}} -> String.starts_with?(mime_type, "text/") end)
true

Requirements

This library requires the file command to be available on the system. It's pre-installed on most Unix-like systems (Linux, macOS, etc.).

Note: Windows is not supported.

Summary

Functions

Detects the MIME type of a file.

Detects the MIME type of a file, raising an exception on failure.

Detects MIME types for multiple files in parallel.

Checks if MIME type detection is supported on this system.

Returns the version of the file command.

Types

error_reason()

@type error_reason() :: atom() | {atom(), term()} | {atom(), term(), term()}

mime_type()

@type mime_type() :: String.t()

path()

@type path() :: Path.t()

Functions

detect(path, opts \\ [])

@spec detect(
  path(),
  keyword()
) :: {:ok, mime_type()} | {:error, error_reason()}

Detects the MIME type of a file.

Returns {:ok, mime_type} on success, or {:error, reason} on failure.

Options

  • :command_executor - Custom command executor for dependency injection
  • :file_system - Custom file system for dependency injection

Examples

iex> {:ok, mime_type} = MagicMime.detect("mix.exs")
iex> String.starts_with?(mime_type, "text/")
true

iex> MagicMime.detect("nonexistent.file")
{:error, :enoent}

Error Types

  • :file_command_not_found - The file command is not available
  • :enoent - File does not exist
  • :eacces - Permission denied
  • {:command_error, exit_code, stderr} - Command execution failed

detect!(path, opts \\ [])

@spec detect!(
  path(),
  keyword()
) :: mime_type() | no_return()

Detects the MIME type of a file, raising an exception on failure.

Returns the MIME type as a string on success, or raises MagicMime.Error on failure.

Options

  • :command_executor - Custom command executor for dependency injection
  • :file_system - Custom file system for dependency injection

Examples

iex> mime_type = MagicMime.detect!("mix.exs")
iex> String.starts_with?(mime_type, "text/")
true

iex> MagicMime.detect!("nonexistent.file")
** (MagicMime.Error) File does not exist: nonexistent.file

detect_many(paths, opts \\ [])

@spec detect_many(
  [path()],
  keyword()
) :: [{path(), {:ok, mime_type()} | {:error, error_reason()}}]

Detects MIME types for multiple files in parallel.

Returns a list of tuples containing the file path and the result ({:ok, mime_type} or {:error, reason}).

Options

  • :concurrency - Number of concurrent tasks (default: System.schedulers_online())
  • :command_executor - Custom command executor for dependency injection
  • :file_system - Custom file system for dependency injection

Examples

iex> results = MagicMime.detect_many(["mix.exs", "README.md"])
iex> Enum.all?(results, fn {_path, {:ok, mime_type}} -> String.starts_with?(mime_type, "text/") end)
true

iex> results = MagicMime.detect_many(["mix.exs", "README.md"], concurrency: 2)
iex> Enum.all?(results, fn {_path, {:ok, mime_type}} -> String.starts_with?(mime_type, "text/") end)
true

mime_supported?(opts \\ [])

@spec mime_supported?(keyword()) :: boolean()

Checks if MIME type detection is supported on this system.

Returns true if the file command is available, false otherwise.

Options

  • :command_executor - Custom command executor for dependency injection

Examples

iex> MagicMime.mime_supported?()
true

version(opts \\ [])

@spec version(keyword()) :: {:ok, String.t()} | {:error, error_reason()}

Returns the version of the file command.

Returns {:ok, version} on success, or {:error, reason} on failure.

Options

  • :command_executor - Custom command executor for dependency injection

Examples

iex> {:ok, version} = MagicMime.version()
iex> is_binary(version)
true

iex> {:ok, version} = MagicMime.version()
iex> is_binary(version)
true