stafcommandparser.h

Software Testing Automation Framework (STAF)的开发代码

/***********************************************************************/
/* STAFCommandParseResultGetOptionValue - Gets the value of a          */
/*                                        particular instance of a     */
/*                                        particular option            */
/*                                                                     */
/* Accepts: (In)  Pointer to a STAF Command Parse Result               */
/*          (In)  The name of this option                              */
/*          (In)  The number of the desired instance of this option    */
/*          (Out) Pointer to the option value                          */
/*          (Out) Pointer to OS return code                            */
/*                                                                     */
/* Returns:  kSTAFOk, on success                                       */
/*           other on error                                            */
/***********************************************************************/
STAFRC_t STAFCommandParseResultGetOptionValue(
    STAFCommandParseResult_t result, const STAFString_t optionName,
    unsigned int optionIndex, STAFString_t *optionValue,
    unsigned int *osRC);


/***********************************************************************/
/* STAFCommandParseResultGetNumArgs - Gets the number of free-standing */
/*                                 arguments the user specified        */
/*                                                                     */
/* Accepts: (In)  Pointer to a STAF Command Parse Result               */
/*          (Out) Pointer to the number of arguments                   */
/*          (Out) Pointer to OS return code                            */
/*                                                                     */
/* Returns:  kSTAFOk, on success                                       */
/*           other on error                                            */
/***********************************************************************/
STAFRC_t STAFCommandParseResultGetNumArgs(
    STAFCommandParseResult_t result, unsigned int *numArgs,
    unsigned int *osRC);


/***********************************************************************/
/* STAFCommandParseResultGetArgValue - Gets the value of a particular  */
/*                                     argument                        */
/*                                                                     */
/* Accepts: (In)  Pointer to a STAF Command Parse Result               */
/*          (In)  The number of the desired argument                   */
/*          (Out) Pointer to the argument value                        */
/*          (Out) Pointer to OS return code                            */
/*                                                                     */
/* Returns:  kSTAFOk, on success                                       */
/*           other on error                                            */
/***********************************************************************/
STAFRC_t STAFCommandParseResultGetArgValue(
    STAFCommandParseResult_t result, unsigned int argNum,
    STAFString_t *argValue, unsigned int *osRC);


/* XXX: This function may not be required.  We may not actually alloc 
        new memory */

/***********************************************************************/
/* STAFCommandParseResultFreeMemory - Frees the memory returned by     */
/*                                    the STAF Command Parse Result    */
/*                                    APIs                             */
/*                                                                     */
/* Accepts: (In)  Pointer to a STAF Command Parse Result               */
/*          (In)  Pointer to the memory to free                        */
/*          (Out) Pointer to OS return code                            */
/*                                                                     */
/* Returns:  kSTAFOk, on success                                       */
/*           other on error                                            */
/***********************************************************************/
STAFRC_t STAFCommandParseResultFreeMemory(
    STAFCommandParseResult_t result, char *ptr, unsigned int *osRC);


/***********************************************************************/
/* STAFCommandParseDestruct - Destroys a STAF Command Parse Result     */
/*                            object                                   */
/*                                                                     */
/* Accepts: (In)  Pointer to a STAF Command Parse Result               */
/*          (Out) Pointer to OS return code                            */
/*                                                                     */
/* Returns:  kSTAFOk, on success                                       */
/*           other on error                                            */
/***********************************************************************/
STAFRC_t STAFCommandParseResultDestruct(
    STAFCommandParseResult_t *pResult, unsigned int *osRC);

#ifdef __cplusplus
}

#include "STAFException.h"

// STAFCommandParseResult - This class is returned from a STAFCommandParser.
//                          It represents the results of parsing a string via
//                          the STAFCommandParser.

class STAFCommandParseResult
{
public:

    // The return code from the parse
    STAFRC_t rc;

    // The description of the error when rc != 0
    STAFString errorBuffer;

    // Returns the number of times an option was specified
    unsigned int optionTimes(const STAFString &optionName);


    // Returns the value of a given instance of a given option.
    // Returns an empty string if no such option or instance exists.
    STAFString optionValue(const STAFString &optionName,
                           unsigned int number = 1);


    // Returns the total number of options specified in the string
    unsigned int numInstances();


    // Returns the name of the given option instance
    STAFString instanceName(unsigned int number);


    // Returns the value of the given option instance
    STAFString instanceValue(unsigned int number);


    // Returns the number of extra arguments
    unsigned int numArgs();


    // Returns a given argument.  Returns an empty string if no such argument
    // exists.
    STAFString arg(unsigned int number);

    ~STAFCommandParseResult();

    STAFCommandParseResult_t getImpl() { return fResultImpl; }

 private:

    // Disallow copy construction and assignment
    STAFCommandParseResult(const STAFCommandParseResult &);
    STAFCommandParseResult &operator=(const STAFCommandParseResult &);

    friend class STAFCommandParser;

    STAFCommandParseResult(STAFCommandParseResult_t theResult,
        STAFRC_t theRC, const STAFString &theErrorBuffer)
        : rc(theRC), errorBuffer(theErrorBuffer), fResultImpl(theResult)
    { /* Do Nothing */ }

    STAFCommandParseResult_t fResultImpl;
};

typedef STAFRefPtr<STAFCommandParseResult> STAFCommandParseResultPtr;


// STAFCommandParser - This class provides a parsing interface for STAF, in
//                     particular, STAF services

class STAFCommandParser
{
public:

    // This enum is used to determine if an option may, may not, or must
    // have a value associated with it

    enum ValueRequirement { kValueNotAllowed = 0, kValueAllowed = 1,
                            kValueRequired = 2};

    // The constructor accepts an array of options and a count of those
    // options, along with an indication of case sensitivity to option names

    STAFCommandParser(unsigned int maxArgs = 0, bool caseSensitive = false);


    void addOption(const STAFString &option, unsigned int numAllowed,
                   ValueRequirement valueReq);


    void addOptionGroup(const STAFString &group, unsigned int minAllowed,
                        unsigned int maxAllowed);

    void addOptionNeed(const STAFString &needers, const STAFString &needees);

    // Parses a given string.  Returns 0, if successful, > 0, otherwise.
    // ErrorBuffer will be set if unsuccessful.

    STAFCommandParseResultPtr parse(const STAFString &parseString);

    ~STAFCommandParser();

    STAFCommandParser_t getImpl() { return fParserImpl; }

private:

    // Disallow copy construction and assignment
    STAFCommandParser(const STAFCommandParser &);
    STAFCommandParser &operator=(const STAFCommandParser &);

    STAFCommandParser_t fParserImpl;
};


// Now include inline definitions

#ifndef STAF_NATIVE_COMPILER
#include "STAFCommandParserInlImpl.cpp"
#endif

// End C++ language definitions

// End #ifdef __cplusplus
#endif

#endif