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 -include_lib("hope_kv_list.hrl").
   7
   8 -behavior(hope_gen_dictionary).
   9
  10 -export_type(
  11     [ t/2
  12     ]).
  13
  14 -export(
  15     [ empty/0
  16     , get/2  % get option
  17     , get/3  % get existing or default
  18     , get/4  % get existing if valid, or default
  19     , set/3
  20     , update/3
  21     , pop/2
  22     , iter/2
  23     , map/2
  24     , filter/2
  25     , fold/3
  26     , of_kv_list/1
  27     , to_kv_list/1
  28     , has_key/2
  29     , find_unique_presence_violations/2  % No optional keys
  30     , find_unique_presence_violations/3  % Specify optional keys
  31     , validate_unique_presence/2  % No optional keys
  32     , validate_unique_presence/3  % Specify optional keys
  33     , presence_violations_to_list/1
  34     ]).
  35
  36
  37 -type t(K, V) ::
  38     [{K, V}].
  39
  40 -type presence_violations(A) ::
  41     % This is a hack to effectively parametarize the types of record fields.
  42     % IMPORTANT: Make sure that the order of fields matches the definition of
  43     % #hope_kv_list_presence_violations
  44     { hope_kv_list_presence_violations
  45     , [A]  % keys_missing
  46     , [A]  % keys_duplicated
  47     , [A]  % keys_unsupported
  48     }.
  49
  50 -type presence_error(A) ::
  51       {keys_missing     , [A]}
  52     | {keys_duplicated  , [A]}
  53     | {keys_unsupported , [A]}
  54     .
  55
  56
  57 %% ============================================================================
  58 %% API
  59 %% ============================================================================
  60
  61 -spec empty() ->
  62     [].
  63 empty() ->
  64     [].
  65
  66 -spec get(t(K, V), K) ->
  67     hope_option:t(V).
  68 get(T, K) ->
  69     case lists:keyfind(K, 1, T)
  70     of  false  -> none
  71     ;   {K, V} -> {some, V}
  72     end.
  73
  74 -spec get(t(K, V), K, V) ->
  75     V.
  76 get(T, K, Default) ->
  77     Vopt = get(T, K),
  78     hope_option:get(Vopt, Default).
  79
  80 -spec get(t(K, V), K, V, fun((V) -> boolean())) ->
  81     V.
  82 get(T, K, Default, IsValid) ->
  83     VOpt1 = get(T, K),
  84     VOpt2 = hope_option:validate(VOpt1, IsValid),
  85     hope_option:get(VOpt2, Default).
  86
  87 -spec set(t(K, V), K, V) ->
  88     t(K, V).
  89 set(T, K, V) ->
  90     lists:keystore(K, 1, T, {K, V}).
  91
  92 -spec update(t(K, V), K, fun((hope_option:t(V)) -> V)) ->
  93     t(K, V).
  94 update(T, K, F) ->
  95     V1Opt = get(T, K),
  96     V2 = F(V1Opt),
  97     % TODO: Eliminate the 2nd lookup.
  98     set(T, K, V2).
  99
 100 -spec pop(t(K, V), K) ->
 101     {hope_option:t(V), t(K, V)}.
 102 pop(T1, K) ->
 103     case lists:keytake(K, 1, T1)
 104     of  {value, {K, V}, T2} -> {{some, V}, T2}
 105     ;   false               -> {none     , T1}
 106     end.
 107
 108 -spec iter(t(K, V), fun((K, V) -> any())) ->
 109     {}.
 110 iter(T, F1) ->
 111     F2 = lift_map(F1),
 112     ok = lists:foreach(F2, T),
 113     {}.
 114
 115 -spec map(t(K, V), fun((K, V) -> V)) ->
 116     t(K, V).
 117 map(T, F1) ->
 118     F2 = fun ({K, _}=X) -> {K, apply_map(F1, X)} end,
 119     lists:map(F2, T).
 120
 121 -spec filter(t(K, V), fun((K, V) -> boolean())) ->
 122     t(K, V).
 123 filter(T, F1) ->
 124     F2 = lift_map(F1),
 125     lists:filter(F2, T).
 126
 127 -spec fold(t(K, V), fun((K, V, Acc) -> Acc), Acc) ->
 128     Acc.
 129 fold(T, F1, Accumulator) ->
 130     F2 = fun ({K, V}, Acc) -> F1(K, V, Acc) end,
 131     lists:foldl(F2, Accumulator, T).
 132
 133 -spec to_kv_list(t(K, V)) ->
 134     [{K, V}].
 135 to_kv_list(T) ->
 136     T.
 137
 138 -spec of_kv_list([{K, V}]) ->
 139     t(K, V).
 140 of_kv_list(List) ->
 141     % TODO: Decide if validation is to be done here. Do so if yes.
 142     List.
 143
 144 -spec validate_unique_presence(T, [K]) ->
 145     hope_result:t(T, [presence_error(K)])
 146     when T :: t(K, _V).
 147 validate_unique_presence(T, KeysRequired) ->
 148     KeysOptional = [],
 149     validate_unique_presence(T, KeysRequired, KeysOptional).
 150
 151 -spec validate_unique_presence(t(K, _V), [K], [K]) ->
 152     hope_result:t(T, [presence_error(K)])
 153     when T :: t(K, _V).
 154 validate_unique_presence(T, KeysRequired, KeysOptional) ->
 155     case find_unique_presence_violations(T, KeysRequired, KeysOptional)
 156     of  #hope_kv_list_presence_violations
 157         { keys_missing     = []
 158         , keys_duplicated  = []
 159         , keys_unsupported = []
 160         } ->
 161             {ok, T}
 162     ;   #hope_kv_list_presence_violations{}=Violations ->
 163             {error, presence_violations_to_list(Violations)}
 164     end.
 165
 166 -spec find_unique_presence_violations(t(K, _V), [K]) ->
 167     presence_violations(K).
 168 find_unique_presence_violations(T, KeysRequired) ->
 169     KeysOptional = [],
 170     find_unique_presence_violations(T, KeysRequired, KeysOptional).
 171
 172 -spec find_unique_presence_violations(t(K, _V), [K], [K]) ->
 173     presence_violations(K).
 174 find_unique_presence_violations(T, KeysRequired, KeysOptional) ->
 175     KeysSupported   = KeysRequired ++ KeysOptional,
 176     KeysGiven       = [K || {K, _V} <- T],
 177     KeysGivenUnique = lists:usort(KeysGiven),
 178     KeysDuplicated  = lists:usort(KeysGiven -- KeysGivenUnique),
 179     KeysMissing     = KeysRequired -- KeysGivenUnique,
 180     KeysUnsupported = KeysGivenUnique -- KeysSupported,
 181     #hope_kv_list_presence_violations
 182     { keys_missing     = KeysMissing
 183     , keys_duplicated  = KeysDuplicated
 184     , keys_unsupported = KeysUnsupported
 185     }.
 186
 187 -spec presence_violations_to_list(presence_violations(K)) ->
 188     [presence_error(K)].
 189 presence_violations_to_list(#hope_kv_list_presence_violations
 190 { keys_missing     = KeysMissing
 191 , keys_duplicated  = KeysDuplicated
 192 , keys_unsupported = KeysUnsupported
 193 }) ->
 194     ErrorMissing =
 195         case KeysMissing
 196         of  []    -> []
 197         ;   [_|_] -> [{keys_missing, KeysMissing}]
 198         end,
 199     ErrorDups =
 200         case KeysDuplicated
 201         of  []    -> []
 202         ;   [_|_] -> [{keys_duplicated, KeysDuplicated}]
 203         end,
 204     ErrorUnsupported =
 205         case KeysUnsupported
 206         of  []    -> []
 207         ;   [_|_] -> [{keys_unsupported, KeysUnsupported}]
 208         end,
 209     ErrorDups ++ ErrorMissing ++ ErrorUnsupported.
 210
 211 -spec has_key(t(K, _), K) ->
 212     boolean().
 213 has_key(T, K1) ->
 214     lists:any(fun ({K2, _}) -> K1 =:= K2 end, T).
 215
 216 %% ============================================================================
 217 %% Helpers
 218 %% ============================================================================
 219
 220 -spec lift_map(F) ->
 221     G
 222     when F :: fun(( K, V1 ) -> V2)
 223        , G :: fun(({K, V1}) -> V2)
 224        .
 225 lift_map(F) ->
 226     fun (X) -> apply_map(F, X) end.
 227
 228 -spec apply_map(fun((K, V1) -> V2), {K, V1}) ->
 229     V2.
 230 apply_map(F, {K, V}) ->
 231     F(K, V).