1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
|
## Copyright (C) 2000-2013 Paul Kienzle
##
## 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 {Command} {} demo @var{name}
## @deftypefnx {Command} {} demo @var{name} @var{n}
## @deftypefnx {Function File} {} demo ("@var{name}")
## @deftypefnx {Function File} {} demo ("@var{name}", @var{n})
##
## Run example code block @var{n} associated with the function @var{name}.
## If @var{n} is not specified, all examples are run.
##
## Examples are stored in the script file, or in a file with the same
## name but no extension located on Octave's load path. To keep examples
## separate from regular script code, all lines are prefixed by @code{%!}. Each
## example must also be introduced by the keyword @qcode{"demo"} flush left
## to the prefix with no intervening spaces. The remainder of the example
## can contain arbitrary Octave code. For example:
##
## @example
## @group
## %!demo
## %! t = 0:0.01:2*pi;
## %! x = sin (t);
## %! plot (t, x);
## %! %-------------------------------------------------
## %! % the figure window shows one cycle of a sine wave
## @end group
## @end example
##
## Note that the code is displayed before it is executed, so a simple
## comment at the end suffices for labeling what is being shown. It is
## generally not necessary to use @code{disp} or @code{printf} within the demo.
##
## Demos are run in a function environment with no access to external
## variables. This means that every demo must have separate initialization
## code. Alternatively, all demos can be combined into a single large demo
## with the code
##
## @example
## %! input("Press <enter> to continue: ","s");
## @end example
##
## @noindent
## between the sections, but this is discouraged. Other techniques
## to avoid multiple initialization blocks include using multiple plots
## with a new @code{figure} command between each plot, or using @code{subplot}
## to put multiple plots in the same window.
##
## Also, because demo evaluates within a function context, you cannot
## define new functions inside a demo. If you must have function blocks,
## rather than just anonymous functions or inline functions, you will have to
## use @code{eval (example ("function",n))} to see them. Because eval only
## evaluates one line, or one statement if the statement crosses
## multiple lines, you must wrap your demo in @qcode{"if 1 <demo stuff> endif"}
## with the @qcode{"if"} on the same line as @qcode{"demo"}. For example:
##
## @example
## @group
## %!demo if 1
## %! function y=f(x)
## %! y=x;
## %! endfunction
## %! f(3)
## %! endif
## @end group
## @end example
##
## @seealso{test, example}
## @end deftypefn
## FIXME: modify subplot so that gnuplot_has_multiplot == 0 causes it to
## use the current figure window but pause if not plotting in the
## first subplot.
function demo (name, n)
if (nargin < 1 || nargin > 2)
print_usage ();
endif
if (nargin < 2)
n = 0;
elseif (ischar (n))
n = str2double (n);
endif
[code, idx] = test (name, "grabdemo");
if (idx == -1)
warning ("no function %s found", name);
return;
elseif (isempty (idx))
warning ("no demo available for %s", name);
return;
elseif (n >= length (idx))
warning ("only %d demos available for %s", length (idx) - 1, name);
return;
endif
if (n > 0)
doidx = n;
else
doidx = 1:(length (idx) - 1);
endif
for i = 1:length (doidx)
## Pause between demos
if (i > 1)
input ("Press <enter> to continue: ", "s");
endif
## Process each demo without failing
try
block = code(idx(doidx(i)):idx(doidx(i)+1)-1);
## Use an environment without variables
eval (["function __demo__()\n" block "\nendfunction"]);
## Display the code that will be executed before executing it
printf ("%s example %d:%s\n\n", name, doidx(i), block);
__demo__;
catch
## Let the programmer know which demo failed.
printf ("%s example %d: failed\n%s\n", name, doidx(i), lasterr ());
end_try_catch
clear __demo__;
endfor
endfunction
%!demo
%! t = 0:0.01:2*pi;
%! x = sin (t);
%! plot (t, x);
%! %-------------------------------------------------
%! % the figure window shows one cycle of a sine wave
%!error demo ()
%!error demo (1, 2, 3)
|