docs/newos_shell_manual.html

   1 <html>
   2 <head>
   3 <title>The NewOS Operating System: Docs</title>
   4 </head>
   5 <body BGCOLOR="#FFFFFF">
   6
   7 <h1 align="center">NewOS shell manual<br>Version 0.2-pre 1</h1>
   8
   9 <hr>
  10
  11 <hr>
  12
  13 <table border="0" width="100%" bgcolor="#E8E8E8">
  14  <tr>
  15   <td width="100%" height="100%" valign="top" align="left">
  16    <center><h3>Contents</h3></center>
  17    <ol>
  18     <li><a href="#What_is_missing">What is missing</a></li>
  19     <li><a href="#Running_a_shell_script">The shell</a></li>
  20     <ol>
  21      <li><a href="#Running_a_shell_script">Running a shell script</a>
  22     </ol>
  23     <li><a href="#Introduction">Introduction</a></li>
  24     <li><a href="#Variables">Variables</a></li>
  25     <ol>
  26      <li><a href="#Variable_Syntax">Syntax</a></li>
  27      <li><a href="#Strings">Numbers and Strings</a></li>
  28      <li><a href="#Build_in_variables">Build in variables</a></li>
  29     </ol>
  30     <li><a href="#Operators">Operators</a></li>
  31     <li><a href="#Functions">Functions</a></li>
  32     <ol>
  33      <li><a href="#exec_function">exec</a></li>
  34      <li><a href="#casting">type casting</a></li>
  35     </ol>
  36     <li><a href="#Statements">Statements</a></li>
  37     <ol>
  38      <li><a href="#Comments">Comments</a></li>
  39      <li><a href="#exec">exec</a></li>
  40      <li><a href="#exit">exit</a></li>
  41      <li><a href="#goto">goto</a></li>
  42      <li><a href="#if">if</a></li>
  43      <li><a href="#labels">label</a></li>
  44     </ol>
  45    </ol>
  46   </td>
  47  </tr>
  48 </table>
  49
  50 <hr>
  51
  52 <table border="0" width="100%" bgcolor="#E8E8E8">
  53  <tr>
  54   <td width="100%" height="100%" valign="top" align="left">
  55    <a name="What_is_missing"></a>
  56    <center><h3>What is missing</h3></center>
  57    The following features are missing but are added in the next release:<br>
  58    <ul>
  59     <li>And,or,xor</li>
  60     <li>Output redirection of 'echo' statement</li>
  61     <li>else?</li>
  62     <li>not operator?</li>
  63     <li>More...</li>
  64    </ul>
  65   </td>
  66  </tr>
  67 </table>
  68
  69 <hr>
  70
  71 <table border="0" width="100%" bgcolor="#E8E8E8">
  72  <tr>
  73   <td width="100%" height="100%" valign="top" align="left">
  74    <a name="The_shell"></a>
  75    <center><h3>The shell</h3></center>
  76    <b>Command line options</b><br><br>
  77    &nbsp;&nbsp;&nbsp;shell [-s] [&lt;script_name&gt; &lt;arguments&gt;]<br><br>
  78    When the &lt;script_name&gt; is given as parameters the shell starts
  79    the interpretor and  runs the script otherwise the shell starts an
  80    interactive session.All options before &nbsp;the script name are handled
  81    as shell parameters. An option is everything which   starts with a '-'.<br>
  82    The script name is placed in the variable $p0 and the flowing &lt;arguments&gt;
  83    are &nbsp;placed in $p1..$p??. $argc contains the number of arguments. The
  84    path in $path is used as search path for the script. The $path value is&nbsp;
  85    hard coded in the shell.<br>
  86    By default the shell exits after when&nbsp; the script ends, but with
  87    the '-s' option   the shell starts an interactive session.<br>
  88   </td>
  89  </tr>
  90 </table>
  91
  92 <hr>
  93
  94 <table border="0" width="100%" bgcolor="#E8E8E8">
  95  <tr>
  96   <td width="100%" height="100%" valign="top" align="left">
  97    <a name="Introduction"></a>
  98    <center><h3>Script language Introduction</h3></center>
  99    The shell script language has the following features:<br>
 100    <ul>
 101     <li>Case sensitive</li>
 102     <li>Identifier names:<br>
 103       Starts with a alphabetic symbol and a number,alphabetic or a '_'  symbols
 104       can follow.<br>
 105       Variables :$&lt;identifier_name&gt;<br>
 106       Label : &lt;identifier_name&gt;:
 107     </li>
 108     <li>if, goto</li>
 109     <li>Formula's</li>
 110     <li>etc...</li>
 111    </ul>
 112   </td>
 113  </tr>
 114 </table>
 115
 116 <hr>
 117
 118 <table border="0" width="100%" bgcolor="#E8E8E8">
 119  <tr>
 120   <td width="100%" height="100%" valign="top" align="left">
 121    <a name="Variables"></a>
 122    <center><h3>Variables</h3></center>
 123    <a name="Variable_Syntax"></a>
 124    <b>Syntax</b><br>
 125    The syntax of a variable name is $&lt;Identifier&gt;.<br>
 126    $a=&lt;value&gt; , defines a variable. <br>
 127    A variable can't be removed yet.<br>
 128    When a new script is started the variables are not shared with the new process.
 129    <br><br>
 130    <a name="Strings"></a>
 131    <b>Numbers and Strings</b><br>
 132    Numbers are stored and handled as&nbsp; 64 bit signed integers<br>
 133    <br>
 134    Strings can start and end with single or double quotes. In double quoted strings
 135    variables (starting with a $) are substituted by their value.<br>
 136    The shell variables doesn't have a type, it can contain a string or a number.<br>
 137    It is not possible to mix strings and numbers in formula's. More info:
 138    <a href="#Operators">Operators</a>
 139    When a value is a string or a number, depends on how they are defined and not
 140    on their contents:<br>
 141    <br>
 142    $a='1', &nbsp; $a contains a string.<br>
 143    <br>
 144    $b= 1 , &nbsp; $b contains a number<br>
 145    <br>
 146    $c=$a+$b this fails because $a contains a string and $b contains a number.<br>
 147    <br>
 148    <a name="Build_in_variables"></a>
 149    <b>Built in variables</b><br>
 150    <table cellpadding="2" cellspacing="2" border="1" width="100%">
 151     <tr>
 152      <td valign="Top">$path</td>
 153      <td valign="Top">Search path for programs</td>
 154     </tr>
 155     <tr>
 156      <td valign="Top">$argc</td>
 157      <td valign="Top">number of arguments</td>
 158     </tr>
 159     <tr>
 160      <td valign="Top">$p0</td>
 161      <td valign="Top">Parameter 0, which is the script filename</td>
 162     </tr>
 163     <tr>
 164      <td valign="Top">$p1...p&lt;no&gt;</td>
 165      <td valign="Top">Script parameters</td>
 166     </tr>
 167    </table>
 168    <b>Note:</b><br>
 169    Parameters are stored as strings. When parameters are used with numbers
 170    they must be cast:<br>
 171    <br>
 172    <b>if(number($p1) == 1) goto the_end</b><br>
 173    or<br>
 174    <b>if($p1 == "1") goto the_end</b><br>
 175    following will fail:<br>
 176    <b>if($p1 == 1) goto the_end</b><br>
 177   </td>
 178  </tr>
 179 </table>
 180
 181 <hr>
 182
 183 <table border="0" width="100%" bgcolor="#E8E8E8">
 184  <tr>
 185   <td width="100%" height="100%" valign="top" align="left">
 186    <a name="Operators"></a>
 187    <center><h3>Operators</h3></center>
 188    In the NewOS shell script language it is possible to write formulas the
 189    same way as in most   modern  programming languages.<br>
 190    The shell can handle the following operators:<br>
 191         +, -, /, *, =, &lt;=, =, =&gt;, &lt;, &gt;, !=, ==<br>
 192    <br>
 193    All operators can be used with numerical values, and are calculated
 194    as integers.<br>
 195    String values can only be used with the compare operators(=,&lt;=,=&gt; etc..)
 196    and the load operator(=).<br>
 197    The compare operator returns a value 1 or 0 for true of false<br>
 198    It is not possible to mix strings and numbers in formulas, the program fails with
 199    an error messages. But a string can be <a href="cast">cast</a> into a number
 200    or vice versa<br>
 201    This is neccesary because some operator handle strings different as numbers :<br>
 202    <ul>
 203     <li>10&gt;2 is true</li>
 204     <li>"10"&gt;"2" is false</li>
 205    </ul>
 206   </td>
 207  </tr>
 208 </table>
 209
 210 <hr>
 211
 212 <table border="0" width="100%" bgcolor="#E8E8E8">
 213  <tr>
 214   <td width="100%" height="100%" valign="top" align="left">
 215    <a name="Functions"></a>
 216    <center><h3>Functions</h3></center>
 217    <a name="exec_function"></a>
 218    <b>exec</b><br>
 219    <br>
 220    <u>syntax:</u><br>
 221    <br>
 222    <b>exec(</b>&lt;string expression&gt;)<br>
 223    <br>
 224    <u>description:</u><br>
 225    <br>
 226    The exec function starts program in &lt;string expression&gt; (which is
 227    the program name and parameters), waits until the process terminates and returns
 228    the exit value.  When filename is not found the execution of the script terminates
 229    with an error  message.<br>
 230    This 'exec' function is using the &nbsp;path in $path as search path.<br>
 231    <br>
 232    <u>examples:</u><br>
 233    $program="shell $p0"<br>
 234    $result=exec($program)<br>
 235    <br>
 236    or<br>
 237    <br>
 238    $result=exec("shell /boot/bin/initX")<br>
 239    <br>
 240
 241    <a name="casting"></a>
 242    <b>type casting: number() and string()</b><br>
 243    <br>
 244    <u>syntax</u><br>
 245    &nbsp;&nbsp;&nbsp; number(&lt;expression&gt;)<br>
 246    &nbsp;&nbsp;&nbsp; string(&lt;expression&gt;)<br>
 247    <br>
 248    The shell makes a distinction between strings &nbsp;and number. '1' is a
 249    string all though it contains a number.<br>
 250    <b>number('1')</b> casts the string into a number. <br>
 251    <br>
 252    <b>string </b>converts a number to a string.<br>
 253    <br>
 254    <u>examples</u><br>
 255    <br>
 256    $a=2<br>
 257    if($p1==$a+1) goto somewhere<br>
 258    <br>
 259    Fails because &nbsp;parameters($p1) is always a string, this should be:<br>
 260    <br>
 261    $a=2<br>
 262    if($p1==string($a+1)) goto somewhere<br>
 263    <br>
 264    or<br>
 265    <br>
 266    $a=2<br>
 267    if(number($p1)==$a+1) goto somewhere<br>
 268    <br>
 269    The difference between the last 2 examples is that the 'number' cast fails
 270    when $p1 doesn't contain a valid number.
 271   </td>
 272  </tr>
 273 </table>
 274
 275 <hr>
 276
 277 <table border="0" width="100%" bgcolor="#E8E8E8">
 278  <tr>
 279   <td width="100%" height="100%" valign="top" align="left">
 280    <a name="Statements"></a>
 281    <center><h3>Statements</h3></center>
 282    <a name="Comments"></a>
 283    <b>Comments</b><br>
 284    Comments always start with the '#' character end at the line end.<br>
 285    <br>
 286
 287    <a name="exec"></a>
 288    <b>exec</b><br>
 289    <u>Syntax:</u><br>
 290    &nbsp; &nbsp; &nbsp;[<b>exec</b>] &lt;program_name&gt; &lt;options&gt;<br>
 291    <br>
 292    <u>description:</u><br>
 293    This command starts another process and executes a binary program.<br>
 294    A program can also started by just using the &lt;program_name&gt;. The exec
 295    statement is optional but when the &lt;program_name&gt; is a detemened by
 296    a variable the 'exec' statements must be used.<br>
 297    <br>
 298    The exec statement can have the following 'options':<br>
 299    <ul>
 300     <li>'&amp;' at the end: The shell doesn't wait until the process ends</li>
 301     <li>Output redirection</li>
 302    </ul>
 303    <u>Examples</u><br>
 304    $texteditor = "word"<br>
 305    if($no_ms) $texteditor="vi"<br>
 306    exec $texteditor $p1<br>
 307    <br>
 308    <a name="exit"></a>
 309    <b>exit</b><br>
 310    <u>Syntax:</u><br
 311    &nbsp; &nbsp; &nbsp;<b>exit</b> [(&lt;expression&gt;)]<br>
 312    <br>
 313    <u>description:</u><br>
 314    The program exits with exit value &lt;expression&gt;.<br>
 315    <br>
 316    When script is started without the -s option the shell always exits
 317    after the script ends.<br>
 318    When no expression is given, the exit code is 0.<br>
 319    Expression must be a number.<br>
 320    <br>
 321
 322    <a name="goto"></a>
 323    <b>goto</b><br>
 324    <u>Syntax:</u><br>
 325    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;<b>goto</b> &lt;label_name&gt;<br>
 326    <br>
 327    <u>description:</u><br>
 328    After the 'goto' statement the program execution starts after the label
 329    &lt;label_name&gt;.<br>
 330    When label can't be found, the program fails with 'label not found' error.<br>
 331    <br>
 332
 333    <a name="if"></a>
 334    <b>if</b><br>
 335    <u>Syntax:</u><br>
 336    &nbsp; &nbsp; &nbsp; &nbsp; <b>if</b>(&lt;expression&gt;) &lt;statement&gt;<br>
 337    <br>
 338    <u>description:</u><br>
 339    &lt;statement&gt; is executed when &lt;expression&gt; &lt;&gt; 0<br>
 340    Only one statement can follow 'if'.<br>
 341    <br>
 342
 343    <a name="labels"></a>
 344    <b>labels</b><br>
 345    <u>Syntax:</u><br>
 346    &nbsp; &nbsp; &nbsp; &lt;label_name&gt;:<br>
 347    <br>
 348    <u>Note:</u><br>
 349    The script file is not yet checked for duplicate labels.
 350   </td>
 351  </tr>
 352 </table>
 353
 354 <hr>
 355
 356 <table border="1" width="100%" bgcolor="#D9D5FF">
 357  <tr>
 358   <td width="100%" height="49" valign="top" align="center"><small><font color="#000000">This
 359    page copyright 2002 </font></small><font size="2">
 360 <!--   <br>
 361    Any questions, comments, gripes, whatever:
 362    <a href="mailto:geist@newos.org">geist@newos.org</a></font>
 363   -->
 364   </td>
 365  </tr>
 366 </table>
 367
 368 </body>
 369 </html>
 370