/** @file  psArguments.h
 *
 *  @brief Contains operations for parsing command line input arguments.
 *
 *  @ingroup Arguments
 *
 *  @author David Robbins, MHPCC
 *
 *  @version $Revision: 1.2 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2006-01-25 03:02:47 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_ARGUMENTS_H
#define PS_ARGUMENTS_H

/// @addtogroup Arguments
/// @{

#include "psMetadata.h"

/** Implements the various verbosity controls.
 *
 *  Arguments shall be removed from the argument list as they are processed.
 *
 *  @return int:        The resultant logging level.
 */
int psArgumentVerbosity(
    int *argc,                         ///< number of arguments
    char **argv                        ///< the argument list
);

/** Checks for an argument and returns its index position if found.
 *
 *  @return int:        The index of the element in the argument list, otherwise 0.
 */
int psArgumentGet(
    int argc,                          ///< number of arguments
    char **argv,                       ///< the argument list
    const char *arg                    ///< the specified argument to match
);

/** Removes from the argument list the argument whose index is argnum.
 *
 *  The number of entries in the argument list shall be decremented.
 *
 *  @return bool:       True if the argnum is in the argument list, otherwise false.
 */
bool psArgumentRemove(
    int argnum,                        ///< the argument to remove
    int *argc,                         ///< number of arguments
    char **argv                        ///< the argument list
);

/** Parses the command line arguments into a metadata container of arguments.
 *
 *  The input arguments shall contain the list of possible arguments as the keywords providing
 *  the default values.  As matching arguments are found on the command line, the values shall be
 *  read into the arguments metadata, with the appropriate type.  The arguments and their values
 *  shall be removed from the list of command line arguments as they are processed.
 *
 *  @return bool:       False if any argument was encountered that is not present in arguments.
 */
bool psArgumentParse(
    psMetadata *arguments,             ///< metadata container for arguments
    int *argc,                         ///< number of arguments
    char **argv                        ///< the argument list
);

/** Prints to stdout a guide to the command-line arguments.      */
void psArgumentHelp(
    psMetadata *arguments              ///< metadata container for arguments
);

/** Sets the log level.
 *
 *  @return psS32:     the log level.
 */
psS32 psLogArguments(
    int *argc,                         ///< number of arguments
    char **argv                        ///< the argument list
);

/** Sets trace levels by facility
 *
 *  @return psS32:      1 (true) if successful or else 2.
 */
psS32 psTraceArguments(
    int *argc,                         ///< number of arguments
    char **argv                        ///< the argument list
);


/// @}

#endif // #ifndef PS_ARGUMENTS_H
