Mercurial > hg > octave-lojdl
changeset 14018:5d5685216876
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 | 0b94080d2b0f |
children | 36d6867c85d9 |
files | NEWS doc/interpreter/doccheck/mk_undocumented_list doc/interpreter/install.txi scripts/deprecated/module.mk scripts/deprecated/shell_cmd.m scripts/miscellaneous/dos.m scripts/miscellaneous/unix.m src/toplev.cc |
diffstat | 8 files changed, 165 insertions(+), 42 deletions(-) [+] |
line wrap: on
line diff
--- a/NEWS +++ b/NEWS @@ -154,9 +154,9 @@ cut is_duplicate_entry cor polyderiv - corrcoef studentize - __error_text__ sylvester_matrix - error_text + corrcoef shell_cmd + __error_text__ studentize + error_text sylvester_matrix Summary of important user-visible changes for version 3.4.3: -----------------------------------------------------------
--- a/doc/interpreter/doccheck/mk_undocumented_list +++ b/doc/interpreter/doccheck/mk_undocumented_list @@ -120,7 +120,6 @@ SEEK_END semicolon setenv -shell_cmd toc triu unimplemented
--- a/doc/interpreter/install.txi +++ b/doc/interpreter/install.txi @@ -747,7 +747,7 @@ these files without @option{-g}. @item -Some people have reported that calls to shell_cmd and the pager do not +Some people have reported that calls to system() and the pager do not work on SunOS systems. This is apparently due to having @w{@code{G_HAVE_SYS_WAIT}} defined to be 0 instead of 1 when compiling @code{libg++}.
--- a/scripts/deprecated/module.mk +++ b/scripts/deprecated/module.mk @@ -24,6 +24,7 @@ deprecated/replot.m \ deprecated/saveimage.m \ deprecated/setstr.m \ + deprecated/shell_cmd.m \ deprecated/sphcat.m \ deprecated/spvcat.m \ deprecated/strerror.m \
new file mode 100644 --- /dev/null +++ b/scripts/deprecated/shell_cmd.m @@ -0,0 +1,68 @@ +## Copyright (C) 2011 Rik Wehbring +## +## 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} {} shell_cmd (@var{string}) +## @deftypefnx {Built-in Function} {} shell_cmd (@var{string}, @var{return_output}) +## @deftypefnx {Built-in Function} {} shell_cmd (@var{string}, @var{return_output}, @var{type}) +## @deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} shell_cmd (@dots{}) +## @deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} shell_cmd (@var{string}, @var{return_output}, @var{type}) +## Execute a shell command specified by @var{string}. +## If the optional argument @var{type} is "async", the process +## is started in the background and the process id of the child process +## is returned immediately. Otherwise, the process is started and +## Octave waits until it exits. If the @var{type} argument is omitted, it +## defaults to a value of "sync". +## +## If the optional argument @var{return_output} is true and the subprocess +## is started synchronously, or if @var{shell_cmd} is called with one input +## argument and one or more output arguments, then the output from the command +## is returned. Otherwise, if the subprocess is executed synchronously, its +## output is sent to the standard output. +## +## The @code{shell_cmd} function can return two values. The first is the +## exit status of the command and the second is any output from the +## command that was written to the standard output stream. For example, +## +## @example +## [status, output] = shell_cmd ("echo foo; exit 2"); +## @end example +## +## @noindent +## will set the variable @code{output} to the string @samp{foo}, and the +## variable @code{status} to the integer @samp{2}. +## +## For commands run asynchronously, @var{status} is the process id of the +## command shell that is started to run the command. +## @seealso{system, unix, dos} +## @end deftypefn + +## Deprecated in version 3.6 + +function [status, output] = shell_cmd (varargin) + persistent warned = false; + if (! warned) + warned = true; + warning ("Octave:deprecated-function", + "shell_cmd is obsolete and will be removed from a future version of Octave; please use system instead"); + endif + + [status, output] = system (varargin{:}); + +endfunction +
--- a/scripts/miscellaneous/dos.m +++ b/scripts/miscellaneous/dos.m @@ -17,14 +17,16 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {[@var{status}, @var{text}] =} dos (@var{command}) -## @deftypefnx {Function File} {[@var{status}, @var{text}] =} dos (@var{command}, "-echo") +## @deftypefn {Function File} {} dos ("@var{command}") +## @deftypefnx {Function File} {@var{status} =} dos ("@var{command}") +## @deftypefnx {Function File} {[@var{status}, @var{text}] =} dos ("@var{command"}) +## @deftypefnx {Function File} {[@dots{}] =} dos ("@var{command}", "-echo") ## Execute a system command if running under a Windows-like operating ## system, otherwise do nothing. Return the exit status of the program -## in @var{status} and any output sent to the standard output in -## @var{text}. If the optional second argument @code{"-echo"} is given, -## then also send the output from the command to the standard output. -## @seealso{unix, isunix, ispc, system} +## in @var{status} and any output from the command in @var{text}. +## When called with no output argument, or the "-echo" argument is +## given, then @var{text} is also sent to standard output. +## @seealso{unix, system, isunix, ispc} ## @end deftypefn ## Author: octave-forge ??? @@ -42,3 +44,28 @@ endif endfunction + + +%!test +%! cmd = ls_command (); +%! old_wstate = warning ("query"); +%! warning ("off", "Octave:undefined-return-values"); +%! unwind_protect +%! [status, output] = dos (cmd); +%! unwind_protect_cleanup +%! warning (old_wstate); +%! end_unwind_protect +%! +%! if (ispc () && ! isunix ()) +%! [status, output] = dos (cmd); +%! assert (status, 0); +%! assert (ischar (output)); +%! assert (! isempty (output)); +%! else +%! assert (status, []); +%! assert (output, []); +%! endif + +%!error dos () +%!error dos (1, 2, 3) +
--- a/scripts/miscellaneous/unix.m +++ b/scripts/miscellaneous/unix.m @@ -17,14 +17,16 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {[@var{status}, @var{text}] =} unix (@var{command}) -## @deftypefnx {Function File} {[@var{status}, @var{text}] =} unix (@var{command}, "-echo") +## @deftypefn {Function File} {} unix ("@var{command}") +## @deftypefnx {Function File} {@var{status} =} unix ("@var{command}") +## @deftypefnx {Function File} {[@var{status}, @var{text}] =} unix ("@var{command}") +## @deftypefnx {Function File} {[@dots{}] =} unix ("@var{command}", "-echo") ## Execute a system command if running under a Unix-like operating ## system, otherwise do nothing. Return the exit status of the program -## in @var{status} and any output sent to the standard output in -## @var{text}. If the optional second argument @code{"-echo"} is given, -## then also send the output from the command to the standard output. -## @seealso{isunix, ispc, system} +## in @var{status} and any output from the command in @var{text}. +## When called with no output argument, or the "-echo" argument is +## given, then @var{text} is also sent to standard output. +## @seealso{dos, system, isunix, ispc} ## @end deftypefn ## Author: octave-forge ??? @@ -42,3 +44,27 @@ endif endfunction + + +%!test +%! cmd = ls_command (); +%! old_wstate = warning ("query"); +%! warning ("off", "Octave:undefined-return-values"); +%! unwind_protect +%! [status, output] = unix (cmd); +%! unwind_protect_cleanup +%! warning (old_wstate); +%! end_unwind_protect +%! +%! if (isunix ()) +%! assert (status, 0); +%! assert (ischar (output)); +%! assert (! isempty (output)); +%! else +%! assert (status, []); +%! assert (output, []); +%! endif + +%!error unix () +%!error unix (1, 2, 3) +
--- a/src/toplev.cc +++ b/src/toplev.cc @@ -827,8 +827,8 @@ else cmd_status = 127; + retval(1) = output_buf.str (); retval(0) = cmd_status; - retval(1) = output_buf.str (); } else error ("unable to start subprocess for `%s'", cmd_str.c_str ()); @@ -840,31 +840,36 @@ DEFUN (system, args, nargout, "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {[@var{status}, @var{output}]} system (@var{string}, @var{return_output}, @var{type})\n\ -@deftypefnx {Built-in Function} {[@var{status}, @var{output}]} shell_cmd (@var{string}, @var{return_output}, @var{type})\n\ +@deftypefn {Built-in Function} {} system (\"@var{string}\")\n\ +@deftypefnx {Built-in Function} {} system (\"@var{string}\", @var{return_output})\n\ +@deftypefnx {Built-in Function} {} system (\"@var{string}\", @var{return_output}, @var{type})\n\ +@deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} system (@dots{})\n\ Execute a shell command specified by @var{string}.\n\ -If the optional argument @var{type} is @code{\"async\"}, the process\n\ -is started in the background and the process id of the child process\n\ -is returned immediately. Otherwise, the process is started, and\n\ -Octave waits until it exits. If the @var{type} argument is omitted, a\n\ -value of @code{\"sync\"} is assumed.\n\ +If the optional argument @var{type} is \"async\", the process\n\ +is started in the background and the process ID of the child process\n\ +is returned immediately. Otherwise, the child process is started and\n\ +Octave waits until it exits. If the @var{type} argument is omitted, it\n\ +defaults to the value \"sync\".\n\ \n\ -If the optional argument @var{return_output} is true and the subprocess\n\ -is started synchronously, or if @var{system} is called with one input\n\ -argument and one or more output arguments, the output from the command\n\ -is returned. Otherwise, if the subprocess is executed synchronously, its\n\ -output is sent to the standard output. To send the output of a command\n\ -executed with @code{system} through the pager, use a command like\n\ +If @var{system} is called with one or more output arguments, or if the\n\ +optional argument @var{return_output} is true and the subprocess is started\n\ +synchronously, then the output from the command is returned as a variable. \n\ +Otherwise, if the subprocess is executed synchronously, its output is sent\n\ +to the standard output. To send the output of a command executed with\n\ +@code{system} through the pager, use a command like\n\ \n\ @example\n\ -disp (system (cmd, 1));\n\ +@group\n\ +[output, text] = system (\"cmd\");\n\ +disp (text);\n\ +@end group\n\ @end example\n\ \n\ @noindent\n\ or\n\ \n\ @example\n\ -printf (\"%s\\n\", system (cmd, 1));\n\ +printf (\"%s\\n\", nthargout (2, \"system\", \"cmd\"));\n\ @end example\n\ \n\ The @code{system} function can return two values. The first is the\n\ @@ -881,6 +886,7 @@ \n\ For commands run asynchronously, @var{status} is the process id of the\n\ command shell that is started to run the command.\n\ +@seealso{unix, dos}\n\ @end deftypefn") { octave_value_list retval; @@ -1011,20 +1017,16 @@ return retval; } -DEFALIAS (shell_cmd, system); - /* -%!error (system ()); -%!error (system (1, 2, 3)); %!test -%! if (ispc ()) -%! cmd = "dir"; -%! else -%! cmd = "ls"; -%! endif +%! cmd = ls_command (); %! [status, output] = system (cmd); +%! assert (status, 0); %! assert (ischar (output)); %! assert (! isempty (output)); + +%!error system () +%!error system (1, 2, 3) */ // FIXME -- this should really be static, but that causes