cvrStatus.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   cvrStatus.h
 *         Contains the class cvr::status, which is the parent class for all
 *         classes that can provide status information.
 * \author Jochen Wickel
 * \author Thomas Rusert
 * \author Pablo Alvarado
 * \date   14.04.2004
 *
 * $Id: cvrStatus.h,v 1.7 2007/10/07 03:17:00 alvarado Exp $
 */

#ifndef _CVR_STATUS_H_
#define _CVR_STATUS_H_

#include <string>


namespace cvr  {
  class statusMonitor;

  /**
   * Base class for all CVR-Lib objects that have a status for error
   * handling.
   *
   * This is sort of an interface, which does not inherit from cvr::object
   * interface, since it is assumed that the objects that inherit from this
   * class will also directly or indirectly inherit from cvr::object.
   *
   * You can set a class inherited from cvr::statusMonitor to select how errors
   * have to be reported.  See the method status::setStatusMonitor and the
   * nested class status::object for more information.
   *
   * @see cvr::statusMonitor, cvr::status::object
   *
   * \ingroup gInterfaces
   */
  class status {
  public:
    /**
     * Class for status string storing and formatting.
     *
     * The status::statusObject is an abstraction that allows a flexible formatting
     * of the status strings and a way of knowing that the string has been
     * completed.
     *
     * When you have a class that inherits from cvs::status the methods of that
     * at class can report errors simply by calling
     *
     * \code
     * setStatusString("Invalid arguments detected.");
     * \endcode
     *
     * That method returns an instance of a status::statusObject, which allows
     * appending additional information, but only if the string set through
     * \c setStatusString has the special tokens \%1 to \%9.
     * These tokens are then replaced by some information you provide through
     * the operator%.
     *
     * For instance:
     * \code
     * int val = 5;
     * std::string str = "hello";
     * setStatusString("Val=%1 and the string str=%2")%val%str;
     * \endcode
     * would produce the status string "Val=5 and the string str=hello".
     *
     * If you wish to delay providing the parameters you can do:
     * \code
     * int val = 5;
     * std::string str = "
     * setStatusString("Val val=%1 and the string str=%2");
     * getStatusObject()%val;
     * getStatusObject()%str;
     * \endcode
     * 
     * This is an internal class to encapsulate the operator%.  Outside this
     * object, the operator% means modulus, but in the context of error reports
     * it can have its own meaning.  If fact, the use of operator% for this
     * task is is inspired (remotely) on one of the boost libraries.
     */
    class statusObject {
    public:
      /**
       * Constructor
       */
      statusObject();

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

      /**
       * Destructor
       */
      ~statusObject();

      /**
       * Copy another statusObject instance
       */
      statusObject& copy(const statusObject& other);

      /**
       * Copy another statusObject instance (alias for copy())
       */
      statusObject& operator=(const statusObject& other);

      /**
       * Set and parse the status string
       */
      void set(const std::string& className,const std::string& str);

      /**
       * Set and parse the status string
       */
      void set(const std::string& className,const char* str);

      /**
       * Get the current status string
       */
      const std::string& get() const;

      /**
       * Fill an integer argument.
       */
      statusObject& operator%(const int data);

      /**
       * Fill a double argument.
       */
      statusObject& operator%(const double data);

      /**
       * Fill a std::string argument.
       */
      statusObject& operator%(const std::string& data);

      /**
       * Fill a const char chain.
       */
      statusObject& operator%(const char* data);

      /**
       * Set Status Monitor.
       *
       * All functors in the CVR-Lib share this object, which controls what to
       * do when the status string is set or changed.  You can set it to throw
       * an exception (see cvr::statusMonitorException), you can redirect the
       * statusString directly to the std::cerr; see cvr::statusMonitorCerr),
       * or you can do nothing but store internally the statusString (see
       * cvr::statusMonitorInactive), which is the default behaviour.
       *
       * If you implement an own class for this (like and error-log window)
       * ensure that you follow the interface explained in cvr::statusMonitor
       * to avoid memory leaks.
       *
       * You have to ensure that this method is called only once at a
       * time in your application, especially if you use several
       * threads.
       */
      static void setStatusMonitor(statusMonitor& monitor);

    private:

      /**
       * Class name of caller
       */
      std::string className_;

      /**
       * Status text
       */
      std::string text_;

      /**
       * Counter of the argument being processed.
       */
      int count_;

      /**
       * Number of arguments found when parting the status string.
       */
      int args_;

      /**
       * Class that controls what to do with the status string.  You can set it
       * to throw an exception after a few milliseconds (such that many
       * appendStatusStrings can be called before the exception is thrown; see
       * cvr::statusMonitorException), you can redirect the statusString
       * directly to the std::cerr; see cvr::statusMonitorCerr), or you can do
       * nothing but store internally the statusString (see
       * cvr::statusMonitorInactive), which is the default behaviour.
       */
      static statusMonitor* statusMonitor_;

      /**
       * Insert the given string at all positions where the %counter_ is found.
       */
      void insert(const std::string& data);
    };

    /**
     * Default constructor
     */
    status();

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

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

    /**
     * @name Error handling and report
     */
    //@{
    /**
     * Return the last message set with setStatusString() and modified with
     * the operators.
     */
    const std::string& getStatusString() const;

    /**
     * Set a status string.
     *
     * @param msg the const string to be reported next time by
     * getStatusString(). The given string will be copied.
     * This message will be usually set within the apply methods to indicate
     * an error cause.
     *
     * Note that the change of the status string is not considered as
     * a change in the functor status.
     */
    statusObject& setStatusString(const char* msg) const;

    /**
     * Set a status string.
     *
     * @param msg the const string to be reported next time by
     * getStatusString(). The given string will be copied.
     * This message will be usually set within the apply methods to indicate
     * an error cause.
     *
     * Note that the change of the status string is not considered as
     * a change in the functor status.
     */
    statusObject& setStatusString(const std::string& msg) const;
    
    /**
     * Get a reference to the internal statusObject.
     */
    statusObject& getStatusObject() const;

    /**
     * Set Status Monitor.
     *
     * All functors in the CVR-Lib share this object, which controls what to
     * do when the status string is set or changed.  You can set it to throw
     * an exception after a few milliseconds (such that many
     * appendStatusString() calls can be done before the exception is thrown;
     * see cvr::statusMonitorException), you can redirect the statusString
     * directly to the std::cerr; see cvr::statusMonitorCerr), or you can do
     * nothing but store internally the statusString (see
     * cvr::statusMonitorInactive), which is the default behaviour.
     *
     * If you implement an own class for this (like and error-log window)
     * ensure that you follow the interface explained in cvr::statusMonitor
     * to avoid some memory leaks.
     *
     * You have to ensure that this method is called only once at a
     * time in your application, especially if you use several
     * threads.
     *
     */
    static void setStatusMonitor(statusMonitor& monitor);
    //@}

  private:
    /**
     * Generate the class name.
     *
     * For complex status monitors, they expect to receive as parameter
     * the name of the caller class.  Since this class serves there only
     * as interface, here we don't have access to the name of the caller class
     * so that we have to recreate that name again using this wrapper class.
     */
    const std::string getClassName() const;

    /**
     * The status string written with setStatusString
     */
    mutable statusObject statusObject_;
  };

  /**
   * Global function to set the status monitor in all CVR-Lib objects that
   * manage a status string, like cvr::functor, cvr::ioHandler,
   * cvr::classifier, etc.
   */
  void setStatusMonitor(statusMonitor& monitor);


} // namespace cvr

#endif