Mercurial > hg > octave-nkf

comparison scripts/deprecated/shell_cmd.m @ 14018:5d5685216876

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Deprecate shell_cmd function and update system, dos, unix commands * NEWS: Announce deprecation of shell_cmd. * deprecated/shell_cmd.m: New file to hold documentation and warning for shell_cmd. * deprecated/module.mk: Add shell_cmd to build system. * mk_undocumented_list: Remove shell_cmd from undocumented list. * install.txi: Replace reference to shell_cmd with system. * dos.m, unix.m: Update docstrings and add %!test block. * toplev.cc (system): Update docstring and add %!test block.
author Rik <octave@nomad.inbox5.com>
date Thu, 08 Dec 2011 17:25:30 -0800
parents
children 72c96de7a403
comparison
equal deleted inserted replaced
14017:0b94080d2b0f 14018:5d5685216876
1 ## Copyright (C) 2011 Rik Wehbring
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} {} shell_cmd (@var{string})
21 ## @deftypefnx {Built-in Function} {} shell_cmd (@var{string}, @var{return_output})
22 ## @deftypefnx {Built-in Function} {} shell_cmd (@var{string}, @var{return_output}, @var{type})
23 ## @deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} shell_cmd (@dots{})
24 ## @deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} shell_cmd (@var{string}, @var{return_output}, @var{type})
25 ## Execute a shell command specified by @var{string}.
26 ## If the optional argument @var{type} is "async", the process
27 ## is started in the background and the process id of the child process
28 ## is returned immediately. Otherwise, the process is started and
29 ## Octave waits until it exits. If the @var{type} argument is omitted, it
30 ## defaults to a value of "sync".
31 ##
32 ## If the optional argument @var{return_output} is true and the subprocess
33 ## is started synchronously, or if @var{shell_cmd} is called with one input
34 ## argument and one or more output arguments, then the output from the command
35 ## is returned. Otherwise, if the subprocess is executed synchronously, its
36 ## output is sent to the standard output.
37 ##
38 ## The @code{shell_cmd} function can return two values. The first is the
39 ## exit status of the command and the second is any output from the
40 ## command that was written to the standard output stream. For example,
41 ##
42 ## @example
43 ## [status, output] = shell_cmd ("echo foo; exit 2");
44 ## @end example
45 ##
46 ## @noindent
47 ## will set the variable @code{output} to the string @samp{foo}, and the
48 ## variable @code{status} to the integer @samp{2}.
49 ##
50 ## For commands run asynchronously, @var{status} is the process id of the
51 ## command shell that is started to run the command.
52 ## @seealso{system, unix, dos}
53 ## @end deftypefn
54
55 ## Deprecated in version 3.6
56
57 function [status, output] = shell_cmd (varargin)
58 persistent warned = false;
59 if (! warned)
60 warned = true;
61 warning ("Octave:deprecated-function",
62 "shell_cmd is obsolete and will be removed from a future version of Octave; please use system instead");
63 endif
64
65 [status, output] = system (varargin{:});
66
67 endfunction
68