stubs for missing functions

[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.  I think we could avoid many of these problems with the
attached patch.  The idea is that for every core Matlab function that
we know about that is missing from Octave, we create a simple stub
function which when run fails with the error:

  error: The FCN function is not yet implemented in Octave.  Please read
  `http://www.octave.org/missing.html' to find out how you can help to
  contribute a working version of this function.
  error: called from:
  ...

Likewise, if someone asks for help about one of these functions, they
will get the following help text:

  `FCN' is a function from the file .../FCN.m

   -- Function File:  FCN ()
       This function is not yet implemented in Octave.  Please read
       `http://www.octave.org/missing.html' to find out how you can help
       to contribute a working version of this function.

(In both cases, FCN will be replaced by the actual function name).

The referenced web page, http://www.octave.org/missing.html remains to
be written.  I intend to explain that there are several possible
reasons why the function is missing:

  The function may exist in Octave Forge but has not yet been adopted
  as a part of the core Octave distribution.

  The function may be new to Matlab.  Perhaps the Octave community
  has no knowledge of it.

  Octave is developed by volunteers who tend to contribute the
  functions which they need, and so far no one has contributed a
  version of this function.

My advice will be something like

  1. check Octave Forge, as a similar function may be available there.

  2. consider writing a function and contributing it.

  3. consider paying someone to implement the function for you.

  4. file a feature request in the bug tracker.

Comments?

Are there any objections to committing this patch?

Thanks,

jwe


# HG changeset patch
# User John W. Eaton <address@hidden>
# Date 1269382331 14400
# Node ID 875e6b7088f1bffed1454fd90a57a89387f41821
# 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-23  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: New script.
+       * stub/module.mk, stub/function-list: New files.
+       * stub/private/unimplemented.m: New function.
+
 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/stub/function-list b/scripts/stub/function-list
new file mode 100644
--- /dev/null
+++ b/scripts/stub/function-list
@@ -0,0 +1,400 @@
+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
+break
+brush
+builddocsearchdb
+bvp4c
+bvp5c
+bvpget
+bvpinit
+bvpset
+bvpxtend
+callSoapService
+calllib
+camdolly
+cameratoolbar
+camlight
+camlookat
+camorbit
+campan
+campos
+camproj
+camroll
+camtarget
+camup
+camva
+camzoom
+case
+catch
+cdf2rdf
+cdfepoch
+cdfinfo
+cdfread
+cdfwrite
+cellplot
+checkin
+checkout
+cholinc
+classdef
+clearvars
+clipboard
+cmopts
+cmpermute
+cmunique
+colordef
+colormapeditor
+comet3
+commandhistory
+commandwindow
+condeig
+coneplot
+continue
+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
+else
+elseif
+end
+erfcinv
+errordlg
+evalc
+events
+exifread
+expint
+export2wsdlg
+figurepalette
+filebrowser
+fill3
+findfigs
+fitsinfo
+fitsread
+flow
+fminsearch
+for
+frame2im
+freqspace
+function
+function_handle
+funm
+gallery
+gammaincinv
+gco
+getappdata
+getframe
+getpixelposition
+getpref
+global
+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
+if
+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
+otherwise
+padecoef
+pagesetupdlg
+pan
+parfor
+parseSoapResponse
+path2rc
+pathtool
+pcode
+pdepe
+pdeval
+persistent
+pie3
+playshow
+plotbrowser
+plotedit
+plottools
+polyeig
+prefdir
+preferences
+printdlg
+printopt
+printpreview
+profile
+profsave
+propedit
+properties
+propertyeditor
+psi
+publish
+qmr
+quad2d
+questdlg
+randi
+rbbox
+rectangle
+recycle
+reducepatch
+reducevolume
+resample
+reset
+return
+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
+switch
+symmlq
+syntax
+tetramesh
+texlabel
+textscan
+textwrap
+tfqmr
+timer
+timerfind
+timerfindall
+timeseries
+toolboxdir
+try
+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
+verctrl
+viewmtx
+visdiff
+volumebounds
+waitbar
+waitfor
+warndlg
+waterfall
+wavfinfo
+wavplay
+wavrecord
+web
+whatsnew
+while
+whitebg
+wk1finfo
+wk1read
+wk1write
+workspace
+xlsfinfo
+xlsread
+xlswrite
+xmlread
+xmlwrite
+xslt
+zoom
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,16 @@
+FCN_FILE_DIRS += stub
+
+stub_PRIVATE_FCN_FILES = \
+  stub/private/unimplemented.m
+
+stub_fcn_names = $(shell cat $(srcdir)/stub/function-list)
+
+stub_FCN_FILES = \
+  $(addprefix stub/, $(addsuffix .m, $(stub_fcn_names))) \
+  $(stub_PRIVATE_FCN_FILES)
+
+$(stub_FCN_FILES):
+       $(srcdir)/mkstub.sh $(notdir $(basename $@)) > 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,34 @@
+## 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));
+
+  while (txt(end) == "\n")
+    txt(end) = "";
+  endwhile
+
+  error (txt);
+
+endfunction