/************************************************************************
 *
 * driver.h - testsuite driver declarations
 *
 * $Id$
 *
 ***************************************************************************
 *
 * Licensed to the Apache Software  Foundation (ASF) under one or more
 * contributor  license agreements.  See  the NOTICE  file distributed
 * with  this  work  for  additional information  regarding  copyright
 * ownership.   The ASF  licenses this  file to  you under  the Apache
 * License, Version  2.0 (the  "License"); you may  not use  this file
 * except in  compliance with the License.   You may obtain  a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the  License is distributed on an  "AS IS" BASIS,
 * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY  KIND, either  express or
 * implied.   See  the License  for  the  specific language  governing
 * permissions and limitations under the License.
 *
 * Copyright 1994-2005 Rogue Wave Software.
 * 
 **************************************************************************/

#ifndef RW_DRIVER_H_INCLUDED
#define RW_DRIVER_H_INCLUDED

#include <rw_testdefs.h>   // for test config macros


/**
 * Initializes the test driver, passes program arguments to it, processes
 * command line arguments, any arguments specified in the environment
 * variable RWSTD_TESTOPTS, and if successful, invokes the program-supplied
 * callback function.
 *
 * @param argc  The number of non-null elements in the argv array.
 * @param argv  A null-terminated array of command line arguments.
 *        If (argc == 0) the argument may be null.
 * @param filename  The name of the source file name, typically
 *        the __FILE__ macro. The argument may be null.
 * @param clause  The clause exercised by the program, such as
 *        lib.basic.string. The argument may be null.
 * @param comment An optional comment describing in more detail
 *        the functionality of the program. The argument may be null.
 * @param testfun  A pointer to a callback function to call by the
 *        driver after successful initialization. The argument must
 *        not be null.
 * @param optspec An optional character string describing command
 *        line options accepted by the program. The argument may
 *        be null.
 * @param ...  Optional list of handlers of command line options
 *         corresponding to the optspec.
 *
 * @return If initialization is successful, returns the value returned
 *         by the callback function. Otherwise, returns the non-zero
 *         value returned by the last initialization function or
 *         command line option handler.
 *
 * After the driver has been initialzied the user-supplied callback function
 * may call any of the driver diagnostic functions to record and perhaps also
 * issue diagnostic messages of varying severity.
 *
 * There are 10 levels of severity with 0 being the lowest and 9 the highest.
 * Diagnostics of all levels of severity come in two states: active and
 * inactive. All diagnostics are recorded but normally only active diagnostics
 * of severity 4 or above are issued. It is possible to cause diagnostics of
 * lower severity levels to be issued via a command line option to the driver.
 * Choosing to issue severity 0 diagnostics has the effect of issuing inactive
 * diagnostics.
 *
 * After the callback function returns the driver displays a summary detailing
 * the number of recorded diagnostics in each of the two states (active and
 * inactive).
 * 
 */
_TEST_EXPORT int
rw_test (int           argc,
         char*         argv[],
         const char*   filename,
         const char*   clause,
         const char*   comment,
         int         (*testfun)(int, char**),
         const char*   optspec,
         ...);

/**
 * Records and optionally issues a diagnostic of the highest severity 9.
 *
 * @param expr  A zero value denoting an active diagnostic or any non-zero
 *        vaue denoting an inactive diagnostic.
 * @param filename  An optional name of the file invoking the function.
 *        The argument may be null.
 * @param line  When positive, denotes the line number of the location
 *        relevant to the diagnostic. Negative values are ignored.
 * @param fmtspec  A printf format specifier (with extensions) used
 *        to format the text of the diagnostic.  See rwtest-fmtspec page
 *        for details.
 * @param ... Optional list of values to format.
 *
 * @return  Returns the value of expr passed to it.
 *
 * Every diagnostic is recorded but only active diagnostics may be issued,
 * depending on the setting of the diagnosable severity. The value of the
 * first argument determines whether a diagnostc is active or inactive.
 * Unlike the remaining diagnostic functions, rw_fatal doesn't return to
 * the caller when expr is 0 (i.e., when the diagnostic is active).
 * Instead, it causes the driver the exit the process with the staus equal
 * to 9, the severity of the diagnostic.
 */
_TEST_EXPORT int
rw_fatal (int         expr,
          const char* filename,
          int         line,
          const char* fmtspec,
          ...);

/**
 * Records and optionally issues a diagnostic of severity 8.
 *
 * @see #rw_fatal
 */
_TEST_EXPORT int
rw_error (int, const char*, int, const char*, ...);

/**
 * Records and optionally issues a diagnostic of severity 7.
 *
 * @see #rw_fatal
 */
_TEST_EXPORT int
rw_assert (int, const char*, int, const char*, ...);

/**
 * Records and optionally issues a diagnostic of severity 5.
 *
 * @see #rw_fatal
 */
_TEST_EXPORT int
rw_warn (int, const char*, int, const char*, ...);

/**
 * Records and optionally issues a diagnostic of severity 2.
 *
 * @see #rw_fatal
 */
_TEST_EXPORT int
rw_note (int, const char*, int, const char*, ...);

/**
 * Records and optionally issues a diagnostic of severity 1.
 *
 * @see #rw_fatal
 */
_TEST_EXPORT int
rw_info (int, const char*, int, const char*, ...);

/**
 * Enable/disable the specified diagnostic.
 *
 * @param fun Diagnostic function to enable or disable. Must be one of
 *        rw_fatal, rw_error, rw_assert, rw_warn, rw_note or rw_info.
 * @param enable Flag to indicate that the diagnostic function should
 *        be enabled or disabled.
 * @return  Returns the previous state of the diagnostic. If the first
 *        parameter is not an acceptable input, will return false.
 *
 * Example:
 *   rw_enable (rw_error, false); // disable all rw_error diagnostics
 *   rw_enable (rw_error);        // enable all rw_error diagnostics
 */
_TEST_EXPORT bool
rw_enable (int (*fun) (int, const char*, int, const char*, ...),
           bool enable = true);

#endif   // RW_DRIVER_H_INCLUDED