Re: stubs for missing functions

[John W. Eaton]

On 23-Mar-2010, S ren Hauberg wrote:

| tir, 23 03 2010 kl. 18:33 -0400, skrev John W. Eaton:
| > We frequently see people sending bug reports or questions on the help
| > list about functions that are available in Matlab but missing from
| > Octave.
| [snip]
| > Comments?
| 
| I think this idea is good. Just a few minor comments/questions:
| 
|      1. We recently introduced warnings when a function in a package
|         shadows something that is distributed with Octave. If we start
|         distributing a bunch of stubs, won't that generate a bunch of
|         warnings if the user installs a package that provides some of
|         these functions?
|      2. It would be nice if http://www.octave.org/missing.html included
|         the list of stubs. When suggesting the user to look at
|         Octave-Forge we can then use the following link:
|         http://octave.sourceforge.net/find_function.php?fun=STUB_FUNCTION 
where 'STUB_FUNCTION' should be replaced with the name of the stub in question.
|      3. It seems like you forgot to deal with keywords in your list of
|         potential stubs. At least the list includes stuff like 'end',
|         'for', 'varargin', etc. In Octave, you can get the complete list
|         of keywords, using the '__keywords__' function.
| 
| Also
| 
| > +function unimplemented (fcn)
| > +
| > +  txt = __makeinfo__ (sprintf ("The %s function is not yet implemented in 
Octave.  Please read @url{http://www.octave.org/missing.html} to find out how 
you can help to contribute a working version of this function.", fcn));
| > +
| > +  while (txt(end) == "\n")
| > +    txt(end) = "";
| > +  endwhile
| 
| Can't this while-loop be replaced by a call to a 'strip' function. Ohh,
| I see we don't have functions for stripping spaces from text. In 'pkg.m'
| we have some functions for doing stuff like this. Perhaps they should be
| made generally available?

I'm attaching an updated version of the patch.  I haven't tried to
skip stub functions when doing completion, but I have added the
functions is_stub_function and stub_functions.

jwe

# HG changeset patch
# User John W. Eaton <address@hidden>
# Date 1269406154 14400
# Node ID e1dde1e1e1e4b6dd2d2e93da64645b9e92c295cb
# Parent  146e615b667496161f7a94eb3a89f5f54acf5de2
create stub functions for unimplemented Matlab functions

diff --git a/scripts/ChangeLog b/scripts/ChangeLog
--- a/scripts/ChangeLog
+++ b/scripts/ChangeLog
@@ -1,3 +1,14 @@
+2010-03-24  John W. Eaton  <address@hidden>
+
+       * Makefile.am: Include stub/module.mk.
+       (nobase_fcn_file_DATA, EXTRA_DIST, DISTCLEANFILES):
+       Include stub_FCN_FILES in the list.
+       (all-local): Depend on stub_FCN_FILES.
+       (stub/$(octave_dirstamp)): New target.
+       * mkstub.sh, mkstubs.sh: New scripts.
+       * stub/module.mk, stub/function-list: New files.
+       * stub/is_stub_function.m, stub/private/unimplemented.m: New functions.
+
 2010-03-23  John W. Eaton  <address@hidden>
 
        * plot/refreshdata.m: Don't use cell2mat on cell array of cell arrays.
diff --git a/scripts/Makefile.am b/scripts/Makefile.am
--- a/scripts/Makefile.am
+++ b/scripts/Makefile.am
@@ -65,16 +65,17 @@
 include statistics/models/module.mk
 include statistics/tests/module.mk
 include strings/module.mk
+include stub/module.mk
 include testfun/module.mk
 include time/module.mk
 
-nobase_fcnfile_DATA = $(FCN_FILES) $(GEN_FCN_FILES)
+nobase_fcnfile_DATA = $(FCN_FILES) $(GEN_FCN_FILES) $(stub_FCN_FILES)
 
 image_DATA = $(IMAGES)
 
 FCN_FILES_IN = $(GEN_FCN_FILES:.m=.in)
 
-all-local: $(GEN_FCN_FILES) $(PKG_ADD_FILES) .DOCSTRINGS
+all-local: $(GEN_FCN_FILES) $(stub_FCN_FILES) $(PKG_ADD_FILES) .DOCSTRINGS
 
 octave_dirstamp = $(am__leading_dot)dirstamp
 
@@ -305,6 +306,9 @@
 strings/$(octave_dirstamp):
        $(MKDIR_P) strings
        : > strings/$(octave_dirstamp)
+stub/$(octave_dirstamp):
+       $(MKDIR_P) stub
+       : > stub/$(octave_dirstamp)
 testfun/$(octave_dirstamp):
        $(MKDIR_P) testfun
        : > testfun/$(octave_dirstamp)
@@ -403,6 +407,7 @@
   $(FCN_FILES) \
   $(FCN_FILES_IN) \
   $(GEN_FCN_FILES) \
+  $(stub_FCN_FILES) \
   DOCSTRINGS \
   mkdoc \
   mk-pkg-add
@@ -411,5 +416,6 @@
   DOCSTRINGS \
   $(PKG_ADD_FILES) \
   $(DIRSTAMP_FILES) \
-  $(GEN_FCN_FILES)
+  $(GEN_FCN_FILES) \
+  $(stub_FCN_FILES)
 
diff --git a/scripts/mkstub.sh b/scripts/mkstub.sh
new file mode 100755
--- /dev/null
+++ b/scripts/mkstub.sh
@@ -0,0 +1,23 @@
+#! /bin/sh
+
+if [ $# -eq 1 ]; then
+  FCN="$1"
+else
+  echo "usage: mkstub.sh fcn" 1>&2
+  exit 1;
+fi
+
+cat << EOF
+## -*- texinfo -*-
+## @deftypefn {Function File} {} $FCN ()
+## This function is not yet implemented in Octave.  Please read
+## @url{http://www.octave.org/missing.html} to find out how you can
+## help to contribute a working version of this function.
+## @end deftypefn
+
+function $FCN ()
+
+  unimplemented ("$FCN");
+
+endfunction
+EOF
diff --git a/scripts/mkstubs.sh b/scripts/mkstubs.sh
new file mode 100755
--- /dev/null
+++ b/scripts/mkstubs.sh
@@ -0,0 +1,50 @@
+#! /bin/sh
+
+if [ $# -eq 1 ]; then
+  fcn_list_file="$1"
+else
+  echo "usage: mkstubs.sh fcn-list-file" 1>&2
+  exit 1;
+fi
+
+cat << EOF
+## Copyright (C) 2010 John W. Eaton
+##
+## 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
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} {} stub_functions ()
+## List all stub functions distributed with Octave.
+## @end deftypefn
+
+function retval = stub_functions ()
+
+  persistent stub_fcn_list = {
+EOF
+
+while read fcn
+do
+  echo "    \"$fcn\";";
+done < $fcn_list_file
+
+cat << EOF
+  };
+
+  retval = stub_fcn_list;
+
+endfunction
+EOF
diff --git a/scripts/stub/function-list b/scripts/stub/function-list
new file mode 100644
--- /dev/null
+++ b/scripts/stub/function-list
@@ -0,0 +1,377 @@
+DelaunayTri
+MException
+RandStream
+TriRep
+TriScatteredInterp
+addpref
+align
+alim
+alpha
+alphamap
+annotation
+audiodevinfo
+audioplayer
+audiorecorder
+aufinfo
+auread
+auwrite
+avifile
+aviinfo
+aviread
+bar3
+bar3h
+bench
+betaincinv
+bicg
+bicgstabl
+brush
+builddocsearchdb
+bvp4c
+bvp5c
+bvpget
+bvpinit
+bvpset
+bvpxtend
+callSoapService
+calllib
+camdolly
+cameratoolbar
+camlight
+camlookat
+camorbit
+campan
+campos
+camproj
+camroll
+camtarget
+camup
+camva
+camzoom
+cdf2rdf
+cdfepoch
+cdfinfo
+cdfread
+cdfwrite
+cellplot
+checkin
+checkout
+cholinc
+clearvars
+clipboard
+cmopts
+cmpermute
+cmunique
+colordef
+colormapeditor
+comet3
+commandhistory
+commandwindow
+condeig
+coneplot
+contourslice
+copyobj
+createClassFromWsdl
+createSoapMessage
+curl
+customverctrl
+daqread
+datacursormode
+datatipinfo
+dbmex
+dde23
+ddeget
+ddesd
+ddeset
+decic
+depdir
+depfun
+deval
+dialog
+dither
+divergence
+docopt
+docsearch
+dragrect
+dynamicprops
+echodemo
+ellipj
+ellipke
+erfcinv
+errordlg
+evalc
+exifread
+expint
+export2wsdlg
+figurepalette
+filebrowser
+fill3
+findfigs
+fitsinfo
+fitsread
+flow
+fminsearch
+frame2im
+freqspace
+funm
+gallery
+gammaincinv
+gco
+getappdata
+getframe
+getpixelposition
+getpref
+gmres
+grabcode
+graymon
+gsvd
+guidata
+guide
+guihandles
+handle
+hdf
+hdf5
+hdf5info
+hdf5read
+hdf5write
+hdfinfo
+hdfread
+hdftool
+helpbrowser
+helpdesk
+helpdlg
+helpwin
+hgexport
+hgload
+hgsave
+hgsetget
+hgtransform
+hostid
+ilu
+im2frame
+im2java
+imapprox
+imformats
+import
+importdata
+inmem
+inputParser
+inputdlg
+inspect
+instrfind
+instrfindall
+interpstreamspeed
+isappdata
+iscom
+isinterface
+isjava
+isocaps
+ispref
+isprop
+isstudent
+javaArray
+javaMethod
+javaMethodEDT
+javaObject
+javaObjectEDT
+javaaddpath
+javachk
+javaclasspath
+javarmpath
+ldl
+libfunctions
+libfunctionsview
+libisloaded
+libpointer
+libstruct
+light
+lightangle
+lighting
+linkaxes
+linkdata
+linsolve
+listdlg
+listfonts
+loadlibrary
+lscov
+lsqr
+makehgtform
+material
+matlabrc
+maxNumCompThreads
+memmapfile
+memory
+metaclass
+methodsview
+minres
+mlint
+mlintrpt
+mmfileinfo
+mmreader
+movegui
+movie
+movie2avi
+msgbox
+multibandread
+multibandwrite
+native2unicode
+noanimate
+ode113
+ode15i
+ode15s
+ode23
+ode23s
+ode23t
+ode23tb
+ode45
+odefile
+odeget
+odeset
+odextend
+onCleanup
+open
+openfig
+opengl
+openvar
+ordeig
+ordqz
+ordschur
+padecoef
+pagesetupdlg
+pan
+parfor
+parseSoapResponse
+path2rc
+pathtool
+pcode
+pdepe
+pdeval
+pie3
+playshow
+plotbrowser
+plotedit
+plottools
+polyeig
+prefdir
+preferences
+printdlg
+printopt
+printpreview
+profile
+profsave
+propedit
+propertyeditor
+publish
+qmr
+quad2d
+questdlg
+randi
+rbbox
+rectangle
+recycle
+reducepatch
+reducevolume
+resample
+reset
+rgbplot
+rmappdata
+rmpref
+root
+rotate
+rotate3d
+rsf2csf
+saveas
+selectmoveresize
+sendmail
+serial
+setappdata
+setpixelposition
+setpref
+showplottool
+shrinkfaces
+smooth3
+snapnow
+sound
+soundsc
+ss2tf
+stream2
+stream3
+streamline
+streamparticles
+streamribbon
+streamslice
+streamtube
+strings
+subvolume
+superclasses
+support
+surf2patch
+symmlq
+syntax
+tetramesh
+texlabel
+textscan
+textwrap
+tfqmr
+timer
+timerfind
+timerfindall
+timeseries
+toolboxdir
+tscollection
+tstool
+uibuttongroup
+uicontextmenu
+uicontrol
+uigetdir
+uigetfile
+uigetpref
+uiimport
+uimenu
+uiopen
+uipanel
+uipushtool
+uiputfile
+uiresume
+uisave
+uisetcolor
+uisetfont
+uisetpref
+uistack
+uitable
+uitoggletool
+uitoolbar
+uiwait
+undocheckout
+unicode2native
+unloadlibrary
+unmesh
+usejava
+userpath
+validateattributes
+varargin
+varargout
+verLessThan
+viewmtx
+visdiff
+volumebounds
+waitbar
+waitfor
+warndlg
+waterfall
+wavfinfo
+wavplay
+wavrecord
+web
+whatsnew
+whitebg
+wk1finfo
+wk1read
+wk1write
+workspace
+xlsfinfo
+xlsread
+xlswrite
+xmlread
+xmlwrite
+xslt
+zoom
diff --git a/scripts/stub/is_stub_function.m b/scripts/stub/is_stub_function.m
new file mode 100644
--- /dev/null
+++ b/scripts/stub/is_stub_function.m
@@ -0,0 +1,43 @@
+## Copyright (C) 2010 John W. Eaton
+##
+## 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
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} {} is_stub_function (@var{name})
+## Return true if @var{name} is a stub function included in the
+## Octave distribution.
+## @end deftypefn
+
+function retval = is_stub_function (name)
+
+  if (nargin == 1)
+    if (ischar (name))
+      if (ismember (name, stub_functions ()))
+        d = fileparts (which (name));
+        i = strchr (d, "/", 1, "last");
+        retval = strcmp (d(i+1:end), "stub");
+      else
+        retval = false;
+      endif
+    else
+      error ("is_stub_function: expecting function name as argument");
+    endif
+  else
+    print_usage ();
+  endif
+
+endfunction
diff --git a/scripts/stub/module.mk b/scripts/stub/module.mk
new file mode 100644
--- /dev/null
+++ b/scripts/stub/module.mk
@@ -0,0 +1,24 @@
+FCN_FILE_DIRS += stub
+
+stub_PRIVATE_FCN_FILES = \
+  stub/private/unimplemented.m
+
+stub_fcn_names = $(shell cat $(srcdir)/stub/function-list)
+
+gen_stub_fcns = $(addprefix stub/, $(addsuffix .m, $(stub_fcn_names)))
+
+stub_FCN_FILES = \
+  stub/is_stub_function.m \
+  stub/stub_functions.m \
+  $(gen_stub_fcns) \
+  $(stub_PRIVATE_FCN_FILES)
+
+$(gen_stub_fcns):
+       $(srcdir)/mkstub.sh $(notdir $(basename $@)) > address@hidden
+       mv address@hidden $@
+
+stub/stub_functions.m: mkstubs.sh stub/function-list
+       $(srcdir)/mkstubs.sh $(srcdir)/stub/function-list > address@hidden
+       mv address@hidden $@
+
+DIRSTAMP_FILES += stub/$(octave_dirstamp)
diff --git a/scripts/stub/private/unimplemented.m 
b/scripts/stub/private/unimplemented.m
new file mode 100644
--- /dev/null
+++ b/scripts/stub/private/unimplemented.m
@@ -0,0 +1,32 @@
+## Copyright (C) 2010 John W. Eaton
+##
+## 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
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} {} unimplemented ()
+## Undocumented internal function.
+## @end deftypefn
+
+function unimplemented (fcn)
+
+  txt = __makeinfo__ (sprintf ("The %s function is not yet implemented in 
Octave.  Please read @url{http://www.octave.org/missing.html} to find out how 
you can help to contribute a working version of this function.", fcn));
+
+  txt = regexprep (txt, "\n\n", "");
+
+  error (txt);
+
+endfunction
diff --git a/src/ChangeLog b/src/ChangeLog
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,8 @@
+2010-03-24  John W. Eaton  <address@hidden>
+
+       * load-path.cc (load_path::add_to_fcn_map):
+       Don't warn about shadowing stub functions.
+
 2010-03-23  Jaroslav Hajek  <address@hidden>
 
        * data.cc (Frem, Fmod): New DEFUNs.
diff --git a/src/load-path.cc b/src/load-path.cc
--- a/src/load-path.cc
+++ b/src/load-path.cc
@@ -1688,13 +1688,27 @@
           else
             {
               // Warn if a built-in or library function is being shadowed.
+
               if (! file_info_list.empty ())
                 {
                   file_info& old = file_info_list.front ();
-                  if (sys_path.find (old.dir_name) != std::string::npos)
-                  if (in_path_list (sys_path, old.dir_name))
+
+                  std::string odir = old.dir_name;
+
+                  bool is_stub_dir =
+                    (file_ops::is_dir_sep (odir[odir.length () - 5])
+                     && (odir.substr (odir.length () - 4) == "stub"));
+
+                  // FIXME -- do we need to be more careful about the
+                  // way we look for old.dir_name in sys_path to avoid
+                  // partial matches?
+
+                  if (! is_stub_dir
+                      && sys_path.find (old.dir_name) != std::string::npos
+                      && in_path_list (sys_path, old.dir_name))
                     {
                       std::string fcn_path = file_ops::concat (dir_name, 
fname);
+
                       warning_with_id ("Octave:shadowed-function",
                                        "function %s shadows a core library 
function", 
                                        fcn_path.c_str ());