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
10       either 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
14       occurrence normally overrides any later (irrespective of the  arity  of
15       the 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       get_all_values(Key, List) -> [term()]
106
107              Types:
108
109                 Key = term()
110                 List = [term()]
111
112              Similar to get_value/2, but returns the list of values  for  all
113              entries  {Key,  Value}  in  List.  If  no such entry exists, the
114              result is the empty list.
115
116       get_bool(Key, List) -> boolean()
117
118              Types:
119
120                 Key = term()
121                 List = [term()]
122
123              Returns the value of a boolean key/value option. If  lookup(Key,
124              List)  would yield {Key, true}, this function returns true, oth‐
125              erwise false.
126
127              See also get_value/2, lookup/2.
128
129       get_keys(List) -> [term()]
130
131              Types:
132
133                 List = [term()]
134
135              Returns an unordered list of the keys used in List, not contain‐
136              ing duplicates.
137
138       get_value(Key, List) -> term()
139
140              Types:
141
142                 Key = term()
143                 List = [term()]
144
145              Equivalent to get_value(Key, List, undefined).
146
147       get_value(Key, List, Default) -> term()
148
149              Types:
150
151                 Key = term()
152                 List = [term()]
153                 Default = term()
154
155              Returns  the  value  of  a simple key/value property in List. If
156              lookup(Key,  List)  would  yield  {Key,  Value},  this  function
157              returns the corresponding Value, otherwise Default.
158
159              See also get_all_values/2, get_bool/2, get_value/2, lookup/2.
160
161       is_defined(Key, List) -> boolean()
162
163              Types:
164
165                 Key = term()
166                 List = [term()]
167
168              Returns true if List contains at least one entry associated with
169              Key, otherwise false.
170
171       lookup(Key, List) -> none | tuple()
172
173              Types:
174
175                 Key = term()
176                 List = [term()]
177
178              Returns the first entry associated with  Key  in  List,  if  one
179              exists,  otherwise  returns none. For an atom A in the list, the
180              tuple {A, true} is the entry associated with A.
181
182              See also get_bool/2, get_value/2, lookup_all/2.
183
184       lookup_all(Key, List) -> [tuple()]
185
186              Types:
187
188                 Key = term()
189                 List = [term()]
190
191              Returns the list of all entries associated with Key in List.  If
192              no such entry exists, the result is the empty list.
193
194              See also lookup/2.
195
196       normalize(ListIn, Stages) -> ListOut
197
198              Types:
199
200                 ListIn = [term()]
201                 Stages = [Operation]
202                 Operation =
203                     {aliases, Aliases} |
204                     {negations, Negations} |
205                     {expand, Expansions}
206                 Aliases = Negations = [{Key, Key}]
207                 Expansions   =   [{Property   ::   property(),  Expansion  ::
208                 [term()]}]
209                 ListOut = [term()]
210
211              Passes  ListIn  through  a  sequence  of  substitution/expansion
212              stages.  For an aliases operation, function substitute_aliases/2
213              is applied using the specified list of aliases:
214
215                * For a negations operation, substitute_negations/2 is applied
216                  using the specified negation list.
217
218                * For  an expand operation, function expand/2 is applied using
219                  the specified list of expansions.
220
221              The final result is automatically compacted (compare compact/1).
222
223              Typically you want to substitute negations first, then  aliases,
224              then  perform one or more expansions (sometimes you want to pre-
225              expand particular entries before doing the main expansion).  You
226              might want to substitute negations and/or aliases repeatedly, to
227              allow such forms in the right-hand side of aliases and expansion
228              lists.
229
230              See also substitute_negations/2.
231
232       property(PropertyIn) -> PropertyOut
233
234              Types:
235
236                 PropertyIn = PropertyOut = property()
237
238              Creates a normal form (minimal) representation of a property. If
239              PropertyIn is  {Key,  true},  where  Key  is  an  atom,  Key  is
240              returned, otherwise the whole term PropertyIn is returned.
241
242              See also property/2.
243
244       property(Key, Value) -> Property
245
246              Types:
247
248                 Key = Value = term()
249                 Property = atom() | {term(), term()}
250
251              Creates  a  normal  form  (minimal)  representation  of a simple
252              key/value property. Returns Key if Value is true and Key  is  an
253              atom, otherwise a tuple {Key, Value} is returned.
254
255              See also property/1.
256
257       split(List, Keys) -> {Lists, Rest}
258
259              Types:
260
261                 List = Keys = [term()]
262                 Lists = [[term()]]
263                 Rest = [term()]
264
265              Partitions  List  into a list of sublists and a remainder. Lists
266              contains one sublist for each key in Keys, in the  corresponding
267              order.  The  relative  order  of the elements in each sublist is
268              preserved from the original List. Rest contains the elements  in
269              List  that  are  not  associated with any of the specified keys,
270              also with their original relative order preserved.
271
272              Example:
273
274              split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])
275
276              returns:
277
278              {[[a], [{b, 5}, b],[{c, 2}, {c, 3, 4}]], [{e, 1}, d]}
279
280       substitute_aliases(Aliases, ListIn) -> ListOut
281
282              Types:
283
284                 Aliases = [{Key, Key}]
285                 Key = term()
286                 ListIn = ListOut = [term()]
287
288              Substitutes keys of properties. For each entry in ListIn, if  it
289              is  associated  with  some  key  K1 such that {K1, K2} occurs in
290              Aliases, the key of the entry is changed to K2. If the  same  K1
291              occurs  more  than once in Aliases, only the first occurrence is
292              used.
293
294              For example, substitute_aliases([{color, colour}],  L)  replaces
295              all  tuples  {color, ...} in L with {colour, ...}, and all atoms
296              color with colour.
297
298              See also normalize/2, substitute_negations/2.
299
300       substitute_negations(Negations, ListIn) -> ListOut
301
302              Types:
303
304                 Negations = [{Key1, Key2}]
305                 Key1 = Key2 = term()
306                 ListIn = ListOut = [term()]
307
308              Substitutes keys of boolean-valued properties and simultaneously
309              negates their values. For each entry in ListIn, if it is associ‐
310              ated with some key K1 such that {K1, K2} occurs in Negations: if
311              the  entry was {K1, true}, it is replaced with {K2, false}, oth‐
312              erwise with {K2, true}, thus changing the name of the option and
313              simultaneously  negating  the  value  specified by get_bool(Key,
314              ListIn). If the same K1 occurs more than once in Negations, only
315              the first occurrence is used.
316
317              For  example,  substitute_negations([{no_foo, foo}], L) replaces
318              any atom no_foo or tuple {no_foo, true} in L with {foo,  false},
319              and any other tuple {no_foo, ...} with {foo, true}.
320
321              See also get_bool/2, normalize/2, substitute_aliases/2.
322
323       unfold(ListIn) -> ListOut
324
325              Types:
326
327                 ListIn = ListOut = [term()]
328
329              Unfolds  all  occurrences  of  atoms  in ListIn to tuples {Atom,
330              true}.
331
332
333
334Ericsson AB                       stdlib 3.10                     proplists(3)
Impressum