proplists(3erl) 					     Erlang Module Definition						   proplists(3erl)

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 inser-
       tion, 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.

EXPORTS

       append_values(Key, List) -> List

	      Types  Key = term()
		     List = [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(List) -> List

	      Types  List = [term()]

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

	      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, List) -> List

	      Types  Key = term()
		     Expansions = [{Property,[term()]}]
		     Property = atom() | tuple()

	      Expands particular properties to corresponding sets of properties (or other terms). For each pair {Property,  Expansion}	in  Expan-
	      sions  ,	if E is the first entry in List 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 List .

	      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) -> bool()

	      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 ; other-
	      wise 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()
		     Default = term()
		     List = [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) -> bool()

	      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(List, Stages) -> List

	      Types  List = [term()]
		     Stages = [Operation]
		     Operation = {aliases, Aliases} | {negations, Negations} | {expand, Expansions}
		     Aliases = [{Key, Key}]
		     Negations = [{Key, Key}]
		     Key = term()
		     Expansions = [{Property, [term()]}]
		     Property = atom() | tuple()

	      Passes List 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 com-
	      pacted (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(Property) -> Property

	      Types  Property = atom() | tuple()

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

	      See also: property/2 .

       property(Key, Value) -> Property

	      Types  Key = term()
		     Value = term()
		     Property = atom() | tuple()

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

	      See also: property/1 .

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

	      Types  List = [term()]
		     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, List) -> List

	      Types  Aliases = [{Key, Key}]
		     Key = term()
		     List = [term()]

	      Substitutes keys of properties. For each entry in List , if it is associated with some key K1 such that {K1, K2} occurs in Aliases ,
	      the key of the entry is changed to Key2 . 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, List) -> List

	      Types  Negations = [{Key, Key}]
		     Key = term()
		     List = [term()]

	      Substitutes  keys of boolean-valued properties and simultaneously negates their values. For each entry in List , 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(List) . 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(List) -> List

	      Types  List = [term()]

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

Ericsson AB							   stdlib 1.17.3						   proplists(3erl)