HeyParser.hh

Go to the documentation of this file.

/*
 * HeyParser.hh
 *
 * Copyright (c) 2003 The University of Utah and the Flux Group.
 * All rights reserved.
 *
 * This file is licensed under the terms of the GNU Public License.  
 * See the file "license.terms" for restrictions on redistribution 
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

/**
 * @file HeyParser.hh
 *
 * Header file for the HeyParser, HeyParserException, and HeyPropertyInfo
 * classes.
 */

#ifndef _hey_parser_hh
#define _hey_parser_hh

#include <stack.h>
#include <iostream.h>

/**
 * Base class for exceptions thrown by the parser.
 *
 * @sa HeyParser
 */
class HeyParserException
{
    
public:
    
    /**
     * Construct a HeyParserException object with an optional descriptive
     * message.
     *
     * @param msg A short message describing the problem.
     * @param value The value that caused the problem.
     */
    HeyParserException(const char *msg = NULL,
                       const char *value = NULL)
    {
        this->hpe_Message = msg;
        this->hpe_Value = value;
    };

    /**
     * @return The descriptive message passed into the constructor.
     */
    const char *getMessage(void) const
    {
        return this->hpe_Message;
    };

    /**
     * @return The value passed into the constructor.
     */
    const char *getValue(void) const
    {
        return this->hpe_Value;
    };

    /**
     * Output stream operator for HeyParserException objects.  Currently just
     * prints out the message passed into the constructor.
     *
     * @param os The destination output stream.
     * @param hpe The object to output.
     * @return The value of the 'os' parameter.
     */
    friend std::ostream &operator<<(std::ostream &os,
                                    const HeyParserException &hpe)
    {
        return os << (hpe.hpe_Message != NULL ? hpe.hpe_Message : "")
                  << (hpe.hpe_Value != NULL ? ": " : "")
                  << (hpe.hpe_Value != NULL ? hpe.hpe_Value : "");
    };

private:

    /**
     * A short message describing the problem.
     */
    const char *hpe_Message;
    
    /**
     * The value that caused the problem.
     */
    const char *hpe_Value;
    
};

/**
 * A parser for command-line arguments given in the pseudo-English "hey" form.
 * The syntax for the arguments looks like this:
 *
 *   @li hey @<server@> list @<property@>
 *   @li hey @<server@> get @<property@> of @<object@>
 *   @li hey @<server@> set @<property@> of @<object@> to @<value@>
 *   @li hey @<server@> create @<property@> of @<object@> with @<name@> @<value@>
 *   @li hey @<server@> delete @<property@> of @<object@>
 *   @li hey @<server@> execute @<property@> of @<object@> with @<name@> @<value@>
 *   @li hey @<server@> getsuites of @<object@>
 *   @li hey @<server@> shutdown
 *
 * Where:
 *
 *   @li @<server@> is a reference to a running server program,
 *   @li list/get/etc is the verb describing the action to take,
 *   @li @<property@> is a object or an attribute of an object, and
 *   @li @<name@> @<value@> is a name/value argument pair.
 *
 * For example, to create a 'string' object named 'bar' with a value of 'Hello,
 * World!' in the 'foo' server, you might do:
 *
 * @code
 *   $ hey foo create string with name bar value 'Hello, World!'
 * @endcode
 *
 * Then, you can manipulate the server and object with the following commands:
 *
 * @code
 *   $ hey foo list
 *   string
 *   strings
 *   $ hey foo list strings
 *   bar
 *   $ hey foo get value of string bar
 *   Hello, World!
 *   $ hey foo delete string bar
 *   ok
 *   $ hey foo list strings
 *   $
 * @endcode
 *
 * @sa HeyParserException
 * @sa HeyPropertyInfo
 *
 * @see cbhey.cc
 * @see hey_bad.cc
 * @see hey_good.cc
 */
class HeyParser
{

public:

    /**
     * An enumeration of the possible actions to perform on an object.
     */
    /** @var HeyParser::SHUTDOWN Shutdown the server. */
    typedef enum {
        SHUTDOWN,
        LIST_PROPERTIES,        /**< List the properties of an object. */
        GET_PROPERTY,           /**< Get a property from an object. */
        SET_PROPERTY,           /**< Set a property in an object. */
        CREATE_PROPERTY,        /**< Create a property in an object. */
        DELETE_PROPERTY,        /**< Delete a property in an object. */
        EXECUTE_PROPERTY,       /**< Execute a property in an object. */
        GET_SUITES,             /**< Get the description of a property. */

        WHAT_MAX
    } hp_what_t;

    /**
     * String versions of the hp_what_t enumeration values.
     */
    static const char *hp_what_strings[WHAT_MAX];

    /**
     * Construct a parser that interprets the given command-line arguments.
     * Most of the parsing will be done here so there are fewer surprises along
     * the way.  Note that the object expects all of the arguments, including
     * the command name.
     *
     * @callgraph
     *
     * @param argc The argument count.
     * @param argv The argument values.
     *
     * @throws HeyParserException if there is a problem with the argument list.
     */
    HeyParser(int argc, const char *argv[])
        throw (HeyParserException);

    /**
     * Deconstruct a parser object.
     */
    virtual ~HeyParser(void);

    /**
     * @return The argument count.
     */
    int getArgCount(void) const
    {
        return( this->hp_ArgCount );
    }

    /**
     * @return The argument values.
     */
    const char **getArgValues(void) const
    {
        return( this->hp_ArgValue );
    }

    /**
     * @return The argument that specifies which server to talk to.
     */
    const char *who(void) const
    {
        return( this->hp_ArgValue[1] );
    };

    /**
     * @return The action requested by the user (i.e. what to do).
     */
    hp_what_t what(void) const
    {
        return( this->hp_What );
    };

    /**
     * Pop a pair from the property stack.
     *
     * @param name_out The reference where the property name should be stored.
     * @param value_out The reference where the property value should be
     * stored.
     *
     * @throws HeyParserException if there are no more values on the stack.
     */
    void popProperty(const char *&name_out, const char *&value_out)
        throw (HeyParserException);

    /**
     * @return The value that a property should be set to.
     */
    const char *to(void) const
    {
        return( this->hp_ToValue );
    };
    
    /**
     * Get the argument array containing the 'with' name/value pairs.
     *
     * @param with_out The reference where the 'with' array should be stored.
     * The elements of the array are ordered as they were on the command line.
     * @param count_out The size of the 'with_out' array.
     */
    void with(const char **&with_out, size_t &count_out) const;

    /**
     * Get the value for a particular 'with' argument.
     *
     * @param name The name of the 'with' argument to retrieve.
     * @param instance The instance of the argument to retrieve.
     * @param default_value The default value to return if the 'with' argument
     * could not be found.
     * @return The value coupled with the given instance of 'name', or
     * default_value if the instance could not be found.
     *
     * @throws HeyParserException if the particular instance of the 'with'
     * argument was not found.
     */
    const char *withValue(const char *name,
                          unsigned int instance = 0,
                          const char *default_value = NULL) const
        throw (HeyParserException);

private:

    /**
     * Helper class that stores name/value pairs.
     */
    class Pair
    {

    public:

        /**
         * Construct a Pair object with the given name/value pair.
         *
         * @param name The name.
         * @param value The value.
         */
        Pair(const char *name = NULL, const char *value = NULL) :
            p_Name(name), p_Value(value)
        {
        };

        /**
         * The name of the property.
         */
        const char *p_Name;

        /**
         * The property value.
         */
        const char *p_Value;
    };
    
    /**
     * Consume an argument from the argument list.  This method is for internal
     * use when initially processing the argument list.
     *
     * @sideeffect hp_ArgIndex is incremented by one if there was an argument
     * available.
     *
     * @return The next string in the argument list.
     *
     * @throws HeyParserException if there are no more arguments to be
     * consumed.
     */
    const char *consumeArg(void)
        throw (HeyParserException);

    /**
     * Find the next name/value pair in the argument list.  This method differs
     * from popProperty() in that it translates from the argument list to
     * hp_PropertyStack.  Whereas popProperty() interacts only with
     * hp_PropertyStack.
     *
     * @sideeffect The top element of hp_PropertyStack is popped off.
     *
     * @param name_out The reference where the property name should be stored.
     * @param value_out The reference where the property value should be
     * stored.
     *
     * @throws HeyParserException if there are insufficient arguments.
     */
    void nextProperty(const char *&name_out, const char *&value_out)
        throw (HeyParserException);

    /**
     * The arguments count.
     */
    int hp_ArgCount;

    /**
     * The argument values.
     */
    const char **hp_ArgValue;

    /**
     * The "what" value.  This will only be set by the constructor when it is
     * initially parsing the arguments.
     */
    hp_what_t hp_What;

    /**
     * The 'to' value for a SET_PROPERTY request.
     */
    const char *hp_ToValue;

    /**
     * The current index in the argument list during processing.
     */
    int hp_ArgIndex;

    /**
     * The stack of property pairs.
     */
    stack<struct Pair> hp_PropertyStack;
    
};

/**
 * Helper class that holds descriptions of properties.
 *
 * @see HeyParser
 */
class HeyPropertyInfo
{

public:

    /**
     * Construct a description of a property.  For example, if a server
     * supported the following requests on a 'string' object:
     *
     * @code
     * $ hey server create string with id 2 value Foobar
     * ok
     * $ hey server get string 2
     * Foobar
     * $ hey server delete string 2
     * ok
     * $ hey server get string 2
     * Error: No such string: 2
     * @endcode
     *
     * The 'suites' for these requests would be encoded by the following
     * array of HeyPropertyInfo's.
     *
     * @code
     * HeyPropertyInfo suites[] = {
     *     HeyPropertyInfo("string",
     *                     (1L << HeyParser::CREATE_PROPERTY),
     *                     "",
     *                     "id:int - The string's identifer.\n"
     *                     "value:string - The string's value.\n"
     *                     "\n"
     *                     "Create a string with the given id and value.\n"),
     *     HeyPropertyInfo("string",
     *                     (1L << HeyParser::GET_PROPERTY) |
     *                     (1L << HeyParser::SET_PROPERTY),
     *                     "id:int",
     *                     "Get or set the value of string 'id'.\n"),
     *     HeyPropertyInfo("string",
     *                     (1L << HeyParser::DELETE_PROPERTY),
     *                     "id:int",
     *                     "Delete a string 'id'.\n"),
     *     HeyPropertyInfo::HPI_NULL // TERMINATOR
     * };
     * @endcode
     *
     * The first object indicates that the 'string' property supports
     * CREATE_PROPERTY and takes two arguments, the string identifier and the
     * string's value.  The second and third objects also describe the
     * 'string' property, but this time, they document what happens when used
     * with the get, set, and delete actions.  These objects are then grouped
     * in an array so they can be easily sent to an output stream, like so:
     *
     * @code
     *   cout << suites;
     * @endcode
     *
     * The result would then look like the following:
     *
     * @code
     * $ hey server getsuites
     * Property:  string
     *   Supported verbs: create
     * Create a string with the given id and value.
     *
     * Property:  string
     *   Supported verbs: get set
     *   Specifiers:  id:int
     * Get or set the value of string 'id'.
     *
     * Property:  string
     *   Supported verbs: create
     *   Specifiers:  id:int
     * Delete a string 'id'.
     *
     * @endcode
     *
     * @param name The name of the property.
     * @param commands The commands supported by the property.  The commands
     * are encoded as a bitmap of the HeyParser::hp_what_t values.
     * @param specifiers A description of the specifier argument.
     * @param usage A description of the property and how to use it.
     */
    HeyPropertyInfo(const char *name,
                    unsigned int commands,
                    const char *specifiers = NULL,
                    const char *usage = NULL)
        : hpi_Name(name),
          hpi_Commands(commands),
          hpi_Specifiers(specifiers),
          hpi_Usage(usage)
    {
    };

    /**
     * Deconstruct a HeyPropertyInfo.
     */
    virtual ~HeyPropertyInfo(void)
    {
    };

    /**
     * @return The property's name.
     */
    const char *getName(void) const
    {
        return this->hpi_Name;
    };

    /**
     * @return The bitmap of commands supported by this property.
     */
    unsigned int getCommands(void) const
    {
        return this->hpi_Commands;
    };

    /**
     * @return The string describing the specifier argument, if any.
     */
    const char *getSpecifiers(void) const
    {
        return this->hpi_Specifiers;
    };

    /**
     * @return The string describing how to use this property.
     */
    const char *getUsage(void) const
    {
        return this->hpi_Usage;
    };

    /**
     * Output stream operator for HeyPropertyInfo objects.
     *
     * @param os The destination output stream.
     * @param hpi The object to output.
     * @return The value of the 'os' parameter.
     */
    friend std::ostream &operator<<(std::ostream &os,
                                    const HeyPropertyInfo &hpi)
    {
        unsigned int lpc;

        os << "Property:  " << hpi.hpi_Name << endl
           << "  Supported verbs:";
        for( lpc = 0; lpc < HeyParser::WHAT_MAX; lpc++ )
        {
            if( hpi.hpi_Commands & (1L << lpc) )
            {
                os << " " << HeyParser::hp_what_strings[lpc];
            }
        }
        os << endl;
        if( (hpi.hpi_Specifiers != NULL) &&
            (hpi.hpi_Specifiers[0] != '\0') )
        {
            os << "  Specifiers:  " << hpi.hpi_Specifiers << endl;
        }
        if( (hpi.hpi_Usage != NULL) && (hpi.hpi_Usage[0] != '\0') )
        {
            os << hpi.hpi_Usage;
        }
        return( os );
    };

    /**
     * Output stream operator for an HPI_NULL terminated array of
     * HeyPropertyInfo objects.
     *
     * @param os The destination output stream.
     * @param hpi The array to output.
     * @return The value of the 'os' parameter.
     */
    friend std::ostream &operator<<(std::ostream &os,
                                    const HeyPropertyInfo hpi[])
    {
        unsigned int lpc;

        for( lpc = 0; hpi[lpc].getCommands() != 0; lpc++ )
        {
            os << hpi[lpc] << endl;
        }
        return( os );
    };

    /**
     * Typed NULL for HeyPropertyInfo's.
     */
    static HeyPropertyInfo HPI_NULL;

private:

    /**
     * The property's name.
     */
    const char *hpi_Name;
    
    /**
     * The bitmap of commands supported by this property.
     */
    unsigned int hpi_Commands;
    
    /**
     * The string describing the specifier argument, if any.
     */
    const char *hpi_Specifiers;
    
    /**
     * The string describing how to use this property.
     */
    const char *hpi_Usage;
    
};

#endif

---