Croma

Elixir macro utilities.

• API Documentation
• Hex package information

Usage

• Add :croma as a mix dependency.
• $ mix deps.get
• Add use Croma to import macros defined in this package.
• Hack!

Defining functions

Croma.Defpt.defpt

• Unit-testable defp that is simply converted to
  • def if Mix.env == :test,
  • defp otherwise.

Croma.Defun

• Type specification oriented function definition

  • Example 1

    import Croma.Defun
    defun f(a: integer, b: String.t) :: String.t do
      "#{a} #{b}"
    end
    

  is expanded to ex @spec f(integer, String.t) :: String.t def f(a, b) do "#{a} #{b}" end

  • Example 2

    import Croma.Defun
    defun dumbmap(as: [a], f: (a -> b)) :: [b] when a: term, b: term do
      ([]     , _) -> []
      ([h | t], f) -> [f.(h) | dumbmap(t, f)]
    end
    

  is expanded to ex @spec dumbmap([a], (a -> b)) :: [b] when a: term, b: term def dumbmap(as, f) def dumbmap([], _) do [] end def dumbmap([h | t], f) do [f.(h) | dumbmap(t, f)] end
  • There are also defunp and defunpt macros for private functions.
  • Known limitations:
    • Pattern matching against function parameters should use (param1, param2) when guards -> block style.
    • Overloaded typespecs are not supported.

Croma.Monad

• An interface definition of the monad typeclass.

• Modules that use Croma.Monad must implement the following interface:

  • @type t(a) with a type parameter a.
  • @spec pure(a: a) :: t(a) when a: any
  • @spec bind(t(a), (a -> t(b))) :: t(b) when a: any, b: any

• By using the concrete implementations of the above interface, Croma.Monad provides the default implementations of the following functions:

  • As Functor:
    • @spec map(t(a), (a -> b)) :: t(b) when a: any, b: any
  • As Applicative:
    • @spec ap(t(a), t((a -> b))) :: t(b) when a: any, b: any
    • @spec sequence([t(a)]) :: t([a]) when a: any

• Note that the order of parameters in map/ap is different from that of Haskell counterparts, in order to leverage Elixir's pipe operator |>.

• Croma.Monad also provides bind-less syntax similar to Haskell's do-notation. For example,

  MonadImpl.m do
    x <- mx
    y <- my
    pure f(x, y)
  end
  

is converted to ex MonadImpl.bind(mx, fn x -> MonadImpl.bind(my, fn y -> MonadImpl.pure f(x, y) end) end)

Croma.Result

• Corma.Result.t(a) is defined as @type t(a) :: {:ok, a} | {:error, any}. This module implements Croma.Monad interface.

Croma.ListMonad

• Implementation of Croma.Monad for lists. Croma.ListMonad.t(a) is just an alias to [a].

Working with structs

Croma.Struct

• Utility module to define structs with type specification and validation functions.

  iex> defmodule I do
  ...>   @type t :: integer
  ...>   def validate(i) when is_integer(i), do: {:ok, i}
  ...>   def validate(_), do: {:error, {:invalid_value, [__MODULE__]}}
  ...>   def default, do: 0
  ...> end
  
  ...> defmodule S do
  ...>   use Croma.Struct, fields: [i: I]
  ...> end
  
  ...> S.validate([i: 5])
  {:ok, %S{i: 5}}
  
  ...> S.validate(%{i: "not_an_integer"})
  {:error, {:invalid_value, [S, I]}}
  
  ...> {:ok, s} = S.new([])
  {:ok, %S{i: 0}}
  
  ...> S.update(s, [i: 2])
  {:ok, %S{i: 2}}
  
  ...> S.update(s, %{"i" => "not_an_integer"})
  {:error, {:invalid_value, [S, I]}}
  

• Some helper modules for "per-field module"s that are passed as options to use Croma.Struct (e.g. I in the above example) are available.

  • Wrappers of built-in types such as Croma.String, Croma.Integer, etc.
  • Utility modules such as Croma.SubtypeOfString to define "subtypes" of existing types.
  • Ad-hoc module generators defined in Croma.TypeGen.

Croma.StructCallSyntax

• A new syntax (which uses ~> operator) for calls to functions that take structs as 1st arguments.

  iex> defmodule S do
  ...>   defstruct [:a, :b]
  ...>   def f(s, i) do
  ...>     s.a + s.b + i
  ...>   end
  ...> end
  
  ...> import Croma.StructCallSyntax
  ...> s = %S{a: 1, b: 2}
  ...> s~>f(3)              # => S.f(s, 3)
  6