Helper class used by code generated by the require
macro.
Helper class used by code generated by the require
macro.
Require that a boolean condition about an argument passed to a method, function, or constructor,
and described in the given clue
, is true.
Require that a boolean condition about an argument passed to a method, function, or constructor,
and described in the given clue
, is true.
If the condition is true
, this method returns normally.
Else, it throws IllegalArgumentException
with the
String
obtained by invoking toString
on the
specified clue
and appending that to the macro-generated
error message as the exception's detail message.
the boolean condition to check as requirement
an objects whose toString
method returns a message to include in a failure report.
if the condition is false
.
if message
is null
.
Require that a boolean condition is true about an argument passed to a method, function, or constructor.
Require that a boolean condition is true about an argument passed to a method, function, or constructor.
If the condition is true
, this method returns normally.
Else, it throws IllegalArgumentException
.
This method is implemented in terms of a Scala macro that will generate an error message. See the main documentation for this trait for examples.
the boolean condition to check as requirement
if the condition is false
.
Require that all passed arguments are non-null.
Require that all passed arguments are non-null.
If none of the passed arguments are null
, this method returns normally.
Else, it throws NullPointerException
with an error message that includes the name
(as it appeared in the source) of each argument that was null
.
arguments to check for null
value
if any of the arguments are null
.
Require that a boolean condition about the state of an object on which a method has been
invoked, and described in the given clue
, is true.
Require that a boolean condition about the state of an object on which a method has been
invoked, and described in the given clue
, is true.
If the condition is true
, this method returns normally.
Else, it throws IllegalStateException
with the
String
obtained by invoking toString
on the
specified clue
appended to the macro-generated error message
as the exception's detail message.
the boolean condition to check as a requirement
an object whose toString
method returns a message to include in a failure report.
if the condition is false
.
if message
is null
.
Require that a boolean condition is true about the state of an object on which a method has been invoked.
Require that a boolean condition is true about the state of an object on which a method has been invoked.
If the condition is true
, this method returns normally.
Else, it throws IllegalStateException
.
This method is implemented in terms of a Scala macro that will generate an error message.
the boolean condition to check as requirement
if the condition is false
.
Helper instance used by code generated by macro assertion.
Trait that contains
require
, andrequireState
, andrequireNonNull
methods for checking pre-conditions that give descriptive error messages extracted via a macro.These methods of trait
Requirements
aim to improve error messages provided when a pre-condition check fails at runtime in production code. Although it is recommended practice to supply helpful error messages when doing pre-condition checks, often people don't. Instead of this:People write simply:
Note that the detail message of the
IllegalArgumentException
thrown by the previous line of code is simply,"requirement failed"
. Such messages often end up in a log file or bug report, where a better error message can save time in debugging the problem. By importing the members ofRequirements
(or mixing in its companion trait), you'll get a more helpful error message extracted by a macro, whether or not a clue message is provided:The
requireState
method provides identical error messages torequire
, but throwsIllegalStateException
instead ofIllegalArgumentException
:Thus, whereas the
require
methods throw the Java platform's standard exception indicating a passed argument violated a precondition,IllegalArgumentException
, therequireState
methods throw the standard exception indicating an object's method was invoked when the object was in an inappropriate state for that method,IllegalStateException
.The
requireNonNull
method takes one or more variables as arguments and throwsNullPointerException
with an error messages that includes the variable names if any arenull
. Here's an example:Although trait
Requirements
can help you debug problems that occur in production, bear in mind that a much better alternative is to make it impossible for such events to occur at all. Use the type system to ensure that all pre-conditions are met so that the compiler can find broken pre-conditions and point them out with compiler error messages. When this is not possible or practical, however, traitRequirements
is helpful.