diff options
Diffstat (limited to 'lib/stdlib/doc/src/qlc.xml')
| -rw-r--r-- | lib/stdlib/doc/src/qlc.xml | 646 |
1 files changed, 287 insertions, 359 deletions
diff --git a/lib/stdlib/doc/src/qlc.xml b/lib/stdlib/doc/src/qlc.xml index da24ee9914..6a45ade447 100644 --- a/lib/stdlib/doc/src/qlc.xml +++ b/lib/stdlib/doc/src/qlc.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2004</year><year>2009</year> + <year>2004</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -45,7 +45,9 @@ tables</em>. Typical QLC tables are ETS, Dets, and Mnesia tables. There is also support for user defined tables, see the <seealso marker="#implementing_a_qlc_table">Implementing a QLC - table</seealso> section. A <em>query</em> is stated using + table</seealso> section. <marker + id="query_list_comprehension"></marker> + A <em>query</em> is stated using <em>Query List Comprehensions</em> (QLCs). The answers to a query are determined by data in QLC tables that fulfill the constraints expressed by the QLCs of the query. QLCs are similar @@ -55,10 +57,11 @@ fact, in the absence of optimizations and options such as <c>cache</c> and <c>unique</c> (see below), every QLC free of QLC tables evaluates to the same list of answers as the - identical ordinary list comprehension. </p> + identical ordinary list comprehension.</p> <p>While ordinary list comprehensions evaluate to lists, calling - <seealso marker="#q">qlc:q/1,2</seealso> returns a <em>Query + <seealso marker="#q">qlc:q/1,2</seealso> returns a <marker + id="query_handle"></marker><em> Query Handle</em>. To obtain all the answers to a query, <seealso marker="#eval">qlc:eval/1,2</seealso> should be called with the query handle as first argument. Query handles are essentially @@ -69,7 +72,8 @@ Code replacement is described in the <seealso marker="doc/reference_manual:code_loading">Erlang Reference Manual</seealso>. The list of answers can also be traversed in - chunks by use of a <em>Query Cursor</em>. Query cursors are + chunks by use of a <marker + id="query_cursor"></marker><em>Query Cursor</em>. Query cursors are created by calling <seealso marker="#cursor">qlc:cursor/1,2</seealso> with a query handle as first argument. Query cursors are essentially Erlang processes. @@ -226,75 +230,6 @@ </section> - <section><title>Common data types</title> - - <list type="bulleted"> - <item><p><c>QueryCursor = {qlc_cursor, term()}</c></p> - </item> - <item><p><c>QueryHandle = {qlc_handle, term()}</c></p> - </item> - <item><p><c>QueryHandleOrList = QueryHandle | list()</c></p> - </item> - <item><p><c>Answers = [Answer]</c></p> - </item> - <item><p><c>Answer = term()</c></p> - </item> - <item><p><c>AbstractExpression = </c> - parse trees - for Erlang expressions, see the <seealso - marker="erts:absform">abstract format</seealso> - documentation in the ERTS User's Guide -</p> - </item> - <item><p><c>MatchExpression = </c> - - match specifications, see the <seealso - marker="erts:match_spec">match specification</seealso> - documentation in the ERTS User's Guide and <seealso - marker="ms_transform">ms_transform(3)</seealso> -</p> - </item> - <item><p><c>SpawnOptions = default | spawn_options()</c></p> - </item> - <item><p><c>SortOptions = [SortOption] | SortOption</c></p> - </item> - <item><p><c>SortOption = {compressed, bool()} - | {no_files, NoFiles} - | {order, Order} - | {size, Size} - | {tmpdir, TempDirectory} - | {unique, bool()} </c> - - see <seealso - marker="file_sorter">file_sorter(3)</seealso> -</p> - </item> - <item><p><c>Order = ascending | descending | OrderFun</c></p> - </item> - <item><p><c>OrderFun = fun(term(), term()) -> bool()</c></p> - </item> - <item><p><c>TempDirectory = "" | filename()</c></p> - </item> - <item><p><c>Size = int() > 0</c></p> - </item> - <item><p><c>NoFiles = int() > 1</c></p> - </item> - <item><p><c>KeyPos = int() > 0 | [int() > 0]</c></p> - </item> - <item><p><c>MaxListSize = int() >= 0</c></p> - </item> - <item><p><c>bool() = true | false</c></p> - </item> - <item><p><c>Cache = ets | list | no</c></p> - </item> - <item><p><c>TmpFileUsage = allowed | not_allowed | info_msg - | warning_msg | error_msg</c></p> - </item> - <item><p><c>filename() = </c> - see <seealso - marker="filename">filename(3)</seealso> -</p> - </item> - <item><p><c>spawn_options() = </c> - see <seealso - marker="erts:erlang">erlang(3)</seealso> -</p> - </item> - - </list> - - </section> - <section><title>Getting started</title> <p><marker id="getting_started"></marker> As already mentioned @@ -679,34 +614,105 @@ ets:match_spec_run(ets:lookup(86033, {2,2}), </section> + <datatypes> + <datatype> + <name name="abstract_expr"></name> + <desc><p>Parse trees for Erlang expression, see the <seealso + marker="erts:absform">abstract format</seealso> + documentation in the ERTS User's Guide.</p></desc> + </datatype> + <datatype> + <name name="answer"></name> + </datatype> + <datatype> + <name name="answers"></name> + </datatype> + <datatype> + <name name="cache"></name> + </datatype> + <datatype> + <name name="match_expression"></name> + <desc><p>Match specification, see the <seealso + marker="erts:match_spec">match specification</seealso> + documentation in the ERTS User's Guide and <seealso + marker="ms_transform">ms_transform(3).</seealso></p></desc> + </datatype> + <datatype> + <name name="no_files"></name> + <desc><p>Actually an integer > 1.</p></desc> + </datatype> + <datatype> + <name name="key_pos"></name> + </datatype> + <datatype> + <name name="max_list_size"></name> + </datatype> + <datatype> + <name name="order"></name> + </datatype> + <datatype> + <name name="order_fun"></name> + </datatype> + <datatype> + <name name="query_cursor"></name> + <desc><p>A <seealso marker="#query_cursor">query cursor</seealso>.</p> + </desc> + </datatype> + <datatype> + <name name="query_handle"></name> + <desc><p>A <seealso marker="#query_handle">query handle</seealso>.</p> + </desc> + </datatype> + <datatype> + <name name="query_handle_or_list"></name> + </datatype> + <datatype> + <name name="query_list_comprehension"></name> + <desc><p>A literal + <seealso marker="#query_list_comprehension">query + list comprehension</seealso>.</p></desc> + </datatype> + <datatype> + <name name="spawn_options"></name> + </datatype> + <datatype> + <name name="sort_options"></name> + </datatype> + <datatype> + <name name="sort_option"></name> + <desc><p>See <seealso + marker="file_sorter">file_sorter(3)</seealso>.</p></desc> + </datatype> + <datatype> + <name name="tmp_directory"></name> + </datatype> + <datatype> + <name name="tmp_file_usage"></name> + <desc><p></p></desc> + </datatype> + </datatypes> + <funcs> <func> - <name>append(QHL) -> QH</name> + <name name="append" arity="1"/> <fsummary>Return a query handle.</fsummary> - <type> - <v>QHL = [QueryHandleOrList]</v> - <v>QH = QueryHandle</v> - </type> <desc> <p>Returns a query handle. When evaluating the query handle - <c>QH</c> all answers to the first query handle in - <c>QHL</c> is returned followed by all answers to the rest - of the query handles in <c>QHL</c>.</p> + <c><anno>QH</anno></c> all answers to the first query handle in + <c><anno>QHL</anno></c> are returned followed by all answers + to the rest of the query handles in <c><anno>QHL</anno></c>.</p> </desc> </func> <func> - <name>append(QH1, QH2) -> QH3</name> + <name name="append" arity="2"/> <fsummary>Return a query handle.</fsummary> - <type> - <v>QH1 = QH2 = QueryHandleOrList</v> - <v>QH3 = QueryHandle</v> - </type> <desc> <p>Returns a query handle. When evaluating the query handle - <c>QH3</c> all answers to <c>QH1</c> are returned followed - by all answers to <c>QH2</c>.</p> + <c><anno>QH3</anno></c> all answers to + <c><anno>QH1</anno></c> are returned followed by all answers + to <c><anno>QH2</anno></c>.</p> <p><c>append(QH1, QH2)</c> is equivalent to <c>append([QH1, QH2])</c>.</p> @@ -714,17 +720,9 @@ ets:match_spec_run(ets:lookup(86033, {2,2}), </func> <func> - <name>cursor(QueryHandleOrList [, Options]) -> QueryCursor</name> + <name name="cursor" arity="1"/> + <name name="cursor" arity="2"/> <fsummary>Create a query cursor.</fsummary> - <type> - <v>Options = [Option] | Option</v> - <v>Option = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {spawn_options, SpawnOptions} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all</v> - </type> <desc> <p><marker id="cursor"></marker>Creates a query cursor and makes the calling process the owner of the cursor. The @@ -746,11 +744,13 @@ ets:match_spec_run(ets:lookup(86033, {2,2}), [{b,1},{b,2}] 4> <input>qlc:delete_cursor(QC).</input> ok</pre> + <p><c>cursor(<anno>QH</anno>)</c> is equivalent to + <c>cursor(<anno>QH</anno>, [])</c>.</p> </desc> </func> <func> - <name>delete_cursor(QueryCursor) -> ok</name> + <name name="delete_cursor" arity="1"/> <fsummary>Delete a query cursor.</fsummary> <desc> <p>Deletes a query cursor. Only the owner of the cursor can @@ -759,19 +759,11 @@ ok</pre> </func> <func> - <name>eval(QueryHandleOrList [, Options]) -> Answers | Error</name> - <name>e(QueryHandleOrList [, Options]) -> Answers</name> + <name name="eval" arity="1"/> + <name name="eval" arity="2"/> + <name name="e" arity="1"/> + <name name="e" arity="2"/> <fsummary>Return all answers to a query.</fsummary> - <type> - <v>Options = [Option] | Option</v> - <v>Option = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all</v> - <v>Error = {error, module(), Reason}</v> - <v>Reason = - as returned by file_sorter(3) -</v> - </type> <desc> <p><marker id="eval"></marker>Evaluates a query handle in the calling process and collects all answers in a list.</p> @@ -780,47 +772,39 @@ ok</pre> 1> <input>QH = qlc:q([{X,Y} || X <- [a,b], Y <- [1,2]]),</input> <input>qlc:eval(QH).</input> [{a,1},{a,2},{b,1},{b,2}]</pre> + <p><c>eval(<anno>QH</anno>)</c> is equivalent to + <c>eval(<anno>QH</anno>, [])</c>.</p> </desc> </func> <func> - <name>fold(Function, Acc0, QueryHandleOrList [, Options]) -> - Acc1 | Error</name> + <name name="fold" arity="3"/> + <name name="fold" arity="4"/> <fsummary>Fold a function over the answers to a query.</fsummary> - <type> - <v>Function = fun(Answer, AccIn) -> AccOut</v> - <v>Acc0 = Acc1 = AccIn = AccOut = term()</v> - <v>Options = [Option] | Option</v> - <v>Option = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all</v> - <v>Error = {error, module(), Reason}</v> - <v>Reason = - as returned by file_sorter(3) -</v> - </type> <desc> - <p>Calls <c>Function</c> on successive answers to the query - handle together with an extra argument <c>AccIn</c>. The - query handle and the function are evaluated in the calling - process. <c>Function</c> must return a new accumulator which - is passed to the next call. <c>Acc0</c> is returned if there - are no answers to the query handle.</p> + <p>Calls <c><anno>Function</anno></c> on successive answers to + the query handle together with an extra argument + <c><anno>AccIn</anno></c>. The query handle and the function + are evaluated in the calling process. + <c><anno>Function</anno></c> must return a new accumulator + which is passed to the next call. + <c><anno>Acc0</anno></c> is returned if there are no answers + to the query handle.</p> <pre> 1> <input>QH = [1,2,3,4,5,6],</input> <input>qlc:fold(fun(X, Sum) -> X + Sum end, 0, QH).</input> 21</pre> + <p><c>fold(<anno>Function</anno>, <anno>Acc0</anno>, + <anno>QH</anno>)</c> is equivalent to + <c>fold(<anno>Function</anno>, <anno>Acc0</anno>, + <anno>QH</anno>, [])</c>.</p> </desc> </func> <func> - <name>format_error(Error) -> Chars</name> + <name name="format_error" arity="1"/> <fsummary>Return an English description of a an error tuple.</fsummary> - <type> - <v>Error = {error, module(), term()}</v> - <v>Chars = [char() | Chars]</v> - </type> <desc> <p>Returns a descriptive string in English of an error tuple returned by some of the functions of the <c>qlc</c> module @@ -830,25 +814,9 @@ ok</pre> </func> <func> - <name>info(QueryHandleOrList [, Options]) -> Info</name> + <name name="info" arity="1"/> + <name name="info" arity="2"/> <fsummary>Return code describing a query handle.</fsummary> - <type> - <v>Options = [Option] | Option</v> - <v>Option = EvalOption | ReturnOption</v> - <v>EvalOption = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all</v> - <v>ReturnOption = {depth, Depth} - | {flat, bool()} - | {format, Format} - | {n_elements, NElements}</v> - <v>Depth = infinity | int() >= 0</v> - <v>Format = abstract_code | string</v> - <v>NElements = infinity | int() > 0</v> - <v>Info = AbstractExpression | string()</v> - </type> <desc> <p><marker id="info"></marker>Returns information about a query handle. The information describes the simplifications @@ -879,18 +847,18 @@ ok</pre> <input>io:format("~s~n", [qlc:info(QH, unique_all)]).</input> begin V1 = - qlc:q([ + qlc:q([ SQV || SQV <- [x,y] ], [{unique,true}]), V2 = - qlc:q([ + qlc:q([ SQV || SQV <- [a,b] ], [{unique,true}]), - qlc:q([ + qlc:q([ {X,Y} || X <- V1, Y <- V2 @@ -913,19 +881,19 @@ end</pre> <input>io:format("~s~n", [qlc:info(Q)]).</input> begin V1 = - qlc:q([ + qlc:q([ P0 || P0 = {W,Y} <- ets:table(17) ]), V2 = - qlc:q([ + qlc:q([ [G1|G2] || G2 <- V1, G1 <- ets:table(16), element(2, G1) =:= element(1, G2) ], [{join,lookup}]), - qlc:q([ + qlc:q([ {X,Z,W} || [{X,Z}|{W,Y}] <- V2 ]) @@ -936,44 +904,43 @@ end</pre> method chosen. A convention is used for lookup join: the first generator (<c>G2</c>) is the one traversed, the second one (<c>G1</c>) is the table where constants are looked up.</p> + + <p><c>info(<anno>QH</anno>)</c> is equivalent to + <c>info(<anno>QH</anno>, [])</c>.</p> </desc> </func> <func> - <name>keysort(KeyPos, QH1 [, SortOptions]) -> QH2</name> + <name name="keysort" arity="2"/> + <name name="keysort" arity="3"/> <fsummary>Return a query handle.</fsummary> - <type> - <v>QH1 = QueryHandleOrList</v> - <v>QH2 = QueryHandle</v> - </type> <desc> <p>Returns a query handle. When evaluating the query handle - <c>QH2</c> the answers to the query handle <c>QH1</c> are - sorted by <seealso + <c><anno>QH2</anno></c> the answers to the query handle + <c><anno>QH1</anno></c> are sorted by <seealso marker="file_sorter">file_sorter:keysort/4</seealso> according to the options.</p> - <p>The sorter will use temporary files only if <c>QH1</c> does - not evaluate to a list and the size of the binary - representation of the answers exceeds <c>Size</c> bytes, - where <c>Size</c> is the value of the <c>size</c> option.</p> + <p>The sorter will use temporary files only if + <c><anno>QH1</anno></c> does not evaluate to a list and the + size of the binary representation of the answers exceeds + <c>Size</c> bytes, where <c>Size</c> is the value of the + <c>size</c> option.</p> + + <p><c>keysort(<anno>KeyPos</anno>, <anno>QH1</anno>)</c> + is equivalent to + <c>keysort(<anno>KeyPos</anno>, <anno>QH1</anno>, [])</c>.</p> </desc> </func> <func> - <name>next_answers(QueryCursor [, NumberOfAnswers]) -> - Answers | Error</name> + <name name="next_answers" arity="1"/> + <name name="next_answers" arity="2"/> <fsummary>Return some or all answers to a query.</fsummary> - <type> - <v>NumberOfAnswers = all_remaining | int() > 0</v> - <v>Error = {error, module(), Reason}</v> - <v>Reason = - as returned by file_sorter(3) -</v> - </type> <desc> <p>Returns some or all of the remaining answers to a query - cursor. Only the owner of <c>Cursor</c> can retrieve - answers.</p> - + cursor. Only the owner of <c><anno>QueryCursor</anno></c> can + retrieve answers.</p> <p>The optional argument <c>NumberOfAnswers</c>determines the maximum number of answers returned. The default value is <c>10</c>. If less than the requested number of answers is @@ -983,21 +950,9 @@ end</pre> </func> <func> - <name>q(QueryListComprehension [, Options]) -> QueryHandle</name> + <name name="q" arity="1"/> + <name name="q" arity="2"/> <fsummary>Return a handle for a query list comprehension.</fsummary> - <type> - <v>QueryListComprehension = - - literal query listcomprehension -</v> - <v>Options = [Option] | Option</v> - <v>Option = {max_lookup, MaxLookup} - | {cache, Cache} | cache - | {join, Join} - | {lookup, Lookup} - | {unique, bool()} | unique</v> - <v>MaxLookup = int() >= 0 | infinity</v> - <v>Join = any | lookup | merge | nested_loop</v> - <v>Lookup = bool() | any</v> - </type> <desc> <p><marker id="q"></marker>Returns a query handle for a query list comprehension. The query list comprehension must be the @@ -1024,7 +979,7 @@ end</pre> <pre> ... -A = [X || {X} <- [{1},{2}]], +A = [X || {X} <- [{1},{2}]], QH = qlc:q(A), ...</pre> @@ -1034,6 +989,9 @@ QH = qlc:q(A), list comprehension"); the shell process stops with a <c>badarg</c> reason.</p> + <p><c>q(<anno>QLC</anno>)</c> is equivalent to + <c>q(<anno>QLC</anno>, [])</c>.</p> + <p>The <c>{cache, ets}</c> option can be used to cache the answers to a query list comprehension. The answers are stored in one ETS table for each cached query list @@ -1092,26 +1050,26 @@ QH = qlc:q(A), <input>io:format("~s~n", [qlc:info(Q)]).</input> begin V1 = - qlc:q([ + qlc:q([ P0 || P0 = {X,Z} <- qlc:keysort(1, [{a,1},{b,4},{c,6}], []) ]), V2 = - qlc:q([ + qlc:q([ P0 || P0 = {W,Y} <- qlc:keysort(2, [{2,a},{3,b},{4,c}], []) ]), V3 = - qlc:q([ + qlc:q([ [G1|G2] || G1 <- V1, G2 <- V2, element(1, G1) == element(2, G2) ], [{join,merge},{cache,list}]), - qlc:q([ + qlc:q([ {A,X,Z,W} || A <- [a,b,c], [{X,Z}|{W,Y}] <- V3, @@ -1170,7 +1128,7 @@ ets:match_spec_run( elements of the key {X, Y} are compared separately.</p> <p>The <c>{lookup, true}</c> option can be used to ensure - that the <c>qlc</c> module will look up constants in some + that the <c>qlc</c> module will look up constants in some QLC table. If there are more than one QLC table among the generators' list expressions, constants have to be looked up in at least one @@ -1190,7 +1148,7 @@ ets:match_spec_run( <c>{join, nested_loop}</c> invokes the method of matching every pair of objects from two handles. The last method is mostly very slow. The evaluation of the query - fails if the <c>qlc</c> module cannot carry out the chosen + fails if the <c>qlc</c> module cannot carry out the chosen join method. The default value is <c>any</c> which means that some fast join method will be used if possible.</p> @@ -1198,47 +1156,33 @@ ets:match_spec_run( </func> <func> - <name>sort(QH1 [, SortOptions]) -> QH2</name> + <name name="sort" arity="1"/> + <name name="sort" arity="2"/> <fsummary>Return a query handle.</fsummary> - <type> - <v>QH1 = QueryHandleOrList</v> - <v>QH2 = QueryHandle</v> - </type> <desc> <p>Returns a query handle. When evaluating the query handle - <c>QH2</c> the answers to the query handle <c>QH1</c> are - sorted by <seealso + <c><anno>QH2</anno></c> the answers to the query handle + <c><anno>QH1</anno></c> are sorted by <seealso marker="file_sorter">file_sorter:sort/3</seealso> according to the options.</p> - <p>The sorter will use temporary files only if <c>QH1</c> does - not evaluate to a list and the size of the binary - representation of the answers exceeds <c>Size</c> bytes, - where <c>Size</c> is the value of the <c>size</c> option.</p> + <p>The sorter will use temporary files only if + <c><anno>QH1</anno></c> does not evaluate to a list and the + size of the binary representation of the answers exceeds + <c>Size</c> bytes, where <c>Size</c> is the value of the + <c>size</c> option.</p> + + <p><c>sort(<anno>QH1</anno>)</c> is equivalent to + <c>sort(<anno>QH1</anno>, [])</c>.</p> + </desc> </func> <func> - <name>string_to_handle(QueryString [, Options [, Bindings]]) -> - QueryHandle | Error</name> + <name name="string_to_handle" arity="1"/> + <name name="string_to_handle" arity="2"/> + <name name="string_to_handle" arity="3"/> <fsummary>Return a handle for a query list comprehension.</fsummary> - <type> - <v>QueryString = string()</v> - <v>Options = [Option] | Option</v> - <v>Option = {max_lookup, MaxLookup} - | {cache, Cache} | cache - | {join, Join} - | {lookup, Lookup} - | {unique, bool()} | unique</v> - <v>MaxLookup = int() >= 0 | infinity</v> - <v>Join = any | lookup | merge | nested_loop</v> - <v>Lookup = bool() | any</v> - <v>Bindings = - as returned by - erl_eval:bindings/1 -</v> - <v>Error = {error, module(), Reason}</v> - <v>Reason = - ErrorInfo as returned by - erl_scan:string/1 or erl_parse:parse_exprs/1 -</v> - </type> <desc> <p>A string version of <c>qlc:q/1,2</c>. When the query handle is evaluated the fun created by the parse transform is @@ -1253,57 +1197,24 @@ ets:match_spec_run( <input>qlc:eval(QH).</input> [2,3,4]</pre> + <p><c>string_to_handle(<anno>QueryString</anno>)</c> + is equivalent to + <c>string_to_handle(<anno>QueryString</anno>, [])</c>.</p> + + <p><c>string_to_handle(<anno>QueryString</anno>, + <anno>Options</anno>)</c> + is equivalent to + <c>string_to_handle(<anno>QueryString</anno>, + <anno>Options</anno>, erl_eval:new_bindings())</c>.</p> + <p>This function is probably useful mostly when called from outside of Erlang, for instance from a driver written in C.</p> </desc> </func> <func> - <name>table(TraverseFun, Options) -> QueryHandle</name> + <name name="table" arity="2"/> <fsummary>Return a query handle for a table.</fsummary> - <type> - <v>TraverseFun = TraverseFun0 | TraverseFun1</v> - <v>TraverseFun0 = fun() -> TraverseResult</v> - <v>TraverseFun1 = fun(MatchExpression) -> TraverseResult</v> - <v>TraverseResult = Objects | term()</v> - <v>Objects = [] | [term() | ObjectList]</v> - <v>ObjectList = TraverseFun0 | Objects</v> - <v>Options = [Option] | Option</v> - <v>Option = {format_fun, FormatFun} - | {info_fun, InfoFun} - | {lookup_fun, LookupFun} - | {parent_fun, ParentFun} - | {post_fun, PostFun} - | {pre_fun, PreFun} - | {key_equality, KeyComparison}</v> - <v>FormatFun = undefined | fun(SelectedObjects) -> FormatedTable</v> - <v>SelectedObjects = all - | {all, NElements, DepthFun} - | {match_spec, MatchExpression} - | {lookup, Position, Keys} - | {lookup, Position, Keys, NElements, DepthFun}</v> - <v>NElements = infinity | int() > 0</v> - <v>DepthFun = fun(term()) -> term()</v> - <v>FormatedTable = {Mod, Fun, Args} - | AbstractExpression - | character_list()</v> - <v>InfoFun = undefined | fun(InfoTag) -> InfoValue</v> - <v>InfoTag = indices | is_unique_objects | keypos | num_of_objects</v> - <v>InfoValue = undefined | term()</v> - <v>LookupFun = undefined | fun(Position, Keys) -> LookupResult</v> - <v>LookupResult = [term()] | term()</v> - <v>ParentFun = undefined | fun() -> ParentFunValue</v> - <v>PostFun = undefined | fun() -> void()</v> - <v>PreFun = undefined | fun([PreArg]) -> void()</v> - <v>PreArg = {parent_value, ParentFunValue} | {stop_fun, StopFun}</v> - <v>ParentFunValue = undefined | term()</v> - <v>StopFun = undefined | fun() -> void()</v> - <v>KeyComparison = '=:=' | '=='</v> - <v>Position = int() > 0</v> - <v>Keys = [term()]</v> - <v>Mod = Fun = atom()</v> - <v>Args = [term()]</v> - </type> <desc> <p><marker id="table"></marker>Returns a query handle for a QLC table. In Erlang/OTP there is support for ETS, Dets and @@ -1315,77 +1226,90 @@ ets:match_spec_run( as well as properties of the table are handled by callback functions provided as options to <c>qlc:table/2</c>.</p> - <p>The callback function <c>TraverseFun</c> is used for - traversing the table. It is to return a list of objects - terminated by either <c>[]</c> or a nullary fun to be used - for traversing the not yet traversed objects of the table. - Any other return value is immediately returned as value of - the query evaluation. Unary <c>TraverseFun</c>s are to - accept a match specification as argument. The match - specification is created by the parse transform by analyzing - the pattern of the generator calling <c>qlc:table/2</c> and - filters using variables introduced in the pattern. If the - parse transform cannot find a match specification equivalent - to the pattern and filters, <c>TraverseFun</c> will be - called with a match specification returning every object. - Modules that can utilize match specifications for optimized + <p>The callback function <c><anno>TraverseFun</anno></c> is + used for traversing the table. It is to return a list of + objects terminated by either <c>[]</c> or a nullary fun to + be used for traversing the not yet traversed objects of the + table. Any other return value is immediately returned as + value of the query evaluation. Unary + <c><anno>TraverseFun</anno></c>s are to accept a match + specification as argument. The match specification is + created by the parse transform by analyzing the pattern of + the generator calling <c>qlc:table/2</c> and filters using + variables introduced in the pattern. If the parse transform + cannot find a match specification equivalent to the pattern + and filters, <c><anno>TraverseFun</anno></c> will be called + with a match specification returning every object. Modules + that can utilize match specifications for optimized traversal of tables should call <c>qlc:table/2</c> with a - unary <c>TraverseFun</c> while other modules can provide a - nullary <c>TraverseFun</c>. <c>ets:table/2</c> is an example - of the former; <c>gb_table:table/1</c> in the <seealso - marker="#implementing_a_qlc_table">Implementing a QLC - table</seealso> section is an example of the latter.</p> - - <p><c>PreFun</c> is a unary callback function that is called - once before the table is read for the first time. If the - call fails, the query evaluation fails. Similarly, the - nullary callback function <c>PostFun</c> is called once - after the table was last read. The return value, which is - caught, is ignored. If <c>PreFun</c> has been called for a - table, <c>PostFun</c> is guaranteed to be called for that - table, even if the evaluation of the query fails for some - reason. The order in which pre (post) functions for + unary + <c><anno>TraverseFun</anno></c> while other modules can + provide a nullary + <c><anno>TraverseFun</anno></c>. <c>ets:table/2</c> is an + example of the former; <c>gb_table:table/1</c> in the + <seealso marker="#implementing_a_qlc_table">Implementing a + QLC table</seealso> section is an example of the latter.</p> + + <p><c><anno>PreFun</anno></c> is a unary callback function + that is called once before the table is read for the first + time. If the call fails, the query evaluation fails. + Similarly, the nullary callback function + <c><anno>PostFun</anno></c> is called once after the table + was last read. The return value, which is caught, is + ignored. If <c><anno>PreFun</anno></c> has been called for a + table, + <c><anno>PostFun</anno></c> is guaranteed to be called for + that table, even if the evaluation of the query fails for + some reason. The order in which pre (post) functions for different tables are evaluated is not specified. Other table - access than reading, such as calling <c>InfoFun</c>, is - assumed to be OK at any time. The argument <c>PreArgs</c> is - a list of tagged values. Currently there are two tags, + access than reading, such as calling + <c><anno>InfoFun</anno></c>, is assumed to be OK at any + time. The argument <c><anno>PreArgs</anno></c> is a list of + tagged values. Currently there are two tags, <c>parent_value</c> and <c>stop_fun</c>, used by Mnesia for managing transactions. The value of <c>parent_value</c> is - the value returned by <c>ParentFun</c>, or <c>undefined</c> - if there is no <c>ParentFun</c>. <c>ParentFun</c> is called - once just before the call of <c>PreFun</c> in the context of - the process calling <c>eval</c>, <c>fold</c>, or + the value returned by <c><anno>ParentFun</anno></c>, or + <c>undefined</c> if there is no <c>ParentFun</c>. + <c><anno>ParentFun</anno></c> is called once just before the + call of + <c><anno>PreFun</anno></c> in the context of the process + calling + <c>eval</c>, <c>fold</c>, or <c>cursor</c>. The value of <c>stop_fun</c> is a nullary fun that deletes the cursor if called from the parent, or <c>undefined</c> if there is no cursor.</p> <p><marker id="lookup_fun"></marker>The binary callback - function <c>LookupFun</c> is used for looking up objects in - the table. The first argument <c>Position</c> is the key - position or an indexed position and the second argument - <c>Keys</c> is a sorted list of unique values. The return - value is to be a list of all objects (tuples) such that the - element at <c>Position</c> is a member of <c>Keys</c>. Any - other return value is immediately returned as value of the - query evaluation. <c>LookupFun</c> is called instead of + function <c><anno>LookupFun</anno></c> is used for looking + up objects in the table. The first argument + <c><anno>Position</anno></c> is the key position or an + indexed position and the second argument + <c><anno>Keys</anno></c> is a sorted list of unique values. + The return value is to be a list of all objects (tuples) + such that the element at <c>Position</c> is a member of + <c><anno>Keys</anno></c>. Any other return value is + immediately returned as value of the query evaluation. + <c><anno>LookupFun</anno></c> is called instead of traversing the table if the parse transform at compile time can find out that the filters match and compare the element - at <c>Position</c> in such a way that only <c>Keys</c> need - to be looked up in order to find all potential answers. The - key position is obtained by calling <c>InfoFun(keypos)</c> - and the indexed positions by calling - <c>InfoFun(indices)</c>. If the key position can be used for - lookup it is always chosen, otherwise the indexed position - requiring the least number of lookups is chosen. If there is - a tie between two indexed positions the one occurring first - in the list returned by <c>InfoFun</c> is chosen. Positions - requiring more than <seealso - marker="#max_lookup">max_lookup</seealso> lookups are - ignored.</p> - - <p>The unary callback function <c>InfoFun</c> is to return - information about the table. <c>undefined</c> should be - returned if the value of some tag is unknown:</p> + at <c><anno>Position</anno></c> in such a way that only + <c><anno>Keys</anno></c> need to be looked up in order to + find all potential answers. The key position is obtained by + calling + <c><anno>InfoFun</anno>(keypos)</c> and the indexed + positions by calling + <c><anno>InfoFun</anno>(indices)</c>. If the key position + can be used for lookup it is always chosen, otherwise the + indexed position requiring the least number of lookups is + chosen. If there is a tie between two indexed positions the + one occurring first in the list returned by + <c><anno>InfoFun</anno></c> is chosen. Positions requiring + more than <seealso marker="#max_lookup">max_lookup</seealso> + lookups are ignored.</p> + + <p>The unary callback function <c><anno>InfoFun</anno></c> is + to return information about the table. <c>undefined</c> + should be returned if the value of some tag is unknown:</p> <list type="bulleted"> <item><c>indices</c>. Returns a list of indexed @@ -1406,20 +1330,22 @@ ets:match_spec_run( </item> </list> - <p>The unary callback function <c>FormatFun</c> is used by - <seealso marker="#info">qlc:info/1,2</seealso> for - displaying the call that created the table's query handle. - The default value, <c>undefined</c>, means that + <p>The unary callback function <c><anno>FormatFun</anno></c> + is used by <seealso marker="#info">qlc:info/1,2</seealso> + for displaying the call that created the table's query + handle. The default value, <c>undefined</c>, means that <c>info/1,2</c> displays a call to <c>'$MOD':'$FUN'/0</c>. - It is up to <c>FormatFun</c> to present the selected objects - of the table in a suitable way. However, if a character list - is chosen for presentation it must be an Erlang expression - that can be scanned and parsed (a trailing dot will be added - by <c>qlc:info</c> though). <c>FormatFun</c> is called with - an argument that describes the selected objects based on - optimizations done as a result of analyzing the filters of - the QLC where the call to <c>qlc:table/2</c> occurs. The - possible values of the argument are:</p> + It is up to <c><anno>FormatFun</anno></c> to present the + selected objects of the table in a suitable way. However, if + a character list is chosen for presentation it must be an + Erlang expression that can be scanned and parsed (a trailing + dot will be added by <c>qlc:info</c> though). + <c><anno>FormatFun</anno></c> is called with an argument + that describes the selected objects based on optimizations + done as a result of analyzing the filters of the QLC where + the call to + <c>qlc:table/2</c> occurs. The possible values of the + argument are:</p> <list type="bulleted"> <item><c>{lookup, Position, Keys, NElements, DepthFun}</c>. @@ -1443,10 +1369,12 @@ ets:match_spec_run( can be used for limiting the size of terms; calling <c>DepthFun(Term)</c> substitutes <c>'...'</c> for parts of <c>Term</c> below the depth specified by the <c>info/1,2</c> - option <c>depth</c>. If calling <c>FormatFun</c> with an - argument including <c>NElements</c> and <c>DepthFun</c> - fails, <c>FormatFun</c> is called once again with an - argument excluding <c>NElements</c> and <c>DepthFun</c> + option <c>depth</c>. If calling + <c><anno>FormatFun</anno></c> with an argument including + <c>NElements</c> and <c>DepthFun</c> fails, + <c><anno>FormatFun</anno></c> is called once again with an + argument excluding + <c>NElements</c> and <c>DepthFun</c> (<c>{lookup, Position, Keys}</c> or <c>all</c>).</p> @@ -1458,7 +1386,7 @@ ets:match_spec_run( <p>See <seealso marker="ets#qlc_table">ets(3)</seealso>, <seealso marker="dets#qlc_table">dets(3)</seealso> and - <seealso marker="mnesia:mnesia#qlc_table">mnesia(3)</seealso> + <seealso marker="mnesia:mnesia#qlc_table">mnesia(3)</seealso> for the various options recognized by <c>table/1,2</c> in respective module.</p> </desc> @@ -1472,12 +1400,12 @@ ets:match_spec_run( <seealso marker="doc/reference_manual:users_guide"> Erlang Reference Manual</seealso>, <seealso marker="erl_eval">erl_eval(3)</seealso>, - <seealso marker="erts:erlang">erlang(3)</seealso>, + <seealso marker="erts:erlang">erlang(3)</seealso>, <seealso marker="ets">ets(3)</seealso>, - <seealso marker="kernel:file">file(3)</seealso>, - <seealso marker="error_logger:file">error_logger(3)</seealso>, + <seealso marker="kernel:file">file(3)</seealso>, + <seealso marker="error_logger:file">error_logger(3)</seealso>, <seealso marker="file_sorter">file_sorter(3)</seealso>, - <seealso marker="mnesia:mnesia">mnesia(3)</seealso>, + <seealso marker="mnesia:mnesia">mnesia(3)</seealso>, <seealso marker="doc/programming_examples:users_guide"> Programming Examples</seealso>, <seealso marker="shell">shell(3)</seealso></p> |