From 8e2ec999394c77741241ef1a12728b11195961c8 Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas.larsson@erlang-solutions.com>
Date: Mon, 21 Mar 2016 17:53:26 +0100
Subject: erts: Document erlang:match_spec_test/3
OTP-13501
---
erts/doc/src/erlang.xml | 42 ++++++++++++++++++++++++++++++++++++++++++
erts/preloaded/src/erlang.erl | 8 ++++----
2 files changed, 46 insertions(+), 4 deletions(-)
(limited to 'erts')
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index d6fe585c8d..fde04504c8 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -2612,6 +2612,48 @@ os_prompt% </pre>
</desc>
</func>
+ <func>
+ <name name="match_spec_test" arity="3"/>
+ <fsummary>Test that a match specification works</fsummary>
+ <desc>
+ <p>
+ This function is a utility to test a match_spec used in calls to
+ <seealso marker="stdlib:ets#select/2">ets:select/2</seealso> and
+ <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.
+ The function both tests MatchSpec for "syntactic" correctness and
+ runs the match_spec against the object. If the match_spec contains
+ errors, the tuple {error, Errors} is returned where Errors is a list
+ of natural language descriptions of what was wrong with the match_spec.
+ </p>
+ <p>
+ If the <c><anno>Type</anno></c> is <c>table</c> the object to match
+ against should be a tuple. The function then returns
+ {ok,Result,[],Warnings} where Result is what would have been the
+ result in a real ets:select/2 call or false if the match_spec does
+ not match the object tuple.
+ </p>
+
+ <p>
+ If <c><anno>Type</anno></c> is <c>trace</c> the object to match
+ against should be a list. The function returns
+ {ok, Result, Flags, Warnings} where Result is <c>true</c> if a trace
+ message should be emitted, <c>false</c> if a trace message should not
+ be emitted or the message term to be appended to the trace message.
+ Flags is a list containing all the trace flags that will be enabled,
+ at the moment this is only <c>return_trace</c>.
+ </p>
+
+ <p>
+ This is a useful debugging and test tool, especially when writing complicated
+ match specifications.
+ </p>
+ <p>
+ See also
+ <seealso marker="stdlib:ets#test_ms/2">ets:test_ms/2</seealso>.
+ </p>
+ </desc>
+ </func>
+
<func>
<name name="max" arity="2"/>
<fsummary>Returns the largest of two terms.</fsummary>
diff --git a/erts/preloaded/src/erlang.erl b/erts/preloaded/src/erlang.erl
index 40d0abd321..3cc17014ff 100644
--- a/erts/preloaded/src/erlang.erl
+++ b/erts/preloaded/src/erlang.erl
@@ -1163,10 +1163,10 @@ map_size(_Map) ->
erlang:nif_error(undefined).
%% match_spec_test/3
--spec erlang:match_spec_test(P1, P2, P3) -> TestResult when
- P1 :: [term()] | tuple(),
- P2 :: term(),
- P3 :: table | trace,
+-spec erlang:match_spec_test(MatchAgainst, MatchSpec, Type) -> TestResult when
+ MatchAgainst :: [term()] | tuple(),
+ MatchSpec :: term(),
+ Type :: table | trace,
TestResult :: {ok, term(), [return_trace], [ {error | warning, string()} ]} | {error, [ {error | warning, string()} ]}.
match_spec_test(_P1, _P2, _P3) ->
erlang:nif_error(undefined).
--
cgit v1.2.3