defmodule CljElixir do
  @moduledoc "CljElixir: Clojure-syntax language for the BEAM"

  @doc """
  Compile a CljElixir source string to Elixir AST.

  Returns `{:ok, elixir_ast}` on success, or `{:error, diagnostics}` on failure.

  ## Options

    * `:file` - the file path for error reporting (default: `"nofile"`)

  ## Examples

      iex> CljElixir.compile_string("(+ 1 2)")
      {:ok, {:+, [line: 1], [1, 2]}}

  """
  @spec compile_string(String.t(), keyword()) :: {:ok, term()} | {:error, list()}
  def compile_string(source, opts \\ []) do
    CljElixir.Compiler.compile_string(source, opts)
  end

  @doc """
  Compile a `.clje` file to Elixir AST.

  Reads the file and delegates to `compile_string/2` with the `:file` option set.

  Returns `{:ok, elixir_ast}` on success, or `{:error, diagnostics}` on failure.
  Raises `File.Error` if the file cannot be read.
  """
  @spec compile_file(Path.t(), keyword()) :: {:ok, term()} | {:error, list()}
  def compile_file(path, opts \\ []) do
    CljElixir.Compiler.compile_file(path, opts)
  end

  @doc """
  Compile and evaluate a CljElixir source string.

  Returns `{:ok, result, bindings}` on success, or `{:error, diagnostics}` on failure.

  ## Options

    * `:file` - the file path for error reporting (default: `"nofile"`)
    * `:bindings` - variable bindings for evaluation (default: `[]`)
    * `:env` - the macro environment for evaluation (default: `__ENV__`)

  ## Examples

      iex> CljElixir.eval_string("(+ 1 2)")
      {:ok, 3, []}

  """
  @spec eval_string(String.t(), keyword()) :: {:ok, term(), keyword()} | {:error, list()}
  def eval_string(source, opts \\ []) do
    CljElixir.Compiler.eval_string(source, opts)
  end

  @doc """
  Compile and evaluate a `.clje` file.

  Reads the file and delegates to `eval_string/2` with the `:file` option set.

  Returns `{:ok, result, bindings}` on success, or `{:error, diagnostics}` on failure.
  Raises `File.Error` if the file cannot be read.
  """
  @spec eval_file(Path.t(), keyword()) :: {:ok, term(), keyword()} | {:error, list()}
  def eval_file(path, opts \\ []) do
    CljElixir.Compiler.eval_file(path, opts)
  end
end