1## Copyright (C) 2000, 2006, 2007, 2008, 2009 Paul Kienzle
3## This file is part of Octave.
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.
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.
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/>.
20## @deftypefn {Function File} {} demo ('@var{name}',@var{n})
22## Runs any examples associated with the function '@var{name}'.
23## Examples are stored in the script file, or in a file with the same
24## name but no extension somewhere on your path. To keep them separate
25## from the usual script code, all lines are prefixed by @code{%!}. Each
26## example is introduced by the keyword 'demo' flush left to the prefix,
27## with no intervening spaces. The remainder of the example can contain
28## arbitrary Octave code. For example:
33## %! t=0:0.01:2*pi; x = sin(t);
35## %! %-------------------------------------------------
36## %! % the figure window shows one cycle of a sine wave
40## Note that the code is displayed before it is executed, so a simple
41## comment at the end suffices. It is generally not necessary to use
42## disp or printf within the demo.
44## Demos are run in a function environment with no access to external
45## variables. This means that all demos in your function must use
46## separate initialization code. Alternatively, you can combine your
47## demos into one huge demo, with the code:
50## %! input("Press <enter> to continue: ","s");
53## between the sections, but this is discouraged. Other techniques
54## include using multiple plots by saying figure between each, or
55## using subplot to put multiple plots in the same window.
57## Also, since demo evaluates inside a function context, you cannot
58## define new functions inside a demo. Instead you will have to
59## use @code{eval(example('function',n))} to see them. Because eval only
60## evaluates one line, or one statement if the statement crosses
61## multiple lines, you must wrap your demo in "if 1 <demo stuff> endif"
62## with the 'if' on the same line as 'demo'. For example,
74## @seealso{test, example}
77## FIXME: modify subplot so that gnuplot_has_multiplot == 0 causes it to
78## use the current figure window but pause if not plotting in the
81function demo (name, n)
83 if (nargin < 1 || nargin > 2)
91 [code, idx] = test (name, "grabdemo");
92 if (length (idx) == 0)
93 warning ("demo not available for %s", name);
95 elseif (n >= length (idx))
96 warning ("only %d demos available for %s", length (idx) - 1, name);
104 doidx = 1:length(idx)-1;
106 for i = 1:length (doidx)
107 ## Pause between demos
109 input ("Press <enter> to continue: ", "s");
112 ## Process each demo without failing
114 block = code(idx(doidx(i)):idx(doidx(i)+1)-1);
115 ## Use an environment without variables
116 eval (cstrcat ("function __demo__()\n", block, "\nendfunction"));
117 ## Display the code that will be executed before executing it
118 printf ("%s example %d:%s\n\n", name, doidx(i), block);
121 ## Let the programmer know which demo failed.
122 printf ("%s example %d: failed\n%s", name, doidx(i), __error_text__);
130%! t=0:0.01:2*pi; x = sin(t);
132%! %-------------------------------------------------
133%! % the figure window shows one cycle of a sine wave
