Beesnest/DcParameters.h

Go to the documentation of this file.

/*
Copyright 2007 Erez Bibi (erezbibi@users.sourceforge.net)
This file is part of Beesnest.

Beesnest is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Beesnest is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Beesnest; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

/* DcParameters.h: interface for the CdcParameters class. */


#ifndef CDC_PARAMETERS
#define CDC_PARAMETERS

#include "DcGlobals.h"
#include "DcExceptionFile.h"
#include _GET_INCLUDE_PATH (DcFileUtil.h)

/**
 * Reads, Parses and holds the Beesnest configuration. <br>
 *
 * <p><b>That was silly - I Need to work with a regular XML parser or not with
 * an XML format at all.</b></p>
 *
 * This class contains just static data members and functions. it reads
 * parameters from a XML-like file, and stores them for the use of this server.
 *
 * <p>
 * The format of the Parameters file is similar to a normal XML format, BUT:<br>
 * - From a # sign to the end of the line, the text is ignored (a comment).<br>
 * - You cannot insert a list of nodes with the same name.<br>
 * - A node cannot be self closed, like "&lt;Node /&gt;".<br>
 * - Beesnest ignores node attributes, but you can put them in the file.<br>
 * - There is no XML header in the beginning of the page.<br>
 * - There are no standard XML comments.<br>
 *
 * <p>
 * All the parameters are stored as strings. There is a function to convert a
 * string to an integer.
 *
 * <p>
 * The parameters get stored in a map (hash table), and a tree. the name of each
 * parameter is 'field1'->'field2'... <br>
 * e.g. if the file look like this: <br>
 * <pre>
 * &lt;Beesnest&gt;
 *      &lt;Server&gt;
 *      &lt;Name&gt; Val &lt;/Name&gt;
 *      &lt;/Server&gt;
 * &lt;/Beesnest&gt;
 * </pre>
 * The value 'Val' will be stored under the name: "Server->Name"
 *
 * The user can look for a value under some point in the tree as well.
 *
 * @author Erez Bibi
 * @version 1.0
 */
class CdcParameters
{
private:

    class CdcObject
    { };

public:
    /** Node in the tree. */
    class CdcNode : public CdcObject
    {
    public:

        typedef list <CdcObject*> t_node_list;
        t_node_list oNodes; /* List of child nodes. */
        CdcNode* up;        /* Pointer to the father. */
        CdcString name;     /* The name of this node. */
        CdcString value;    /* The value of this node. */
        CdcNode (const CdcString& n, CdcNode* u)    /* Constructor. */
            :name (n), up (u) {}
    };

private:
    typedef map <string, CdcNode*> t_obj_map;

    /** The hash table that holds the nodes (parameters). */
    static t_obj_map mParam;

    /** No Constructor or Destructor available. */
    CdcParameters() {}
    virtual ~CdcParameters() {}

    /**
     * This function looks for a value under some node in the tree. This is a
     * recursive function.
     * <p>
     * @param node The node to start to look under.
     * @param value The value to look for.
     * @param partly True if looking for part of a value. False is
     * the default.
     * @return (bool) True if this value exists under this node.
     */
    static bool IsUnder (CdcParameters::CdcNode* node,
        const CdcString& value, bool partly);

    /**
     * This function looks for a node name in the tree. This is a recursive
     * function.
     * <p>
     * @param name The node name to look for.
     * @param node The node to start the search at.
     * @param append_name True if the return value should be the node name
     * appended to the recursive call result. False if the return
     * value is just the recursive call result.
     * @return The full name of this parameter.
     */
    static CdcString FindName (const CdcString& name,
        CdcParameters::CdcNode* node, bool append_name);

    /**
     * Build a CdcString buffer from all the text files in the path <b>path</b>
     * and with extension <b>ext</b>.
     * <p>
     * @param buff The string buffer to fill.
     * @param path The path to take the files from (w/o sub directories).
     * @param ext The extension of the files to take.
     */
    static void BuildParamBuffer (CdcString& buff,
        const CdcString& path, const CdcString& ext);

    /**
     * Read a text file into CdcString. It reads the file without lines that
     * start with '#' or empty lines.
     * <p>
     * @param buff The string buffer to fill.
     * @param file_name The file to read.
     */
    static void ReadParamFile (CdcString& buff, const CdcString& file_name);

public:

    /**
     * This static function reads the Parameters file, parses it, and fills the
     * values of the class parameters (map).
     * <p>
     * @param file_ext The files extension to read, as string.
     * @return (bool) True if the Parameters file format is Well-Formed
     * (according to my rules...).
     * @throw (CdcException) if the Parameters file format is wrong.
     */
    static bool ReadParams (const char* file_ext) throw (CdcException);

    /**
     * Return a string from the parameters map.
     * <p>
     * @param name The name of the parameter.
     * @return (CdcString) the value of the parameter (as string) or an empty
     * string.
     */
    static CdcString GetParam (const CdcString& name);
    static CdcString GetParam (const char* name)
    { return GetParam (CdcString (name)); }

    /**
     * Return a pointer to the node that name is pointing to.
     * <p>
     * @param name The name of the parameter (node).
     * @return (CdcNode) Pointer to a node or NULL.
     */
    static CdcNode* GetNodePointer (const char* name);

    /**
     * This function looks for some value under a point in the parameters tree
     * (node).
     * <p>
     * @param name The point to start look for the value. It should be built as
     * "Field1->Field2->...".
     * @param value The value to look for.
     * @param partly True if looking for part of a value. False is the default.
     * @return (bool) True if this value exists under this point.
     */
    static bool IsUnder (const CdcString& name, const CdcString& value,
        bool partly = false);
    static bool IsUnder (const char* name, const CdcString& value,
        bool partly = false)
    { return IsUnder (CdcString (name), value, partly); }


    /**
     * This function returns the full parameter name of a parameter with direct
     * name of <b>name</b>.
     * <p>
     * E.g. if <b>name</b> is "Format" and <b>start_at</b> is "Server", the
     * returned value will be "Server->Log-File->Format".
     * <p>
     * @param name The parameter name to look for.
     * @param start_at The place to start the search at.
     * @return (CdcString) The full name of this parameter.
     */
    static CdcString GetFullName (const CdcString& name,
        const CdcString& start_at);

    /**
     * Try to convert a string to an integer.
     * <p>
     * @param str The string to convert.
     * @return (int) The value of the string or 0 if it cannot be converted
     */
    static int ToInt (const CdcString& str);

    /**
     * Every adapter/engine gets a pointer to this function, so it can get
     * values from the configuration database.
     * <p>
     * @param name The name (path) of the required value.
     * @param val Buffer to put the value in.
     * @param max_len The size of this buffer.
     * @return True if the parameter was found in the database.
     */
    friend bool ExtGetParam (const char* name, char* val, int max_len);

};

#endif /*  CDC_PARAMETERS */