parsing.h

Go to the documentation of this file.

/*
 * parsing.h
 *
 * Copyright (C) 2007,2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Simple parsing helper methods.
 */

#ifndef WAVEPACKET_PARSING_H__
#define WAVEPACKET_PARSING_H__

// includes --------------------------------------------------------------------
#include "common/common.h"

#include <iostream>


/// \ingroup util
/*@{*/

////////////////////////////////////////////////////////////////////////////////
//
//      parsing helper methods
//
////////////////////////////////////////////////////////////////////////////////

/// a UTF-8 character.  Note that this is multiple 8-bit chars in a sequence.
///     See http://en.wikipedia.org/wiki/Utf8
struct utf8_char_t {
        enum eConstants {
                eHighBit        = 0x80, ///< high bit set
                eTwoHigh        = 0xC0, ///< both high bits set
                eMaxChars       = 6,    ///< from RFC 3629
                eBufferSize     = 8     ///< internal use only--keep dword align
        };

        // constructor, manipulators
        utf8_char_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        nBytes = 1;
                        value[0] = 0;   // null character
                }
        int getByteCount(void) const throw() { return nBytes; }
        int getValue(void) const throw();
        void setToReplacement(void) throw();
        void dump(IN const char * title) const throw();

        /// "!c" means c is a null character, or invalid
        bool operator !(void) const throw() {
                        return (nBytes < 1) || (0 == value[0]);
                }

        /// inversion of ! operator: c is true if it is valid and non-null
        operator bool (void) const throw() {
                        return (nBytes > 0) && (nBytes <= eMaxChars) && value[0];
                }

        /// is this valid?  Can be both valid and null!
        bool isValid(void) const throw() {
                        // note that we are not doing full validation of bit
                        // flags
                        return (nBytes > 0) && (nBytes <= eMaxChars);
                }

        /// single-byte character comparison
        bool operator == (IN char a) const throw() {
                        return (1 == nBytes) && (value[0] == a);
                }

        // data fields
        char            value[eBufferSize];
        int             nBytes;
};



/// is this character a single-byte (ASCII) UTF-8 character?
inline bool isSingleByteUTF8Character(IN char a) throw()
{
        // single-byte character if high bit is NOT set
        return (!(utf8_char_t::eHighBit & a));
}



/// is this character the leading byte of a multi-byte UTF-8 character?
inline bool isMultiByteUTF8Character(IN char a) throw()
{
        // multi-byte leading character if both high bits set
        return ((utf8_char_t::eTwoHigh & (byte_t) a) == utf8_char_t::eTwoHigh);
}



/// is this character a (likely) leading byte for a UTF-8 character?
inline bool isLeadingUTF8Byte(IN char a) throw()
{
        // leading character if high bit is unset, or both high bits set
        return (isSingleByteUTF8Character(a) ||
                isMultiByteUTF8Character(a));
}



/// is this character a trailing byte for a multi-byte UTF-8 character?
inline bool isTrailingUTF8Byte(IN char a) throw()
{
        // trailing character if high bit is set, next bit not set
        return ((utf8_char_t::eTwoHigh & (byte_t) a) == utf8_char_t::eHighBit);
}



/// get the next (UTF-8) character from the stream
///     returns false on eof (end of stream)
bool getUTF8CharacterFromStream(IN std::istream& stream,
                        OUT utf8_char_t& c);



/// get the next (UTF-8) character from the given string
///     returns a pointer to the next character in the string
const char * getUTF8CharacterFromString(IN const char * input,
                        OUT utf8_char_t& c);



/// given an initial byte of a (potentially) multi-byte UTF-8 character,
///     return how many bytes total in the character
/// returns -1 on error.
int getUTF8ByteCount(IN char a);



// sigh... Win32 version of isspace() is broken for UTF8!  need to wrap
#ifdef WIN32
// win32 - force casting to char so win32 doesn't freak out
#define isSpace( c ) isspace( (0xff & ((char) c)) )
#else   // WIN32
// other OS's: isspace() is okay
#define isSpace( c ) isspace(c)
#endif  // WIN32

/// retrieves the next word from the specified line of text, and returns a
///     pointer to the first character in the line after the word.  Leading
///     whitespace will be ignored when parsing.
///     The word returned will either be empty, a newline, or a set of
///     non-space characters.  If the returned word is empty, then NULL is
///     also the return value (word can only be empty at end-of-line).  Note
///     that you can have non-empty words returned with a NULL return value.
const char * getNextWord(IN const char * text,
                        OUT std::string& word);


/// eParseBehavior: these can be OR'd together
enum eParseBehavior {
        // fundamental behaviors
        eParse_None             = 0x0000,       ///< no special behavior
        eParse_StripComments    = 0x0001,       ///< strip comments (start with #)
        eParse_StripBogus       = 0x0002,       ///< strip bogus characters ('\\r')
        eParse_RespectQuotes    = 0x0004,       ///< treat quoted tokens as a unit

        // common combinations
        eParse_Strip            = 0x0003,       ///< strip comments + bogus

        // must be last!
        eParse_Invalid          = 0x8000
};


///   Reads to the next newline or end of stream, and stashes all characters
///     (except the final newline) in the output string.
///   Caller can ask to have comments and/or bogus characters stripped out.
///   returns a std::string containing the line.  throws on errors
///     This routine is UTF-8 compliant.
std::string getNextLineFromStream(IN std::istream& stream,
                                IN eParseBehavior behavior);


///   finds the next whitespace-delimited token, and puts it in the given token
///     (std::string).
///   returns a pointer to the character (whitespace or end of string) right
///     after the token.
///     This routine is UTF-8 compliant.
const char * getNextTokenFromString(IN const char * input,
                                OUT std::string& token,
                                IN eParseBehavior);


///  finds the next whitespace-delimited token, and puts it in the given
///    buffer.
///  returns a pointer to the character right after the token
///  the chars parameter returns how many characters are in the buffer.
///  the buffer is null-terminated
///  if the buffer wasn't big enough for the token, the token will be
///    truncated.  The buffer will be null-terminated (the routine
///    saves enough room for the final null).  chars will contain the
///    number of characters parsed from the string, even if not all of
///    them were copied into the buffer.  So you can detect truncation
///    if chars >= buffer_size.
///     This routine is UTF-8 compliant
const char * getNextTokenFromString(IN const char * input,
                                IO char * buffer,
                                IN int buffer_size,
                                IN eParseBehavior,
                                OUT int& chars) throw();


/// expects the given token to be next in the string.  Throws if the
///     next token is something else.  Returns a pointer to the character
///     immediately following the expected token.
const char * expectFromString(IN const char * input,
                                IN const char * expect,
                                IN eParseBehavior);


/// helper method to extract a float (assuming it is the next token)
///     This routine is UTF-8 compliant
const char * getFloatFromString(IN const char * input,
                                OUT float& x) throw();


/// helper method to read up to N floats.  Returns the number read.
/// Assumes that that caller doesn't need the string returned!
/// The caller must provide a pre-allocated array of floats for
///     output.
int readFloatsFromString(IN const char * input,
                                IN int nFloats,
                                OUT float * output) throw();


/// tries to determine if the given string is a true or false value.
///     This is NOT localized.  This is for machine-parsed input only,
///     such as config files.  A string is considered false if it is
///     the word "false" (any case), the single letter "F", the
///     character "0", or empty.  Any other value is considered true.
///     Note that expressions that evaluate to zero but are not a
///     single digit, such as "-0" or "+0", are considered true.
bool getBooleanFromString(IN const char * input) throw();


///    true if the given character is bogus ('\\r', etc)
bool isBogus(IN char a) throw();


/// dictionary routines
///   These let you construct a dictionary (key -> value map) based on an input
///   string, and then look for required/optional values.
typedef Dictionary dictionary_t;        // map of key->value pairs

void getDictionaryFromString(IN const char * string,
                                IN const char * debug_info,
                                OUT dictionary_t& data);

const char * getValue(IN const dictionary_t&, IN const char * key);
const char * getRequiredValue(IN const dictionary_t&, IN const char * key);
const char * getOptionalValue(IN const dictionary_t&, IN const char * key,
                        IN const char * default_value) throw();


/// inplace conversion to lower case (returns pointer to beginning of string)
//char * lowercase(char * text) throw();

#endif  // WAVEPACKET_PARSING_H__