///////////////////////////////////////////////////////////////////////
//
// Base class for all processors.
//
// A Processor represents a chunk of analysis code that can be
// placed into the event loop by the user.  It is constructed in the
// macro when the user calls:
// /rat/proc procname
//
// The user can then configure the processor with the macro command:
// /rat/procset variable_name variable_value
// This is translated into calls to SetI(), SetF(), SetD(), or SetS()
// depending upon the detected type of variable_value.  If there is a
// problem, ParamUnknown or ParamInvalid exceptions are thrown.
//
// Once the event loop starts, DSEvent() called once per physics
// event.
//
// To create a new processor, subclass Processor and then edit
// ProcBlockManager::ProcBlockManager().
//
// The DSEvent return type may now be used in conditional statements
// if the processor should be used this way return OKTRUE or OKFLASE
// instead of OK.
//
// Author: Stan Seibert <volsung@physics.utexas.edu>
//
// REVISION HISTORY:
//     21/01/2013 : P G Jones - Added start and end of run methods.
//     2013-11-26 : P G Jones - Added conditional statements.
//     2014-04-24 : P G Jones - Removed Event method, changed to references.
//
///////////////////////////////////////////////////////////////////////

#ifndef __RAT_Processor__
#define __RAT_Processor__

#include <string>

namespace RAT
{

namespace DS
{
  class Entry;
  class Run;
}

class Processor
{
public:
  // The short name of this processor.
  std::string fName;

  std::string fNickName; ///< Optional alternative name for the fitter

  // Create new processor.
  //
  // Sets the name of the processor.  This may be used to identify
  // processors in the future.  Should be set by all subclasses and
  // look like a valid C++ identifier.
  //
  // name: Short name of processor
  Processor( const std::string& name );

  // Destroy processor.
  virtual ~Processor() { };

  // Result codes returned by DSEvent().
  enum Result { OK=0, // Processor ran successfully.
                FAIL=1, // Processor task failed, but non-fatal, so execution of later processors continues.
                ABORT=2, // Processing of event is immediately  terminated, no further processors are run on this event
                OKTRUE=3, // Processor ran successfully and returns true
                OKFALSE=4 };// Processor ran successfully and returns false

  // Base class for parameter exceptions.
  //
  // Thrown if some problem happens while setting a parameter.
  class ParamError
  {
  public:
    // Create parameter error.
    //
    // param:  Name of parameter which triggered this
    // error.
    ParamError( const std::string param ) : fParam( param ) { };

    std::string fParam; // Name of parameter which triggered this error.
  };

  // Exception thrown when parameter name is not known to this  processor.
  class ParamUnknown : public ParamError
  {
  public:
    // Create unknown parameter error.
    //
    // param:  Name of unknown parameter
    ParamUnknown( const std::string param ) : ParamError( param ) { };
  };

  // Exception thrown when parameter name is known, but value is
  // invalid.
  //
  // Note that this class contains no member variable to hold the
  // parameter value which caused the problem.  This is because we do
  // not know the type.  You should mention the value inside the
  // error message member variable instead.  See dformat() for a nice
  // function to format strings, much like sprintf().
  class ParamInvalid : public ParamError
  {
  public:
    // Create invalid parameter value error.
    //
    // param:  Name of parameter
    // msg:    Message explaining problem with setting the value.
    ParamInvalid( const std::string param, std::string msg ) : ParamError( param ), fMsg( msg ) { };

    std::string fMsg; // Message explaining problem.
  };

  // Set integer parameter.
  //
  // param:  Name of parameter.
  // value:  Value of parameter.
  // Throws ParamUnknown if param is not recognized.
  // Throws ParamInvalid if value is not allowed for param.
  virtual void SetI( const std::string& param, const int value );

  // Set float parameter.
  //
  // param:  Name of parameter.
  // value:  Value of parameter.
  // Throws ParamUnknown if param is not recognized.
  // Throws ParamInvalid if value is not allowed for param.
  virtual void SetF( const std::string& param, const float value );

  // Set double parameter
  //
  // param:  Name of parameter.
  // value:  Value of parameter.
  // Throws ParamUnknown if param is not recognized.
  // Throws ParamInvalid if value is not allowed for param.
  virtual void SetD( const std::string& param, const double value );

  // Set string parameter.
  //
  // param:  Name of parameter.
  // value:  Value of parameter.
  // Throws ParamUnknown if param is not recognized.
  // Throws ParamInvalid if value is not allowed for param.
  virtual void SetS( const std::string& param, const std::string& value );

  // Called at the start of a new run
  //
  // This is the preferred place to access the database, no access before!
  //
  // run: Data structure for the run
  virtual void BeginOfRun( DS::Run& run );

  // Process one physics event.
  //
  // The processor can do whatever operation it likes on the event.
  //
  //
  // run: Data structure for the run
  // ds: Data structure for current event.
  //
  // Returns a Status code for success/failure in processing this event.
  // Processors used in conditional statements should return OKTRUE
  // or OKFALSE instead of OK.
  virtual Processor::Result DSEvent( DS::Run& run, DS::Entry& ds );

  // Process one full run (called at the end of the run)
  //
  // This is the preferred place to do overall analysis, not the destructor
  //
  // run: Data structure for the run
  virtual void EndOfRun( DS::Run& run );

  const std::string GetNickName() {return fNickName;}

};


} // namespace RAT

#endif