interpreter.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 2002-2022 The Octave Project Developers
//
// See the file COPYRIGHT.md in the top-level directory of this
// distribution or <https://octave.org/copyright/>.
//
// This file is part of Octave.
//
// Octave 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.
//
// Octave 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 Octave; see the file COPYING.  If not, see
// <https://www.gnu.org/licenses/>.
//
////////////////////////////////////////////////////////////////////////
 
#if ! defined (octave_interpreter_h)
#define octave_interpreter_h 1
 
#include "octave-config.h"
 
#include <map>
#include <set>
#include <stack>
#include <string>
 
#include "child-list.h"
#include "oct-time.h"
#include "quit.h"
#include "str-vec.h"
 
#include "cdef-manager.h"
#include "display.h"
#include "dynamic-ld.h"
#include "environment.h"
#include "error.h"
#include "event-manager.h"
#include "graphics.h"
#include "gtk-manager.h"
#include "help.h"
#include "input.h"
#include "load-path.h"
#include "load-save.h"
#include "oct-hist.h"
#include "oct-stream.h"
#include "ov-typeinfo.h"
#include "pager.h"
#include "pt-eval.h"
#include "settings.h"
#include "symtab.h"
#include "url-handle-manager.h"
 
extern OCTINTERP_API bool quit_allowed;
 
// TRUE means we are ready to interpret commands, but not everything
// is ready for interactive use.
extern OCTINTERP_API bool octave_interpreter_ready;
 
// TRUE means we've processed all the init code and we are good to go.
extern OCTINTERP_API bool octave_initialized;
 
#include "oct-time.h"
 
OCTAVE_NAMESPACE_BEGIN
 
  class profiler;
  class child_list;
  class push_parser;
 
  // The time we last time we changed directories.
  extern sys::time Vlast_chdir_time;
 
  // The application object contains a pointer to the current
  // interpreter and the interpreter contains a pointer back to the
  // application context so we need a forward declaration for one (or
  // both) of them...
 
  class application;
 
  class temporary_file_list
  {
  public:
 
    temporary_file_list (void) : m_files () { }
 
    // No copying!
 
    temporary_file_list (const temporary_file_list&) = delete;
 
    temporary_file_list& operator = (const temporary_file_list&) = delete;
 
    ~temporary_file_list (void);
 
    void insert (const std::string& file);
 
    void cleanup (void);
 
  private:
 
    // List of temporary files to delete when we exit.
    std::set<std::string> m_files;
 
  };
 
  class OCTINTERP_API interpreter
  {
  public:
 
    // Create an interpreter object and perform basic initialization.
 
    interpreter (application *app_context = nullptr);
 
    // No copying, at least not yet...
 
    interpreter (const interpreter&) = delete;
 
    interpreter& operator = (const interpreter&) = delete;
 
    // Clean up the interpreter object.
 
    ~interpreter (void);
 
    void intern_nargin (octave_idx_type nargs);
 
    // If creating an embedded interpreter, you may inhibit reading
    // the command history file by calling initialize_history with
    // read_history_file = false prior to calling initialize.
 
    void initialize_history (bool read_history_file = false);
 
    // If creating an embedded interpreter, you may inhibit setting
    // the default compiled-in path by calling initialize_load_path
    // with set_initial_path = false prior calling initialize.  After
    // that, you can add directories to the load path to set up a
    // custom path.
 
    void initialize_load_path (bool set_initial_path = true);
 
    // Load command line history, set the load path.
 
    void initialize (void);
 
    // Note: GET_LINE_AND_EVAL is only used by new experimental terminal
    // widget.
 
    void get_line_and_eval (void);
 
    // Parse a line of input.  If input ends at a complete statement
    // boundary, execute the resulting parse tree.  Useful to handle
    // parsing user input when running in server mode.
 
    void parse_and_execute (const std::string& input, bool& incomplete_parse);
 
    // Initialize the interpreter (if not already done by an explicit
    // call to initialize), execute startup files, --eval option code,
    // script files, and/or interactive commands.
 
    int execute (void);
 
    bool server_mode (void) const { return m_evaluator.server_mode (); }
 
    bool interactive (void) const
    {
      return m_interactive;
    }
 
    void interactive (bool arg)
    {
      m_interactive = arg;
    }
 
    void read_site_files (bool flag)
    {
      m_read_site_files = flag;
    }
 
    void read_init_files (bool flag)
    {
      m_read_init_files = flag;
    }
 
    void verbose (bool flag)
    {
      m_verbose = flag;
    }
 
    void traditional (bool flag)
    {
      m_traditional = flag;
    }
 
    bool traditional (void) const
    {
      return m_traditional;
    }
 
    void inhibit_startup_message (bool flag)
    {
      m_inhibit_startup_message = flag;
    }
 
    bool in_top_level_repl (void) const
    {
      return m_evaluator.in_top_level_repl ();
    }
 
    bool initialized (void) const
    {
      return m_initialized;
    }
 
    void interrupt_all_in_process_group (bool b)
    {
      m_interrupt_all_in_process_group = b;
    }
 
    bool interrupt_all_in_process_group (void) const
    {
      return m_interrupt_all_in_process_group;
    }
 
    application *get_app_context (void)
    {
      return m_app_context;
    }
 
    display_info& get_display_info (void)
    {
      return m_display_info;
    }
 
    environment& get_environment (void)
    {
      return m_environment;
    }
 
    settings& get_settings (void)
    {
      return m_settings;
    }
 
    error_system& get_error_system (void)
    {
      return m_error_system;
    }
 
    help_system& get_help_system (void)
    {
      return m_help_system;
    }
 
    input_system& get_input_system (void)
    {
      return m_input_system;
    }
 
    output_system& get_output_system (void)
    {
      return m_output_system;
    }
 
    history_system& get_history_system (void)
    {
      return m_history_system;
    }
 
    dynamic_loader& get_dynamic_loader (void)
    {
      return m_dynamic_loader;
    }
 
    load_path& get_load_path (void)
    {
      return m_load_path;
    }
 
    load_save_system& get_load_save_system (void)
    {
      return m_load_save_system;
    }
 
    type_info& get_type_info (void)
    {
      return m_type_info;
    }
 
    symbol_table& get_symbol_table (void)
    {
      return m_symbol_table;
    }
 
    tree_evaluator& get_evaluator (void);
 
    symbol_scope get_top_scope (void) const;
    symbol_scope get_current_scope (void) const;
    symbol_scope require_current_scope (const std::string& who) const;
 
    profiler& get_profiler (void);
 
    stream_list& get_stream_list (void);
 
    child_list& get_child_list (void)
    {
      return m_child_list;
    }
 
    url_handle_manager& get_url_handle_manager (void);
 
    cdef_manager& get_cdef_manager (void)
    {
      return m_cdef_manager;
    }
 
    gtk_manager& get_gtk_manager (void)
    {
      return m_gtk_manager;
    }
 
    event_manager& get_event_manager (void)
    {
      return m_event_manager;
    }
 
    gh_manager& get_gh_manager (void)
    {
      return *m_gh_manager;
    }
 
    // Any Octave code that needs to change the current directory should
    // call this function instead of calling the system chdir function
    // directly so that the  load-path and GUI may be notified of the
    // change.
 
    int chdir (const std::string& dir);
 
    void mlock (bool skip_first = false) const;
    void munlock (bool skip_first = false) const;
    bool mislocked (bool skip_first = false) const;
 
    // NOTE: since we have a version that accepts a bool argument, we
    // can't rely on automatic conversion from char* to std::string.
    void munlock (const char *nm);
    void munlock (const std::string& nm);
 
    bool mislocked (const char *nm);
    bool mislocked (const std::string& nm);
 
    std::string mfilename (const std::string& opt = "") const;
 
    octave_value_list eval_string (const std::string& eval_str, bool silent,
                                   int& parse_status, int nargout);
 
    octave_value eval_string (const std::string& eval_str, bool silent,
                              int& parse_status);
 
    octave_value_list eval_string (const octave_value& arg, bool silent,
                                   int& parse_status, int nargout);
 
    octave_value_list eval (const std::string& try_code, int nargout);
 
    octave_value_list eval (const std::string& try_code,
                            const std::string& catch_code, int nargout);
 
    octave_value_list evalin (const std::string& context,
                              const std::string& try_code, int nargout);
 
    octave_value_list evalin (const std::string& context,
                              const std::string& try_code,
                              const std::string& catch_code, int nargout);
 
    octave_value_list
    feval (const char *name,
           const octave_value_list& args = octave_value_list (),
           int nargout = 0);
 
    octave_value_list
    feval (const std::string& name,
           const octave_value_list& args = octave_value_list (),
           int nargout = 0);
 
    octave_value_list
    feval (octave_function *fcn,
           const octave_value_list& args = octave_value_list (),
           int nargout = 0);
 
    octave_value_list
    feval (const octave_value& f_arg,
           const octave_value_list& args = octave_value_list (),
           int nargout = 0);
 
    octave_value_list feval (const octave_value_list& args, int nargout = 0);
 
    octave_value make_function_handle (const std::string& name);
 
    void install_variable (const std::string& name, const octave_value& value,
                           bool global);
 
    void set_global_value (const std::string& name, const octave_value& value);
 
    octave_value global_varval (const std::string& name) const;
 
    void global_assign (const std::string& name,
                        const octave_value& val = octave_value ());
 
    octave_value top_level_varval (const std::string& name) const;
 
    void top_level_assign (const std::string& name,
                           const octave_value& val = octave_value ());
 
    bool is_variable (const std::string& name) const;
 
    bool is_local_variable (const std::string& name) const;
 
    octave_value varval (const std::string& name) const;
 
    void assign (const std::string& name,
                 const octave_value& val = octave_value ());
 
    void assignin (const std::string& context, const std::string& varname,
                   const octave_value& val = octave_value ());
 
    void source_file (const std::string& file_name,
                      const std::string& context = "",
                      bool verbose = false, bool require_file = true);
 
    bool at_top_level (void) const;
 
    bool isglobal (const std::string& name) const;
 
    octave_value find (const std::string& name);
 
    void clear_all (bool force = false);
 
    void clear_objects (void);
 
    void clear_variable (const std::string& name);
 
    void clear_variable_pattern (const std::string& pattern);
 
    void clear_variable_regexp (const std::string& pattern);
 
    void clear_variables (void);
 
    void clear_global_variable (const std::string& name);
 
    void clear_global_variable_pattern (const std::string& pattern);
 
    void clear_global_variable_regexp (const std::string& pattern);
 
    void clear_global_variables (void);
 
    void clear_functions (bool force = false);
 
    void clear_function (const std::string& name);
 
    void clear_symbol (const std::string& name);
 
    void clear_function_pattern (const std::string& pat);
 
    void clear_function_regexp (const std::string& pat);
 
    void clear_symbol_pattern (const std::string& pat);
 
    void clear_symbol_regexp (const std::string& pat);
 
    std::list<std::string> variable_names (void);
 
    std::list<std::string> top_level_variable_names (void);
 
    std::list<std::string> global_variable_names (void);
 
    std::list<std::string> user_function_names (void);
 
    std::list<std::string> autoloaded_functions (void) const;
 
    void interrupt (void);
 
    // Pause interpreter execution at the next available statement and
    // enter the debugger.
    void pause (void);
 
    // Exit debugger or stop execution and return to the top-level REPL
    // or server loop.
    void stop (void);
 
    // Add EXPR to the set of expressions that may be evaluated when the
    // debugger stops at a breakpoint.
    void add_debug_watch_expression (const std::string& expr);
 
    // Remove EXPR from the set of expressions that may be evaluated
    // when the debugger stops at a breakpoint.
    void remove_debug_watch_expression (const std::string& expr);
 
    // Clear the set of expressions that may be evaluated when the
    // debugger stops at a breakpoint.
    void clear_debug_watch_expressions (void);
 
    // Return the set of expressions that may be evaluated when the
    // debugger stops at a breakpoint.
    std::set<std::string> debug_watch_expressions (void) const;
 
    // Resume interpreter execution if paused.
    void resume (void);
 
    // Provided for convenience.  Will be removed once we eliminate the
    // old terminal widget.
    bool experimental_terminal_widget (void) const;
 
    void handle_exception (const execution_exception& ee);
 
    void recover_from_exception (void);
 
    void mark_for_deletion (const std::string& file);
 
    void cleanup_tmp_files (void);
 
    void quit (int exit_status, bool force = false, bool confirm = true);
 
    void cancel_quit (bool flag) { m_cancel_quit = flag; }
 
    bool executing_finish_script (void) const
    {
      return m_executing_finish_script;
    }
 
    void add_atexit_fcn (const std::string& fname);
 
    bool remove_atexit_fcn (const std::string& fname);
 
  private:
 
    // Remove when corresponding public deprecated function is removed.
    static void add_atexit_function_deprecated (const std::string& fname);
 
    // Remove when corresponding public deprecated function is removed.
    static bool remove_atexit_function_deprecated (const std::string& fname);
 
  public:
 
#if defined (OCTAVE_PROVIDE_DEPRECATED_SYMBOLS)
    OCTAVE_DEPRECATED (6, "use interpreter::add_atexit_fcn member function instead")
    static void add_atexit_function (const std::string& fname)
    {
      add_atexit_function_deprecated (fname);
    }
 
    OCTAVE_DEPRECATED (6, "use interpreter::remove_atexit_fcn member function instead")
    static bool remove_atexit_function (const std::string& fname)
    {
      return remove_atexit_function_deprecated (fname);
    }
    #endif
 
    static interpreter * the_interpreter (void) { return m_instance; }
 
  private:
 
    void display_startup_message (void) const;
 
    int execute_startup_files (void);
 
    int execute_eval_option_code (void);
 
    int execute_command_line_file (void);
 
    int main_loop (void);
 
    int server_loop (void);
 
    void shutdown (void);
 
    void execute_atexit_fcns (void);
 
    void maximum_braindamage (void);
 
    void execute_pkg_add (const std::string& dir);
 
    //--------
 
    // The interpreter instance;  Currently it is only possible to
    // have one, so OCTAVE_THREAD_LOCAL will normally be defined to be
    // empty.  Eventually we would like to allow multiple interpreters
    // to be active at once, but they will still be limited to one per
    // thread.  When that is possible, OCTAVE_THREAD_LOCAL can be
    // replaced by the C++ thread_local keyword.  For now, use a macro
    // to allow experimenting with thread_local storage.
 
    OCTAVE_THREAD_LOCAL static interpreter *m_instance;
 
    application *m_app_context;
 
    temporary_file_list m_tmp_files;
 
    std::list<std::string> m_atexit_fcns;
 
    display_info m_display_info;
 
    environment m_environment;
 
    settings m_settings;
 
    error_system m_error_system;
 
    help_system m_help_system;
 
    input_system m_input_system;
 
    output_system m_output_system;
 
    history_system m_history_system;
 
    dynamic_loader m_dynamic_loader;
 
    load_path m_load_path;
 
    load_save_system m_load_save_system;
 
    type_info m_type_info;
 
    symbol_table m_symbol_table;
 
    tree_evaluator m_evaluator;
 
    stream_list m_stream_list;
 
    child_list m_child_list;
 
    url_handle_manager m_url_handle_manager;
 
    cdef_manager m_cdef_manager;
 
    gtk_manager m_gtk_manager;
 
    event_manager m_event_manager;
 
    gh_manager *m_gh_manager;
 
    // TRUE means this is an interactive interpreter (forced or not).
    bool m_interactive;
 
    bool m_read_site_files;
 
    bool m_read_init_files;
 
    bool m_verbose;
 
    bool m_traditional;
 
    bool m_inhibit_startup_message;
 
    bool m_load_path_initialized;
 
    bool m_history_initialized;
 
    bool m_interrupt_all_in_process_group;
 
    bool m_cancel_quit;
 
    bool m_executing_finish_script;
 
    bool m_executing_atexit;
 
    bool m_initialized;
  };
 
OCTAVE_NAMESPACE_END
 
#endif