Mercurial > octave-nkf

comparison scripts/deprecated/usage.m @ 19145:d4a920d28242

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
children db92e7e28e1f
comparison
equal deleted inserted replaced
19144:fa48651fbb8a 19145:d4a920d28242
1 ## Copyright (C) 2014 John W. Eaton
2 ##
3 ## This file is part of Octave.
4 ##
5 ## Octave is free software; you can redistribute it and/or modify it
6 ## under the terms of the GNU General Public License as published by
7 ## the Free Software Foundation; either version 3 of the License, or (at
8 ## your option) any later version.
9 ##
10 ## Octave is distributed in the hope that it will be useful, but
11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 ## General Public License for more details.
14 ##
15 ## You should have received a copy of the GNU General Public License
16 ## along with Octave; see the file COPYING. If not, see
17 ## <http://www.gnu.org/licenses/>.
18
19 ## -*- texinfo -*-
20 ## @deftypefn {Built-in Function} {} usage (@var{msg})
21 ##
22 ## @code{usage} is deprecated and will be removed in Octave version 4.6.
23 ## Please use @code{print_usage} in all new code.
24 ##
25 ## Print the message @var{msg}, prefixed by the string @samp{usage: }, and
26 ## set Octave's internal error state such that control will return to the
27 ## top level without evaluating any more commands. This is useful for
28 ## aborting from functions.
29 ##
30 ## After @code{usage} is evaluated, Octave will print a traceback of all
31 ## the function calls leading to the usage message.
32 ##
33 ## You should use this function for reporting problems errors that result
34 ## from an improper call to a function, such as calling a function with an
35 ## incorrect number of arguments, or with arguments of the wrong type. For
36 ## example, most functions distributed with Octave begin with code like
37 ## this
38 ##
39 ## @example
40 ## @group
41 ## if (nargin != 2)
42 ## usage (\"foo (a, b)\");
43 ## endif
44 ## @end group
45 ## @end example
46 ##
47 ## @noindent
48 ## to check for the proper number of arguments.
49 ## @seealso{print_usage}
50 ## @end deftypefn
51
52 ## Deprecated in version 4.2
53
54 function retval = usage (varargin)
55
56 persistent warned = false;
57 if (! warned)
58 warned = true;
59 warning ("Octave:deprecated-function",
60 "usage is obsolete and will be removed from a future version of Octave, please use print_usage instead");
61 endif
62
63 retval = __usage__ (varargin{:});
64
65 endfunction
66