👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for proplists (linux section 3erl)

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 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  prop-
       erties, 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 Expansions , 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 ; 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()
		     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	,  other-
	      wise 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 associ-
	      ated 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, Expan-
		     sions}
		     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	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 repeat-
	      edly, 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, otherwise 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 ele-
	      ments in each sublist is preserved from the original List . Rest contains the  ele-
	      ments  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  occur-
	      rence 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 val-
	      ues.  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)


All times are GMT -4. The time now is 05:23 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?