cvrIoHandler.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998-2004
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 *
 *
 * This file is part of the Computer Vision and Robotics Library (CVR-Lib)
 *
 * The CVR-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the BSD License.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. 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.
 *
 * 3. Neither the name of the authors 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 THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 THE COPYRIGHT OWNER OR CONTRIBUTORS 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.
 */



/**
 * \file   cvrIoHandler.h
 *         Contains the class cvr::ioHandler, which is the base for all
 *         serialization concepts in the CVR-Lib
 * \author Pablo Alvarado
 * \date   07.12.2000
 *
 * $Id: cvrIoHandler.h,v 1.12 2006/09/29 13:35:19 doerfler Exp $
 */

#ifndef _CVR_IO_HANDLER_H_
#define _CVR_IO_HANDLER_H_


#include "cvrObject.h"
#include "cvrTypes.h"
#include "cvrStatus.h"
#include <string>
#include <iosfwd> // required for method use()

namespace cvr {

  /**
   * Input/output handlers.
   *
   * The ioHandler classes offer an abstract interface for the functor
   * parameters and other cvr::ioObject classes to read() and write() them in
   * different formats.
   *
   * The CVR-Libstandard ioHandler is the cvr::lispStreamHandler, which uses
   * a LISP-similar syntax to write and read data from streams.  To save space
   * and time while serializing objects, you can use the
   * cvr::binaryStreamHandler.
   *
   * All ioHandlers are used as wrappers for std::istreams or std::ostreams
   * objects.  Therefore, the abstract interface provides the virtual methods
   * use() to indicate which stream has to be used.
   *
   * @ingroup gStorable
   */
  class ioHandler : public object, public status {
  public:

    /**
     * Default constructor
     */
    ioHandler();

    /**
     * Copy constructor
     */
    ioHandler(const ioHandler& other);

    /**
     * Destructor
     */
    virtual ~ioHandler();

    /**
     * Copy data of "other" functor.
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    ioHandler& copy(const ioHandler& other);

    /**
     * Returns the name of this class.
     */
    virtual const std::string& name() const = 0;

    /**
     * Returns a pointer to a clone of this functor.
     */
    virtual ioHandler* clone() const = 0;

    /**
     * Returns a pointer to a new instance of the dynamic class type.
     */
    virtual ioHandler* newInstance() const = 0;

    /**
     * Indicate the output stream to be used
     *
     * Calling this method you will reinitialize the state of the
     * parser (see also clear()).
     */
    virtual void use(std::ostream& aStream) = 0;

    /**
     * Indicate the input stream to be used
     *
     * Calling this method you will reinitialize the state of the
     * parser (see also clear()).
     */
    virtual void use(std::istream& aStream) = 0;

    /**
     * Write the begin token or tokens
     */
    virtual bool writeBegin();

    /**
     * Write the end token or tokens
     */
    virtual bool writeEnd();

    /**
     * Read the begin token or tokens
     */
    virtual bool readBegin();

    /**
     * Read the end token or tokens
     */
    virtual bool readEnd();

    /**
     * \name Write methods for standard types
     */
    //@{
    /**
     * Write standard types
     */
    virtual bool write(const std::string& data) = 0;
    virtual bool write(const char* data) = 0;
    virtual bool write(const double& data) = 0;
    virtual bool write(const float& data) = 0;
    virtual bool write(const int data) = 0;
    virtual bool write(const unsigned int& data) = 0;
    virtual bool write(const char& data) = 0;
    virtual bool write(const byte& data) = 0;
    virtual bool write(const ubyte& data) = 0;
    virtual bool write(const bool data) = 0;
    virtual bool write(const long& data) = 0;
    virtual bool write(const unsigned long& data) = 0;
    virtual bool write(const short& data) = 0;
    virtual bool write(const unsigned short& data) = 0;
    //@}


    /**
     * \name Write methods for symbol-data pairs
     */
    //@{
    /**
     * Write symbol-data pair
     */
    virtual bool write(const std::string& name,const std::string& data);
    virtual bool write(const std::string& name,const char* data);
    virtual bool write(const std::string& name,const double& data);
    virtual bool write(const std::string& name,const float& data);
    virtual bool write(const std::string& name,const int data);
    virtual bool write(const std::string& name,const unsigned int& data);
    virtual bool write(const std::string& name,const char& data);
    virtual bool write(const std::string& name,const byte& data);
    virtual bool write(const std::string& name,const ubyte& data);
    virtual bool write(const std::string& name,const bool data);
    virtual bool write(const std::string& name,const long& data);
    virtual bool write(const std::string& name,const unsigned long& data);
    virtual bool write(const std::string& name,const short& data);
    virtual bool write(const std::string& name,const unsigned short& data);
    //@}

    /**
     * \name Read methods for standard types
     */
    //@{
    /**
     * Read standard type
     */
    virtual bool read(std::string& data) = 0;
    virtual bool read(double& data) = 0;
    virtual bool read(float& data) = 0;
    virtual bool read(int& data) = 0;
    virtual bool read(unsigned int& data) = 0;
    virtual bool read(char& data) = 0;
    virtual bool read(byte& data) = 0;
    virtual bool read(ubyte& data) = 0;
    virtual bool read(bool& data) = 0;
    virtual bool read(long& data) = 0;
    virtual bool read(unsigned long& data) = 0;
    virtual bool read(short& data) = 0;
    virtual bool read(unsigned short& data) = 0;
    //@}

    /**
     * \name Read methods for symbol-data pairs
     */
    //@{
    /**
     * Read symbol-data pair
     */
    virtual bool read(const std::string& name, std::string& data);
    virtual bool read(const std::string& name, double& data);
    virtual bool read(const std::string& name, float& data);
    virtual bool read(const std::string& name, int& data);
    virtual bool read(const std::string& name, unsigned int& data);
    virtual bool read(const std::string& name, char& data);
    virtual bool read(const std::string& name, byte& data);
    virtual bool read(const std::string& name, ubyte& data);
    virtual bool read(const std::string& name, bool& data);
    virtual bool read(const std::string& name, long& data);
    virtual bool read(const std::string& name, unsigned long& data);
    virtual bool read(const std::string& name, short& data);
    virtual bool read(const std::string& name, unsigned short& data);
    //@}

    /**
     * Write a std::string as a symbol token.
     *
     * A symbol must not contain special characters or spaces.  Only letters
     * and numbers are allowed, and the first character must be a letter.
     *
     * @param data The symbol to be written
     */
    virtual bool writeSymbol(const std::string& data) = 0;

    /**
     * Write comment writes the input data without any preprocessing,
     * just ensuring that the comment format is given
     */
    virtual bool writeComment(const std::string& data) = 0;

    /**
     * Write comment writes the input data without any preprocessing,
     * just ensuring that the comment format is given
     */
    virtual bool writeComment(const char* data) = 0;

    /**
     * Read a std::string as a symbol token
     *
     * A symbol must not contain special characters or spaces.  Only letters
     * and numbers are allowed, and the first character must be a letter.
     *
     * @param data the symbol readed will be left here
     */
    virtual bool readSymbol(std::string& data) = 0;

    /**
     * Try to read the given symbol from the handler.
     * If present, returns true and the token is removed from the
     * handler, if not present returns false and leaves the handle as
     * it was before calling this member...
     *
     * A symbol must not contain special characters or spaces.  Only letters
     * and numbers are allowed, and the first character must be a letter.
     *
     * @param data the symbol to be readed
     */
    virtual bool trySymbol(const std::string& data) = 0;

    /**
     * Try to read the begin token from the handler.
     * If present, returns true and the token is removed from the
     * handler, if not present returns false and leaves the handle as
     * it was before calling this member...
     */
    virtual bool tryBegin() = 0;

    /**
     * Try to read the end token from the handler.
     * If present, returns true and the token is removed from the
     * handler, if not present returns false and leaves the handle as
     * it was before calling this member...
     */
    virtual bool tryEnd() = 0;

    /**
     * Write spaces (default value 1)
     * The spaces are tokes that will be ignored by reading
     * @param s the number of space-tokens to be written
     */
    virtual bool writeSpaces(const int s=1) = 0;

    /**
     * Write end-of-line token
     * The EOL are tokes that will be ignored by reading
     */
    virtual bool writeEOL() = 0;

    /**
     * Write key/value separator.
     * The key/value separator is the token which will separate a symbol from
     * its value in a symbol-data-pair.
     */
    virtual bool writeKeyValueSeparator() = 0;

    /**
     * Write inter-data separator.
     * The data-separator token separates data elements in a data list or array
     */
    virtual bool writeDataSeparator() = 0;

    /**
     * Read key/value separator token.
     */
    virtual bool readKeyValueSeparator() = 0;

    /**
     * Read inter-data separator token.
     */
    virtual bool readDataSeparator() = 0;

    /**
     * Return the actual nesting level for begins and ends.
     *
     * Example
     * \code
     * ioHandler_childClass h; // h is an ioHandler of a childClass
     *                         // this could be for example a lispStreamHandler
     * int i;
     * i = h.getLevel(); // returns 0;
     * h.writeBegin();
     * i = h.getLevel(); // returns 1;
     * h.writeBegin();
     * i = h.getLevel(); // returns 2;
     * h.writeEnd();
     * i = h.getLevel(); // returns 1;
     * h.writeEnd();
     * i = h.getLevel(); // returns 0;
     * \endcode
     */
    virtual const int& getLevel() const;

    /**
     * Restore all the information in the handler taken in the actual
     * level.
     */
    virtual bool restoreLevel() = 0;

    /**
     * Usually this member is needed by reinitialization routines to set
     * the begin/end nesting level to zero.
     */
    virtual void resetLevel(const int theLevel = 0);

    /**
     * Append contextual information
     *
     * This function should help the users to find errors in their files.
     * It just inserts some contextual information into the status string
     * to help localizing wrong data.
     *
     * It is useful for streams that can be edited by hand, because the
     * users will make errors!
     *
     * The default behaviour does nothing.
     */
    virtual void appendContextStatus() const;


  protected:
    /**
     * begin() nesting level
     */
    int level_;

  };

  /**
   * \name Read functions for standard types
   */
  //@{
  bool read(ioHandler& handler,std::string& data);
  bool read(ioHandler& handler,double& data);
  bool read(ioHandler& handler,float& data);
  bool read(ioHandler& handler,int& data);
  bool read(ioHandler& handler,unsigned int& data);
  bool read(ioHandler& handler,char& data);
  bool read(ioHandler& handler,byte& data);
  bool read(ioHandler& handler,ubyte& data);
  bool read(ioHandler& handler,bool& data);
  bool read(ioHandler& handler,long& data);
  bool read(ioHandler& handler,unsigned long& data);
  bool read(ioHandler& handler,short& data);
  bool read(ioHandler& handler,unsigned short& data);
  //@}

  /**
   * \name Write functions for standard types
   */
  //@{
  bool write(ioHandler& handler,const std::string& data);
  bool write(ioHandler& handler,const char* data);
  bool write(ioHandler& handler,const double& data);
  bool write(ioHandler& handler,const float& data);
  bool write(ioHandler& handler, const int data);
  bool write(ioHandler& handler,const unsigned int& data);
  bool write(ioHandler& handler,const char& data);
  bool write(ioHandler& handler,const byte& data);
  bool write(ioHandler& handler,const ubyte& data);
  bool write(ioHandler& handler,const bool data);
  bool write(ioHandler& handler,const long& data);
  bool write(ioHandler& handler,const unsigned long& data);
  bool write(ioHandler& handler,const short& data);
  bool write(ioHandler& handler,const unsigned short& data);
  //@}



  /**
   * @name Read functions with standard storable interface
   */
  //@{
  // Implementation note: The non-template overloads are needed since
  // otherwise these templates get instantiated a lot in the parameters IO
  // functions
  bool read(ioHandler& handler, const std::string& name,
            std::string& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            double& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            float& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            int& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            unsigned int& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            char& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            byte& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            ubyte& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            bool& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            long& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            unsigned long& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            short& data, const bool complete=true);
  bool read(ioHandler& handler, const std::string& name,
            unsigned short& data, const bool complete=true);

  template <class T>
  bool read(ioHandler& handler,const std::string& name,
            T& data,const bool complete=true);
  //@}

  /**
   * @ name Write functions with standard storable interface
   */
  //@{
  // Implementation note: The non-template overloads are needed since
  // otherwise these templates get instantiated a lot in the parameters IO
  // functions
  bool write(ioHandler& handler, const std::string& name,
             const std::string& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const char* data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const double& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const float& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const int data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const unsigned int& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const char& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const byte& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const ubyte& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const bool data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const long& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const unsigned long& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const short& data, const bool complete=true);
  bool write(ioHandler& handler, const std::string& name,
             const unsigned short& data, const bool complete=true);

  template <class T>
  bool write(ioHandler& handler,const std::string& name,
             const T& data,const bool complete=true);
  //@}

}

#include "cvrIoHandler_template.h"

#endif