Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       proplists - Support functions for property lists

DESCRIPTION

       Property  lists  are ordinary lists containing entries in the form of either tuples, whose
       first elements are keys used for lookup and insertion, or atoms, which work  as  shorthand
       for  tuples  {Atom,  true}. (Other terms are allowed in the lists, but are ignored by this
       module.) If there is more than one entry in a list for a certain key, the first occurrence
       normally overrides any later (irrespective of the arity of the tuples).

       Property lists are useful for representing inherited properties, such as options passed to
       a function where a user may  specify  options  overriding  the  default  settings,  object
       properties, annotations, etc.

       Two  keys  are  considered equal if they match (=:=). In other words, numbers are compared
       literally rather than by value, so that, for instance, 1 and 1.0 are different keys.

DATA TYPES

       property() = atom() | tuple()

EXPORTS

       append_values(Key, ListIn) -> ListOut

              Types:

                 Key = term()
                 ListIn = ListOut = [term()]

              Similar to get_all_values/2, but each value is wrapped  in  a  list  unless  it  is
              already  itself  a  list,  and the resulting list of lists is concatenated. This is
              often useful for "incremental" options; e.g., append_values(a, [{a, [1,2]}, {b, 0},
              {a, 3}, {c, -1}, {a, [4]}]) will return the list [1,2,3,4].

       compact(ListIn) -> ListOut

              Types:

                 ListIn = ListOut = [property()]

              Minimizes  the  representation  of  all  entries in the list. This is equivalent to
              [property(P) || P <- ListIn].

              See also: property/1, unfold/1.

       delete(Key, List) -> List

              Types:

                 Key = term()
                 List = [term()]

              Deletes all entries associated with Key from List.

       expand(Expansions, ListIn) -> ListOut

              Types:

                 Expansions = [{Property :: property(), Expansion :: [term()]}]
                 ListIn = ListOut = [term()]

              Expands particular properties to corresponding sets of properties (or other terms).
              For  each  pair  {Property,  Expansion}  in  Expansions, if E is the first entry in
              ListIn with the same key as Property, and E and  Property  have  equivalent  normal
              forms,  then  E  is replaced with the terms in Expansion, and any following entries
              with the same key are deleted from ListIn.

              For example, the following expressions all return [fie, bar, baz, fum]:

                        expand([{foo, [bar, baz]}],
                        [fie, foo, fum])
                        expand([{{foo, true}, [bar, baz]}],
                        [fie, foo, fum])
                        expand([{{foo, false}, [bar, baz]}],
                        [fie, {foo, false}, fum])

              However, no expansion is done in the following call:

                        expand([{{foo, true}, [bar, baz]}],
                        [{foo, false}, fie, foo, fum])

              because {foo, false} shadows foo.

              Note that if the original property term is to  be  preserved  in  the  result  when
              expanded,  it  must  be  included in the expansion list. The inserted terms are not
              expanded recursively. If Expansions contains more than one property with  the  same
              key, only the first occurrence is used.

              See also: normalize/2.

       get_all_values(Key, List) -> [term()]

              Types:

                 Key = term()
                 List = [term()]

              Similar to get_value/2, but returns the list of values for all entries {Key, Value}
              in List. If no such entry exists, the result is the empty list.

              See also: get_value/2.

       get_bool(Key, List) -> boolean()

              Types:

                 Key = term()
                 List = [term()]

              Returns the value of a boolean key/value option. If lookup(Key, List)  would  yield
              {Key, true}, this function returns true; otherwise false is returned.

              See also: get_value/2, lookup/2.

       get_keys(List) -> [term()]

              Types:

                 List = [term()]

              Returns an unordered list of the keys used in List, not containing duplicates.

       get_value(Key, List) -> term()

              Types:

                 Key = term()
                 List = [term()]

              Equivalent to get_value(Key, List, undefined).

       get_value(Key, List, Default) -> term()

              Types:

                 Key = term()
                 List = [term()]
                 Default = term()

              Returns  the  value  of  a  simple key/value property in List. If lookup(Key, List)
              would yield {Key, Value}, this function returns the corresponding Value,  otherwise
              Default is returned.

              See also: get_all_values/2, get_bool/2, get_value/2, lookup/2.

       is_defined(Key, List) -> boolean()

              Types:

                 Key = term()
                 List = [term()]

              Returns  true  if  List  contains at least one entry associated with Key, otherwise
              false is returned.

       lookup(Key, List) -> none | tuple()

              Types:

                 Key = term()
                 List = [term()]

              Returns the first entry associated with Key  in  List,  if  one  exists,  otherwise
              returns  none.  For  an  atom  A  in  the  list,  the  tuple {A, true} is the entry
              associated with A.

              See also: get_bool/2, get_value/2, lookup_all/2.

       lookup_all(Key, List) -> [tuple()]

              Types:

                 Key = term()
                 List = [term()]

              Returns the list of all entries associated with Key  in  List.  If  no  such  entry
              exists, the result is the empty list.

              See also: lookup/2.

       normalize(ListIn, Stages) -> ListOut

              Types:

                 ListIn = [term()]
                 Stages = [Operation]
                 Operation = {aliases, Aliases}
                           | {negations, Negations}
                           | {expand, Expansions}
                 Aliases = Negations = [{Key, Key}]
                 Expansions = [{Property :: property(), Expansion :: [term()]}]
                 ListOut = [term()]

              Passes  ListIn  through a sequence of substitution/expansion stages. For an aliases
              operation, the function substitute_aliases/2 is applied using  the  given  list  of
              aliases;  for  a  negations  operation, substitute_negations/2 is applied using the
              given negation list; for an expand operation,  the  function  expand/2  is  applied
              using  the  given  list  of expansions. The final result is automatically compacted
              (cf. compact/1).

              Typically you want to substitute negations first, then aliases, then perform one or
              more  expansions  (sometimes you want to pre-expand particular entries before doing
              the main  expansion).  You  might  want  to  substitute  negations  and/or  aliases
              repeatedly,  to  allow  such  forms in the right-hand side of aliases and expansion
              lists.

              See also: compact/1, expand/2, substitute_aliases/2, substitute_negations/2.

       property(PropertyIn) -> PropertyOut

              Types:

                 PropertyIn = PropertyOut = property()

              Creates a normal form (minimal) representation of  a  property.  If  PropertyIn  is
              {Key,  true}  where  Key  is  an  atom,  this returns Key, otherwise the whole term
              PropertyIn is returned.

              See also: property/2.

       property(Key, Value) -> Property

              Types:

                 Key = Value = term()
                 Property = atom() | {term(), term()}

              Creates a normal form (minimal) representation  of  a  simple  key/value  property.
              Returns  Key if Value is true and Key is an atom, otherwise a tuple {Key, Value} is
              returned.

              See also: property/1.

       split(List, Keys) -> {Lists, Rest}

              Types:

                 List = Keys = [term()]
                 Lists = [[term()]]
                 Rest = [term()]

              Partitions List into a list of sublists and a remainder. Lists contains one sublist
              for  each  key  in  Keys,  in  the  corresponding  order. The relative order of the
              elements in each sublist is preserved from the original  List.  Rest  contains  the
              elements  in  List  that  are  not associated with any of the given keys, also with
              their original relative order preserved.

              Example: split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])

              returns

              {[[a], [{b, 5}, b],[{c, 2}, {c, 3, 4}]], [{e, 1}, d]}

       substitute_aliases(Aliases, ListIn) -> ListOut

              Types:

                 Aliases = [{Key, Key}]
                 Key = term()
                 ListIn = ListOut = [term()]

              Substitutes keys of properties. For each entry in ListIn, if it is associated  with
              some  key  K1 such that {K1, K2} occurs in Aliases, the key of the entry is changed
              to K2. If the same K1 occurs more than once in Aliases, only the  first  occurrence
              is used.

              Example:  substitute_aliases([{color,  colour}], L) will replace all tuples {color,
              ...} in L with {colour, ...}, and all atoms color with colour.

              See also: normalize/2, substitute_negations/2.

       substitute_negations(Negations, ListIn) -> ListOut

              Types:

                 Negations = [{Key, Key}]
                 Key = term()
                 ListIn = ListOut = [term()]

              Substitutes keys of boolean-valued  properties  and  simultaneously  negates  their
              values.  For  each  entry in ListIn, if it is associated with some key K1 such that
              {K1, K2} occurs in Negations, then if the entry was {K1, true} it will be  replaced
              with  {K2, false}, otherwise it will be replaced with {K2, true}, thus changing the
              name of the option and simultaneously negating the value given by get_bool(ListIn).
              If  the  same  K1  occurs more than once in Negations, only the first occurrence is
              used.

              Example: substitute_negations([{no_foo, foo}], L) will replace any atom  no_foo  or
              tuple {no_foo, true} in L with {foo, false}, and any other tuple {no_foo, ...} with
              {foo, true}.

              See also: get_bool/2, normalize/2, substitute_aliases/2.

       unfold(ListIn) -> ListOut

              Types:

                 ListIn = ListOut = [term()]

              Unfolds all occurrences of atoms in ListIn to tuples {Atom, true}.