type_check.ex

defmodule TypeCheck do
  require TypeCheck.Type

  @moduledoc """
  Fast and flexible runtime type-checking.

  The main way to use TypeCheck is by adding `use TypeCheck` in your modules.
  This will allow you to use the macros of `TypeCheck.Macros` in your module,
  which are versions of the normal type-specification module attributes
  with an extra exclamation mark at the end:  `@type!`, `@spec!`, `@typep!` and `@opaque!`.


  It will also bring all functions in `TypeCheck.Builtin` in scope,
  which is usually what you want as this allows you to
  use all types and special syntax that are built-in to Elixir
  in the TypeCheck specifications.


  Using these, you're able to add function-specifications to your functions
  which will wrap them with runtime type-checks.
  You'll also be able to create your own type-specifications that can be used
  in other type- and function-specifications in the same or other modules later on:

      defmodule User do
        use TypeCheck
        defstruct [:name, :age]
        @type! age :: non_neg_integer()
        @type! t :: %User{name: binary(), age: age()}

        @spec! new(binary(), age()) :: t()
        def new(name, age) do
          %User{name: name, age: age}
        end

        @spec! old_enough?(t(), age()) :: boolean()
        def old_enough?(user, limit) do
          user.age >= limit
        end
      end

  Finally, you can test whether your functions correctly adhere to their specs,
  by adding a `spectest` in your testing suite. See `TypeCheck.ExUnit.spectest/2` for details.

  ## Types and their syntax

  TypeCheck allows types written using (essentially) the same syntax as [Elixir's builtin typespecs](https://hexdocs.pm/elixir/typespecs.html#types-and-their-syntax).
  This means the following:

  - literal values like `:ok`, `10.0` or `"my string"` desugar to a call to `TypeCheck.Builtin.literal/1`, which is a type that matches only exactly that value.
  - Basic types like `integer()`, `float()`, `atom()` etc. are directly supported (and exist as functions in `TypeCheck.Builtin`).
  - tuples of types like `{atom(), integer()}` are supported (and desugar to `TypeCheck.Builtin.fixed_tuple/1`)
  - maps where keys are literal values and the values are types like `%{a: integer(), b: integer(), 42 => float()}` desugar to calls to `TypeCheck.Builtin.fixed_map/1`.
    - The same happens with structs like `%User{name: binary(), age: non_neg_integer()}`
  - sum types like `integer() | string() | atom()` are supported, and desugar to calls to `TypeCheck.Builtin.one_of/1`.
  - Ranges like `lower..higher` are supported, matching integers within the given range. This desugars into a call to `TypeCheck.Builtin.range/1`.

  ### Currently unsupported features

  The following typespec syntax can _not_ currently be used in TypeCheck. This will hopefully change in future versions of the library.

  - Literal maps with `required(...)` and `optional(...)` keys. (TypeCheck does already support literal maps with a fixed set of keys, as well as maps with any number of key-value-pairs of fixed types. It is the special syntax that might mix these approaches that is not supported yet.)

  ### Extensions

  TypeCheck adds the following extensions on Elixir's builtin typespec syntax:


  - fixed-size lists containing types like `[1, 2, integer()]` are supported, and desugar to `TypeCheck.Builtin.fixed_list/1`.
    This example matches only lists of 3 elements where the first element is the literal `1`, the second the literal `2` and the last element any integer.
    Elixir's builtin typespecs do not support fixed-size lists.
  - named types like `x :: integer()` are supported; these are useful in combination with "type guards" (see the section below).
  - "type guards" using the syntax `some_type when arbitrary_code` are supported, to add extra arbitrary checks to a value for it to match the type. (See the section about type guards below.)
  - `lazy(some_type)`, which defers type-expansion until during runtime. This is required to be able to expand recursive types. C.f. `TypeCheck.Builtin.lazy/1`

  ## Named Types Type Guards

  To add extra custom checks to a type, you can use a so-called 'type guard'.
  This is arbitrary code that is executed during a type-check once the type itself already matches.

  You can use "named types" to refer to (parts of) the value that matched the type, and refer to these from a type-guard:

  ```
  type sorted_pair :: {lower :: number(), higher :: number()} when lower <= higher
  ```

      iex> TypeCheck.conforms!({10, 20}, sorted_pair)
      {10, 20}
      iex> TypeCheck.conforms!({20, 10}, sorted_pair)
      ** (TypeCheck.TypeError) `{20, 10}` does not match the definition of the named type `TypeCheckTest.TypeGuardExample.sorted_pair`
          which is: `TypeCheckTest.TypeGuardExample.sorted_pair
          ::
          (sorted_pair :: {lower :: number(), higher :: number()} when lower <= higher)`. Reason:
            `{20, 10}` does not check against `(sorted_pair :: {lower :: number(), higher :: number()} when lower <= higher)`. Reason:
              type guard:
                `lower <= higher` evaluated to false or nil.
                bound values: %{higher: 10, lower: 20, sorted_pair: {20, 10}}

  Named types are available in your guard even from the (both local and remote) types that you are using in your time, as long as those types are not defined as _opaque_ types.


  ## Manual type-checking

  If you want to check values against a type _outside_ of the checks the `@spec!` macro
  wraps a function with,
  you can use the `conforms/2`/`conforms?/2`/`conforms!/2` macros in this module directly in your code.

  These are evaluated _at compile time_ which means the resulting checks will be optimized by the compiler.
  Unfortunately it also means that the types passed to them have to be known at compile time.

  If you have a type that is constructed dynamically at runtime, you can resort to
  `dynamic_conforms/2` and variants.
  Because these variants have to evaluate the type-checking code at runtime,
  these checks are not optimized by the compiler.

  ### Introspection

  To allow checking what types and specs exist,
  the introspection function `__type_check__/1` will be added to a module when `use TypeCheck` is used.

  - `YourModule.__type_check__(:types)` returns a keyword list of all `{type_name, arity}`
    pairs for all types defined in the module using `@type!`/`@typep!` or `@opaque!`.
  - `YourModule.__type_check__(:specs)` returns a keyword list of all `{function_name, arity}`
    pairs for all functions in the module wrapped with a spec using `@spec!`.

  Note that these lists might also contain private types / private function names.
  """

  defmacro __using__(options) do
    case __CALLER__.module do
      nil ->
        quote generated: true, location: :keep do
          require TypeCheck
          require TypeCheck.Type
          import TypeCheck.Builtin
          :ok
        end

      _other ->
        type_require =
          if __CALLER__.module == TypeCheck.Type do
            :ok
          else
            quote do: require(TypeCheck.Type)
          end

        builtin_import =
          if __CALLER__.module == TypeCheck.Builtin do
            :ok
          else
            quote do: import(TypeCheck.Builtin)
          end

        quote generated: true, location: :keep do
          use TypeCheck.Macros, unquote(options)
          require TypeCheck
          unquote(type_require)
          unquote(builtin_import)
          :ok
        end
    end
  end

  @doc """
  Makes sure `value` typechecks the type description `type`.

  If it typechecks, we return `{:ok, value}`
  Otherwise, we return `{:error, %TypeCheck.TypeError{}}` which contains information
  about why the value failed the check.

  `conforms` is a macro and expands the type check at compile-time,
  allowing it to be optimized by the compiler.

  C.f. `TypeCheck.Type.build/1` for more information on what type-expressions
  are allowed as `type` parameter.

  Note: _usually_ you'll want to `import TypeCheck.Builtin` in the context where you use `conforms`,
  which will bring Elixir's builtin types into scope.
  (Calling `use TypeCheck` will already do this; see the module documentation of `TypeCheck` for more information))
  """
  @type value :: any()
  # Note: Below spec highlights how the macro functions when it is _used_:
  @spec conforms(value, TypeCheck.Type.expandable_type()) ::
          {:ok, value} | {:error, TypeCheck.TypeError.t()}
  defmacro conforms(value, type, options \\ Macro.escape(TypeCheck.Options.new())) do
    {evaluated_options, _} = Code.eval_quoted(options, [], __CALLER__)

    evaluated_options = TypeCheck.Options.new(evaluated_options)
    type = TypeCheck.Type.build_unescaped(type, __CALLER__, evaluated_options)
    check = TypeCheck.Protocols.ToCheck.to_check(type, value)

    res =
      quote generated: true, location: :keep do
        case unquote(check) do
          {:ok, bindings, altered_value} ->
            {:ok, altered_value}

          {:error, problem} ->
            exception =
              TypeCheck.TypeError.exception({problem, unquote(Macro.Env.location(__CALLER__))})

            {:error, exception}
        end
      end

    if(evaluated_options.debug) do
      value_str = value |> Macro.to_string() |> Code.format_string!()

      TypeCheck.Internals.Helper.prettyprint_spec(
        "TypeCheck.conforms(#{value_str}, #{inspect(type)}, #{inspect(options)})",
        res
      )
    end

    res
  end

  @doc """
  Similar to `conforms/2`, but returns `true` if the value typechecked and `false` if it did not.

  The same features and restrictions apply to this function as to `conforms/2`.
  """
  @spec conforms?(value, TypeCheck.Type.expandable_type()) :: boolean()
  defmacro conforms?(value, type, options \\ Macro.escape(TypeCheck.Options.new())) do
    {evaluated_options, _} = Code.eval_quoted(options, [], __CALLER__)

    evaluated_options = TypeCheck.Options.new(evaluated_options)
    type = TypeCheck.Type.build_unescaped(type, __CALLER__, evaluated_options)
    check = TypeCheck.Protocols.ToCheck.to_check(type, value)

    res =
      quote generated: true, location: :keep do
        match?({:ok, _, _}, unquote(check))
      end

    if(evaluated_options.debug) do
      value_str = value |> Macro.to_string() |> Code.format_string!()

      TypeCheck.Internals.Helper.prettyprint_spec(
        "TypeCheck.conforms?(#{value_str}, #{inspect(type)}, #{inspect(options)})",
        res
      )
    end

    res
  end

  @doc """
  Similar to `conforms/2`, but returns `value` if the value typechecked and raises TypeCheck.TypeError if it did not.

  The same features and restrictions apply to this function as to `conforms/2`.
  """
  @spec conforms!(value, TypeCheck.Type.expandable_type()) :: value | no_return()
  defmacro conforms!(value, type, options \\ Macro.escape(TypeCheck.Options.new())) do
    {evaluated_options, _} = Code.eval_quoted(options, [], __CALLER__)

    evaluated_options = TypeCheck.Options.new(evaluated_options)
    type = TypeCheck.Type.build_unescaped(type, __CALLER__, evaluated_options)
    check = TypeCheck.Protocols.ToCheck.to_check(type, value)

    res =
      quote generated: true, location: :keep do
        case unquote(check) do
          {:ok, _bindings, altered_value} -> altered_value
          {:error, other} -> raise TypeCheck.TypeError, other
        end
      end

    if(evaluated_options.debug) do
      value_str = value |> Macro.to_string() |> Code.format_string!()

      TypeCheck.Internals.Helper.prettyprint_spec(
        "TypeCheck.conforms!(#{value_str}, #{inspect(type)}, #{inspect(options)})",
        res
      )
    end

    res
  end

  @doc """

  Makes sure `value` typechecks the type `type`. Evaluated _at runtime_.

  Because `dynamic_conforms/2` is evaluated at runtime:

  1. The typecheck cannot be optimized by the compiler, which makes it slower.

  2. You must pass an already-expanded type as `type`.
     This can be done by using one of your custom types directly (e.g. `YourModule.typename()`),
     or by calling `TypeCheck.Type.build`.

  Use `dynamic_conforms` only when you cannot use the normal `conforms/2`,
  for instance when you're only able to construct the type to check against at runtime.

      iex> forty_two = TypeCheck.Type.build(42)
      iex> TypeCheck.dynamic_conforms(42, forty_two)
      {:ok, 42}
      iex> {:error, type_error} = TypeCheck.dynamic_conforms(20, forty_two)
      iex> type_error.message =~ "`20` is not the same value as `42`."
      true
  """
  @spec dynamic_conforms(value, TypeCheck.Type.t()) ::
          {:ok, value} | {:error, TypeCheck.TypeError.t()}
  def dynamic_conforms(value, type, options \\ TypeCheck.Options.new()) do
    evaluated_options = TypeCheck.Options.new(options)
    check_code = TypeCheck.Protocols.ToCheck.to_check(type, Macro.var(:value, nil))

    if(evaluated_options.debug) do
      TypeCheck.Internals.Helper.prettyprint_spec(
        "TypeCheck.dynamic_conforms(#{inspect(value)}, #{inspect(type)}, #{inspect(options)})",
        check_code
      )
    end

    case Code.eval_quoted(check_code, value: value) do
      {{:ok, _, altered_value}, _} ->
        {:ok, altered_value}

      {{:error, problem}, _} ->
        {:current_stacktrace, [_, _, caller | _]} = Process.info(self(), :current_stacktrace)
        location = elem(caller, 3)
        location = update_in(location[:file], &to_string/1)
        exception = TypeCheck.TypeError.exception({problem, location})
        {:error, exception}
    end
  end

  @doc """
  Similar to `dynamic_conforms/2`, but returns `true` if the value typechecked and `false` if it did not.

  The same features and restrictions apply to this function as to `dynamic_conforms/2`.


      iex> forty_two = TypeCheck.Type.build(42)
      iex> TypeCheck.dynamic_conforms?(42, forty_two)
      true
      iex> TypeCheck.dynamic_conforms?(20, forty_two)
      false
  """
  @spec dynamic_conforms?(value, TypeCheck.Type.t()) :: boolean
  def dynamic_conforms?(value, type, options \\ TypeCheck.Options.new()) do
    case dynamic_conforms(value, type, options) do
      {:ok, _value} -> true
      _other -> false
    end
  end

  @doc """
  Similar to `dynamic_conforms/2`, but returns `value` if the value typechecked and raises TypeCheck.TypeError if it did not.

  The same features and restrictions apply to this function as to `dynamic_conforms/2`.

      iex> forty_two = TypeCheck.Type.build(42)
      iex> TypeCheck.dynamic_conforms!(42, forty_two)
      42
      iex> TypeCheck.dynamic_conforms!(20, forty_two)
      ** (TypeCheck.TypeError) At lib/type_check.ex:362:
          `20` is not the same value as `42`.
  """
  @spec dynamic_conforms!(value, TypeCheck.Type.t()) :: value | no_return()
  def dynamic_conforms!(value, type, options \\ TypeCheck.Options.new()) do
    case dynamic_conforms(value, type, options) do
      {:ok, value} -> value
      {:error, exception} -> raise exception
    end
  end
end