src/hope_kv_list.erl

   1 %%%----------------------------------------------------------------------------
   2 %%% Equivalent to stdlib's orddict, but with a pretty (IMO), uniform interface.
   3 %%%----------------------------------------------------------------------------
   4 -module(hope_kv_list).
   5
   6 -behavior(hope_dictionary).
   7
   8 -export_type(
   9     [ t/2
  10     ]).
  11
  12 -export(
  13     [ empty/0
  14     , get/2
  15     , set/3
  16     , update/3
  17     , pop/2
  18     , iter/2
  19     , map/2
  20     , filter/2
  21     , fold/3
  22     , of_kv_list/1
  23     , to_kv_list/1
  24     , validate_unique_presence/2  % Assume default optional parameter(s)
  25     , validate_unique_presence/3  % Specify optional parameter(s)
  26     ]).
  27
  28
  29 -type t(K, V) ::
  30     [{K, V}].
  31
  32 -type presence_error(A) ::
  33       {keys_missing     , [A]}
  34     | {keys_duplicated  , [A]}
  35     | {keys_unsupported , [A]}
  36     .
  37
  38
  39 %% ============================================================================
  40 %% API
  41 %% ============================================================================
  42
  43 -spec empty() ->
  44     [].
  45 empty() ->
  46     [].
  47
  48 -spec get(t(K, V), K) ->
  49     hope_option:t(V).
  50 get(T, K) ->
  51     case lists:keyfind(K, 1, T)
  52     of  false  -> none
  53     ;   {K, V} -> {some, V}
  54     end.
  55
  56 -spec set(t(K, V), K, V) ->
  57     t(K, V).
  58 set(T, K, V) ->
  59     lists:keystore(K, 1, T, {K, V}).
  60
  61 -spec update(t(K, V), K, fun((hope_option:t(V)) -> V)) ->
  62     t(K, V).
  63 update(T, K, F) ->
  64     V1Opt = get(T, K),
  65     V2 = F(V1Opt),
  66     % TODO: Eliminate the 2nd lookup.
  67     set(T, K, V2).
  68
  69 -spec pop(t(K, V), K) ->
  70     {hope_option:t(V), t(K, V)}.
  71 pop(T1, K) ->
  72     case lists:keytake(K, 1, T1)
  73     of  {value, {K, V}, T2} -> {{some, V}, T2}
  74     ;   false               -> {none     , T1}
  75     end.
  76
  77 -spec iter(t(K, V), fun((K, V) -> ok)) ->
  78     ok.
  79 iter(T, F1) ->
  80     F2 = lift_map(F1),
  81     lists:foreach(F2, T).
  82
  83 -spec map(t(K, V), fun((K, V) -> V)) ->
  84     t(K, V).
  85 map(T, F1) ->
  86     F2 = fun ({K, _}=X) -> {K, apply_map(F1, X)} end,
  87     lists:map(F2, T).
  88
  89 -spec filter(t(K, V), fun((K, V) -> boolean())) ->
  90     t(K, V).
  91 filter(T, F1) ->
  92     F2 = lift_map(F1),
  93     lists:filter(F2, T).
  94
  95 -spec fold(t(K, V), fun((K, V, Acc) -> Acc), Acc) ->
  96     Acc.
  97 fold(T, F1, Accumulator) ->
  98     F2 = fun ({K, V}, Acc) -> F1(K, V, Acc) end,
  99     lists:foldl(F2, Accumulator, T).
 100
 101 -spec to_kv_list(t(K, V)) ->
 102     [{K, V}].
 103 to_kv_list(T) ->
 104     T.
 105
 106 -spec of_kv_list([{K, V}]) ->
 107     t(K, V).
 108 of_kv_list(List) ->
 109     % TODO: Decide if validation is to be done here. Do so if yes.
 110     List.
 111
 112 -spec validate_unique_presence(t(K, _V), [K]) ->
 113     hope_result:t(ok, [presence_error(K)]).
 114 validate_unique_presence(T, KeysRequired) ->
 115     KeysOptional = [],
 116     validate_unique_presence(T, KeysRequired, KeysOptional).
 117
 118 -spec validate_unique_presence(t(K, _V), [K], [K]) ->
 119     hope_result:t(ok, [presence_error(K)]).
 120 validate_unique_presence(T, KeysRequired, KeysOptional) ->
 121     KeysSupported   = KeysRequired ++ KeysOptional,
 122     KeysGiven       = [K || {K, _V} <- T],
 123     KeysGivenUnique = lists:usort(KeysGiven),
 124     KeysDups        = lists:usort(KeysGiven -- KeysGivenUnique),
 125     KeysMissing     = KeysRequired -- KeysGivenUnique,
 126     KeysUnsupported = KeysGivenUnique -- KeysSupported,
 127     case {KeysDups, KeysMissing, KeysUnsupported}
 128     of  {[], [], []} ->
 129             {ok, ok}
 130     ;   {Dups, Missing, Unsupported} ->
 131             ErrorDups =
 132                 case Dups
 133                 of  []    -> []
 134                 ;   [_|_] -> [{keys_duplicated, Dups}]
 135                 end,
 136             ErrorMissing =
 137                 case Missing
 138                 of  []    -> []
 139                 ;   [_|_] -> [{keys_missing, Missing}]
 140                 end,
 141             ErrorUnsupported =
 142                 case Unsupported
 143                 of  []    -> []
 144                 ;   [_|_] -> [{keys_unsupported, Unsupported}]
 145                 end,
 146             Errors = ErrorDups ++ ErrorMissing ++ ErrorUnsupported,
 147             {error, Errors}
 148     end.
 149
 150
 151 %% ============================================================================
 152 %% Helpers
 153 %% ============================================================================
 154
 155 -spec lift_map(F) ->
 156     G
 157     when F :: fun(( K, V1 ) -> V2)
 158        , G :: fun(({K, V1}) -> V2)
 159        .
 160 lift_map(F) ->
 161     fun (X) -> apply_map(F, X) end.
 162
 163 -spec apply_map(fun((K, V1) -> V2), {K, V1}) ->
 164     V2.
 165 apply_map(F, {K, V}) ->
 166     F(K, V).