/* Copyright (C) 1998 H. Conrad Cunningham.  All rights reserved.  */

package SoftwareInterfaces;

/**
 * A class to provide assertion checking.
 *
 * <p> This class provides a set of class (static) methods to check
 * assertions--preconditions, postconditions, class invariants, and 
 * general assertion conditions.  If the assertion checking is enabled and
 * the assertion does not hold, the appropriate exception from the 
 * AssertionViolation hierarchy is thrown.
 *
 * <p> The publically accessible class (static) variables <code>condOn</code>, 
 * <code>predOn</code>, <code>postOn</code>, and <code>invOn</code> enable 
 * or disable the assertion checking for conditions (<code>cond</code>), 
 * preconditions (<code>cond</code>), postconditions (<code>post</code>), 
 * and invariants (<code>inv</code>), respectively.  If these boolean 
 * variables are <code>true</code>, then checking is enabled.  By default,
 * all checks are enabled.
 *
 * @author H. Conrad Cunningham
 * @version 1 June 1998
 */

public class Assert
{   
    /**
     * If condition checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param cond a boolean assertion at any point in a program
     * @throws AssertionViolation if condition checking is enabled and 
     *     assertion is not <code>true</code> 
     * <dt><b>Postcondition:</b> 
     * <dd>assertion checking is disabled or assertion <code>cond</code> 
     *     is <code>true</code>
     */
    public static void cond(boolean cond) throws AssertionViolation
    {  if (condOn && !cond)
       {   throw new AssertionViolation("Assertion false."); }
    }


    /**
     * If condition checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param cond a boolean assertion at any point in a program
     * @param msg message to print when exception thrown
     * @throws AssertionViolation if condition checking is enabled and 
     *     assertion is not <code>true</code>.  Also prints <code>msg</code>.
     * <dt><b>Postcondition:</b> 
     * <dd>assertion checking is disabled or assertion <code>cond</code> 
     *     is <code>true</code>
     */
    public static void cond(boolean cond, String msg) throws AssertionViolation
    {  if (condOn && !cond)
       {   throw new AssertionViolation(msg); }
    }


    /**
     * If precondition checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param precond a boolean assertion at entry to a method
     * @throws PreconditionViolation if precondition checking is enabled and 
     *     assertion is not <code>true</code>. 
     * <dt><b>Postcondition:</b> 
     * <dd>precondition checking is disabled or assertion <code>precond</code> 
     *     is <code>true</code>
     */
    public static void pre(boolean precond) throws PreconditionViolation
    {  if (preOn && !precond)
       {   throw new PreconditionViolation
	       ("Precondition false on method entry."); 
       }
    }


    /**
     * If precondition checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param precond a boolean assertion at entry to a method
     * @param msg message to print when exception thrown
     * @throws PreconditionViolation if precondition checking is enabled and 
     *     assertion is not <code>true</code>.  Also prints <code>msg</code>.
     * <dt><b>Postcondition:</b> 
     * <dd>precondition checking is disabled or assertion <code>precond</code> 
     *     is <code>true</code>
     */
    public static void pre(boolean precond, String msg) 
        throws PreconditionViolation
    {  if (preOn && !precond)
       {   throw new PreconditionViolation(msg); }
    }



    /**
     * If postcondition checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param postcond a boolean assertion at exit of a method
     * @throws PostconditionViolation if postcondition checking is enabled and 
     *     assertion is not <code>true</code>.
     * <dt><b>Postcondition:</b> 
     * <dd>postcondition checking is disabled or assertion 
     *     <code>postcond</code> is <code>true</code>
     */
    public static void post(boolean postcond) throws PostconditionViolation
    {  if (postOn && !postcond)
       {   throw new PostconditionViolation
	       ("Postcondition false on method exit."); 
       }
    }


    /**
     * If postcondition checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param postcond a boolean assertion at exit of a method
     * @param msg message to print when exception thrown
     * @throws PostconditionViolation if postcondition checking is enabled and 
     *     assertion is not <code>true</code>.  Also prints <code>msg</code>.
     * <dt><b>Postcondition:</b> 
     * <dd>postcondition checking is disabled or assertion 
     *     <code>postcond</code> <code>true</code>
     */
    public static void post(boolean postcond, String msg) 
        throws PostconditionViolation
    {  if (postOn && !postcond)
       {   throw new PostconditionViolation(msg); }
    }

    /**
     * If invariant checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param invcond a boolean assertion at entry and exit of a method
     * @throws InvariantViolation if invariant checking is enabled and 
     *     assertion is not <code>true</code>.
     * <dt><b>Postcondition:</b> 
     * <dd>invariant checking is disabled or assertion <code>invcond</code> 
     *     is <code>true</code>
     */
    public static void inv(boolean invcond) throws InvariantViolation
    {  if (invOn && !invcond)
       {   throw new InvariantViolation("Invariant false."); }
    }


    /**
     * If invariant checking is enabled, checks whether a boolean 
     * assertion holds (i.e., is true) and throws an exception if it does
     * not hold.
     *
     * @param invcond a boolean assertion at entry and exit of a method
     * @param msg message to print when exception thrown
     * @throws InvariantViolation if invariant checking is enabled and 
     *     assertion is not <code>true</code>.  Also prints <code>msg</code>.
     * <dt><b>Postcondition:</b> 
     * <dd>invariant checking is disabled or assertion <code>invcond</code> 
     *     is <code>true</code>
     */
    public static void inv(boolean invcond, String msg) 
        throws InvariantViolation
    {  if (invOn && !invcond)
       {   throw new InvariantViolation(msg); }
    }

    public static boolean condOn = true;   // method cond checking enabled?
    public static boolean preOn = true;    // method pre checking enabled?
    public static boolean postOn = true;   // method post checking enabled?
    public static boolean invOn = true;    // method inv checking enabled?
}