ov-fcn-handle.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 2003-2026 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_ov_fcn_handle_h)
#define octave_ov_fcn_handle_h 1
 
#include "octave-config.h"
 
#include <iosfwd>
#include <list>
#include <memory>
#include <string>
 
#include "oct-map.h"
#include "ov-base.h"
#include "ov-fcn.h"
#include "ov-typeinfo.h"
#include "stack-frame.h"
#include "symscope.h"
 
OCTAVE_BEGIN_NAMESPACE(octave)
 
class interpreter;
class tree_evaluator;
 
// Function handles.
 
class OCTINTERP_API base_fcn_handle
{
public:
 
  base_fcn_handle (const std::string& name = "",
                   const std::string& file = "")
    : m_name (name), m_file (file)
  { }
 
  base_fcn_handle (const base_fcn_handle&) = default;
 
  virtual ~base_fcn_handle () = default;
 
  virtual base_fcn_handle * clone () const = 0;
 
  virtual std::string type () const = 0;
 
  virtual bool is_internal () const { return false; }
 
  virtual bool is_simple () const { return false; }
 
  virtual bool is_scoped () const { return false; }
 
  virtual bool is_nested () const { return false; }
 
  virtual bool is_nested (const std::shared_ptr<stack_frame>&) const
  {
    return false;
  }
 
  virtual bool is_weak_nested () const { return false; }
 
  virtual bool is_class_simple () const { return false; }
 
  virtual bool is_anonymous () const { return false; }
 
  virtual bool is_weak_anonymous () const { return false; }
 
  virtual OCTINTERP_API octave_value make_weak_nested_handle () const;
 
  virtual OCTINTERP_API octave_value make_weak_anonymous_handle () const;
 
  std::string fcn_name () const { return m_name; }
 
  std::string file () const { return m_file; }
 
  OCTINTERP_API octave_value_list
  subsref (const std::string& type, const std::list<octave_value_list>& idx,
           int nargout);
 
  virtual octave_value_list
  call (int nargout, const octave_value_list& args) = 0;
 
  // FIXME: These must go away.  They don't do the right thing for
  // scoping or overloads.
  virtual octave_function * function_value (bool = false)
  {
    return nullptr;
  }
 
  virtual octave_user_function * user_function_value (bool = false)
  {
    return nullptr;
  }
 
  virtual octave_value fcn_val () { return octave_value (); }
 
  virtual octave_value workspace () const { return octave_value (); }
 
  // Should be const.
  virtual octave_scalar_map info () { return octave_scalar_map (); }
 
  virtual void set_dispatch_class (const std::string& /*class_name*/) { }
 
  virtual std::string get_dispatch_class () const { return ""; }
 
  OCTINTERP_API octave_value
  convert_to_str_internal (bool pad, bool force, char type) const;
 
  virtual OCTINTERP_API bool save_ascii (std::ostream& os);
 
  virtual OCTINTERP_API bool load_ascii (std::istream& is);
 
  virtual OCTINTERP_API bool
  save_binary (std::ostream& os, bool save_as_floats);
 
  virtual OCTINTERP_API bool
  load_binary (std::istream& is, bool swap, mach_info::float_format fmt);
 
  virtual OCTINTERP_API bool
  save_hdf5 (octave_hdf5_id loc_id, const char *name, bool save_as_floats);
 
  virtual OCTINTERP_API bool
  load_hdf5 (octave_hdf5_id& group_hid, octave_hdf5_id& space_hid,
             octave_hdf5_id& type_hid);
 
  virtual void print_raw (std::ostream&, bool /*pr_as_read_syntax*/,
                          int /*current_print_indent_level*/) const
  { }
 
  // Function handles are printed without a newline by default.
  virtual bool print_as_scalar () const { return true; }
 
  virtual bool
  set_fcn (const std::string& /*octaveroot*/, const std::string& /*fpath*/)
  {
    return false;
  }
 
  virtual octave_function *
  get_cached_fcn (void *, void *) { return nullptr; }
 
  virtual octave_function *
  get_cached_fcn (const octave_value_list&) { return nullptr; }
 
  virtual bool
  has_function_cache () const { return false; }
 
  virtual void compile () { }
 
protected:
 
  OCTINTERP_API void warn_load (const char *file_type) const;
  OCTINTERP_API void warn_save (const char *file_type) const;
 
  OCTINTERP_API void unimplemented (const char *op, const char *fmt) const;
 
  // The name of the handle, not including the "@", or the text of the
  // anonymous function.
  std::string m_name;
 
  // The name of the file where the named function was defined.
  std::string m_file;
};
 
OCTAVE_END_NAMESPACE(octave)
 
class OCTINTERP_API octave_fcn_handle : public octave_base_value
{
public:
 
  static const std::string anonymous;
 
  // Creates an invalid function handle.  Used to create generic
  // function handle objects when loading function handles.  Further
  // dispatch happens in the octave_fcn_handle load/save functions.
  octave_fcn_handle ();
 
  // Create a handle to a built-in or internal function.
  octave_fcn_handle (const octave_value& fcn);
 
  // Create a simple function handle that is not bound to a function.
  // Lookup happens when a function call is attempted.
  octave_fcn_handle (const std::string& name);
 
  // Create a simple function handle that is bound to a function.
  octave_fcn_handle (const octave_value& fcn, const std::string& name);
 
  // Create a function handle that might be bound to a class method.
  octave_fcn_handle (const std::string& class_nm, const std::string& meth_nm);
 
  // Create a function handle bound to a class method.
  octave_fcn_handle (const octave_value& fcn, const std::string& class_nm,
                     const std::string& meth_nm);
 
  // Create a function handle bound to a class method.
  octave_fcn_handle (const octave_value& obj, const octave_value& fcn,
                     const std::string& class_nm,
                     const std::string& meth_nm);
 
  // Create a function handle bound to a scoped function.
  octave_fcn_handle (const octave_value& fcn, const std::string& name,
                     const std::list<std::string>& parentage);
 
  // Create a handle to a nested function.
  octave_fcn_handle (const octave_value& fcn, const std::string& name,
                     const std::shared_ptr<octave::stack_frame>& closure_frames);
 
  // Create an anonymous function handle with local variable values
  // provided in LOCAL_VARS.
  octave_fcn_handle (const octave_value& fcn,
                     const octave::stack_frame::local_vars_map& local_vars,
                     const std::shared_ptr<octave::stack_frame>& closure_frames
                     = std::shared_ptr<octave::stack_frame> ());
 
  // Create a simple function handle that is not bound to a function.
  // Lookup happens when a function call is attempted and the function
  // lookup is cached in a octave_fcn_cache.
  octave_fcn_handle (const std::string& name, octave_value cache);
 
  octave_fcn_handle (octave::base_fcn_handle *rep);
 
  octave_fcn_handle (const octave_fcn_handle& fh);
 
  ~octave_fcn_handle () = default;
 
  octave_base_value * clone () const
  {
    return new octave_fcn_handle (*this);
  }
 
  octave_base_value * empty_clone () const
  {
    return new octave_fcn_handle ();
  }
 
  // We don't need to override all three forms of subsref.  The using
  // declaration will avoid warnings about partially-overloaded virtual
  // functions.
  using octave_base_value::subsref;
 
  octave_value subsref (const std::string& type,
                        const std::list<octave_value_list>& idx)
  {
    octave_value_list tmp = subsref (type, idx, 1);
    return tmp.length () > 0 ? tmp(0) : octave_value ();
  }
 
  octave_value_list subsref (const std::string& type,
                             const std::list<octave_value_list>& idx,
                             int nargout)
  {
    return m_rep->subsref (type, idx, nargout);
  }
 
  octave_value_list call (int nargout, const octave_value_list& args);
 
  bool is_defined () const { return true; }
 
  builtin_type_t builtin_type () const { return btyp_func_handle; }
 
  bool is_function_handle () const { return true; }
 
  bool is_internal () const { return m_rep->is_internal (); }
 
  bool is_simple () const { return m_rep->is_simple (); }
 
  bool is_scoped () const { return m_rep->is_scoped (); }
 
  bool is_nested () const { return m_rep->is_nested (); }
 
  bool is_nested (const std::shared_ptr<octave::stack_frame>& frame) const
  {
    return m_rep->is_nested (frame);
  }
 
  bool is_weak_nested () const { return m_rep->is_weak_nested (); }
 
  bool is_class_simple () const { return m_rep->is_class_simple (); }
 
  bool is_anonymous () const { return m_rep->is_anonymous (); }
 
  bool is_weak_anonymous () const { return m_rep->is_weak_anonymous (); }
 
  octave_value make_weak_nested_handle () const
  {
    return m_rep->make_weak_nested_handle ();
  }
 
  octave_value make_weak_anonymous_handle () const
  {
    return m_rep->make_weak_anonymous_handle ();
  }
 
  dim_vector dims () const;
 
  // FIXME: These must go away.  They don't do the right thing for
  // scoping or overloads.
  octave_function * function_value (bool = false)
  {
    return m_rep->function_value ();
  }
 
  octave_user_function * user_function_value (bool = false)
  {
    return m_rep->user_function_value ();
  }
 
  octave_fcn_handle * fcn_handle_value (bool = false) { return this; }
 
  octave_value fcn_val () { return m_rep->fcn_val (); }
 
  // FCN_NAME should be eliminated.
  std::string fcn_name () const { return m_rep->fcn_name (); }
 
  octave_value workspace () const
  {
    return m_rep->workspace ();
  }
 
  octave_scalar_map info () { return m_rep->info (); }
 
  void set_dispatch_class (const std::string& class_name)
  {
    m_rep->set_dispatch_class (class_name);
  }
 
  std::string get_dispatch_class () const
  {
    return m_rep->get_dispatch_class ();
  }
 
  octave_value convert_to_str_internal (bool pad, bool force, char type) const
  {
    return m_rep->convert_to_str_internal (pad, force, type);
  }
 
  bool save_ascii (std::ostream& os);
 
  bool load_ascii (std::istream& is);
 
  bool save_binary (std::ostream& os, bool save_as_floats);
 
  bool load_binary (std::istream& is, bool swap,
                    octave::mach_info::float_format fmt);
 
  bool save_hdf5 (octave_hdf5_id loc_id, const char *name, bool save_as_floats);
 
  bool load_hdf5 (octave_hdf5_id loc_id, const char *name);
 
  void print (std::ostream& os, bool pr_as_read_syntax = false);
 
  void print_raw (std::ostream& os, bool pr_as_read_syntax = false) const;
 
  // Simple function handles are printed without a newline.
  bool print_as_scalar () const { return m_rep->print_as_scalar (); }
 
  friend bool
  is_equal_to (const octave_fcn_handle& fh1, const octave_fcn_handle& fh2);
 
private:
 
  std::shared_ptr<octave::base_fcn_handle> m_rep;
 
  octave::base_fcn_handle * get_rep () const { return m_rep.get (); }
 
  DECLARE_OV_TYPEID_FUNCTIONS_AND_DATA_API (OCTINTERP_API)
};
 
extern bool
is_equal_to (const octave_fcn_handle& fh1, const octave_fcn_handle& fh2);
 
#endif