1proplists(3)               Erlang Module Definition               proplists(3)
2
3
4

NAME

6       proplists - Support functions for property lists.
7

DESCRIPTION

9       Property lists are ordinary lists containing entries in the form of ei‐
10       ther tuples, whose first elements are keys used for lookup  and  inser‐
11       tion, or atoms, which work as shorthand for tuples {Atom, true}. (Other
12       terms are allowed in the lists, but are ignored  by  this  module.)  If
13       there is more than one entry in a list for a certain key, the first oc‐
14       currence normally overrides any later (irrespective of the arity of the
15       tuples).
16
17       Property  lists  are useful for representing inherited properties, such
18       as options passed to a function where a user can specify options  over‐
19       riding the default settings, object properties, annotations, and so on.
20
21       Two keys are considered equal if they match (=:=). That is, numbers are
22       compared literally rather than by value, so that, for  example,  1  and
23       1.0 are different keys.
24

DATA TYPES

26       property() = atom() | tuple()
27
28       proplist() = [property()]
29

EXPORTS

31       append_values(Key, ListIn) -> ListOut
32
33              Types:
34
35                 Key = term()
36                 ListIn = ListOut = [term()]
37
38              Similar to get_all_values/2, but each value is wrapped in a list
39              unless it is already itself a list. The resulting list of  lists
40              is concatenated. This is often useful for "incremental" options.
41
42              Example:
43
44              append_values(a, [{a, [1,2]}, {b, 0}, {a, 3}, {c, -1}, {a, [4]}])
45
46              returns:
47
48              [1,2,3,4]
49
50       compact(ListIn) -> ListOut
51
52              Types:
53
54                 ListIn = ListOut = [property()]
55
56              Minimizes the representation of all entries in the list. This is
57              equivalent to [property(P) || P <- ListIn].
58
59              See also property/1, unfold/1.
60
61       delete(Key, List) -> List
62
63              Types:
64
65                 Key = term()
66                 List = [term()]
67
68              Deletes all entries associated with Key from List.
69
70       expand(Expansions, ListIn) -> ListOut
71
72              Types:
73
74                 Expansions  =  [{Property   ::   property(),   Expansion   ::
75                 [term()]}]
76                 ListIn = ListOut = [term()]
77
78              Expands  particular  properties to corresponding sets of proper‐
79              ties (or other terms). For each pair  {Property,  Expansion}  in
80              Expansions:  if E is the first entry in ListIn with the same key
81              as Property, and E and Property have  equivalent  normal  forms,
82              then  E is replaced with the terms in Expansion, and any follow‐
83              ing entries with the same key are deleted from ListIn.
84
85              For example, the following expressions  all  return  [fie,  bar,
86              baz, fum]:
87
88              expand([{foo, [bar, baz]}], [fie, foo, fum])
89              expand([{{foo, true}, [bar, baz]}], [fie, foo, fum])
90              expand([{{foo, false}, [bar, baz]}], [fie, {foo, false}, fum])
91
92              However,  no  expansion  is  done  in the following call because
93              {foo, false} shadows foo:
94
95              expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])
96
97              Notice that if the original property term is to be preserved  in
98              the  result  when expanded, it must be included in the expansion
99              list. The inserted terms are not expanded recursively. If Expan‐
100              sions  contains  more  than one property with the same key, only
101              the first occurrence is used.
102
103              See also normalize/2.
104
105       from_map(Map) -> List
106
107              Types:
108
109                 Map = #{Key => Value}
110                 List = [{Key, Value}]
111                 Key = Value = term()
112
113              Converts the map Map to a property list.
114
115       get_all_values(Key, List) -> [term()]
116
117              Types:
118
119                 Key = term()
120                 List = [term()]
121
122              Similar to get_value/2, but returns the list of values  for  all
123              entries  {Key,  Value} in List. If no such entry exists, the re‐
124              sult is the empty list.
125
126       get_bool(Key, List) -> boolean()
127
128              Types:
129
130                 Key = term()
131                 List = [term()]
132
133              Returns the value of a boolean key/value option. If  lookup(Key,
134              List)  would yield {Key, true}, this function returns true, oth‐
135              erwise false.
136
137              See also get_value/2, lookup/2.
138
139       get_keys(List) -> [term()]
140
141              Types:
142
143                 List = [term()]
144
145              Returns an unordered list of the keys used in List, not contain‐
146              ing duplicates.
147
148       get_value(Key, List) -> term()
149
150              Types:
151
152                 Key = term()
153                 List = [term()]
154
155              Equivalent to get_value(Key, List, undefined).
156
157       get_value(Key, List, Default) -> term()
158
159              Types:
160
161                 Key = term()
162                 List = [term()]
163                 Default = term()
164
165              Returns  the  value  of  a simple key/value property in List. If
166              lookup(Key, List) would yield {Key, Value},  this  function  re‐
167              turns the corresponding Value, otherwise Default.
168
169              See also get_all_values/2, get_bool/2, get_value/2, lookup/2.
170
171       is_defined(Key, List) -> boolean()
172
173              Types:
174
175                 Key = term()
176                 List = [term()]
177
178              Returns true if List contains at least one entry associated with
179              Key, otherwise false.
180
181       lookup(Key, List) -> none | tuple()
182
183              Types:
184
185                 Key = term()
186                 List = [term()]
187
188              Returns the first entry associated with Key in List, if one  ex‐
189              ists, otherwise returns none. For an atom A in the list, the tu‐
190              ple {A, true} is the entry associated with A.
191
192              See also get_bool/2, get_value/2, lookup_all/2.
193
194       lookup_all(Key, List) -> [tuple()]
195
196              Types:
197
198                 Key = term()
199                 List = [term()]
200
201              Returns the list of all entries associated with Key in List.  If
202              no such entry exists, the result is the empty list.
203
204              See also lookup/2.
205
206       normalize(ListIn, Stages) -> ListOut
207
208              Types:
209
210                 ListIn = [term()]
211                 Stages = [Operation]
212                 Operation =
213                     {aliases, Aliases} |
214                     {negations, Negations} |
215                     {expand, Expansions}
216                 Aliases = Negations = [{Key, Key}]
217                 Expansions   =   [{Property   ::   property(),  Expansion  ::
218                 [term()]}]
219                 ListOut = [term()]
220
221              Passes  ListIn  through  a  sequence  of  substitution/expansion
222              stages.  For an aliases operation, function substitute_aliases/2
223              is applied using the specified list of aliases:
224
225                * For a negations operation, substitute_negations/2 is applied
226                  using the specified negation list.
227
228                * For  an expand operation, function expand/2 is applied using
229                  the specified list of expansions.
230
231              The final result is automatically compacted (compare compact/1).
232
233              Typically you want to substitute negations first, then  aliases,
234              then  perform one or more expansions (sometimes you want to pre-
235              expand particular entries before doing the main expansion).  You
236              might want to substitute negations and/or aliases repeatedly, to
237              allow such forms in the right-hand side of aliases and expansion
238              lists.
239
240              See also substitute_negations/2.
241
242       property(PropertyIn) -> PropertyOut
243
244              Types:
245
246                 PropertyIn = PropertyOut = property()
247
248              Creates a normal form (minimal) representation of a property. If
249              PropertyIn is {Key, true}, where Key is  an  atom,  Key  is  re‐
250              turned, otherwise the whole term PropertyIn is returned.
251
252              See also property/2.
253
254       property(Key, Value) -> Property
255
256              Types:
257
258                 Key = Value = term()
259                 Property = atom() | {term(), term()}
260
261              Creates  a  normal  form  (minimal)  representation  of a simple
262              key/value property. Returns Key if Value is true and Key  is  an
263              atom, otherwise a tuple {Key, Value} is returned.
264
265              See also property/1.
266
267       split(List, Keys) -> {Lists, Rest}
268
269              Types:
270
271                 List = Keys = [term()]
272                 Lists = [[term()]]
273                 Rest = [term()]
274
275              Partitions  List  into a list of sublists and a remainder. Lists
276              contains one sublist for each key in Keys, in the  corresponding
277              order.  The  relative  order  of the elements in each sublist is
278              preserved from the original List. Rest contains the elements  in
279              List  that  are  not  associated with any of the specified keys,
280              also with their original relative order preserved.
281
282              Example:
283
284              split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])
285
286              returns:
287
288              {[[a], [{b, 5}, b],[{c, 2}, {c, 3, 4}]], [{e, 1}, d]}
289
290       substitute_aliases(Aliases, ListIn) -> ListOut
291
292              Types:
293
294                 Aliases = [{Key, Key}]
295                 Key = term()
296                 ListIn = ListOut = [term()]
297
298              Substitutes keys of properties. For each entry in ListIn, if  it
299              is  associated  with  some  key  K1 such that {K1, K2} occurs in
300              Aliases, the key of the entry is changed to K2. If the  same  K1
301              occurs  more  than once in Aliases, only the first occurrence is
302              used.
303
304              For example, substitute_aliases([{color, colour}],  L)  replaces
305              all  tuples  {color, ...} in L with {colour, ...}, and all atoms
306              color with colour.
307
308              See also normalize/2, substitute_negations/2.
309
310       substitute_negations(Negations, ListIn) -> ListOut
311
312              Types:
313
314                 Negations = [{Key1, Key2}]
315                 Key1 = Key2 = term()
316                 ListIn = ListOut = [term()]
317
318              Substitutes keys of boolean-valued properties and simultaneously
319              negates their values. For each entry in ListIn, if it is associ‐
320              ated with some key K1 such that {K1, K2} occurs in Negations: if
321              the  entry was {K1, true}, it is replaced with {K2, false}, oth‐
322              erwise with K2, thus changing the name of the option and  simul‐
323              taneously negating the value specified by get_bool(Key, ListIn).
324              If the same K1 occurs more than  once  in  Negations,  only  the
325              first occurrence is used.
326
327              For  example,  substitute_negations([{no_foo, foo}], L) replaces
328              any atom no_foo or tuple {no_foo, true} in L with {foo,  false},
329              and any other tuple {no_foo, ...} with foo.
330
331              See also get_bool/2, normalize/2, substitute_aliases/2.
332
333       to_map(List) -> Map
334
335              Types:
336
337                 List = [Shorthand | {Key, Value} | term()]
338                 Map = #{Shorthand => true, Key => Value}
339                 Shorthand = atom()
340                 Key = Value = term()
341
342              Converts the property list List to a map.
343
344              Shorthand atom values in List will be expanded to an association
345              of the form Atom => true. Tuples of the  form  {Key,  Value}  in
346              List  will  be  converted  to  an association of the form Key =>
347              Value. Anything else will be silently ignored.
348
349              If the same key appears in List multiple times, the value of the
350              one  appearing nearest to the head of List will be in the result
351              map, that is the value that would  be  returned  by  a  call  to
352              get_value(Key, List).
353
354              Example:
355
356              to_map([a, {b, 1}, {c, 2}, {c, 3}])
357
358              returns:
359
360              #{a => true, b => 1, c => 2}
361
362       to_map(List, Stages) -> Map
363
364              Types:
365
366                 List = [term()]
367                 Stages = [Operation]
368                 Operation =
369                     {aliases, Aliases} |
370                     {negations, Negations} |
371                     {expand, Expansions}
372                 Aliases = Negations = [{Key, Key}]
373                 Expansions   =   [{Property   ::   property(),  Expansion  ::
374                 [term()]}]
375                 Map = #{term() => term()}
376
377              Converts the property list List to a map after applying the nor‐
378              malizations given in Stages.
379
380              See also normalize/2, to_map/1.
381
382       unfold(ListIn) -> ListOut
383
384              Types:
385
386                 ListIn = ListOut = [term()]
387
388              Unfolds  all  occurrences  of  atoms  in ListIn to tuples {Atom,
389              true}.
390
391
392
393Ericsson AB                      stdlib 5.1.1                     proplists(3)
Impressum