scilab/modules/core/help/en_US/2_control_flow/pause.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="pause">
   3     <refnamediv>
   4         <refname>pause</refname>
   5         <refpurpose>pause mode, invoke keyboard</refpurpose>
   6     </refnamediv>
   7     <refsynopsisdiv>
   8         <title>Syntax</title>
   9         <synopsis>
  10             pause
  11         </synopsis>
  12     </refsynopsisdiv>
  13     <refsection>
  14         <title>Description</title>
  15         <para>
  16             Switch to the <code>pause</code> mode;
  17             inserted in the code of a function, <code>pause</code> interrupts the execution
  18             of the function: one receives a prompt symbol which indicates
  19             the level of the <code>pause</code> (e.g. <literal>-1-&gt;</literal>). The user is
  20             then in a new workspace in which all the lower-level variables
  21             (and in particular all the variable of the function) are available.
  22             To return to the calling workspace enter <code>return</code>.
  23         </para>
  24         <para>
  25             In this mode, <literal>[...]=return(...) </literal>
  26             returns the variables of the argument <literal>(...)</literal> to the calling workspace with
  27             names in the output <literal>[...]</literal>. Otherwise, the lower-level variables
  28             are protected and cannot be modified.
  29         </para>
  30         <para>
  31             The <literal>pause</literal> is extremely useful for debugging purposes.
  32         </para>
  33         <para>
  34             This mode is killed by the command <code>abort</code>.
  35         </para>
  36     </refsection>
  37     <refsection>
  38         <title>Examples</title>
  39         <programlisting role="example"><![CDATA[
  40     function c=foo(b)
  41     a=42+b
  42     disp("Thanks to the pause, you can investigate if ''a'' has the right value");
  43     disp("Value can be changed too if needed.");
  44     pause
  45     c=a+2
  46     endfunction
  47
  48     foo(2)
  49  ]]></programlisting>
  50     </refsection>
  51     <refsection role="see also">
  52         <title>See also</title>
  53         <simplelist type="inline">
  54             <member>
  55                 <link linkend="halt">halt</link>
  56             </member>
  57             <member>
  58                 <link linkend="return">return</link>
  59             </member>
  60             <member>
  61                 <link linkend="abort">abort</link>
  62             </member>
  63             <member>
  64                 <link linkend="quit">quit</link>
  65             </member>
  66             <member>
  67                 <link linkend="whereami">whereami</link>
  68             </member>
  69             <member>
  70                 <link linkend="where">where</link>
  71             </member>
  72             <member>
  73                 <link linkend="sleep">sleep</link>
  74             </member>
  75         </simplelist>
  76     </refsection>
  77 </refentry>