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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) 2006 - 2008 - INRIA
   5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   6  * Copyright (C) 2020 - Samuel GOUGEON
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15  -->
  16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
  18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
  19           xml:lang="en" xml:id="pause">
  20     <refnamediv>
  21         <refname>pause</refname>
  22         <refpurpose>
  23             temporarily pauses the running execution, and allows instructions in console.
  24         </refpurpose>
  25     </refnamediv>
  26     <refsynopsisdiv>
  27         <title>Syntax</title>
  28         <synopsis>
  29             pause
  30         </synopsis>
  31     </refsynopsisdiv>
  32     <refsection>
  33         <title>Description</title>
  34         <para>
  35             Switch to the <function>pause</function> mode.
  36             Inserted in the code of a function, <function>pause</function> interrupts the execution
  37             of the function: one receives a prompt symbol which indicates
  38             the level of the <function>pause</function> (e.g. <literal>-1-&gt;</literal>).
  39             The user is then in the workspace where the pause occurs, and where all the variables
  40             around are accessible and can be changed by hand on purpose.
  41         </para>
  42         <para>
  43             To resume the execution, enter <code>resume</code>.
  44         </para>
  45         <para>
  46             Enter <code>abort</code> to definitively stop the execution and return to the main level.
  47         </para>
  48         <note>
  49             The <function>pause</function> is very useful for debugging purposes.
  50         </note>
  51     </refsection>
  52     <refsection>
  53         <title>Examples</title>
  54         <programlisting role="example"><![CDATA[
  55 function c = foo(b)
  56     a = 42 + b
  57     disp("Thanks to the pause, you can investigate if ''a'' has the right value");
  58     disp("Values of local variables can be changed too if required.");
  59     pause
  60     c = a + 2
  61 endfunction
  62
  63 a = 3;
  64 foo(2)
  65      ]]></programlisting>
  66         <screen><![CDATA[
  67 --> a = 3;
  68 --> foo(2)
  69   "Thanks to the pause, you can investigate if 'a' has the right value"
  70   "Values of local variables can be changed too if required."
  71
  72 Type 'resume' or 'abort' to return to standard level prompt.
  73
  74 -1-> a
  75  a  =
  76    44.
  77
  78 -1-> a = 0;
  79
  80 -1-> resume
  81  ans  =
  82    2.
  83 ]]></screen>
  84     </refsection>
  85     <refsection role="see also">
  86         <title>See also</title>
  87         <simplelist type="inline">
  88             <member>
  89                 <link linkend="debug">debug</link>
  90             </member>
  91             <member>
  92                 <link linkend="halt">halt</link>
  93             </member>
  94             <member>
  95                 <link linkend="return">return</link>
  96             </member>
  97             <member>
  98                 <link linkend="abort">abort</link>
  99             </member>
 100             <member>
 101                 <link linkend="whereami">whereami</link>
 102             </member>
 103             <member>
 104                 <link linkend="sleep">sleep</link>
 105             </member>
 106             <member>
 107                 <link linkend="quit">quit</link>
 108             </member>
 109         </simplelist>
 110     </refsection>
 111     <refsection role="history">
 112         <title>History</title>
 113         <revhistory>
 114             <revision>
 115                 <revnumber>6.0.0</revnumber>
 116                 <revdescription>
 117                     The new values of local variables changed during a pause are now taken
 118                     into account when resuming the execution with <literal>resume</literal>.
 119                 </revdescription>
 120             </revision>
 121         </revhistory>
 122     </refsection>
 123 </refentry>