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