Requirements

Trait that contains require, and requireState, and requireNonNull 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:

scala> val length = 5
length: Int = 5

scala> val idx = 6
idx: Int = 6

scala> require(idx >= 0 && idx <= length, "index, " + idx + ", was less than zero or greater than or equal to length, " + length)
java.lang.IllegalArgumentException: requirement failed: index, 6, was less than zero or greater than or equal to length, 5
	at scala.Predef$.require(Predef.scala:233)
	...

People write simply:

scala> require(idx >= 0 && idx <= length)
java.lang.IllegalArgumentException: requirement failed
	at scala.Predef$.require(Predef.scala:221)
	...

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 of Requirements (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:

scala> import org.scalactic._
import org.scalactic._

scala> import Requirements._
import Requirements._

scala> require(idx >= 0 && idx <= length)
java.lang.IllegalArgumentException: 6 was greater than or equal to 0, but 6 was not less than or equal to 5
	at org.scalactic.Requirements$RequirementsHelper.macroRequire(Requirements.scala:56)
	...

scala> require(idx >= 0 && idx <= length, "(hopefully that helps)")
java.lang.IllegalArgumentException: 6 was greater than or equal to 0, but 6 was not less than or equal to 5 (hopefully that helps)
	at org.scalactic.Requirements$RequirementsHelper.macroRequire(Requirements.scala:56)
	...

The requireState method provides identical error messages to require, but throws IllegalStateException instead of IllegalArgumentException:

scala> val connectionOpen = false
connectionOpen: Boolean = false

scala> requireState(connectionOpen)
java.lang.IllegalStateException: connectionOpen was false
	at org.scalactic.Requirements$RequirementsHelper.macroRequireState(Requirements.scala:71)
	...

Thus, whereas the require methods throw the Java platform's standard exception indicating a passed argument violated a precondition, IllegalArgumentException, the requireState 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 throws NullArgumentException with an error messages that includes the variable names if any are null. Here's an example:

scala> val e: String = null
e: String = null

scala> val f: java.util.Date = null
f: java.util.Date = null

scala> requireNonNull(a, b, c, d, e, f)
org.scalactic.exceptions.NullArgumentException: e and f were null
	at org.scalactic.Requirements$RequirementsHelper.macroRequireNonNull(Requirements.scala:101)
	...

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, trait Requirements is helpful.

Source: Requirements.scala

Linear Supertypes

AnyRef, Any

Known Subclasses

Requirements

Type Members

class RequirementsHelper extends Serializable

Helper class used by code generated by the require macro.
Helper class used by code generated by the require macro.

Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def asInstanceOf[T0]: T0

Definition Classes
Any
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def hashCode(): Int

Definition Classes
AnyRef → Any
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
macro def require(condition: Boolean, clue: Any)(implicit prettifier: Prettifier, pos: Position): Unit

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.
condition
the boolean condition to check as requirement
clue
an objects whose toString method returns a message to include in a failure report.

Exceptions thrown
IllegalArgumentException if the condition is false.
NullPointerException if message is null.
macro def require(condition: Boolean)(implicit prettifier: Prettifier, pos: Position): Unit

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.
condition
the boolean condition to check as requirement

Exceptions thrown
IllegalArgumentException if the condition is false.
macro def requireNonNull(arguments: Any*)(implicit prettifier: Prettifier, pos: Position): Unit

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 NullArgumentException with an error message that includes the name (as it appeared in the source) of each argument that was null.
arguments
arguments to check for null value

Exceptions thrown
NullArgumentException if any of the arguments are null.
macro def requireState(condition: Boolean, clue: Any)(implicit prettifier: Prettifier, pos: Position): Unit

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.
condition
the boolean condition to check as a requirement
clue
an object whose toString method returns a message to include in a failure report.

Exceptions thrown
IllegalStateException if the condition is false.
NullPointerException if message is null.
macro def requireState(condition: Boolean)(implicit prettifier: Prettifier, pos: Position): Unit

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.
condition
the boolean condition to check as requirement

Exceptions thrown
IllegalStateException if the condition is false.
val requirementsHelper: RequirementsHelper

Helper instance used by code generated by macro assertion.
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def toString(): String

Definition Classes
AnyRef → Any
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )

Related Docs: object Requirements | package scalactic

trait Requirements extends AnyRef

Type Members

class RequirementsHelper extends Serializable

Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

final def ==(arg0: Any): Boolean

final def asInstanceOf[T0]: T0

def clone(): AnyRef

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def finalize(): Unit

final def getClass(): Class[_]

def hashCode(): Int

final def isInstanceOf[T0]: Boolean

final def ne(arg0: AnyRef): Boolean

final def notify(): Unit

final def notifyAll(): Unit

macro def require(condition: Boolean, clue: Any)(implicit prettifier: Prettifier, pos: Position): Unit

macro def require(condition: Boolean)(implicit prettifier: Prettifier, pos: Position): Unit

macro def requireNonNull(arguments: Any*)(implicit prettifier: Prettifier, pos: Position): Unit

macro def requireState(condition: Boolean, clue: Any)(implicit prettifier: Prettifier, pos: Position): Unit

macro def requireState(condition: Boolean)(implicit prettifier: Prettifier, pos: Position): Unit

val requirementsHelper: RequirementsHelper

final def synchronized[T0](arg0: ⇒ T0): T0

def toString(): String

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

Inherited from AnyRef

Inherited from Any

Ungrouped