cmtkCommandLine.h

Go to the documentation of this file.

/*
//
//  Copyright 1997-2009 Torsten Rohlfing
//
//  Copyright 2004-2011 SRI International
//
//  This file is part of the Computational Morphometry Toolkit.
//
//  http://www.nitrc.org/projects/cmtk/
//
//  The Computational Morphometry Toolkit 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 3 of
//  the License, or (at your option) any later version.
//
//  The Computational Morphometry Toolkit 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 the Computational Morphometry Toolkit.  If not, see
//  <http://www.gnu.org/licenses/>.
//
//  $Revision: 2752 $
//
//  $LastChangedDate: 2011-01-17 11:33:31 -0800 (Mon, 17 Jan 2011) $
//
//  $LastChangedBy: torstenrohlfing $
//
*/

#ifndef __cmtkCommandLine_h_included_
#define __cmtkCommandLine_h_included_

#include <cmtkconfig.h>

#include <System/cmtkCannotBeCopied.h>

#include <map>
#include <list>
#include <string>
#include <sstream>
#include <vector>

#include <stdlib.h>
#include <string.h>

#include <System/cmtkSmartPtr.h>
#include <System/cmtkConsole.h>
#include <System/cmtkCommandLineTypeTraits.h>
#include <System/cmtkExitException.h>

#include <mxml.h>

namespace
cmtk
{


class CommandLine :
  private CannotBeCopied
{
public:
  typedef CommandLine Self;

  typedef enum
  {
    PRG_TITLE = 0,
    PRG_DESCR = 1,
    PRG_CATEG = 2,
    PRG_ACKNL = 3,
    PRG_LCNSE = 4,
    PRG_CNTRB = 5,
    PRG_DOCUM = 6,
    PRG_VERSN = 7,
    PRG_SYNTX = 100
  } ProgramProperties;

  typedef enum
  {
    PROPS_XML = 0,
    PROPS_ADVANCED = 1,
    PROPS_MULTIPLE = 2,
    PROPS_NOXML = 4,
    PROPS_DIRNAME = 8,
    PROPS_FILENAME = 16,
    PROPS_IMAGE = 32,
    PROPS_LABELS = 64,
    PROPS_XFORM = 128,
    PROPS_OUTPUT = 256,
    PROPS_OPTIONAL = 512
  } ItemProperties;

  void SetProgramInfo( const ProgramProperties key, const std::string& value )
  {
    this->m_ProgramInfo[key] = value;
  }

  class Exception
  {
  public:
    Exception( const char* message = NULL, const size_t index = 0 ) :
      Message( message ), Index( index ) 
    {}
    
    Exception( const std::string& message, const size_t index = 0 ) :
      Message( message ), Index( index ) 
    {}
    
    std::string Message;
    
    size_t Index;
  };

  typedef void (*CallbackFunc)();

  typedef void (*CallbackFuncArg)( const char* );

  typedef void (*CallbackFuncIntArg)( const long int );

  typedef void (*CallbackFuncDblArg)( const double );

  typedef void (*CallbackFuncMultiArg)( const char**, int& argsUsed );

  class Key
  {
  public:
    explicit Key( const std::string& keyString ) : m_KeyChar( 0 ), m_KeyString( keyString ) {}

    explicit Key( const char keyChar, const std::string& keyString ) : m_KeyChar( keyChar ), m_KeyString( keyString ) {}

    char m_KeyChar;

    std::string m_KeyString;
  };

  class Item
  {
  public:
    typedef SmartPointer<Item> SmartPtr;

    Item() : m_Properties( PROPS_XML ) {};

    virtual ~Item() {}

    virtual Item* SetProperties( const long int properties )
    {
      this->m_Properties = properties;
      return this;
    }

    virtual long int GetProperties() const
    {
      return this->m_Properties;
    }

    virtual Item* SetAttribute( const std::string& key, const std::string& value )
    {
      this->m_Attributes[key] = value;
      return this;
    }
    
    virtual void Evaluate( const size_t argc, const char* argv[], size_t& index ) = 0;

    virtual mxml_node_t* MakeXML( mxml_node_t *const parent 
      ) const = 0;

    virtual std::string GetParamTypeString() const { return ""; }

    virtual std::ostringstream& PrintHelp( std::ostringstream& fmt 
      ) const
    {
      // by default, simply return stream unchanged.
      return fmt;
    }

    virtual void PrintWiki() const
    {
      // by default, do nothing
    }

    virtual bool IsDefault() const
    {
      return false;
    }

  protected:
    long int m_Properties;

    std::map<std::string, std::string> m_Attributes;

    static long int ConvertStrToLong( const char* str );

    static double ConvertStrToDouble( const char* str );

    template<class T> T Convert( const char* str );

    template<class T>
    class Helper
    {
    public:
      static mxml_node_t* MakeXML( const Item* item, mxml_node_t *const parent );

      static std::string GetParamTypeString( const Item* item );
    };

  private:
    friend class CommandLine;
  };

private:
  template<class T> 
  class Switch : 
    public Item
  {
  public:
    Switch( T *const field, const T value ) : 
      m_Field( field ), 
      m_Value( value ) 
    {
    }

    virtual ~Switch() {}

    virtual void Evaluate( const size_t, const char*[], size_t& )
    { 
      *this->m_Field  = this->m_Value;
    }

    virtual mxml_node_t* MakeXML(  mxml_node_t *const parent ) const 
    {
      if ( ! (this->m_Properties & PROPS_NOXML) )
        {
        return mxmlNewElement( parent, "boolean" );
        }
      return NULL;
    }

    virtual std::ostringstream& PrintHelp( std::ostringstream& fmt 
      ) const
    {
      if ( this->IsDefault() )
        fmt << "\n[This is the default]";
      return fmt;
    }
    
    virtual void PrintWiki() const
    {
      if ( this->IsDefault() )
        StdOut << " '''[This is the default]'''";
    }
    
    virtual bool IsDefault() const
    {
      return ( *(this->m_Field) == this->m_Value );
    }

  private:
    T* m_Field;

    const T m_Value;
  };

  template<class T>
  class Option : 
    public Item
  {
  public:
    Option( T *const var, bool *const flag ) : Var( var ), Flag( flag ) {}
    
    virtual ~Option() {}

    virtual void Evaluate( const size_t argc, const char* argv[], size_t& index );

    virtual mxml_node_t* MakeXML(  mxml_node_t *const parent ) const;

    virtual std::string GetParamTypeString() const;

    virtual std::ostringstream& PrintHelp( std::ostringstream& fmt 
      ) const;

    virtual void PrintWiki() const;

  protected:
    T* Var;

    bool* Flag;
  };

  template<class T>
  class List : 
    public Item
  {
  public:
    List( std::list<T>& list ) : m_pList( &list ) {}

    virtual ~List() {}
    
    virtual void Evaluate( const size_t argc, const char* argv[], size_t& index );

    virtual mxml_node_t* MakeXML(  mxml_node_t *const parent ) const;

  private:
    std::list<T>* m_pList;
  };

  template<class T>
  class Vector : 
    public Item
  {
  public:
    Vector( std::vector<T>& vector ) : m_pVector( &vector ), m_HasBeenUsed( false ) {}
    
    virtual ~Vector() {}

    virtual void Evaluate( const size_t argc, const char* argv[], size_t& index );

    virtual mxml_node_t* MakeXML(  mxml_node_t *const parent ) const;

    virtual std::string GetParamTypeString() const;

  private:
    std::vector<T>* m_pVector;

    bool m_HasBeenUsed;
  };

  class Callback : 
    public Item
  {
  public:
    Callback( CallbackFunc func ) : m_Func( func ), m_FuncArg( NULL ), m_FuncIntArg( NULL ), m_FuncDblArg( NULL ), m_FuncMultiArg( NULL ) {}
    
    Callback( CallbackFuncArg funcArg ) : m_Func( NULL ), m_FuncArg( funcArg ), m_FuncIntArg( NULL ), m_FuncDblArg( NULL ), m_FuncMultiArg( NULL ) {}
    
    Callback( CallbackFuncIntArg funcIntArg ) : m_Func( NULL ), m_FuncArg( NULL ), m_FuncIntArg( funcIntArg ), m_FuncDblArg( NULL ), m_FuncMultiArg( NULL ) {}
    
    Callback( CallbackFuncDblArg funcDblArg ) : m_Func( NULL ), m_FuncArg( NULL ), m_FuncIntArg( NULL ), m_FuncDblArg( funcDblArg ), m_FuncMultiArg( NULL ) {}
    
    Callback( CallbackFuncMultiArg funcMultiArg ) : m_Func( NULL ), m_FuncArg( NULL ), m_FuncIntArg( NULL ), m_FuncDblArg( NULL ), m_FuncMultiArg(  funcMultiArg ) {}
    
    virtual ~Callback() {}

    virtual void Evaluate( const size_t argc, const char* argv[], size_t& index );

    virtual mxml_node_t* MakeXML(  mxml_node_t *const parent ) const;

    virtual std::string GetParamTypeString() const;

  private:
    CallbackFunc m_Func;

    CallbackFuncArg m_FuncArg;

    CallbackFuncIntArg m_FuncIntArg;

    CallbackFuncDblArg m_FuncDblArg;

    CallbackFuncMultiArg m_FuncMultiArg;
  };

  class NonOptionParameter :
    public Option<const char*>
  {
  public:
    typedef NonOptionParameter Self;

    typedef SmartPointer<Self> SmartPtr;
    
    typedef Option<const char*> Superclass;

    NonOptionParameter( const char* *const var, const char* name, const char* comment, bool *const flag ) : Superclass( var, flag ), m_Name( name ), m_Comment( comment ) {};

    virtual void Evaluate( const size_t argc, const char* argv[], size_t& index );

    virtual mxml_node_t* MakeXMLWithIndex( mxml_node_t *const parent, 
                                           const int index 
      ) const;

    virtual std::string GetParamTypeString() const;

    virtual std::ostringstream& PrintHelp( std::ostringstream& fmt 
      ) const
    {
      // by default, simply return stream unchanged.
      if ( this->Var )
        fmt << "\n[Default: " << *(this->Var) << "]";
      else
        fmt << "\n[There is no default for this parameter]";
      return fmt;
    }

    virtual void PrintWiki() const
    {
      // by default, simply return stream unchanged.
      if ( this->Var )
        StdOut << " '''[Default: " << *(this->Var) << "]'''\n";
      else
        StdOut << " '''[There is no default for this parameter]'''\n";
    }

    const char* m_Name;

    const char* m_Comment;
  };

  class NonOptionParameterVector :
    public Option< std::vector<std::string> >
  {
  public:
    typedef NonOptionParameterVector Self;

    typedef SmartPointer<Self> SmartPtr;
    
    typedef Option< std::vector<std::string> > Superclass;

    NonOptionParameterVector( std::vector<std::string> *pvec, const char* name, const char* comment, bool *const flag ) 
      : Superclass( pvec, flag ), 
        m_Name( name ), 
        m_Comment( comment ) {};

    virtual void Evaluate( const size_t argc, const char* argv[], size_t& index );

    virtual mxml_node_t* MakeXMLWithIndex( mxml_node_t *const parent, 
                                           const int index 
      ) const;

    virtual std::string GetParamTypeString() const;

    virtual std::ostringstream& PrintHelp( std::ostringstream& fmt 
      ) const
    {
      if ( this->Var->size() )
        {
        fmt << "\n[Default: ( \"" << (*this->Var)[0] << "\"";
        for ( size_t i = 1; i < this->Var->size(); ++i )
          fmt << ", \"" << (*this->Var)[i] << "\" ";
        fmt << ") ]";
        }
      else
        {
        fmt << "\n[Default: (empty)]";
        }
      return fmt;
    }
    
    virtual void PrintWiki() const
    {
      if ( this->Var->size() )
        {
        StdOut << "'''[Default: ( \"" << (*this->Var)[0] << "\"";
        for ( size_t i = 1; i < this->Var->size(); ++i )
          StdOut << ", \"" << (*this->Var)[i] << "\" ";
        StdOut << ") ]'''\n";
        }
      else
        {
        StdOut << "'''[Default: (empty)]'''\n";
        }
    }
    
    const char* m_Name;

    const char* m_Comment;
  };

public:
  CommandLine( const int properties = PROPS_NOXML );

  ~CommandLine();

  class EnumGroupBase;

  class KeyToAction
  {
  public:
    typedef SmartPointer<KeyToAction> SmartPtr;

    const Key m_Key;

    KeyToAction( const Key& key, 
                 const std::string& comment ) : 
      m_Key( key ),
      m_Comment( comment ),
      m_Properties( PROPS_XML )
    {}
    
    virtual ~KeyToAction() {};

    virtual bool MatchAndExecute( const std::string& key, 
                                  const size_t argc, 
                                  const char* argv[], 
                                  size_t& index 
      ) = 0;

    virtual bool MatchAndExecute( const char keyChar, 
                                  const size_t argc, 
                                  const char* argv[], 
                                  size_t& index 
      ) = 0;

    virtual void SetProperties( const long int properties );

    virtual long int GetProperties() const;
    
    virtual mxml_node_t* MakeXML( mxml_node_t *const parent 
      ) const;

    virtual void PrintHelp( const size_t globalIndent = 0 ) const = 0;
    
  protected:
    virtual void FormatHelp( std::ostringstream& fmt ) const;    

    virtual void PrintWikiWithPrefix( const std::string& prefix = "" ) const;

    virtual std::string GetActionTypeInfo() const 
    {
      return "";
    }
    
    std::string m_Comment;

    long int m_Properties;

    virtual bool MatchLongOption( const std::string& key ) const;

    friend class CommandLine;

    friend class CommandLine::EnumGroupBase;
  };

  class KeyToActionSingle :
    public KeyToAction
  {
  public:
    typedef KeyToAction Superclass;

    typedef SmartPointer<KeyToActionSingle> SmartPtr;

    KeyToActionSingle( const Key& key, 
                       Item::SmartPtr action, 
                       const std::string& comment ) : 
      KeyToAction( key, comment ),
      m_Action( action )
    {}
    
    virtual ~KeyToActionSingle() {};

    bool MatchAndExecute( const std::string& key, 
                          const size_t argc, 
                          const char* argv[], 
                          size_t& index 
      );

    bool MatchAndExecute( const char keyChar, 
                          const size_t argc, 
                          const char* argv[], 
                          size_t& index 
      );

    virtual mxml_node_t* MakeXML( mxml_node_t *const parent 
      ) const;

    virtual void PrintHelp( const size_t globalIndent = 0 ) const;
    
    virtual void PrintWikiWithPrefix( const std::string& prefix = "" ) const;
    
    virtual std::string GetActionTypeInfo() const
    {
      return this->m_Action->GetParamTypeString();
    }

    Item::SmartPtr m_Action;
  };

  class EnumGroupBase :
    public std::list< SmartPointer<KeyToActionSingle> >
  {
  public:
    typedef SmartPointer<EnumGroupBase> SmartPtr;

    std::string GetDefaultKey() const
    {
      for ( const_iterator it = this->begin(); it != this->end(); ++it )
        {
        if ( (*it)->m_Action->IsDefault() )
          {
          return std::string( (*it)->m_Key.m_KeyString );
          }
        }
      return "";
    }
  };

  class KeyToActionEnum :
    public KeyToAction
  {
  public:
    typedef KeyToAction Superclass;

    typedef SmartPointer<KeyToActionEnum> SmartPtr;

    KeyToActionEnum( const Key& key ,
                     EnumGroupBase::SmartPtr keyToActionEnum ,
                     const std::string& comment  ) :
      KeyToAction( key, comment ),
      m_EnumGroup( keyToActionEnum )
    {}
    
    virtual ~KeyToActionEnum() {};

    bool MatchAndExecute( const std::string& key, 
                          const size_t argc, 
                          const char* argv[], 
                          size_t& index 
      );

    bool MatchAndExecute( const char keyChar, 
                          const size_t argc, 
                          const char* argv[], 
                          size_t& index 
      );

    virtual mxml_node_t* MakeXML( mxml_node_t *const parent 
      ) const;

    virtual void PrintHelp( const size_t globalIndent = 0 ) const;
    
    virtual void PrintWikiWithPrefix( const std::string& prefix = "" ) const;
    
  private:
    EnumGroupBase::SmartPtr m_EnumGroup;

    friend class EnumGroupBase;
  };

  template<class TDataType>
  class EnumGroup :
    public EnumGroupBase
  {
  public:
    typedef SmartPointer< EnumGroup<TDataType> > SmartPtr;
    
    EnumGroup( TDataType *const variable 
      ) :
      m_Variable( variable )
    {
    }

    Item::SmartPtr& 
    AddSwitch( const Key& key, const TDataType& value, const std::string& comment ) 
    {
      KeyToActionSingle::SmartPtr keyToAction( new KeyToActionSingle( key, Item::SmartPtr( new Switch<TDataType>( this->m_Variable, value ) ), comment ) );
      this->push_back( keyToAction );
      return keyToAction->m_Action;
    }

  private:
    TDataType *m_Variable;
  };

  template<class TDataType>
  typename EnumGroup<TDataType>::SmartPtr AddEnum( const std::string& name, TDataType *const variable, const std::string& comment )
  {
    typename EnumGroup<TDataType>::SmartPtr enumGroup( new EnumGroup<TDataType>( variable ) );
    KeyToActionEnum::SmartPtr keyToAction( new KeyToActionEnum( Key( name ), enumGroup, comment ) );

    this->m_KeyActionList->push_back( keyToAction );
    this->m_KeyActionListComplete.push_back( keyToAction );

    return enumGroup;
  }

  template<class T> 
  Item::SmartPtr 
  AddSwitch( const Key& key, T *const var, const T value, const char* comment ) 
  {
    return this->AddKeyAction( KeyToActionSingle::SmartPtr( new KeyToActionSingle( key, Item::SmartPtr( new Switch<T>( var, value ) ), comment ) ) )->m_Action;
  }
  
  template<class T> 
  Item::SmartPtr
  AddOption( const Key& key, T *const var, const char* comment, bool *const flag = NULL ) 
  {
    return this->AddKeyAction( KeyToActionSingle::SmartPtr( new KeyToActionSingle( key, Item::SmartPtr( new Option<T>( var, flag ) ), comment ) ) )->m_Action;
  }
  
  template<class T> 
  Item::SmartPtr
  AddList( const Key& key, std::list<T>& list, const char* comment ) 
  {
    return this->AddKeyAction( KeyToActionSingle::SmartPtr( new KeyToActionSingle( key, Item::SmartPtr( new List<T>( list ) ), comment ) ) )->m_Action;
  }
  
  template<class T> 
  Item::SmartPtr
  AddVector( const Key& key, std::vector<T>& vector, const char* comment ) 
  {
    return this->AddKeyAction( KeyToActionSingle::SmartPtr( new KeyToActionSingle( key, Item::SmartPtr( new Vector<T>( vector ) ), comment ) ) )->m_Action;
  }
  
  Item::SmartPtr
  AddCallback( const Key& key, CallbackFunc func, const char* comment ) 
  {
    return this->AddKeyAction( KeyToActionSingle::SmartPtr( new KeyToActionSingle( key, Item::SmartPtr( new Callback( func ) ), comment ) ) )->m_Action;
  }

  template<class TArg>
  Item::SmartPtr
  AddCallback( const Key& key, void (*funcArg)( const TArg ), const char* comment ) 
  {
    return this->AddKeyAction( KeyToActionSingle::SmartPtr( new KeyToActionSingle( key, Item::SmartPtr( new Callback( funcArg ) ), comment ) ) )->m_Action;
  }
  
  Item::SmartPtr
  AddCallback( const Key& key, CallbackFuncMultiArg funcMultiArg, const char* comment ) 
  {
    return this->AddKeyAction( KeyToActionSingle::SmartPtr( new KeyToActionSingle( key, Item::SmartPtr( new Callback( funcMultiArg ) ), comment ) ) )->m_Action;
  }
  
  Item::SmartPtr
  AddParameter( const char* *const var, const char* name, const char* comment, bool *const flag = NULL ) 
  {
    NonOptionParameter::SmartPtr parameter( new NonOptionParameter( var, name, comment, flag ) );
    this->m_NonOptionParameterList.push_back( parameter );
    return parameter;
  }

  Item::SmartPtr
  AddParameterVector( std::vector<std::string>* pvec, const char* name, const char* comment, bool *const flag = NULL ) 
  {
    NonOptionParameterVector::SmartPtr vparameter( new NonOptionParameterVector( pvec, name, comment, flag ) );
    this->m_NonOptionParameterVectorList.push_back( vparameter );
    return  vparameter;
  }

  typedef std::vector<KeyToAction::SmartPtr> KeyActionListType;

  KeyActionListType* m_KeyActionList;
                                    
  KeyActionListType m_KeyActionListComplete;
                                    
  KeyToActionSingle::SmartPtr AddKeyAction( const KeyToActionSingle::SmartPtr& keyAction )
  {
    this->m_KeyActionList->push_back( keyAction );
    this->m_KeyActionListComplete.push_back( keyAction );
    return keyAction;
  }

  KeyToActionEnum::SmartPtr AddKeyAction( const KeyToActionEnum::SmartPtr& keyAction )
  {
    this->m_KeyActionList->push_back( keyAction );
    this->m_KeyActionListComplete.push_back( keyAction );
    return keyAction;
  }

  class KeyActionGroupType
  {
  public:
    typedef SmartPointer<KeyActionGroupType> SmartPtr;
    
    KeyActionGroupType( const std::string& name, const std::string& description ) : m_Name( name ), m_Description( description ) {};

    std::string m_Name;

    std::string m_Description;

    KeyActionListType m_KeyActionList;

    virtual void SetProperties( const long int properties )
    {
      this->m_Properties = properties;
    }

    virtual long int GetProperties() const
    {
      return this->m_Properties;
    }
    
  private:
    long int m_Properties;
  };

  KeyActionGroupType::SmartPtr& BeginGroup( const char* name, const char* description );

  void EndGroup();

  bool Parse( const int argc, const char* argv[] ) throw( ExitException, Self::Exception );

  static const int HelpTextIndent = 10;

  void PrintHelp() const;

  void PrintWiki() const;

  size_t GetNextIndex() const { return this->Index; }

  const char* GetNext() 
  {
    if ( Index >= ArgC ) 
      throw( Exception( "Out of arguments.", Index ) ); 
    return ArgV[Index++];
  }
  
  const char* GetNextOptional() 
  {
    if ( Index >= ArgC ) return NULL;
    return ArgV[Index++];
  }

  void WriteXML() const;
  
private:
  size_t ArgC;

  const char** ArgV;
  
  long int m_Properties;

  size_t Index;

  typedef std::vector<KeyActionGroupType::SmartPtr> KeyActionGroupListType;
  
  KeyActionGroupListType m_KeyActionGroupList;

  typedef std::vector<NonOptionParameter::SmartPtr> NonOptionParameterListType;

  NonOptionParameterListType m_NonOptionParameterList;

  typedef std::vector<NonOptionParameterVector::SmartPtr> NonOptionParameterVectorListType;

  NonOptionParameterVectorListType m_NonOptionParameterVectorList;

  typedef std::map<ProgramProperties,std::string> ProgramPropertiesMapType;

  ProgramPropertiesMapType m_ProgramInfo;

  mxml_node_t* AddProgramInfoXML( mxml_node_t *const parent ,
                                  const ProgramProperties key ,
                                  const char* name  ) const;

  void SetDefaultInfo();
  
  template<class T> friend class Option;  

  template<class T> friend class Switch;  

  friend class Callback;  
};

Console& operator<<( Console& console, CommandLine::Exception e );


} // namespace cmtk

#include "cmtkCommandLineItem.txx"
#include "cmtkCommandLineOption.txx"
#include "cmtkCommandLineConvert.txx"
#include "cmtkCommandLineList.txx"
#include "cmtkCommandLineVector.txx"

#endif // #ifndef __cmtkCommandLine_h_included_