Re: Mex Extensions

[David Bateman]

Thomas Treichl wrote:
> Hi,
> 

> - I miss one of the great octave features in the mex-interface that I could
>   imagine to be added: The help string implementation like that one I can
>   use with the DLD. I could imagine to either use something like
> 
>     #ifndef MATLAB
>       mexSetHelpOctave ("help-string and tests and demos");
>     #endif

As a function call, this implies that each time the mex function is
called, the help text is reset. This is easy enough to do probably as
the octave_function class has a method "void document (const
std::string&)" whose sole purpose is to set the document string

> 
>   or something more complicated like
> 
>     #ifndef MATLAB
>       mexOctave (int nlhs, ...mxArray* prhs[], const char *octavehelptext)
>     #else
>       mexFunction (int nlhs, ...mxArray* prhs[])
>     #end

Ugly ifdefs aren't the way either as it means that non octave aware
projects will never have proper help.

No, the best way to do this is use the same means as matlab itself. That
is use the mex file if it exists in the path, but get the help text from
the m-file in the loadpath. It appears to me that octave pretty much
does this as it stands, as there is no help in the symbol record of the
mex function, it search with parse.y(get_help_from_file) which only
checks for m-files. The only criticism of this from me is that then the
help misreports that the function is defined in the m-file rather than
the mex file.

To address this we might modify defun.cc(install_mex_function) to also
call parse.y(get_help_from_file) and associate the help string from the
m-file with the symbol record of the mex-function. The construct for
octave_mex_function would also then need modifying to accept the help
string.. Consider the attached patch..

> 
>   to be able to use the "help"-, the "test"- and the "demo"-command in
> octave

The test and demo commands should work perfectly as is they don't care
what the file they are called against is..

D.

*** ./src/defun.cc.orig22       2007-01-10 00:28:04.122034252 +0100
--- ./src/defun.cc      2007-01-10 01:03:28.267849398 +0100
***************
*** 45,50 ****
--- 45,51 ----
  #include "symtab.h"
  #include "toplev.h"
  #include "variables.h"
+ #include "parse.h"
  
  // Print the usage part of the doc string of FCN (user-defined or DEFUN).
  
***************
*** 199,205 ****
      t |= symbol_record::COMMAND;
  
    sym_rec->unprotect ();
!   sym_rec->define (new octave_mex_function (fptr, fmex, shl, name), t);
  
    // Also insert the full name in the symbol table.  This way, we can
    // properly cope with changes to LOAD_PATH.
--- 200,209 ----
      t |= symbol_record::COMMAND;
  
    sym_rec->unprotect ();
!   bool doc_found;
!   std::string doc = get_help_from_file (name, doc_found);
!   sym_rec->define (new octave_mex_function (fptr, fmex, shl, name, doc), t);
!   sym_rec->document (doc);
  
    // Also insert the full name in the symbol table.  This way, we can
    // properly cope with changes to LOAD_PATH.
*** ./src/ov-mex-fcn.h.orig22   2007-01-10 00:28:25.973031801 +0100
--- ./src/ov-mex-fcn.h  2007-01-10 00:47:21.724225212 +0100
***************
*** 47,53 ****
    octave_mex_function (void) { }
  
    octave_mex_function (void *fptr, bool fmex, const octave_shlib& shl,
!                      const std::string& nm = std::string ());
  
    ~octave_mex_function (void);
  
--- 47,54 ----
    octave_mex_function (void) { }
  
    octave_mex_function (void *fptr, bool fmex, const octave_shlib& shl,
!                      const std::string& nm = std::string (),
!                      const std::string& ds = std::string ());
  
    ~octave_mex_function (void);
  
*** ./src/ov-mex-fcn.cc.orig22  2007-01-10 00:28:18.059103167 +0100
--- ./src/ov-mex-fcn.cc 2007-01-10 00:47:34.069314291 +0100
***************
*** 43,50 ****
  
  octave_mex_function::octave_mex_function
    (void *fptr, bool fmex, const octave_shlib& shl,
!    const std::string& nm)
!   : octave_function (nm), mex_fcn_ptr (fptr), exit_fcn_ptr (0),
      have_fmex (fmex), sh_lib (shl)
  {
    mark_fcn_file_up_to_date (time_parsed ());
--- 43,50 ----
  
  octave_mex_function::octave_mex_function
    (void *fptr, bool fmex, const octave_shlib& shl,
!    const std::string& nm, const std::string &ds)
!   : octave_function (nm, ds), mex_fcn_ptr (fptr), exit_fcn_ptr (0),
      have_fmex (fmex), sh_lib (shl)
  {
    mark_fcn_file_up_to_date (time_parsed ());