changeset 19111:d4a920d28242

Depecrate usage() function. * NEWS: Announce deprecation. * error.cc (F__usage__): Rename usage to internal name __usage__. * scripts/deprecated/usage.m: New function to wrap C++ __usage__ function. * scripts/deprecated/module.mk: Add usage.m to build system. * errors.txi: Remove usage() from manual.
author Rik <rik@octave.org>
date Sat, 20 Sep 2014 14:25:30 -0700
parents fa48651fbb8a
children bc640d4678fb
files NEWS doc/interpreter/errors.txi libinterp/corefcn/error.cc scripts/deprecated/module.mk scripts/deprecated/usage.m
diffstat 5 files changed, 76 insertions(+), 9 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Sat Sep 20 17:16:56 2014 -0400
+++ b/NEWS	Sat Sep 20 14:25:30 2014 -0700
@@ -90,11 +90,13 @@
     be removed from Octave 4.6 (or whatever version is the second major
     release after 4.2):
 
-      bicubic
-      find_dir_in_path
-      nargchk
-      nfields
-      syl
+      Function           | Replacement
+      -------------------|------------------
+      bicubic            | interp2
+      find_dir_in_path   | dir_in_loadpath
+      nfields            | numfields
+      usage              | print_usage
+      syl                | sylvester
 
     The following functions were deprecated in Octave 3.8 and have been
     removed from Octave 4.2.
--- a/doc/interpreter/errors.txi	Sat Sep 20 17:16:56 2014 -0400
+++ b/doc/interpreter/errors.txi	Sat Sep 20 14:25:30 2014 -0700
@@ -126,8 +126,6 @@
 
 @DOCSTRING(print_usage)
 
-@DOCSTRING(usage)
-
 @DOCSTRING(beep)
 
 @DOCSTRING(beep_on_error)
--- a/libinterp/corefcn/error.cc	Sat Sep 20 17:16:56 2014 -0400
+++ b/libinterp/corefcn/error.cc	Sat Sep 20 14:25:30 2014 -0700
@@ -1921,7 +1921,7 @@
   return retval;
 }
 
-DEFUN (usage, args, ,
+DEFUN (__usage__, args, ,
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} usage (@var{msg})\n\
 Print the message @var{msg}, prefixed by the string @samp{usage: }, and\n\
--- a/scripts/deprecated/module.mk	Sat Sep 20 17:16:56 2014 -0400
+++ b/scripts/deprecated/module.mk	Sat Sep 20 14:25:30 2014 -0700
@@ -7,7 +7,8 @@
   deprecated/nargchk.m \
   deprecated/nfields.m \
   deprecated/strmatch.m \
-  deprecated/syl.m
+  deprecated/syl.m \
+  deprecated/usage.m
 
 FCN_FILES += $(deprecated_FCN_FILES)
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/deprecated/usage.m	Sat Sep 20 14:25:30 2014 -0700
@@ -0,0 +1,66 @@
+## Copyright (C) 2014 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 {Built-in Function} {} usage (@var{msg})
+##
+## @code{usage} is deprecated and will be removed in Octave version 4.6.
+## Please use @code{print_usage} in all new code.
+##
+## Print the message @var{msg}, prefixed by the string @samp{usage: }, and
+## set Octave's internal error state such that control will return to the
+## top level without evaluating any more commands.  This is useful for
+## aborting from functions.
+## 
+## After @code{usage} is evaluated, Octave will print a traceback of all
+## the function calls leading to the usage message.
+## 
+## You should use this function for reporting problems errors that result
+## from an improper call to a function, such as calling a function with an
+## incorrect number of arguments, or with arguments of the wrong type.  For
+## example, most functions distributed with Octave begin with code like
+## this
+## 
+## @example
+## @group
+## if (nargin != 2)
+##   usage (\"foo (a, b)\");
+## endif
+## @end group
+## @end example
+## 
+## @noindent
+## to check for the proper number of arguments.
+## @seealso{print_usage}
+## @end deftypefn
+
+## Deprecated in version 4.2
+
+function retval = usage (varargin)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "usage is obsolete and will be removed from a future version of Octave, please use print_usage instead");
+  endif
+
+  retval = __usage__ (varargin{:});
+
+endfunction
+