Metastatic.Languages (Metastatic v0.33.0)

View Source

Single source of truth for supported languages and their adapters.

All language detection, validation, and adapter lookup throughout the codebase should go through this module. Adding support for a new language requires only adding a single entry to @adapters here (assuming the adapter module already exists and implements Metastatic.Adapter).

Compile-Time Derivation

Extension maps, supported language lists, and display strings are all derived at compile time from the @adapters map and each adapter's file_extensions/0 callback, so they stay in sync automatically.

Examples

iex> Metastatic.Languages.supported?(:python)
true

iex> Metastatic.Languages.supported?(:brainfuck)
false

iex> {:ok, :ruby} = Metastatic.Languages.detect_language("app.rb")

iex> {:ok, Metastatic.Adapters.Python} = Metastatic.Languages.get_adapter(:python)

Summary

Functions

adapters()

Returns the map of all adapters (language atom => module).

detect_language(path)

Detects language from a file path based on its extension.

experimental?(language)

Checks whether a language is experimental.

experimental_languages()

Returns the list of languages whose adapters are considered experimental.

extension_for_language(language)

Returns the primary file extension for a language.

get_adapter(language)

Returns the adapter module for a supported language.

parse_language(lang_str)

Parses a language string (e.g. from CLI --language option) into an atom.

supported?(language)

Checks whether a language atom is supported.

supported_extensions()

Returns all supported file extensions.

supported_languages()

Returns the list of supported language atoms, sorted alphabetically.

supported_languages_string()

Returns a comma-separated string of supported language names.

Functions

adapters()

@spec adapters() :: %{required(atom()) => module()}

Returns the map of all adapters (language atom => module).

Examples

iex> adapters = Metastatic.Languages.adapters()
iex> Map.has_key?(adapters, :python)
true

detect_language(path)

@spec detect_language(String.t()) :: {:ok, atom()} | {:error, String.t()}

Detects language from a file path based on its extension.

Examples

iex> Metastatic.Languages.detect_language("script.py")
{:ok, :python}

iex> Metastatic.Languages.detect_language("app.rb")
{:ok, :ruby}

iex> Metastatic.Languages.detect_language("unknown.xyz")
{:error, "Cannot detect language from extension: .xyz"}

experimental?(language)

@spec experimental?(atom()) :: boolean()

Checks whether a language is experimental.

Examples

iex> Metastatic.Languages.experimental?(:haskell)
true

iex> Metastatic.Languages.experimental?(:elixir)
false

experimental_languages()

@spec experimental_languages() :: [atom()]

Returns the list of languages whose adapters are considered experimental.

Experimental adapters require an external toolchain (GHC/Agda) that is not part of the default CI matrix. They are functional but not covered by the default test run.

Examples

iex> :agda in Metastatic.Languages.experimental_languages()
true

iex> :python in Metastatic.Languages.experimental_languages()
false

extension_for_language(language)

@spec extension_for_language(atom()) :: {:ok, String.t()} | {:error, String.t()}

Returns the primary file extension for a language.

Examples

iex> Metastatic.Languages.extension_for_language(:python)
{:ok, ".py"}

iex> Metastatic.Languages.extension_for_language(:unknown)
{:error, "No extension known for language: unknown"}

get_adapter(language)

@spec get_adapter(atom()) :: {:ok, module()} | {:error, String.t()}

Returns the adapter module for a supported language.

Examples

iex> Metastatic.Languages.get_adapter(:python)
{:ok, Metastatic.Adapters.Python}

iex> Metastatic.Languages.get_adapter(:unknown)
{:error, "Unsupported language: unknown. Supported: elixir, erlang, haskell, python, ruby"}

parse_language(lang_str)

@spec parse_language(String.t() | nil) :: {:ok, atom()} | {:error, String.t()} | :none

Parses a language string (e.g. from CLI --language option) into an atom.

Return contract

This function has three outcomes, each documented explicitly:

  • {:ok, atom} — a supported language
  • {:error, message} — an unknown/unsupported language
  • :none — the input was nil (no language specified; caller should auto-detect). This replaces the historical nil return so that the "not specified" case is distinguishable from a value that failed to parse and is never confused with a language atom.

Examples

iex> Metastatic.Languages.parse_language("python")
{:ok, :python}

iex> Metastatic.Languages.parse_language("Ruby")
{:ok, :ruby}

iex> Metastatic.Languages.parse_language(nil)
:none

iex> Metastatic.Languages.parse_language("brainfuck")
{:error, "Invalid language: brainfuck. Supported: elixir, erlang, haskell, python, ruby"}

supported?(language)

@spec supported?(atom()) :: boolean()

Checks whether a language atom is supported.

Examples

iex> Metastatic.Languages.supported?(:python)
true

iex> Metastatic.Languages.supported?(:brainfuck)
false

supported_extensions()

@spec supported_extensions() :: [String.t()]

Returns all supported file extensions.

Examples

iex> ".py" in Metastatic.Languages.supported_extensions()
true

supported_languages()

@spec supported_languages() :: [atom()]

Returns the list of supported language atoms, sorted alphabetically.

Examples

iex> Metastatic.Languages.supported_languages()
[:elixir, :erlang, :haskell, :python, :ruby]

supported_languages_string()

@spec supported_languages_string() :: String.t()

Returns a comma-separated string of supported language names.

Useful for error messages and help text.

Examples

iex> Metastatic.Languages.supported_languages_string()
"elixir, erlang, haskell, python, ruby"