SimpleEnum (simple_enum v0.1.0) View Source

SimpleEnum is a simple library that implements Enumerations in Elixir.

An Enumeration is a user-defined type that consists of a set of several named constants that are known as Enumerators.
The purpose of SimpleEnum is to provide an equivalent for the Elixir language.

SimpleEnum is:

fast: being based on a macro system, access to the Enum will be resolved at compile time when it is possible (see. Fast vs Slow access)
simple: The use of the library has been designed to be as simple as possible for a developer to use. In addition to providing the Enums, it automatically defines their types and provides an introspection system.

Installation

The package can be installed by adding simple_enum to your list of dependencies in mix.exs:

# my_app/mix.exs
def deps do
  [
    {:simple_enum, "~> 0.1"}
  ]
end

Then, update your dependencies:

$ mix deps.get

Optionally, if you use the formatter, add this line to .formatter.exs:

# my_app/.formatter.exs
[
  import_deps: [:simple_enum]
]

Basic Usage

iex> defmodule MyEnums do
...>   import SimpleEnum, only: [defenum: 2]
...>
...>   defenum :color, [:blue, :green, :red]
...>   defenum :day, monday: "MON", tuesday: "TUE", wednesday: "WED"
...> end

iex> require MyEnums

iex> MyEnums.color(:blue)
0
iex> MyEnums.color(0)
:blue
iex> MyEnums.day(:monday)
"MON"
iex> MyEnums.day("MON")
:monday
iex> MyEnums.day("MONN")
** (ArgumentError) invalid value "MONN" for Enum MyEnums.day/1. Expected one of [:monday, :tuesday, :wednesday, "MON", "TUE", "WED"]

Link to this section Summary

Functions

defenum(name, enumerators)

Defines a set of macros to create and access Enumerations.

Link to this section Functions

defenum(name, enumerators)

(macro)

Defines a set of macros to create and access Enumerations.

The name of the generated macros and types will be name (which has to be an atom).
The enumerators argument has to be either:

A keyword list composed of strings (to create a string-based Enumeration)
A keyword list composed of integers (to create an integer-based Enumeration)
A list of atoms (to create an integer-based Enumeration)

For more details about string-based Enumeration and integer-based Enumeration, you can check the corresponding guide.

The following macros are generated:

name/1 to access a key, a value or to inspect an Enumeration
name/2 to access a key, a value or its tuple by specifying the return type

The following types are generated:

@type enum :: :key1 | :key2 | :value1 | :value2
@type enum_keys :: :key1 | :key2
@type enum_values :: :value1 | :value2

For more details about types you can also check the corresponding guide.

All these macros are public macros (as defined by defmacro/2).

See the "Examples" section for examples on how to use these macros.

Examples

defmodule MyApp.Enums do
  import SimpleEnum, only: [defenum: 2]
  defenum :color, [:blue, :green, :red]
end

In the example above, a set of macros named color but with different arities will be defined to manipulate the underlying Enumeration.

# Import the module to make the color macros locally available
import MyApp.Enums

# To lookup the corresponding value
color(:blue)    #=> 0
color(:green)   #=> 1
color(:red)     #=> 2
color(0)        #=> :blue
color(1)        #=> :green
color(2)        #=> :red

# To lookup for the key regardless of the given value
color(:red, :key) #=> :red
color(2, :key)    #=> :red

# To lookup for the value regardless of the given value
color(:red, :value) #=> 2
color(2, :value)    #=> 2

# To get the key/value pair of the given value
color(:red, :tuple) #=> {:red, 2}
color(2, :tuple)    #=> {:red, 2}

Is also possible to inspect the Enumeration by using introspection helpers :

color(:__keys__)        #=> [:blue, :green, :red]
color(:__values__)      #=> [0, 1, 2]
color(:__enumerators__) #=> [blue: 0, green: 1, red: 2]