pipe_line

%%%-------------------------------------------------------------------

%%% @doc

%%% A set of specialized folds for piping a value through a list of

%%% functions.

%%% @end

%%%-------------------------------------------------------------------

-module(pipe).
-compile(inline).

-define(MATCH_ERROR(Error),

        (element(1, Error) == error)).
-define(SPEC_MONAD(For),

        -spec For(Fun :: monoid(), Value :: term()) -> term()).
-define(SPEC_PARTIAL_PIPE(For),

        -spec For(Start :: term(), Funs :: [monoid()]) -> term()).

-type monoid() :: fun((term()) -> term()).
-type monad() :: fun((monoid(), term()) -> term()).

%% API

-export([always/2,

         ignore/2,

         apply/2,

         if_ok/2,

         if_not_error/2,

         if_not_throw/2,

         if_not_exception/2,

         compose/1,

         via/2,

         pipe/3,

         line/2,

         ok/2,

         not_error/2,

         not_throw/2,

         not_exception/2]).

-export_type([monoid/0,

              monad/0]).

%%%===================================================================

%%% API

%%%===================================================================


%% @doc

%% A function application that always executes the given function.

%% This is also the identity function.

%% @end

?SPEC_MONAD(always).
always(Fun, Value) ->
    Fun(Value).

%% @doc

%% A function application that ignores the return value of the given

%% function, instead passing the value through unchanged. Useful for

%% functions which are executed solely for their side effects.

%% @end

?SPEC_MONAD(ignore).
ignore(Fun, Value) ->
    Fun(Value),
    Value.

%% @doc

%% A function application that expands a list or tuple into multiple

%% arguments to apply to the given function. A generic adapter for

%% when single argument functions are difficult to derive.

%% @end

-spec apply(Fun :: fun((...) -> term()), Value :: term()) -> term().
apply(Fun, Value) when is_list(Value) ->
    erlang:apply(Fun, Value);
apply(Fun, Value) when is_tuple(Value) ->
    erlang:apply(Fun, tuple_to_list(Value)).

%% @doc

%% A function application that only applies the given function when

%% the value is an {ok, _} tuple, otherwise the given value is

%% returned unchanged. Best for conditional execution over well

%% behaved functions that always return {ok, _} or {error, _}

%% tuples.

%%

%% The value inside the {ok, _} tuple is unwrapped and used as the

%% argument to the called function.

%% @end

?SPEC_MONAD(if_ok).
if_ok(Fun, Value) ->
    case Value of
        {ok, Ok} ->
            Fun(Ok);
        _ ->
            Value
    end.

%% @doc

%% A function application that only applies the given function when

%% the value is not an {error, _} tuple, otherwise the given value

%% is returned unchanged. Best for conditional execution over

%% functions with a variety of return formats, where a best effort is

%% required.

%%

%% The value inside an {ok, _} tuple is unwrapped and used as the

%% argument to the called function, otherwise the value is used as is.

%% @end

?SPEC_MONAD(if_not_error).
if_not_error(Fun, Value) ->
    case Value of
        {ok, Ok} ->
            Fun(Ok);
        Error when ?MATCH_ERROR(Error) ->
            Error;
        _ ->
            Fun(Value)
    end.

%% @doc

%% A function application that only applies the given function when

%% the value is not an {error, _} tuple, otherwise the given value

%% is returned unchanged. Best for conditional execution over poorly

%% behaved functions which throw exceptions for expected failures.

%%

%% If the called function throws an exception, it will be caught and

%% converted to the form {error, {throw, Reason}}.

%%

%% The value inside an {ok, _} tuple is unwrapped and used as the

%% argument to the called function, otherwise the value is used as is.

%% @end

?SPEC_MONAD(if_not_throw).
if_not_throw(Fun, Value) ->
    Try = fun (Unwrapped) ->
        try Fun(Unwrapped)
        catch
            throw:Reason ->
                exception_as_error(throw, Reason)
        end
    end,
    case Value of
        {ok, Ok} ->
            Try(Ok);
        Error when ?MATCH_ERROR(Error) ->
            Error;
        _ ->
            Try(Value)
    end.

%% @doc

%% A function application that only applies the given function when

%% the value is not an {error, _} tuple, otherwise the given value

%% is returned unchanged. Best for when exceptions must not stop

%% execution and the calling code is prepared to match on and handle

%% caught exceptions.

%%

%% If the called function throws an exception of any type (including

%% exit signals), it will be caught and converted to the form {error,

%% {Class, Reason}}.

%%

%% The value inside an {ok, _} tuple is unwrapped and used as the

%% argument to the called function, otherwise the value is used as is.

%% @end

?SPEC_MONAD(if_not_exception).
if_not_exception(Fun, Value) ->
    case Value of
        {ok, Ok} ->
            try Fun(Ok)
            catch
                Class:Reason ->
                    exception_as_error(Class, Reason)
            end;
        Error when ?MATCH_ERROR(Error) ->
            Error;
        _ ->
            try Fun(Value)
            catch
                Class:Reason ->
                    exception_as_error(Class, Reason)
            end
    end.

%% @doc

%% Combine a list of function applications into a single function

%% application.

%% @end

-spec compose(Monads :: [monad()]) -> monad().
compose([]) ->
    fun always/2;
compose([_ | _] = Monads) ->
    [Head | Tail] = lists:reverse(Monads),
    lists:foldl(fun compose/2, Head, Tail).

%% @doc

%% Combine a list of function applications with an unapplied single

%% argument function to create a pipeline stage that can have

%% customized behaviour.

%%

%% When used with a pipe function such as pipe:line/2, allows for each

%% stage to have custom error handling.

%% @end

-spec via(Apply :: [monad()], Start :: monoid()) -> monoid().
via(Apply, Start) ->
    Composed = compose(Apply),
    fun (Value) -> Composed(Start, Value) end.

%% @doc

%% The generic pipe function. This works as a specialized fold. The

%% initial value is used as an argument to the first unapplied

%% function in the given list, the result of that used as the argument

%% to the next function and so on. The returned value is the result of

%% the final function.

%%

%% Control over if each function is to be applied is given to the list

%% of function applications, which decide what to do based on the

%% current value to be applied. Function applications execute in left

%% to right order, with the leftmost being the first able to control

%% execution.

%%

%% To customize an individual pipe stage, use pipe:via/2. To pipe over

%% multiple argument functions, use pipe:apply/2.

%% @end

%% @see pipe:via/2

%% @see pipe:apply/2

-spec pipe(Apply :: [monad()] | monad(),

           Start :: term(),

           Funs :: [monoid()]) -> term().
pipe([_ | _] = Apply, Start, Funs) ->
    pipe(compose(Apply), Start, Funs);
pipe(Apply, Start, Funs) ->
    do_pipe(Apply, Start, Funs).

%% @doc

%% A pipe function which executes each function in turn, regardless of

%% the value returned.

%% @end

%% @see pipe:always/2

?SPEC_PARTIAL_PIPE(line).
line(Start, Funs) ->
    do_pipe(fun always/2, Start, Funs).

%% @doc

%% A pipe function which executes each function only when the returned

%% value is of the form {ok, _}. Ensure the initial value is also of

%% that form, otherwise none of the functions will be executed.

%% @end

%% @see pipe:if_ok/2

?SPEC_PARTIAL_PIPE(ok).
ok(Start, Funs) ->
    do_pipe(fun if_ok/2, Start, Funs).

%% @doc

%% A pipe function which executes each function only when the returned

%% value is not of the form {error, _}.

%% @end

%% @see pipe:if_not_error/2

?SPEC_PARTIAL_PIPE(not_error).
not_error(Start, Funs) ->
    do_pipe(fun if_not_error/2, Start, Funs).

%% @doc

%% A pipe function which executes each function only when the returned

%% value is not of the form {error, _}. Thrown exceptions are caught

%% and converted into error tuples.

%% @end

%% @see pipe:if_not_throw/2

?SPEC_PARTIAL_PIPE(not_throw).
not_throw(Start, Funs) ->
    do_pipe(fun if_not_throw/2, Start, Funs).

%% @doc

%% A pipe function which executes each function only when the returned

%% value is not of the form {error, _}. All exceptions are caught

%% and converted into error tuples.

%% @end

%% @see pipe:if_not_exception/2

?SPEC_PARTIAL_PIPE(not_exception).
not_exception(Start, Funs) ->
    do_pipe(fun if_not_exception/2, Start, Funs).

%%%===================================================================

%%% Internal Functions

%%%===================================================================


compose(Monad1, Monad2) ->
    fun (Fun, Value) ->
            Monad1(fun (Inner) -> Monad2(Fun, Inner) end, Value)
    end.

exception_as_error(Class, Reason) ->
    {error, {Class, Reason}}.

do_pipe(_Apply, Value, []) ->
    Value;
do_pipe(Apply, Value, [Fun | Funs]) ->
    do_pipe(Apply, Apply(Fun, Value), Funs).