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 class.
 */

#ifndef _hey_parser_hh
#define _hey_parser_hh

#include <stack>
#include <iostream>

/**
 * 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.
     */
    HeyParserException(const char *msg = NULL)
    {
        this->hpe_Message = msg;
    };

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

    /**
     * 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 ostream &operator<<(ostream &os, const HeyParserException &hpe)
    {
        return os << (hpe.hpe_Message != NULL ? hpe.hpe_Message : "");
    };

private:

    /**
     * A short message describing the problem.
     */
    const char *hpe_Message;
    
};

/**
 * A parser for command-line arguments given in the pseudo-english "hey" form:
 *
 *   @li hey @<server@> list
 *   @li hey @<server@> get @<attribute@> of @<object@>
 *   @li hey @<server@> set @<attribute@> of @<object@> to @<value@>
 *
 * @see hey_manager.cc
 * @see hey_strict_policy.cc
 */
class HeyParser
{

public:

    /**
     * An enumeration of the possible actions to perform on an object.
     */
    typedef enum {
        LIST_PROPERTIES,        /**< List the properties of an object. */
        GET_PROPERTY,           /**< Get a property from an object. */
        SET_PROPERTY,           /**< Set a property in an object. */
    } hp_what_t;

    /**
     * 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.
     *
     * @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();

    /**
     * @return The argument that specifies which server to talk to.
     */
    const char *who(void);

    /**
     * @return The action requested by the user (i.e. what to do).
     */
    hp_what_t what(void);

    /**
     * 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.
     *
     * @throws HeyParserException if "to" was not given on the command line.
     */
    const char *to(void)
        throw (HeyParserException);
    
private:

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

    public:

        /**
         * Construct an empty Pair object.
         */
        Pair()
        {
            this->p_Name = NULL;
            this->p_Value = NULL;
        };

        /**
         * Construct a Pair object with the given name/value pair.
         *
         * @param name The name.
         * @param value The value.
         */
        Pair(const char *name, const char *value) :
            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.
     *
     * @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.
     *
     * @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 current index in the argument list during processing.
     */
    int hp_ArgIndex;

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

#endif

---