////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 2002-2024 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 <atomic>
#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 "gh-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 std::atomic<bool> octave_initialized;

#include "oct-time.h"

OCTAVE_BEGIN_NAMESPACE(octave)

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 () : m_files () { }

  OCTAVE_DISABLE_COPY_MOVE (temporary_file_list)

  ~temporary_file_list ();

  void insert (const std::string& file);

  void cleanup ();

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);

  OCTAVE_DISABLE_COPY_MOVE (interpreter)

  // Clean up the interpreter object.

  ~interpreter ();

  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 ();

  // Note: GET_LINE_AND_EVAL is only used by new experimental terminal
  // widget.

  void get_line_and_eval ();

  // 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 ();

  bool server_mode () const { return m_evaluator.server_mode (); }

  bool interactive () const
  {
    return m_interactive;
  }

  void interactive (bool arg)
  {
    m_interactive = arg;
  }

  void read_site_files (bool flag)
  {
    m_read_site_files = flag;
  }

  void read_user_files (bool flag)
  {
    m_read_user_files = flag;
  }

  OCTAVE_DEPRECATED (10, "interpreter::read_init_files is deprecated, use read_user_files")
  void read_init_files (bool flag)
  {
    read_user_files (flag);
  }

  void init_trace (bool flag)
  {
    m_init_trace = flag;
  }

  OCTAVE_DEPRECATED (10, "interpreter::verbose is deprecated, use init_trace")
  void verbose (bool flag)
  {
    init_trace (flag);
  }

  void traditional (bool flag)
  {
    m_traditional = flag;
  }

  bool traditional () const
  {
    return m_traditional;
  }

  void inhibit_startup_message (bool flag)
  {
    m_inhibit_startup_message = flag;
  }

  bool in_top_level_repl () const
  {
    return m_evaluator.in_top_level_repl ();
  }

  bool is_initialized () const
  {
    return m_initialized;
  }

  OCTAVE_DEPRECATED (9, "use octave::is_initialized instead")
  bool initialized () const
  {
    return is_initialized ();
  }

  void interrupt_all_in_process_group (bool b)
  {
    m_interrupt_all_in_process_group = b;
  }

  bool interrupt_all_in_process_group () const
  {
    return m_interrupt_all_in_process_group;
  }

  application * get_app_context ()
  {
    return m_app_context;
  }

  display_info& get_display_info ()
  {
    return m_display_info;
  }

  environment& get_environment ()
  {
    return m_environment;
  }

  settings& get_settings ()
  {
    return m_settings;
  }

  error_system& get_error_system ()
  {
    return m_error_system;
  }

  tree_evaluator& get_evaluator ();

  help_system& get_help_system ()
  {
    return m_help_system;
  }

  input_system& get_input_system ()
  {
    return m_input_system;
  }

  output_system& get_output_system ()
  {
    return m_output_system;
  }

  history_system& get_history_system ()
  {
    return m_history_system;
  }

  dynamic_loader& get_dynamic_loader ()
  {
    return m_dynamic_loader;
  }

  load_path& get_load_path ()
  {
    return m_load_path;
  }

  load_save_system& get_load_save_system ()
  {
    return m_load_save_system;
  }

  type_info& get_type_info ()
  {
    return m_type_info;
  }

  symbol_table& get_symbol_table ()
  {
    return m_symbol_table;
  }

  symbol_scope get_top_scope () const;
  symbol_scope get_current_scope () const;
  symbol_scope require_current_scope (const std::string& who) const;

  profiler& get_profiler ();

  stream_list& get_stream_list ();

  child_list& get_child_list ()
  {
    return m_child_list;
  }

  url_handle_manager& get_url_handle_manager ();

  cdef_manager& get_cdef_manager ()
  {
    return m_cdef_manager;
  }

  gtk_manager& get_gtk_manager ()
  {
    return m_gtk_manager;
  }

  event_manager& get_event_manager ()
  {
    return m_event_manager;
  }

  gh_manager& get_gh_manager ()
  {
    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);

  std::string inputname (int n, bool ids_only = true) const;

  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 () 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 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 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 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 ();

  std::list<std::string> top_level_variable_names ();

  std::list<std::string> global_variable_names ();

  std::list<std::string> user_function_names ();

  std::list<std::string> autoloaded_functions () const;

  void interrupt ();

  // Pause interpreter execution at the next available statement and
  // enter the debugger.
  void pause ();

  // Exit debugger or stop execution and return to the top-level REPL
  // or server loop.
  void stop ();

  // 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 ();

  // Return the set of expressions that may be evaluated when the
  // debugger stops at a breakpoint.
  std::set<std::string> debug_watch_expressions () const;

  // Resume interpreter execution if paused.
  void resume ();

  octave_value PS1 (const octave_value_list& args, int nargout);
  std::string PS1 () const;
  std::string PS1 (const std::string& s);
  void set_PS1 (const std::string& s);

  octave_value PS2 (const octave_value_list& args, int nargout);
  std::string PS2 () const;
  std::string PS2 (const std::string& s);
  void set_PS2 (const std::string& s);

  octave_value PS4 (const octave_value_list& args, int nargout);
  std::string PS4 () const;
  std::string PS4 (const std::string& s);
  void set_PS4 (const std::string& s);

  // Provided for convenience.  Will be removed once we eliminate the
  // old terminal widget.
  bool experimental_terminal_widget () const;

  void handle_exception (const execution_exception& ee);

  void recover_from_exception ();

  void mark_for_deletion (const std::string& file);

  void cleanup_tmp_files ();

  void quit (int exit_status, bool force = false, bool confirm = true);

  void cancel_quit (bool flag) { m_cancel_quit = flag; }

  bool executing_finish_script () const
  {
    return m_executing_finish_script;
  }

  void add_atexit_fcn (const std::string& fname);

  bool remove_atexit_fcn (const std::string& fname);

  static interpreter * the_interpreter () { return s_instance; }

private:

  void display_startup_message () const;

  int execute_startup_files ();

  int execute_eval_option_code ();

  int execute_command_line_file ();

  int main_loop ();

  int server_loop ();

  void shutdown ();

  void execute_atexit_fcns ();

  void maximum_braindamage ();

  void execute_pkg_add (const std::string& dir);

  int safe_source_file (const std::string& file_name,
                        const std::string& context = "",
                        bool verbose = false, bool require_file = true);

  //--------

  // 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 *s_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;

  tree_evaluator m_evaluator;

  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;

  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_user_files;

  bool m_init_trace;

  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_END_NAMESPACE(octave)

#endif