GNU Octave  8.1.0
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
interpreter.h
Go to the documentation of this file.
1 ////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (C) 2002-2023 The Octave Project Developers
4 //
5 // See the file COPYRIGHT.md in the top-level directory of this
6 // distribution or <https://octave.org/copyright/>.
7 //
8 // This file is part of Octave.
9 //
10 // Octave is free software: you can redistribute it and/or modify it
11 // under the terms of the GNU General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // Octave is distributed in the hope that it will be useful, but
16 // WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU General Public License for more details.
19 //
20 // You should have received a copy of the GNU General Public License
21 // along with Octave; see the file COPYING. If not, see
22 // <https://www.gnu.org/licenses/>.
23 //
24 ////////////////////////////////////////////////////////////////////////
25 
26 #if ! defined (octave_interpreter_h)
27 #define octave_interpreter_h 1
28 
29 #include "octave-config.h"
30 
31 #include <map>
32 #include <set>
33 #include <stack>
34 #include <string>
35 
36 #include "child-list.h"
37 #include "oct-time.h"
38 #include "quit.h"
39 #include "str-vec.h"
40 
41 #include "cdef-manager.h"
42 #include "display.h"
43 #include "dynamic-ld.h"
44 #include "environment.h"
45 #include "error.h"
46 #include "event-manager.h"
47 #include "graphics.h"
48 #include "gtk-manager.h"
49 #include "help.h"
50 #include "input.h"
51 #include "load-path.h"
52 #include "load-save.h"
53 #include "oct-hist.h"
54 #include "oct-stream.h"
55 #include "ov-typeinfo.h"
56 #include "pager.h"
57 #include "pt-eval.h"
58 #include "settings.h"
59 #include "symtab.h"
60 #include "url-handle-manager.h"
61 
62 extern OCTINTERP_API bool quit_allowed;
63 
64 // TRUE means we are ready to interpret commands, but not everything
65 // is ready for interactive use.
66 extern OCTINTERP_API bool octave_interpreter_ready;
67 
68 // TRUE means we've processed all the init code and we are good to go.
69 extern OCTINTERP_API bool octave_initialized;
70 
71 #include "oct-time.h"
72 
74 
75 class profiler;
76 class child_list;
77 class push_parser;
78 
79 // The time we last time we changed directories.
80 extern sys::time Vlast_chdir_time;
81 
82 // The application object contains a pointer to the current
83 // interpreter and the interpreter contains a pointer back to the
84 // application context so we need a forward declaration for one (or
85 // both) of them...
86 
87 class application;
88 
90 {
91 public:
92 
93  temporary_file_list (void) : m_files () { }
94 
95  // No copying!
96 
98 
100 
101  ~temporary_file_list (void);
102 
103  void insert (const std::string& file);
104 
105  void cleanup (void);
106 
107 private:
108 
109  // List of temporary files to delete when we exit.
110  std::set<std::string> m_files;
111 
112 };
113 
114 class OCTINTERP_API interpreter
115 {
116 public:
117 
118  // Create an interpreter object and perform basic initialization.
119 
120  interpreter (application *app_context = nullptr);
121 
122  // No copying, at least not yet...
123 
124  interpreter (const interpreter&) = delete;
125 
126  interpreter& operator = (const interpreter&) = delete;
127 
128  // Clean up the interpreter object.
129 
130  ~interpreter (void);
131 
132  void intern_nargin (octave_idx_type nargs);
133 
134  // If creating an embedded interpreter, you may inhibit reading
135  // the command history file by calling initialize_history with
136  // read_history_file = false prior to calling initialize.
137 
138  void initialize_history (bool read_history_file = false);
139 
140  // If creating an embedded interpreter, you may inhibit setting
141  // the default compiled-in path by calling initialize_load_path
142  // with set_initial_path = false prior calling initialize. After
143  // that, you can add directories to the load path to set up a
144  // custom path.
145 
146  void initialize_load_path (bool set_initial_path = true);
147 
148  // Load command line history, set the load path.
149 
150  void initialize (void);
151 
152  // Note: GET_LINE_AND_EVAL is only used by new experimental terminal
153  // widget.
154 
155  void get_line_and_eval (void);
156 
157  // Parse a line of input. If input ends at a complete statement
158  // boundary, execute the resulting parse tree. Useful to handle
159  // parsing user input when running in server mode.
160 
161  void parse_and_execute (const std::string& input, bool& incomplete_parse);
162 
163  // Initialize the interpreter (if not already done by an explicit
164  // call to initialize), execute startup files, --eval option code,
165  // script files, and/or interactive commands.
166 
167  int execute (void);
168 
169  bool server_mode (void) const { return m_evaluator.server_mode (); }
170 
171  bool interactive (void) const
172  {
173  return m_interactive;
174  }
175 
176  void interactive (bool arg)
177  {
178  m_interactive = arg;
179  }
180 
181  void read_site_files (bool flag)
182  {
183  m_read_site_files = flag;
184  }
185 
186  void read_init_files (bool flag)
187  {
188  m_read_init_files = flag;
189  }
190 
191  void verbose (bool flag)
192  {
193  m_verbose = flag;
194  }
195 
196  void traditional (bool flag)
197  {
198  m_traditional = flag;
199  }
200 
201  bool traditional (void) const
202  {
203  return m_traditional;
204  }
205 
206  void inhibit_startup_message (bool flag)
207  {
208  m_inhibit_startup_message = flag;
209  }
210 
211  bool in_top_level_repl (void) const
212  {
213  return m_evaluator.in_top_level_repl ();
214  }
215 
216  bool initialized (void) const
217  {
218  return m_initialized;
219  }
220 
222  {
223  m_interrupt_all_in_process_group = b;
224  }
225 
227  {
228  return m_interrupt_all_in_process_group;
229  }
230 
232  {
233  return m_app_context;
234  }
235 
237  {
238  return m_display_info;
239  }
240 
242  {
243  return m_environment;
244  }
245 
247  {
248  return m_settings;
249  }
250 
252  {
253  return m_error_system;
254  }
255 
256  tree_evaluator& get_evaluator (void);
257 
259  {
260  return m_help_system;
261  }
262 
264  {
265  return m_input_system;
266  }
267 
269  {
270  return m_output_system;
271  }
272 
274  {
275  return m_history_system;
276  }
277 
279  {
280  return m_dynamic_loader;
281  }
282 
284  {
285  return m_load_path;
286  }
287 
289  {
290  return m_load_save_system;
291  }
292 
294  {
295  return m_type_info;
296  }
297 
299  {
300  return m_symbol_table;
301  }
302 
303  symbol_scope get_top_scope (void) const;
304  symbol_scope get_current_scope (void) const;
305  symbol_scope require_current_scope (const std::string& who) const;
306 
307  profiler& get_profiler (void);
308 
309  stream_list& get_stream_list (void);
310 
312  {
313  return m_child_list;
314  }
315 
316  url_handle_manager& get_url_handle_manager (void);
317 
319  {
320  return m_cdef_manager;
321  }
322 
324  {
325  return m_gtk_manager;
326  }
327 
329  {
330  return m_event_manager;
331  }
332 
333  gh_manager& get_gh_manager (void)
334  {
335  return *m_gh_manager;
336  }
337 
338  // Any Octave code that needs to change the current directory should
339  // call this function instead of calling the system chdir function
340  // directly so that the load-path and GUI may be notified of the
341  // change.
342 
343  int chdir (const std::string& dir);
344 
345  void mlock (bool skip_first = false) const;
346  void munlock (bool skip_first = false) const;
347  bool mislocked (bool skip_first = false) const;
348 
349  // NOTE: since we have a version that accepts a bool argument, we
350  // can't rely on automatic conversion from char* to std::string.
351  void munlock (const char *nm);
352  void munlock (const std::string& nm);
353 
354  bool mislocked (const char *nm);
355  bool mislocked (const std::string& nm);
356 
357  std::string mfilename (const std::string& opt = "") const;
358 
359  octave_value_list eval_string (const std::string& eval_str, bool silent,
360  int& parse_status, int nargout);
361 
362  octave_value eval_string (const std::string& eval_str, bool silent,
363  int& parse_status);
364 
365  octave_value_list eval_string (const octave_value& arg, bool silent,
366  int& parse_status, int nargout);
367 
368  octave_value_list eval (const std::string& try_code, int nargout);
369 
370  octave_value_list eval (const std::string& try_code,
371  const std::string& catch_code, int nargout);
372 
373  octave_value_list evalin (const std::string& context,
374  const std::string& try_code, int nargout);
375 
376  octave_value_list evalin (const std::string& context,
377  const std::string& try_code,
378  const std::string& catch_code, int nargout);
379 
381  feval (const char *name,
382  const octave_value_list& args = octave_value_list (),
383  int nargout = 0);
384 
386  feval (const std::string& name,
387  const octave_value_list& args = octave_value_list (),
388  int nargout = 0);
389 
391  feval (octave_function *fcn,
392  const octave_value_list& args = octave_value_list (),
393  int nargout = 0);
394 
396  feval (const octave_value& f_arg,
397  const octave_value_list& args = octave_value_list (),
398  int nargout = 0);
399 
400  octave_value_list feval (const octave_value_list& args, int nargout = 0);
401 
402  octave_value make_function_handle (const std::string& name);
403 
404  void install_variable (const std::string& name, const octave_value& value,
405  bool global);
406 
407  void set_global_value (const std::string& name, const octave_value& value);
408 
409  octave_value global_varval (const std::string& name) const;
410 
411  void global_assign (const std::string& name,
412  const octave_value& val = octave_value ());
413 
414  octave_value top_level_varval (const std::string& name) const;
415 
416  void top_level_assign (const std::string& name,
417  const octave_value& val = octave_value ());
418 
419  bool is_variable (const std::string& name) const;
420 
421  bool is_local_variable (const std::string& name) const;
422 
423  octave_value varval (const std::string& name) const;
424 
425  void assign (const std::string& name,
426  const octave_value& val = octave_value ());
427 
428  void assignin (const std::string& context, const std::string& varname,
429  const octave_value& val = octave_value ());
430 
431  void source_file (const std::string& file_name,
432  const std::string& context = "",
433  bool verbose = false, bool require_file = true);
434 
435  bool at_top_level (void) const;
436 
437  bool isglobal (const std::string& name) const;
438 
439  octave_value find (const std::string& name);
440 
441  void clear_all (bool force = false);
442 
443  void clear_objects (void);
444 
445  void clear_variable (const std::string& name);
446 
447  void clear_variable_pattern (const std::string& pattern);
448 
449  void clear_variable_regexp (const std::string& pattern);
450 
451  void clear_variables (void);
452 
453  void clear_global_variable (const std::string& name);
454 
455  void clear_global_variable_pattern (const std::string& pattern);
456 
457  void clear_global_variable_regexp (const std::string& pattern);
458 
459  void clear_global_variables (void);
460 
461  void clear_functions (bool force = false);
462 
463  void clear_function (const std::string& name);
464 
465  void clear_symbol (const std::string& name);
466 
467  void clear_function_pattern (const std::string& pat);
468 
469  void clear_function_regexp (const std::string& pat);
470 
471  void clear_symbol_pattern (const std::string& pat);
472 
473  void clear_symbol_regexp (const std::string& pat);
474 
475  std::list<std::string> variable_names (void);
476 
477  std::list<std::string> top_level_variable_names (void);
478 
479  std::list<std::string> global_variable_names (void);
480 
481  std::list<std::string> user_function_names (void);
482 
483  std::list<std::string> autoloaded_functions (void) const;
484 
485  void interrupt (void);
486 
487  // Pause interpreter execution at the next available statement and
488  // enter the debugger.
489  void pause (void);
490 
491  // Exit debugger or stop execution and return to the top-level REPL
492  // or server loop.
493  void stop (void);
494 
495  // Add EXPR to the set of expressions that may be evaluated when the
496  // debugger stops at a breakpoint.
497  void add_debug_watch_expression (const std::string& expr);
498 
499  // Remove EXPR from the set of expressions that may be evaluated
500  // when the debugger stops at a breakpoint.
501  void remove_debug_watch_expression (const std::string& expr);
502 
503  // Clear the set of expressions that may be evaluated when the
504  // debugger stops at a breakpoint.
505  void clear_debug_watch_expressions (void);
506 
507  // Return the set of expressions that may be evaluated when the
508  // debugger stops at a breakpoint.
509  std::set<std::string> debug_watch_expressions (void) const;
510 
511  // Resume interpreter execution if paused.
512  void resume (void);
513 
514  // Provided for convenience. Will be removed once we eliminate the
515  // old terminal widget.
516  bool experimental_terminal_widget (void) const;
517 
518  void handle_exception (const execution_exception& ee);
519 
520  void recover_from_exception (void);
521 
522  void mark_for_deletion (const std::string& file);
523 
524  void cleanup_tmp_files (void);
525 
526  void quit (int exit_status, bool force = false, bool confirm = true);
527 
528  void cancel_quit (bool flag) { m_cancel_quit = flag; }
529 
530  bool executing_finish_script (void) const
531  {
532  return m_executing_finish_script;
533  }
534 
535  void add_atexit_fcn (const std::string& fname);
536 
537  bool remove_atexit_fcn (const std::string& fname);
538 
539  static interpreter * the_interpreter (void) { return m_instance; }
540 
541 private:
542 
543  void display_startup_message (void) const;
544 
545  int execute_startup_files (void);
546 
547  int execute_eval_option_code (void);
548 
549  int execute_command_line_file (void);
550 
551  int main_loop (void);
552 
553  int server_loop (void);
554 
555  void shutdown (void);
556 
557  void execute_atexit_fcns (void);
558 
559  void maximum_braindamage (void);
560 
561  void execute_pkg_add (const std::string& dir);
562 
563  //--------
564 
565  // The interpreter instance; Currently it is only possible to
566  // have one, so OCTAVE_THREAD_LOCAL will normally be defined to be
567  // empty. Eventually we would like to allow multiple interpreters
568  // to be active at once, but they will still be limited to one per
569  // thread. When that is possible, OCTAVE_THREAD_LOCAL can be
570  // replaced by the C++ thread_local keyword. For now, use a macro
571  // to allow experimenting with thread_local storage.
572 
573  OCTAVE_THREAD_LOCAL static interpreter *m_instance;
574 
576 
578 
579  std::list<std::string> m_atexit_fcns;
580 
582 
584 
586 
588 
590 
592 
594 
596 
598 
600 
602 
604 
606 
608 
610 
612 
614 
616 
618 
620 
621  gh_manager *m_gh_manager;
622 
623  // TRUE means this is an interactive interpreter (forced or not).
625 
627 
629 
630  bool m_verbose;
631 
633 
635 
637 
639 
641 
643 
645 
647 
649 };
650 
652 
653 #endif
OCTAVE_END_NAMESPACE(octave)
Provides threadsafe access to octave.
output_system & get_output_system(void)
Definition: interpreter.h:268
bool m_interrupt_all_in_process_group
Definition: interpreter.h:640
url_handle_manager m_url_handle_manager
Definition: interpreter.h:613
void interrupt_all_in_process_group(bool b)
Definition: interpreter.h:221
load_path m_load_path
Definition: interpreter.h:601
stream_list m_stream_list
Definition: interpreter.h:609
environment m_environment
Definition: interpreter.h:583
event_manager & get_event_manager(void)
Definition: interpreter.h:328
error_system m_error_system
Definition: interpreter.h:587
type_info & get_type_info(void)
Definition: interpreter.h:293
bool in_top_level_repl(void) const
Definition: interpreter.h:211
history_system & get_history_system(void)
Definition: interpreter.h:273
help_system m_help_system
Definition: interpreter.h:591
type_info m_type_info
Definition: interpreter.h:605
application * get_app_context(void)
Definition: interpreter.h:231
void verbose(bool flag)
Definition: interpreter.h:191
void read_site_files(bool flag)
Definition: interpreter.h:181
event_manager m_event_manager
Definition: interpreter.h:619
gh_manager & get_gh_manager(void)
Definition: interpreter.h:333
bool m_read_site_files
Definition: interpreter.h:626
dynamic_loader m_dynamic_loader
Definition: interpreter.h:599
bool server_mode(void) const
Definition: interpreter.h:169
display_info m_display_info
Definition: interpreter.h:581
help_system & get_help_system(void)
Definition: interpreter.h:258
bool m_verbose
Definition: interpreter.h:630
error_system & get_error_system(void)
Definition: interpreter.h:251
bool executing_finish_script(void) const
Definition: interpreter.h:530
interpreter(const interpreter &)=delete
bool m_read_init_files
Definition: interpreter.h:628
load_save_system m_load_save_system
Definition: interpreter.h:603
void cancel_quit(bool flag)
Definition: interpreter.h:528
child_list & get_child_list(void)
Definition: interpreter.h:311
bool m_initialized
Definition: interpreter.h:648
bool m_traditional
Definition: interpreter.h:632
history_system m_history_system
Definition: interpreter.h:597
gtk_manager m_gtk_manager
Definition: interpreter.h:617
output_system m_output_system
Definition: interpreter.h:595
child_list m_child_list
Definition: interpreter.h:611
bool traditional(void) const
Definition: interpreter.h:201
symbol_table m_symbol_table
Definition: interpreter.h:607
bool m_cancel_quit
Definition: interpreter.h:642
dynamic_loader & get_dynamic_loader(void)
Definition: interpreter.h:278
static OCTAVE_THREAD_LOCAL interpreter * m_instance
Definition: interpreter.h:573
bool m_executing_finish_script
Definition: interpreter.h:644
void traditional(bool flag)
Definition: interpreter.h:196
bool m_inhibit_startup_message
Definition: interpreter.h:634
temporary_file_list m_tmp_files
Definition: interpreter.h:577
environment & get_environment(void)
Definition: interpreter.h:241
static interpreter * the_interpreter(void)
Definition: interpreter.h:539
symbol_table & get_symbol_table(void)
Definition: interpreter.h:298
bool initialized(void) const
Definition: interpreter.h:216
settings & get_settings(void)
Definition: interpreter.h:246
void interactive(bool arg)
Definition: interpreter.h:176
bool interrupt_all_in_process_group(void) const
Definition: interpreter.h:226
bool m_load_path_initialized
Definition: interpreter.h:636
display_info & get_display_info(void)
Definition: interpreter.h:236
void inhibit_startup_message(bool flag)
Definition: interpreter.h:206
cdef_manager m_cdef_manager
Definition: interpreter.h:615
bool m_history_initialized
Definition: interpreter.h:638
void read_init_files(bool flag)
Definition: interpreter.h:186
load_save_system & get_load_save_system(void)
Definition: interpreter.h:288
void set_global_value(const std::string &name, const octave_value &value)
input_system m_input_system
Definition: interpreter.h:593
cdef_manager & get_cdef_manager(void)
Definition: interpreter.h:318
application * m_app_context
Definition: interpreter.h:575
bool m_executing_atexit
Definition: interpreter.h:646
bool interactive(void) const
Definition: interpreter.h:171
gh_manager * m_gh_manager
Definition: interpreter.h:621
tree_evaluator m_evaluator
Definition: interpreter.h:589
bool m_interactive
Definition: interpreter.h:624
std::list< std::string > m_atexit_fcns
Definition: interpreter.h:579
gtk_manager & get_gtk_manager(void)
Definition: interpreter.h:323
input_system & get_input_system(void)
Definition: interpreter.h:263
load_path & get_load_path(void)
Definition: interpreter.h:283
settings m_settings
Definition: interpreter.h:585
void insert(const std::string &file)
Definition: interpreter.cc:322
temporary_file_list & operator=(const temporary_file_list &)=delete
std::set< std::string > m_files
Definition: interpreter.h:110
temporary_file_list(const temporary_file_list &)=delete
static octave_idx_type find(octave_idx_type i, octave_idx_type *pp)
Definition: colamd.cc:106
OCTAVE_BEGIN_NAMESPACE(octave) static octave_value daspk_fcn
OCTINTERP_API bool octave_interpreter_ready
Definition: interpreter.cc:91
sys::time Vlast_chdir_time
Definition: interpreter.cc:340
OCTINTERP_API bool quit_allowed
Definition: interpreter.cc:87
OCTINTERP_API bool octave_initialized
Definition: interpreter.cc:94
int chdir(const std::string &path_arg)
Definition: lo-sysdep.cc:106
octave_value_list feval(const char *name, const octave_value_list &args, int nargout)
Evaluate an Octave function (built-in or interpreted) and return the list of result values.
Definition: oct-parse.cc:10370
void source_file(const std::string &file_name, const std::string &context, bool verbose, bool require_file)
Definition: oct-parse.cc:10319
static int input(yyscan_t yyscanner)
static void initialize(void)