interpret.h

Go to the documentation of this file.

/*
 *  interpret.h
 *
 *  This file is part of NEST.
 *
 *  Copyright (C) 2004 The NEST Initiative
 *
 *  NEST 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 2 of the License, or
 *  (at your option) any later version.
 *
 *  NEST 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 NEST.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef INTERPRETER_H
#define INTERPRETER_H
/* 
    interpret.h defines the SLI Interpreter class
*/

#include <typeinfo>
#include <list>

#include "token.h"
#include "slitype.h"
#include "tokenstack.h"
#include "sliactions.h"
#include "slibuiltins.h"
#include "slimodule.h"

class Parser;
class Scanner;
class DictionaryStack;
class Dictionary;
class FunctionDatum;
class BoolDatum;
class DynModule;

namespace nest {
  class Network;
}

extern "C"{
  void SLIthrowsignal(int s);
}

class SLIInterpreter
{
  std::list<SLIModule *> modules;

  /* Flags and variables to control debugging and
   * optimizations.
   */
  bool debug_mode_;       
  bool show_stack_;       
  bool show_backtrace_;   
  bool catch_errors_;     
  bool opt_tailrecursion_;
  int  call_depth_;       
  int  max_call_depth_;   


  unsigned long   cycle_count; 
  bool            cycle_guard;
  unsigned long   cycle_restriction; 



  int             verbositylevel;
  void inittypes(void);
  void initdictionaries(void);
  void initbuiltins(void);
  void initexternals(void);
  
public:
    unsigned long   code_accessed;  // for code coverage analysis.
    unsigned long   code_executed;  // ration should be coverage


    Dictionary *statusdict;
    Dictionary *errordict;
 
    DictionaryStack *DStack;
    Parser  *parse;

 
    // Names of basics functions
    Name ilookup_name;
    Name ipop_name;
    Name isetcallback_name;
    Name iiterate_name;
    Name iloop_name;
    Name irepeat_name;
    Name ifor_name;
    Name iforallarray_name;
    Name iforalliter_name;
    Name iforallindexedarray_name;
    Name iforallindexedstring_name;
    Name iforallstring_name;

    Name pi_name;
    Name e_name;

    Name iparse_name;
    Name stop_name;
    Name end_name;
    
    // Names of symbols and objects
    Name null_name;
    Name true_name;
    Name false_name;
    Name mark_name;
    Name istopped_name; 
    Name systemdict_name;
    Name userdict_name;
    Name errordict_name;
    Name quitbyerror_name;
    Name newerror_name;
    Name errorname_name;
    Name commandname_name;
    Name signo_name;
    Name recordstacks_name;
    Name estack_name;
    Name ostack_name;
    Name dstack_name;
    Name commandstring_name;
    Name interpreter_name;

    // Names of basic errors
    Name ArgumentTypeError;
    Name StackUnderflowError;
    Name UndefinedNameError;
    Name WriteProtectedError;
    Name DivisionByZeroError;
    Name RangeCheckError;
    Name PositiveIntegerExpectedError;
    Name BadIOError;
    Name StringStreamExpectedError;
    Name CycleGuardError;
    Name SystemSignal;
    Name BadErrorHandler;
    Name KernelError;
    Name InternalKernelError;

    Token execbarrier_token; 
  
  // Debug Message levels as static consts
  static const int M_ALL;  
  static const int M_DEBUG; 
  static const int M_STATUS;
  static const int M_INFO; 
  static const int M_WARNING; 
  static const int M_ERROR; 
  static const int M_FATAL; 
  static const int M_QUIET; 

 private:
  static char const * const M_ALL_NAME;
  static char const * const M_DEBUG_NAME;
  static char const * const M_STATUS_NAME;
  static char const * const M_INFO_NAME;
  static char const * const M_WARNING_NAME;
  static char const * const M_ERROR_NAME;
  static char const * const M_FATAL_NAME;
  static char const * const M_QUIET_NAME;

 public:

  // These static members must be accessible from
  // the Datum constructors
    
  static SLIType Integertype;
  static SLIType Doubletype;
  static SLIType Stringtype;
  static SLIType Nametype;
  static SLIType Booltype;
  static SLIType Literaltype;
  static SLIType Arraytype;
  static SLIType Proceduretype;
  static SLIType Litproceduretype;
  static SLIType Dictionarytype;
  static SLIType Symboltype;
  static SLIType Functiontype;
  static SLIType Trietype;
  static SLIType Callbacktype;
  static SLIType Istreamtype;
  static SLIType XIstreamtype;
  static SLIType Ostreamtype;
  static SLIType IntVectortype;
  static SLIType DoubleVectortype;
  static SLIType Iteratortype;

  // SLIType default actions
  static DatatypeFunction         datatypefunction;
  static NametypeFunction         nametypefunction;
  static ProceduretypeFunction    proceduretypefunction;
  static LitproceduretypeFunction litproceduretypefunction;
  static FunctiontypeFunction     functiontypefunction;
  static TrietypeFunction         trietypefunction;
  static CallbacktypeFunction     callbacktypefunction;
  static XIstreamtypeFunction     xistreamtypefunction;

  // Basic Operations needed to run the default actions
  static const IlookupFunction      ilookupfunction;
  static const IsetcallbackFunction isetcallbackfunction;
  static const IiterateFunction     iiteratefunction;
  static const IloopFunction        iloopfunction;
  static const IrepeatFunction      irepeatfunction;
  static const IforFunction         iforfunction;
  static const IforallarrayFunction iforallarrayfunction;
  static const IforalliterFunction  iforalliterfunction;
  static const IforallindexedarrayFunction iforallindexedarrayfunction;
  static const IforallindexedstringFunction iforallindexedstringfunction;
  static const IforallstringFunction iforallstringfunction;

  // State variables of the Interpreter


  Token   ct;            // callback; see comments in execute(void)
  
  TokenStack      OStack;
  TokenStack      EStack;
    
  // public member functions:
  SLIInterpreter(void);    
  ~SLIInterpreter();    

  int startup(); 

  int execute(const std::string &);

  int execute(const Token &);

  int execute(int v=0);

  //  int execute_protected(void);

  int execute_(size_t exitlevel=0);
  int execute_debug_(size_t exitlevel=0);
  
  void createdouble(Name const&, double);
  void createcommand(Name const&, SLIFunction const *);
  void createcommand(Name const&, Name const&, SLIFunction const *);
  void createconstant(Name const&, const Token&);


  const Token & lookup(const Name &n) const;


  const Token & lookup2(const Name &n) const;
    
  const Token & baselookup(const Name &n) const; // lookup in a specified

  bool known(const Name &n) const;

  bool baseknown(const Name &n) const;

  void def(Name const&, Token const &);

  void undef(Name const&);

  void basedef(const Name &n, const Token &t);

  void def_move(Name const&, Token &);
    
  void basedef_move(const Name &n, Token &t);

  void setcycleguard(Index);
  void removecycleguard(void);


  void inc_call_depth()
  {
    ++call_depth_;
  }

  void dec_call_depth()
  {
    --call_depth_;
  }

  void set_call_depth(int l)
  {
    call_depth_=l;
  }

  int get_call_depth() const
  {
    return call_depth_;
  }

  void set_max_call_depth(int d)
  {
    max_call_depth_=d;
  }

  int get_max_call_depth() const
  {
    return max_call_depth_;
  }

  bool step_mode() const
  {
    return debug_mode_ && (call_depth_ < max_call_depth_);
  }

  bool get_debug_mode() const
  {
    return debug_mode_;
  }

  void debug_mode_on()
  {
    debug_mode_=true;
  }

  void debug_mode_off()
  {
    debug_mode_=false;
  }

  void toggle_stack_display();




  void debug_options() const;

  char debug_commandline(Token &);


  bool optimize_tailrecursion() const
  {
    return opt_tailrecursion_;
  }

  void optimize_tailrecursion_on()
  {
    opt_tailrecursion_=true;
  }

  void optimize_tailrecursion_off()
  {
    opt_tailrecursion_=false;
  }

  bool show_backtrace() const
  {
    return show_backtrace_;
  }
  
  void backtrace_on();

 
  void backtrace_off();

 
  bool catch_errors() const
  {
    return catch_errors_;
  }

  void catch_errors_on()
  {
    catch_errors_=true;
  }

  void catch_errors_off()
  {
    catch_errors_=false;
  }

  void stack_backtrace(int n);

  void raiseerror(const char* err) { raiseerror(Name(err));}

  void raiseerror(Name err);

  void raiseerror(std::exception &err);

  void raiseerror(Name cmd, Name err);

  void print_error(Token cmd);

  void raiseagain(void);

  void raisesignal(int);


  // Message loging mechanism

  void verbosity(int);

  int  verbosity(void) const;

  void message(int level, const char from[], const char text[], 
           const char errorname[] = "") const;

  void message(std::ostream& out, const char levelname[], 
           const char from[], const char text[],
           const char errorname[] = "") const;

  void terminate(int returnvalue=-1);

  //*******************************************************
  Name  getcurrentname(void) const;
    
  unsigned long cycles(void) const
    {
      return cycle_count;
    }


  template<class T>  void addmodule(void);
  void addmodule(SLIModule *);

  /*
   * Add a linked dynamic module to the interpreter.
   * Initializers (commandstrings) for linked dynamic modules are executed
   * by sli-init.sli after all C++ initialization is done.
   * Do not use this for modules loaded at runtime!
   */
  void addlinkeddynmodule(DynModule *, nest::Network *);

  FunctionDatum * Ilookup(void) const;
  FunctionDatum * Iiterate(void) const;
  
  void assert_stack_load(size_t n); 

};

// This function template is a workaround for the parameterless
// template member function, given below. As of
// egcs-2.91.16 980328 (gcc-2.8.0 release)
// the compiler is not able to parse a call like
// engine.addmodule<ModuleX>();
// (Stroustrup97), Sec 13.3.1 (p335)

template<class T>
void addmodule(SLIInterpreter &i )
{
  i.addmodule(new T);
}

template<class T>
void SLIInterpreter::addmodule(void)
{
   SLIModule *m=new T();

   modules.push_back(m);
   m->install(std::cout,this);
}

inline
void SLIInterpreter::assert_stack_load(size_t n) 
{
  if ( OStack.load() < n)
    throw StackUnderflow(n, OStack.load());
}


#endif