istype

Library that provides parse transforms to enhance Erlang type checking and conversion.

Usage

1. Add the package to your rebar.config

   {deps, [
       {istype, "0.1.1"}
   ]}.
   

2. Add the parse transform to your rebar.config

   {erl_opts, [
       {parse_transform, istype_transform}
   ]}.
   

3. Use the transforms as documented in their sections below.

istype

Transform that generates guard friendly type checking statements based on the typespec given. This removes the need for the user to implement and maintain code for type validation.

Value istype

-type timeout() :: integer() || infinity.

%% Before transform
istype(Value, timeout()).

%% After transform
is_integer(Value) orelse Value =:= infinity.

The expression generated to validate type is generated in an in order manner.

-type timeout0() :: integer() || infinity.
-type timeout1() :: infinity || integer().

%% Before transform
istype(Value0, timeout0()).

istype(Value1, timeout1()).

%% After transform
is_integer(Value0) orelse Value0 =:= infinity.

Value1 =:= infinity orelse is_integer(Value1).

Expression istype

-type timeout() :: integer() || infinity.

%% Before transform
istype(expression(), timeout()).

%% After transform
begin
    __IsType_X = expression(),
    is_integer(__IsType_X) orelse __IsType_X =:= infinity
end.

When an expression is provided to istype, it is evaluated prior to any checks being processed. This prevents side effects from accidentally processing multiple times.

-type timeout() :: integer() || infinity.

%% Before transform
istype(size(Value), timeout()).

%% After transform
is_integer(size(Value)) orelse size(Value) =:= infinity.

Exceptions are made for any BIF that would be allowed in a guard statement. This is to allow the check to remain an allowable guard.

Tuple istype

-type tuple0() :: {atom}.

%% Before transform
istype(Value, tuple0()).

%% After transform
is_tuple(Value) andalso size(Value) =:= 1 andalso element(1, Value) =:= atom.

When a type specifies a tuple a specific tuple format as a primitive the arity and field types are also checked.

%% Before transform
istype(Value, tuple()).

%% After transform
is_tuple(Value).

The tuple() type is treated as any tuple.

Record istype

-record(record0, {a :: integer(), b}).

-type record0() :: #record0{}.

%% Before transform
istype(Value, record0()).

%% After transform
is_tuple(Value) andalso size(Value) =:= 3 andalso is_integer(Value#record0.a).

As with tuples records are checked against arity and field types.

Nested types

-type timeout() :: integer() | infinity.
-type tuple0() :: {timeout()}.

%% Before transform
istype(Value, tuple0()).

%% After transform
is_tuple(Value) andalso size(Value) =:= 1 andalso (is_integer(element(1, Value)) orelse
                                                   element(1, Value) =:= infinity).

asserttype

Transform that asserts that the value is the specified type. Functionally the same as true = istype(Value, type()).

totype

Transform that enables conversion to custom types. Generates a call to totype:convert/3 with the nested type specs needed for type conversion.

Value totype

-type timeout() :: integer().

1 = totype("1", timeout()).
1 = totype(1.0, timeout()).
1 = totype(<<"1">>, timeout()).

Type conversion looks at the input given for the target type and determines how to convert.

-type type0() :: binary() | list().
-type type1() :: list() | binary().

<<"1">> = totype(1, type0()).
"1" = totype(1, type1()).

When converting to a type that is the union of multiple types the first valid conversion is returned.

Records totype

-record(record0, {a = 0 :: integer()}).
-type record0() :: #record0{}.

#record0{a = 1} = totype([{a, 1}], record0()).
#record0{a = 1} = totype([{"a", "1"}], record0()).
#record0{a = 1} = totype(#{<<"a">> => <<"1">>}], record0()).

Records can be generated from maps and proplists. If a map or list contains a key that is not present in the record that value is dropped silently.

-record(record0, {a = 0 :: integer()}).
-record(record1, {a = <<"">> :: binary()}).

-type record0() :: #record0{}.
-type record1() :: #record1{}.

#record0{a = 1} = totype(#record0{a = "1"}, record0()).
#record1{a = <<"1">>} = totype(#record0{a = "1"}, record1()).

Records can be converted to other records. As with lists and maps only the shared keys are copied.

-record(record0, {a = 0 :: integer()}).

#{a => 2} = totype(#record{a = 2}, map()).
[{a, 2}] = totype(#record{a = 2}, list()).

Records can also be converted into maps and proplists.