From c574bd33c39d91c487c3fcd819226ecfc46c13c8 Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Sat, 19 May 2012 22:07:31 +0200 Subject: Break out assert macros from eunit to stdlib assert.hrl Several people have requested that the assert macros in EUnit should be moved out to a separate header file. This patch puts them in stdlib/include/assert.hrl, which gets included by the eunit.hrl file. Thus, nothing changes for eunit users, but the asserts can now also be included separately. --- lib/stdlib/doc/src/assert_hrl.xml | 160 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 lib/stdlib/doc/src/assert_hrl.xml (limited to 'lib/stdlib/doc/src/assert_hrl.xml') diff --git a/lib/stdlib/doc/src/assert_hrl.xml b/lib/stdlib/doc/src/assert_hrl.xml new file mode 100644 index 0000000000..d812ee16dc --- /dev/null +++ b/lib/stdlib/doc/src/assert_hrl.xml @@ -0,0 +1,160 @@ + + + + +
+ + 20122015 + Ericsson AB. All Rights Reserved. + + + 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. + + + + assert.hrl + + + + +
+ assert.hrl + Assert Macros + +

The include file assert.hrl provides macros for inserting + assertions in your program code.

+

These macros are defined in the Stdlib include file + assert.hrl. Include the following directive in the module + from which the function is called:

+ +-include_lib("stdlib/include/assert.hrl"). +

When an assertion succeeds, the assert macro yields the atom + ok. When an assertion fails, an exception of type error is + instead generated. The associated error term will have the form + {Macro, Info}, where Macro is the name of the macro, for + example assertEqual, and Info will be a list of tagged + values such as [{module, M}, {line, L}, ...] giving more + information about the location and cause of the exception. All entries + in the Info list are optional, and you should not rely + programatically on any of them being present.

+ +

If the macro NOASSERT is defined when the assert.hrl + include file is read by the compiler, the macros will be defined as + equivalent to the atom ok. The test will not be performed, and + there will be no cost at runtime.

+ +

For example, using erlc to compile your modules, the following + will disable all assertions:

+ +erlc -DNOASSERT=true *.erl +

(The value of NOASSERT does not matter, only the fact that it + is defined.)

+

A few other macros also have effect on the enabling or disabling of + assertions:

+ + If NODEBUG is defined, it implies NOASSERT, unless + DEBUG is also defined, which is assumed to take + precedence. + If ASSERT is defined, it overrides NOASSERT, that + is, the assertions will remain enabled. + +

If you prefer, you can thus use only DEBUG/NODEBUG as + the main flags to control the behaviour of the assertions (which is + useful if you have other compiler conditionals or debugging macros + controlled by those flags), or you can use ASSERT/NOASSERT + to control only the assert macros.

+ + + +
+
+ +
+ Macros + + assert(BoolExpr) +

Tests that BoolExpr completes normally returning + true.

+ + + assertNot(BoolExpr) +

Tests that BoolExpr completes normally returning + false.

+ + + assertMatch(GuardedPattern, Expr) +

Tests that Expr completes normally yielding a value + that matches GuardedPattern. For example: + + ?assertMatch({bork, _}, f())

+

Note that a guard when ... can be included: + + ?assertMatch({bork, X} when X > 0, f())

+ + + assertNotMatch(GuardedPattern, Expr) +

Tests that Expr completes normally yielding a value + that does not match GuardedPattern.

+

As in assertMatch, GuardedPattern can have a + when part.

+ + + assertEqual(ExpectedValue, Expr) +

Tests that Expr completes normally yielding a value + that is exactly equal to ExpectedValue.

+ + + assertNotEqual(ExpectedValue, Expr) +

Tests that Expr completes normally yielding a value + that is not exactly equal to ExpectedValue.

+ + + assertException(Class, Term, Expr) +

Tests that Expr completes abnormally with an exception + of type Class and with the associated Term. The + assertion fails if Expr raises a different exception or if it + completes normally returning any value.

+

Note that both Class and Term can be guarded + patterns, as in assertMatch.

+ + + assertNotException(Class, Term, Expr) +

Tests that Expr does not evaluate abnormally with an + exception of type Class and with the associated Term. + The assertion succeeds if Expr raises a different exception or + if it completes normally returning any value.

+

As in assertException, both Class and Term + can be guarded patterns.

+ + + assertError(Term, Expr) +

Equivalent to assertException(error, Term, + Expr)

+ + + assertExit(Term, Expr) +

Equivalent to assertException(exit, Term, Expr)

+ + + assertThrow(Term, Expr) +

Equivalent to assertException(throw, Term, Expr)

+ + + +
+ +
+ SEE ALSO +

compile(3)

+

erlc(3)

+
+ -- cgit v1.2.3