aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/proplists.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/stdlib/doc/src/proplists.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/stdlib/doc/src/proplists.xml')
-rw-r--r--lib/stdlib/doc/src/proplists.xml386
1 files changed, 386 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml
new file mode 100644
index 0000000000..a218dcf1fe
--- /dev/null
+++ b/lib/stdlib/doc/src/proplists.xml
@@ -0,0 +1,386 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2002</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>proplists</title>
+ <prepared>Patrik Nyblom</prepared>
+ <responsible>Kenneth Lundin</responsible>
+ <docno>1</docno>
+ <approved>Kenneth Lundin</approved>
+ <checked></checked>
+ <date>2002-09-28</date>
+ <rev>A</rev>
+ <file>proplists.sgml</file>
+ </header>
+ <module>proplists</module>
+ <modulesummary>Support functions for property lists</modulesummary>
+ <description>
+ <p>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 <c>{Atom, true}</c>. (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).</p>
+ <p>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.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>append_values(Key, List) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Similar to <c>get_all_values/2</c>, 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., <c>append_values(a, [{a, [1,2]}, {b, 0}, {a, 3}, {c, -1}, {a, [4]}])</c> will return the list
+ <c>[1,2,3,4]</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>compact(List) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Minimizes the representation of all entries in the list. This is
+ equivalent to <c><![CDATA[[property(P) || P <- List]]]></c>.</p>
+ <p>See also: <c>property/1</c>, <c>unfold/1</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete(Key, List) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Deletes all entries associated with <c>Key</c> from
+ <c>List</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>expand(Expansions, List) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>Expansions = [{Property,[term()]}]</v>
+ <v>Property = atom() | tuple()</v>
+ </type>
+ <desc>
+ <p>Expands particular properties to corresponding sets of
+ properties (or other terms). For each pair <c>{Property, Expansion}</c> in <c>Expansions</c>, if <c>E</c> is
+ the first entry in <c>List</c> with the same key as
+ <c>Property</c>, and <c>E</c> and <c>Property</c>
+ have equivalent normal forms, then <c>E</c> is replaced with
+ the terms in <c>Expansion</c>, and any following entries with
+ the same key are deleted from <c>List</c>.</p>
+ <p>For example, the following expressions all return <c>[fie, bar, baz, fum]</c>:</p>
+ <code type="none">
+ expand([{foo, [bar, baz]}],
+ [fie, foo, fum])
+ expand([{{foo, true}, [bar, baz]}],
+ [fie, foo, fum])
+ expand([{{foo, false}, [bar, baz]}],
+ [fie, {foo, false}, fum])</code>
+ <p>However, no expansion is done in the following call:</p>
+ <code type="none">
+ expand([{{foo, true}, [bar, baz]}],
+ [{foo, false}, fie, foo, fum])</code>
+ <p>because <c>{foo, false}</c> shadows <c>foo</c>.</p>
+ <p>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
+ <c>Expansions</c> contains more than one property with the same
+ key, only the first occurrence is used.</p>
+ <p>See also: <c>normalize/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_all_values(Key, List) -> [term()]</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Similar to <c>get_value/2</c>, but returns the list of
+ values for <em>all</em> entries <c>{Key, Value}</c> in
+ <c>List</c>. If no such entry exists, the result is the empty
+ list.</p>
+ <p>See also: <c>get_value/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_bool(Key, List) -> bool()</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the value of a boolean key/value option. If
+ <c>lookup(Key, List)</c> would yield <c>{Key, true}</c>,
+ this function returns <c>true</c>; otherwise <c>false</c>
+ is returned.</p>
+ <p>See also: <c>get_value/2</c>, <c>lookup/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_keys(List) -> [term()]</name>
+ <fsummary></fsummary>
+ <type>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns an unordered list of the keys used in <c>List</c>,
+ not containing duplicates.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_value(Key, List) -> term()</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Equivalent to <c>get_value(Key, List, undefined)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_value(Key, List, Default) -> term()</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>Default = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the value of a simple key/value property in
+ <c>List</c>. If <c>lookup(Key, List)</c> would yield
+ <c>{Key, Value}</c>, this function returns the corresponding
+ <c>Value</c>, otherwise <c>Default</c> is returned.</p>
+ <p>See also: <c>get_all_values/2</c>, <c>get_bool/2</c>,
+ <c>get_value/2</c>, <c>lookup/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_defined(Key, List) -> bool()</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>List</c> contains at least
+ one entry associated with <c>Key</c>, otherwise
+ <c>false</c> is returned.</p>
+ </desc>
+ </func>
+ <func>
+ <name>lookup(Key, List) -> none | tuple()</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the first entry associated with <c>Key</c> in
+ <c>List</c>, if one exists, otherwise returns
+ <c>none</c>. For an atom <c>A</c> in the list, the tuple
+ <c>{A, true}</c> is the entry associated with <c>A</c>.</p>
+ <p>See also: <c>get_bool/2</c>, <c>get_value/2</c>,
+ <c>lookup_all/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>lookup_all(Key, List) -> [tuple()]</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the list of all entries associated with <c>Key</c>
+ in <c>List</c>. If no such entry exists, the result is the
+ empty list.</p>
+ <p>See also: <c>lookup/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>normalize(List, Stages) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>List = [term()]</v>
+ <v>Stages = [Operation]</v>
+ <v>Operation = {aliases, Aliases} | {negations, Negations} | {expand, Expansions}</v>
+ <v>Aliases = [{Key, Key}]</v>
+ <v>Negations = [{Key, Key}]</v>
+ <v>Key = term()</v>
+ <v>Expansions = [{Property, [term()]}]</v>
+ <v>Property = atom() | tuple()</v>
+ </type>
+ <desc>
+ <p>Passes <c>List</c> through a sequence of
+ substitution/expansion stages. For an <c>aliases</c> operation,
+ the function <c>substitute_aliases/2</c> is applied using the
+ given list of aliases; for a <c>negations</c> operation,
+ <c>substitute_negations/2</c> is applied using the given
+ negation list; for an <c>expand</c> operation, the function
+ <c>expand/2</c> is applied using the given list of expansions.
+ The final result is automatically compacted (cf.
+ <c>compact/1</c>).</p>
+ <p>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.</p>
+ <p>See also: <c>compact/1</c>, <c>expand/2</c>,
+ <c>substitute_aliases/2</c>, <c>substitute_negations/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>property(Property) -> Property</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Property = atom() | tuple()</v>
+ </type>
+ <desc>
+ <p>Creates a normal form (minimal) representation of a property. If
+ <c>Property</c> is <c>{Key, true}</c> where <c>Key</c> is
+ an atom, this returns <c>Key</c>, otherwise the whole term
+ <c>Property</c> is returned.</p>
+ <p>See also: <c>property/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>property(Key, Value) -> Property</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>Value = term()</v>
+ <v>Property = atom() | tuple()</v>
+ </type>
+ <desc>
+ <p>Creates a normal form (minimal) representation of a simple
+ key/value property. Returns <c>Key</c> if <c>Value</c> is
+ <c>true</c> and <c>Key</c> is an atom, otherwise a tuple
+ <c>{Key, Value}</c> is returned.</p>
+ <p>See also: <c>property/1</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>split(List, Keys) -> {Lists, Rest}</name>
+ <fsummary></fsummary>
+ <type>
+ <v>List = [term()]</v>
+ <v>Keys = [term()]</v>
+ <v>Lists = [[term()]]</v>
+ <v>Rest = [term()]</v>
+ </type>
+ <desc>
+ <p>Partitions <c>List</c> into a list of sublists and a
+ remainder. <c>Lists</c> contains one sublist for each key in
+ <c>Keys</c>, in the corresponding order. The relative order of
+ the elements in each sublist is preserved from the original
+ <c>List</c>. <c>Rest</c> contains the elements in
+ <c>List</c> that are not associated with any of the given keys,
+ also with their original relative order preserved.</p>
+ <p>Example:
+ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</p>
+ <p>returns</p>
+ <p>{[[a], [{b, 5}, b],[{c, 2}, {c, 3, 4}]], [{e, 1}, d]}</p>
+ </desc>
+ </func>
+ <func>
+ <name>substitute_aliases(Aliases, List) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Aliases = [{Key, Key}]</v>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Substitutes keys of properties. For each entry in
+ <c>List</c>, if it is associated with some key <c>K1</c>
+ such that <c>{K1, K2}</c> occurs in <c>Aliases</c>, the
+ key of the entry is changed to <c>Key2</c>. If the same
+ <c>K1</c> occurs more than once in <c>Aliases</c>, only
+ the first occurrence is used.</p>
+ <p>Example: <c>substitute_aliases([{color, colour}], L)</c>
+ will replace all tuples <c>{color, ...}</c> in <c>L</c>
+ with <c>{colour, ...}</c>, and all atoms <c>color</c>
+ with <c>colour</c>.</p>
+ <p>See also: <c>normalize/2</c>, <c>substitute_negations/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>substitute_negations(Negations, List) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>Negations = [{Key, Key}]</v>
+ <v>Key = term()</v>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Substitutes keys of boolean-valued properties and
+ simultaneously negates their values. For each entry in
+ <c>List</c>, if it is associated with some key <c>K1</c>
+ such that <c>{K1, K2}</c> occurs in <c>Negations</c>, then
+ if the entry was <c>{K1, true}</c> it will be replaced with
+ <c>{K2, false}</c>, otherwise it will be replaced with
+ <c>{K2, true}</c>, thus changing the name of the option and
+ simultaneously negating the value given by
+ <c>get_bool(List)</c>. If the same <c>K1</c> occurs more
+ than once in <c>Negations</c>, only the first occurrence is
+ used.</p>
+ <p>Example: <c>substitute_negations([{no_foo, foo}], L)</c>
+ will replace any atom <c>no_foo</c> or tuple
+ <c>{no_foo, true}</c> in <c>L</c> with <c>{foo, false}</c>,
+ and any other tuple <c>{no_foo, ...}</c> with
+ <c>{foo, true}</c>.</p>
+ <p>See also: <c>get_bool/2</c>, <c>normalize/2</c>,
+ <c>substitute_aliases/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>unfold(List) -> List</name>
+ <fsummary></fsummary>
+ <type>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Unfolds all occurrences of atoms in <c>List</c> to tuples
+ <c>{Atom, true}</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+