This file has been translated from LaTeX by HeVeA.

Node: Subsection 9-11-5,	Next: Subsection 9-11-6,	Prev: Subsection 9-11-4,	Up: Section 9-11
  

9.11.5   awk
============

<<   awk(input-files)
     case pattern1:
        body1
     case pattern2:
        body2
     ...
     default:
        bodyd
>>
  
  or
<<   awk(options, input-files)
     case pattern1:
        body1
     case pattern2:
        body2
     ...
     default:
        bodyd
>>
  
  The `awk' function provides input processing similar to awk(1), but
more limited. The `input-files' argument is a sequence of values, each
specifies an `InChannel', or the name of a file for input. If called
with no options and no file arguments, the input is taken from `stdin'.
Output is always to `stdout'.
  The variables `RS' and `FS' define record and field separators as
regular expressions. The default value of `RS' is the regular expression
`\r|\n|\r\n'. The default value of `FS' is the regular expression `[
\t]'+.
  The `awk' function operates by reading the input one record at a time,
and processing it according to the following algorithm.
  For each line, the record is first split into fields using the field
separator `FS', and the fields are bound to the variables `$1, $2, ...'.
The variable `$0' is defined to be the entire line, and `$*' is an array
of all the field values. The `$(NF)' variable is defined to be the
number of fields.
  Next, the cases are evaluated in order. For each case, if the regular
expression `pattern_i' matches the record `$0', then `body_i' is
evaluated. If the body ends in an `export', the state is passed to the
next clause. Otherwise the value is discarded. If the regular expression
contains `\(r\)' expression, those expression override the fields `$1,
$2, ...'.
  For example, here is an `awk' function to print the text between two
delimiters `\begin{<name>}' and `\end{<name>}', where the `<name>' must
belong to a set passed as an argument to the `filter' function.
<<    filter(names) =
         print = false
  
         awk(Awk.in)
         case $"^\\end\{\([:alpha:]+\)\}"
            if $(mem $1, $(names))
               print = false
               export
            export
         default
            if $(print)
               println($0)
         case $"^\\begin\{\([:alpha:]+\)\}"
            print = $(mem $1, $(names))
            export
>>
  
  Note, if you want to redirect the output to a file, the easiest way is
to redefine the `stdout' variable. The `stdout' variable is scoped the
same way as other variables, so this definition does not affect the
meaning of `stdout' outside the `filter' function.
<<    filter(names) =
          stdout = $(fopen file.out, w)
          awk(Awk.in)
             ...
          close(stdout)
>>
  
  Options. 
  
 b  "Break" when evaluating cases. Only the first case that matches will
   be selected. 
  
  The 'break' function can be used to abort the loop, exiting the `awk'
function immediately. 

Node: Subsection 9-11-6,	Next: Subsection 9-11-7,	Prev: Subsection 9-11-5,	Up: Section 9-11
  

9.11.6   fsubst
===============

<<   fsubst(files)
     case pattern1 [options]
        body1
     case pattern2 [options]
        body2
     ...
     default
        bodyd
>>
  
  The `fsubst' function provides a sed(1)-like substitution function.
Similar to `awk', if `fsubst' is called with no arguments, the input is
taken from `stdin'. If arguments are provided, each specifies an
`InChannel', or the name of a file for input.
  The `RS' variable defines a regular expression that determines a
record separator, The default value of `RS' is the regular expression
`\r|\n|\r\n'.
  The `fsubst' function reads the file one record at a time.
  For each record, the cases are evaluated in order. Each case defines a
substitution from a substring matching the `pattern' to replacement text
defined by the body.
  Currently, there is only one option: `g'. If specified, each clause
specifies a global replacement, and all instances of the pattern define
a substitution. Otherwise, the substitution is applied only once.
  Output can be redirected by redefining the `stdout' variable.
  For example, the following program replaces all occurrences of an
expression `word.' with its capitalized form.
<<    section
         stdout = $(fopen Subst.out, w)
         fsubst(Subst.in)
         case $"\<\([[:alnum:]]+\)\." g
            value $(capitalize $1).
         close(stdout)
>>

Node: Subsection 9-11-7,	Next: Subsection 9-11-8,	Prev: Subsection 9-11-6,	Up: Section 9-11
  

9.11.7   lex
============

<<   lex(files)
     case pattern1
        body1
     case pattern2
        body2
     ...
     default
        bodyd
>>
  
  The `lex' function provides a simple lexical-style scanner function.
The input is a sequence of files or channels. The cases specify regular
expressions. Each time the input is read, the regular expression that
matches the longest prefix of the input is selected, and the body is
evaluated.
  If two clauses both match the same input, the last one is selected for
execution. The `default' case matches the regular expression `.'; you
probably want to place it first in the pattern list.
  If the body end with an `export' directive, the state is passed to the
next clause.
  For example, the following program collects all occurrences of
alphanumeric words in an input file.
<<    collect-words($(files)) =
         words[] =
         lex($(files))
         default
            # empty
         case $"[[:alnum:]]+" g
            words[] += $0
            export
>>
  
  The `default' case, if one exists, matches single characters. Since
  It is an error if the input does not match any of the regular
expressions.
  The 'break' function can be used to abort the loop. 

Node: Subsection 9-11-8,	Next: Subsection 9-11-9,	Prev: Subsection 9-11-7,	Up: Section 9-11
  

9.11.8   lex-search
===================

<<   lex-search(files)
     case pattern1
        body1
     case pattern2
        body2
     ...
     default
        bodyd
>>
  
  The `lex-search' function is like the `lex' function, but input that
does not match any of the regular expressions is skipped. If the clauses
include a `default' case, then the `default' matches any skipped text.
  For example, the following program collects all occurrences of
alphanumeric words in an input file, skipping any other text.
<<    collect-words($(files)) =
         words[] =
         lex-search($(files))
         default
            eprintln(Skipped $0)
         case $"[[:alnum:]]+" g
            words[] += $0
            export
>>
  
  The `default' case, if one exists, matches single characters. Since
  It is an error if the input does not match any of the regular
expressions.
  The 'break' function can be used to abort the loop. 

Node: Subsection 9-11-9,	Next: Subsection 9-11-10,	Prev: Subsection 9-11-8,	Up: Section 9-11
  

9.11.9   Lexer
==============

  The `Lexer' object defines a facility for lexical analysis, similar to
the lex(1) and flex(1) programs.
  In omake, lexical analyzers can be constructed dynamically by
extending the `Lexer' class. A lexer definition consists of a set of
directives specified with method calls, and set of clauses specified as
rules.
  For example, consider the following lexer definition, which is
intended for lexical analysis of simple arithmetic expressions for a
desktop calculator.
<<   lexer1. =
        extends $(Lexer)
  
        other: .
           eprintln(Illegal character: $* )
           lex()
  
        white: $"[[:space:]]+"
           lex()
  
        op: $"[-+*/()]"
           switch $*
           case +
              Token.unit($(loc), plus)
           case -
              Token.unit($(loc), minus)
           case *
              Token.unit($(loc), mul)
           case /
              Token.unit($(loc), div)
           case $"("
              Token.unit($(loc), lparen)
           case $")"
              Token.unit($(loc), rparen)
  
        number: $"[[:digit:]]+"
           Token.pair($(loc), exp, $(int $* ))
  
        eof: $"\'"
           Token.unit($(loc), eof)
>>
  
  This program defines an object `lexer1' the extends the `Lexer'
object, which defines lexing environment.
  The remainder of the definition consists of a set of clauses, each
with a method name before the colon; a regular expression after the
colon; and in this case, a body. The body is optional, if it is not
specified, the method with the given name should already exist in the
lexer definition.
  NB The clause that matches the longest prefix of the input is
selected. If two clauses match the same input prefix, then the last one
is selected. This is unlike most standard lexers, but makes more sense
for extensible grammars.
  The first clause matches any input that is not matched by the other
clauses. In this case, an error message is printed for any unknown
character, and the input is skipped. Note that this clause is selected
only if no other clause matches.
  The second clause is responsible for ignoring white space. If
whitespace is found, it is ignored, and the lexer is called recursively.
  The third clause is responsible for the arithmetic operators. It makes
use of the `Token' object, which defines three fields: a `loc' field
that represents the source location; a `name'; and a `value'.
  The lexer defines the `loc' variable to be the location of the current
lexeme in each of the method bodies, so we can use that value to create
the tokens.
  The `Token.unit($(loc), name)' method constructs a new `Token' object
with the given name, and a default value.
  The `number' clause matches nonnegative integer constants. The
`Token.pair($(loc), name, value)' constructs a token with the given name
and value.
  Lexer object operate on `InChannel' objects. The method
`lexer1.lex-channel(channel)' reads the next token from the channel
argument.

Node: Subsection 9-11-10,	Next: Subsection 9-11-11,	Prev: Subsection 9-11-9,	Up: Section 9-11
  

9.11.10   Lexer matching
========================
  
  During lexical analysis, clauses are selected by longest match. That
is, the clause that matches the longest sequence of input characters is
chosen for evaluation. If no clause matches, the lexer raises a
`RuntimeException'. If more than one clause matches the same amount of
input, the first one is chosen for evaluation.

Node: Subsection 9-11-11,	Next: Subsection 9-11-12,	Prev: Subsection 9-11-10,	Up: Section 9-11
  

9.11.11   Extending lexer definitions
=====================================
  
  Suppose we wish to augment the lexer example so that it ignores
comments. We will define comments as any text that begins with the
string `(*', ends with `*)', and comments may be nested.
  One convenient way to do this is to define a separate lexer just to
skip comments.
<<   lex-comment. =
        extends $(Lexer)
  
        level = 0
  
        other: .
           lex()
  
        term: $"[*][)]"
           if $(not $(eq $(level), 0))
              level = $(sub $(level), 1)
              lex()
  
        next: $"[(][*]"
           level = $(add $(level), 1)
           lex()
  
        eof: $"\'"
           eprintln(Unterminated comment)
>>
  
  This lexer contains a field `level' that keeps track of the nesting
level. On encountering a `(*' string, it increments the level, and for
`*)', it decrements the level if nonzero, and continues.
  Next, we need to modify our previous lexer to skip comments. We can do
this by extending the lexer object `lexer1' that we just created.
<<   lexer1. +=
        comment: $"[(][*]"
           lex-comment.lex-channel($(channel))
           lex()
>>
  
  The body for the comment clause calls the `lex-comment' lexer when a
comment is encountered, and continues lexing when that lexer returns.

Node: Subsection 9-11-12,	Next: Subsection 9-11-13,	Prev: Subsection 9-11-11,	Up: Section 9-11
  

9.11.12   Threading the lexer object
====================================
  
  Clause bodies may also end with an `export' directive. In this case
the lexer object itself is used as the returned token. If used with the
`Parser' object below, the lexer should define the `loc', `name' and
`value' fields in each `export' clause. Each time the `Parser' calls the
lexer, it calls it with the lexer returned from the previous lex
invocation. 

Node: Subsection 9-11-13,	Next: Subsection 9-11-14,	Prev: Subsection 9-11-12,	Up: Section 9-11
  

9.11.13   Parser
================
  
  The `Parser' object provides a facility for syntactic analysis based
on context-free grammars.
  `Parser' objects are specified as a sequence of directives, specified
with method calls; and productions, specified as rules.
  For example, let's finish building the desktop calculator started in
the `Lexer' example.
<<   parser1. =
        extends $(Parser)
  
        #
        # Use the main lexer
        #
        lexer = $(lexer1)
  
        #
        # Precedences, in ascending order
        #
        left(plus minus)
        left(mul div)
        right(uminus)
  
        #
        # A program
        #
        start(prog)
  
        prog: exp eof
           return $1
  
        #
        # Simple arithmetic expressions
        #
        exp: minus exp :prec: uminus
           neg($2)
  
        exp: exp plus exp
           add($1, $3)
  
        exp: exp minus exp
           sub($1, $3)
  
        exp: exp mul exp
           mul($1, $3)
  
        exp: exp div exp
           div($1, $3)
  
        exp: lparen exp rparen
           return $2
>>
  
  Parsers are defined as extensions of the `Parser' class. A `Parser'
object must have a `lexer' field. The `lexer' is not required to be a
`Lexer' object, but it must provide a `lexer.lex()' method that returns
a token object with `name' and `value' fields. For this example, we use
the `lexer1' object that we defined previously.
  The next step is to define precedences for the terminal symbols. The
precedences are defined with the `left', `right', and `nonassoc' methods
in order of increasing precedence.
  The grammar must have at least one start symbol, declared with the
`start' method.
  Next, the productions in the grammar are listed as rules. The name of
the production is listed before the colon, and a sequence of variables
is listed to the right of the colon. The body is a semantic action to be
evaluated when the production is recognized as part of the input.
  In this example, these are the productions for the arithmetic
expressions recognized by the desktop calculator. The semantic action
performs the calculation. The variables `$1, $2, ...' correspond to the
values associated with each of the variables on the right-hand-side of
the production.

Node: Subsection 9-11-14,	Next: Subsection 9-11-15,	Prev: Subsection 9-11-13,	Up: Section 9-11
  

9.11.14   Calling the parser
============================
  
  The parser is called with the `$(parser1.parse-channel start,
channel)' or `$(parser1.parse-file start, file)' functions. The `start'
argument is the start symbol, and the `channel' or `file' is the input
to the parser.

Node: Subsection 9-11-15,	Next: Subsection 9-11-16,	Prev: Subsection 9-11-14,	Up: Section 9-11
  

9.11.15   Parsing control
=========================
  
  The parser generator generates a pushdown automation based on LALR(1)
tables. As usual, if the grammar is ambiguous, this may generate
shift/reduce or reduce/reduce conflicts. These conflicts are printed to
standard output when the automaton is generated.
  By default, the automaton is not constructed until the parser is first
used.
  The `build(debug)' method forces the construction of the automaton.
While not required, it is wise to finish each complete parser with a
call to the `build(debug)' method. If the `debug' variable is set, this
also prints with parser table together with any conflicts.
  The `loc' variable is defined within action bodies, and represents the
input range for all tokens on the right-hand-side of the production.

Node: Subsection 9-11-16,	Next: Subsection 9-11-17,	Prev: Subsection 9-11-15,	Up: Section 9-11
  

9.11.16   Extending parsers
===========================
  
  Parsers may also be extended by inheritance. For example, let's extend
the grammar so that it also recognizes the `<<' and `>>' shift
operations.
  First, we extend the lexer so that it recognizes these tokens. This
time, we choose to leave `lexer1' intact, instead of using the +=
operator.
<<   lexer2. =
        extends $(lexer1)
  
        lsl: $"<<"
           Token.unit($(loc), lsl)
  
        asr: $">>"
           Token.unit($(loc), asr)
>>
  
  Next, we extend the parser to handle these new operators. We intend
that the bitwise operators have lower precedence than the other
arithmetic operators. The two-argument form of the `left' method
accomplishes this.
<<   parser2. =
        extends $(parser1)
  
        left(plus, lsl lsr asr)
  
        lexer = $(lexer2)
  
        exp: exp lsl exp
           lsl($1, $3)
  
        exp: exp asr exp
           asr($1, $3)
>>
  
  In this case, we use the new lexer `lexer2', and we add productions
for the new shift operations. 

Node: Subsection 9-11-17,	Next: Subsection 9-11-18,	Prev: Subsection 9-11-16,	Up: Section 9-11
  

9.11.17   Passwd
================

  The `Passwd' object represents an entry in the system's user database.
It contains the following fields.
  
  
  'pw_name': the login name. 
  'pw_passwd': the encrypted password. 
  'pw_uid': user id of the user. 
  'pw_gid': group id of the user. 
  'pw_gecos': the user name or comment field. 
  'pw_dir': the user's home directory. 
  'pw_shell': the user's default shell. 
  
  Not all the fields will have meaning on all operating systems.

Node: Subsection 9-11-18,	Next: Subsection 9-11-19,	Prev: Subsection 9-11-17,	Up: Section 9-11
  

9.11.18   getpwnam, getpwuid
============================

<<    $(getpwnam name...) : Passwd
         name : String
      $(getpwuid uid...) : Passwd
         uid : Int
      raises RuntimeException
>>
  
  The `getpwnam' function looks up an entry by the user's login and the
`getpwuid' function looks up an entry by user's numerical id (uid). If
no entry is found, an exception will be raised.

Node: Subsection 9-11-19,	Next: Subsection 9-11-20,	Prev: Subsection 9-11-18,	Up: Section 9-11
  

9.11.19   getpwents
===================

<<    $(getpwents) : Array
>>
  
  The `getpwents' function returns an array of `Passwd' objects, one for
every user fund in the system user database. Note that depending on the
operating system and on the setup of the user database, the returned
array may be incomplete or even empty. 

Node: Subsection 9-11-20,	Next: Subsection 9-11-21,	Prev: Subsection 9-11-19,	Up: Section 9-11
  

9.11.20   Group
===============

  The `Group' object represents an entry in the system's user group
database. It contains the following fields.
  
  
  'gr_name': the group name. 
  'gr_group': the encrypted password. 
  'gr_gid': group id of the group. 
  'gr_mem': the group member's user names. 
  
  Not all the fields will have meaning on all operating systems.

Node: Subsection 9-11-21,	Next: Subsection 9-11-22,	Prev: Subsection 9-11-20,	Up: Section 9-11
  

9.11.21   getgrnam, getgrgid
============================

<<    $(getgrnam name...) : Group
         name : String
      $(getgrgid gid...) : Group
         gid : Int
      raises RuntimeException
>>
  
  The `getgrnam' function looks up a group entry by the group's name and
the `getgrgid' function looks up an entry by groups's numerical id
(gid). If no entry is found, an exception will be raised.

Node: Subsection 9-11-22,	Next: Subsection 9-11-23,	Prev: Subsection 9-11-21,	Up: Section 9-11
  

9.11.22   tgetstr
=================

<<   $(tgetstr id) : String
        id : String
>>
  
  The `tgetstr' function looks up the terminal capability with the
indicated `id'. This assumes the terminfo to lookup is given in the
`TERM' environment variable. This function returns an empty value if the
given terminal capability is not defined.
  Note: if you intend to use the value returned by `tgetstr' inside the
shell 'prompt', you need to wrap it using the 'prompt-invisible'
function. 

Node: Subsection 9-11-23,	Next: Subsection 9-11-24,	Prev: Subsection 9-11-22,	Up: Section 9-11
  

9.11.23   xterm-escape-begin, xterm-escape-end
==============================================

<<   $(xterm-escape-begin) : String
     $(xterm-escape-end) : String
>>
  
  The `xterm-escape-begin' and `xterm-escape-end' functions return the
escape sequences that can be used to set the XTerm window title. Will
return empty values if this capability is not available.
  Note: if you intend to use these strings inside the shell 'prompt',
you need to use `$(prompt_invisible_begin)$(xterm-escape-begin)' and
`$(xterm-escape-end)$(prompt_invisible_end)'. 

Node: Subsection 9-11-24,	Next: Subsection 9-11-25,	Prev: Subsection 9-11-23,	Up: Section 9-11
  

9.11.24   xterm-escape
======================

<<   $(xterm-escape s) : Sequence
>>
  
  When the `TERM' environment variable indicates that the XTerm title
setting capability is available, `$(xterm-escape s)' is equivalent to
`$(xterm-escape-begin)s$(xterm-escape-end)'. Otherwise, it returns an
empty value.
  Note: if you intend to use the value returned by `xterm-escape' inside
the shell 'prompt', you need to wrap it using the 'prompt-invisible'
function. 

Node: Subsection 9-11-25,	Next: Subsection 9-11-26,	Prev: Subsection 9-11-24,	Up: Section 9-11
  

9.11.25   prompt-invisible-begin, prompt-invisible-end
======================================================

<<   $(prompt-invisible-begin) : String
     $(prompt-invisible-end) : String
>>
  
  The `prompt-invisible-begin' and `prompt-invisible-end' functions
return the escape sequences that must used to mark the "invisible"
sections of the shell 'prompt' (such as various escape sequences). 

Node: Subsection 9-11-26,	Next: Subsection 9-11-27,	Prev: Subsection 9-11-25,	Up: Section 9-11
  

9.11.26   prompt-invisible
==========================

<<   $(prompt-invisible s) : Sequence
>>
  
  The `prompt-invisible' will wrap its argument with
`$(prompt-invisible-begin)' and `$(prompt-invisible-end)'. All the
`invisible" sections of the shell 'prompt' (such as various escape
sequences) must be wrapped this way. 

Node: Subsection 9-11-27,	Next: Chapter 10,	Prev: Subsection 9-11-26,	Up: Section 9-11
  

9.11.27   gettimeofday
======================

<<   $(gettimeofday) : Float
>>
  
  The `gettimeofday' function returns the time of day in seconds since
January 1, 1970.

Node: Chapter 10,	Next: Section 10-1,	Prev: Section 9-11,	Up: Top
  

Chapter 10     Shell commands
*****************************
    
  Shell commands (commands to be executed by the operating system) can
be freely mixed with other code.
  NOTE: the syntax and shell usage is identical on all platforms,
including Win32. To avoid portability problems on Win32, it is
recommended that you avoid the use of the native shell interpreter
`cmd'.
<<    LIB = $(dir lib)
      println(The contents of the $(LIB) directory is:)
      ls $(LIB)
>>
  
* Menu:

* Section 10-1::	Simple commands
* Section 10-2::	Globbing
* Section 10-3::	Background jobs
* Section 10-4::	File redirection
* Section 10-5::	Pipelines
* Section 10-6::	Conditional execution
* Section 10-7::	Grouping
* Section 10-8::	What is a shell command?
* Section 10-9::	Basic builtin functions
* Section 10-10::	Job control builtin functions
* Section 10-11::	Command history


Node: Section 10-1,	Next: Section 10-2,	Prev: Chapter 10,	Up: Chapter 10
  

10.1   Simple commands
*=*=*=*=*=*=*=*=*=*=*=

  
  The syntax of shell commands is similar to the syntax used by the Unix
shell `bash'. In general, a command is a pipeline. A basic command is
part of a pipeline. It is specified with the name of an executable and
some arguments. Here are some examples.
<<    ls
      ls -AF .
      echo Hello world
>>
  
  The command is found using the current search path in the variable
`PATH[]', which should define an array of directories containing
executables.
  A command may also be prefixed by environment variable definitions.
<<    # Prints "Hello world"
      env X="Hello world" Y=2 printenv X
      # Pass the include path to the Visual C++
      env include="c:\Program Files\Microsoft SDK\include" cl foo.cpp
>>
  

Node: Section 10-2,	Next: Section 10-3,	Prev: Section 10-1,	Up: Chapter 10
  

10.2   Globbing
*=*=*=*=*=*=*=*

  
  Commands may contain wildcard patterns. A pattern specifies a set of
files through a limited kind of regular expression. Patterns are
expanded before the function is executed.
<<   # List all files with a .c suffix
     ls *.c
  
     # List all files with a single character prefix, and .c suffix
     ls ?.c
  
     # Rename the file hello.ml to foo.ml
     mv {hello,foo}.ml
>>
  
  A comprehensive description of OMake glob patterns is given in Section
9.4*Note Section 9-4::.

Node: Section 10-3,	Next: Section 10-4,	Prev: Section 10-2,	Up: Chapter 10
  

10.3   Background jobs
*=*=*=*=*=*=*=*=*=*=*=

  
  The command may also be placed in the background by placing an
ampersand after the command. Control returns to the shell without
waiting for the job to complete. The job continues to run in the
background.
<<    gcc -o hugeprogram *.c &
>>
  

Node: Section 10-4,	Next: Section 10-5,	Prev: Section 10-3,	Up: Chapter 10
  

10.4   File redirection
*=*=*=*=*=*=*=*=*=*=*=*

  
  Input and output can be redirected to files by using the `<', `>', and
`>&' directives after the command.
<<    # Write to the "foo" file
      echo Hello world > foo
  
      # Redirect input from the foo file
      cat < foo
  
      # Redirect standard output and errors to the foo file
      gcc -o boo *.c >& foo
>>
  

Node: Section 10-5,	Next: Section 10-6,	Prev: Section 10-4,	Up: Chapter 10
  

10.5   Pipelines
*=*=*=*=*=*=*=*=

  
  Pipelines are sequences of commands, where the output from each
command is sent to the next. Pipelines are defined with the `|' and `|&'
syntax. With `|' the output is redirected, but errors are not. With `|&'
both output and errors are redirected.
<<   # Send the output of the ls command to the printer
     ls *.c | lpr
  
     # Send output and errors to jyh as email
     gcc -o hugefile *.c |& mail jyh
>>
  

Node: Section 10-6,	Next: Section 10-7,	Prev: Section 10-5,	Up: Chapter 10
  

10.6   Conditional execution
*=*=*=*=*=*=*=*=*=*=*=*=*=*=

  
  Commands may also be composed though conditional evaluation using the
`||' and `&&' syntax. Every command has an integer exit code, which may
be zero or some other integer. A command is said to succeed if its exit
code is zero. The expression `command1 && command2' executes `command2'
only if `command1' succeeds. The expression `command1 || command2'
executes `command2' only if `command1' fails.
<<   # Display the x/y file if possible
     cd x && cat y
  
     # Run foo.exe, or print an error message
     (test -x foo.exe && foo.exe) || echo "foo.exe is not executable"
>>
  

Node: Section 10-7,	Next: Section 10-8,	Prev: Section 10-6,	Up: Chapter 10
  

10.7   Grouping
*=*=*=*=*=*=*=*

  
  Parenthesis are used for grouping in a pipeline or conditional
command. In the following expression, the `test' function is used to
test whether the `foo.exe' file is executable. If it is, the `foo.exe'
file is executed. If the file is not executable (or if the `foo.exe'
command fails), the message `"foo.exe is not executable"' is printed.
<<   # Run foo.exe, or print an error message
     (test -x foo.exe && foo.exe) || echo "foo.exe is not executable"
>>
  

Node: Section 10-8,	Next: Section 10-9,	Prev: Section 10-7,	Up: Chapter 10
  

10.8   What is a shell command?
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

  
  Syntactially, shell commands are any line that is not one of the
following:
  
  
 - A variable definition of the form `VAR=string' 
 - A function call `f(...)' or method call `o.f(...)' 
 - A rule definition containing a colon `string: ...' 
 - A special command, including the following: 
     
    - `if ...' 
    - `switch ...' 
    - `match ...' 
    - `section ...' 
    - `return ...' 
  
  
  Commands may also be builtin (aliases). See the documentation for the
'Shell' object for more information.

Node: Section 10-9,	Next: Subsection 10-9-1,	Prev: Section 10-8,	Up: Chapter 10
  

10.9   Basic builtin functions
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

   
* Menu:

* Subsection 10-9-1::	echo
* Subsection 10-9-2::	cd


Node: Subsection 10-9-1,	Next: Subsection 10-9-2,	Prev: Section 10-9,	Up: Section 10-9
  

10.9.1   echo
=============

  The `echo' function prints a string.
<<$(echo <args>)
  echo <args>
>>

Node: Subsection 10-9-2,	Next: Section 10-10,	Prev: Subsection 10-9-1,	Up: Section 10-9
  

10.9.2   cd
===========

  The `cd' function changes the current directory.
<<    cd(dir)
         dir : Dir
>>
  
  The `cd' function also supports a 2-argument form:
<<    $(cd dir, e)
         dir : Dir
         e : expression
>>
  
  In the two-argument form, expression `e' is evaluated in the directory
`dir'. The current directory is not changed otherwise.
  The behavior of the `cd' function can be changed with the `CDPATH'
variable, which specifies a search path for directories. This is
normally useful only in the osh command interpreter.
<<    CDPATH : Dir Sequence
>>
  
  For example, the following will change directory to the first
directory `./foo', `~/dir1/foo', `~/dir2/foo'.
<<    CDPATH[] =
         .
         $(HOME)/dir1
         $(HOME)/dir2
      cd foo
>>
  

Node: Section 10-10,	Next: Subsection 10-10-1,	Prev: Section 10-9,	Up: Chapter 10
  

10.10   Job control builtin functions
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 10-10-1::	jobs
* Subsection 10-10-2::	bg
* Subsection 10-10-3::	fg
* Subsection 10-10-4::	stop
* Subsection 10-10-5::	wait
* Subsection 10-10-6::	kill


Node: Subsection 10-10-1,	Next: Subsection 10-10-2,	Prev: Section 10-10,	Up: Section 10-10
  

10.10.1   jobs
==============

  The `jobs' function prints a list of jobs.
  `jobs' 

Node: Subsection 10-10-2,	Next: Subsection 10-10-3,	Prev: Subsection 10-10-1,	Up: Section 10-10
  

10.10.2   bg
============

  The `bg' function places a job in the background.
  `bg <pid...>' 

Node: Subsection 10-10-3,	Next: Subsection 10-10-4,	Prev: Subsection 10-10-2,	Up: Section 10-10
  

10.10.3   fg
============

  The `fg' function brings a job to the foreground.
  `fg <pid...>' 

Node: Subsection 10-10-4,	Next: Subsection 10-10-5,	Prev: Subsection 10-10-3,	Up: Section 10-10
  

10.10.4   stop
==============

  The `stop' function suspends a job.
  `stop <pid...>' 

Node: Subsection 10-10-5,	Next: Subsection 10-10-6,	Prev: Subsection 10-10-4,	Up: Section 10-10
  

10.10.5   wait
==============

  The `wait' function waits for a job to finish. If no process
identifiers are given, the shell waits for all jobs to complete.
  `wait <pid...>' 

Node: Subsection 10-10-6,	Next: Section 10-11,	Prev: Subsection 10-10-5,	Up: Section 10-10
  

10.10.6   kill
==============

  The `kill' function signals a job.
  `kill [signal] <pid...>' 

Node: Section 10-11,	Next: Subsection 10-11-1,	Prev: Section 10-10,	Up: Chapter 10
  

10.11   Command history
*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 10-11-1::	history


Node: Subsection 10-11-1,	Next: Chapter 11,	Prev: Section 10-11,	Up: Section 10-11
  

10.11.1   history
=================

<<    $(history-index) : Int
      $(history) : String Sequence
      history-file : File
      history-length : Int
>>
  
  The history variables manage the command-line history in osh. They
have no effect in omake.
  The `history-index' variable is the current index into the
command-line history. The `history' variable is the current command-line
history.
  The `history-file' variable can be redefined if you want the
command-line history to be saved. The default value is
`~/.omake/osh_history'.
  The `history-length' variable can be redefined to specify the maximum
number of lines in the history that you want saved. The default value is
`100'.   

Node: Chapter 11,	Next: Section 11-1,	Prev: Section 10-11,	Up: Top
  

Chapter 11     The standard objects
***********************************
    
  `Pervasives' defines the objects that are defined in all programs. The
following objects are defined.
* Menu:

* Section 11-1::	Pervasives objects


Node: Section 11-1,	Next: Subsection 11-1-1,	Prev: Chapter 11,	Up: Chapter 11
  

11.1   Pervasives objects
*=*=*=*=*=*=*=*=*=*=*=*=*

  
* Menu:

* Subsection 11-1-1::	Object
* Subsection 11-1-2::	Map
* Subsection 11-1-3::	Number
* Subsection 11-1-4::	Int
* Subsection 11-1-5::	Float
* Subsection 11-1-6::	Sequence
* Subsection 11-1-7::	Array
* Subsection 11-1-8::	String
* Subsection 11-1-9::	Fun
* Subsection 11-1-10::	Rule
* Subsection 11-1-11::	Target
* Subsection 11-1-12::	Node
* Subsection 11-1-13::	File
* Subsection 11-1-14::	Dir
* Subsection 11-1-15::	Channel
* Subsection 11-1-16::	InChannel
* Subsection 11-1-17::	OutChannel
* Subsection 11-1-18::	Location
* Subsection 11-1-19::	Position
* Subsection 11-1-20::	Exception
* Subsection 11-1-21::	RuntimeException
* Subsection 11-1-22::	UnbuildableException
* Subsection 11-1-23::	Shell


Node: Subsection 11-1-1,	Next: Subsection 11-1-2,	Prev: Section 11-1,	Up: Section 11-1
  

11.1.1   Object
===============

  Parent objects: none.
  The `Object' object is the root object. Every class is a subclass of
`Object'.
  It provides the following fields:
  
  
 - `$(o.object-length)': the number of fields and methods in the object.
   
 - `$(o.object-mem <var>)': returns `true' iff the `<var>' is a field or
   method of the object. 
 - `$(o.object-add <var>, <value>)': adds the field to the object,
   returning a new object. 
 - `$(o.object-find <var>)': fetches the field or method from the
   object; it is equivalent to `$(o.<var>)', but the variable can be
   non-constant. 
 - `$(o.object-map <fun>)': maps a function over the object. The
   function should take two arguments; the first is a field name, the
   second is the value of that field. The result is a new object
   constructed from the values returned by the function. 
 - `o.object-foreach': the `object-foreach' form is equivalent to
   `object-map', but with altered syntax.
   <<   o.object-foreach(<var1>, <var2>)
           <body>
        >>
 
 For example, the following function prints all the fields of an object
   `o'.
   <<   PrintObject(o) =
           o.object-foreach(v, x)
              println($(v) = $(x))
        >>
 
 The `export' form is valid in a `object-foreach' body. The following
   function collects just the field names of an object.
   <<   FieldNames(o) =
           names[] =
           o.object-foreach(v, x)
              names[] += $(v)
              export
           return $(names)
        >>
  

Node: Subsection 11-1-2,	Next: Subsection 11-1-3,	Prev: Subsection 11-1-1,	Up: Section 11-1
  

11.1.2   Map
============

  Parent objects: `Object'.
  A `Map' object is a dictionary from values to values. The `<key>'
values are restricted to simple values: integers, floating-point
numbers, strings, files, directories, and arrays of simple values.
  The Map object provides the following methods.
  
  
 - `$(o.length)': the number of items in the map. 
 - `$(o.mem <key>)': returns `true' iff the `<key>' is defined in the
   map. 
 - `$(o.add <key>, <value>)': adds the field to the map, returning a new
   map. 
 - `$(o.find <key>)': fetches the field from the map. 
 - `$(o.keys)': fetches an array of all the keys in the map, in
   alphabetical order. 
 - `$(o.values)': fetches an array of all the values in the map, in the
   alphabetical order of the corresponding keys. 
 - `$(o.map <fun>)': maps a function over the map. The function should
   take two arguments; the first is a field name, the second is the
   value of that field. The result is a new object constructed from the
   values returned by the function. 
 - `o.foreach': the `foreach' form is equivalent to `map', but with
   altered syntax.
   <<   o.foreach(<var1>, <var2>)
           <body>
        >>
 
 For example, the following function prints all the fields of an object
   `o'.
   <<   PrintObject(o) =
           o.foreach(v, x)
              println($(v) = $(x))
        >>
 
 The `export' form is valid in a `foreach' body. The following function
   collects just the field names of the map.
   <<   FieldNames(o) =
           names =
           o.foreach(v, x)
              names += $(v)
              export
           return $(names)
        >>
  
  There is also simpler syntax when the key is a string. The table can
be defined using definitions with the form `$|key|' (the number of pipe
symbols `|' is allowed to vary).
<<    $|key 1| = value1
      $||key1|key2|| = value2    # The key is key1|key2
      X = $|key 1|               # Define X to be the value of field
$|key 1|
>>
  
  The usual modifiers are also allowed. The expression `$`|key|'
represents lazy evaluation of the key, and `$,|key|' is normal
evaluation.

Node: Subsection 11-1-3,	Next: Subsection 11-1-4,	Prev: Subsection 11-1-2,	Up: Section 11-1
  

11.1.3   Number
===============

  Parent objects: `Object'.
  The `Number' object is the parent object for integers and
floating-point numbers. 

Node: Subsection 11-1-4,	Next: Subsection 11-1-5,	Prev: Subsection 11-1-3,	Up: Section 11-1
  

11.1.4   Int
============

  Parent objects: `Number'.
  The `Int' object represents integer values. 

Node: Subsection 11-1-5,	Next: Subsection 11-1-6,	Prev: Subsection 11-1-4,	Up: Section 11-1
  

11.1.5   Float
==============

  Parent objects: `Number'.
  The `Float' object represents floating-point numbers. 

Node: Subsection 11-1-6,	Next: Subsection 11-1-7,	Prev: Subsection 11-1-5,	Up: Section 11-1
  

11.1.6   Sequence
=================

  Parent objects: `Object'.
  The `Sequence' object represents a generic object containing
sequential elements. It provides the following methods.
  
  
 - `$(s.length)': the number of elements in the sequence. 
 - `$(s.map <fun>)': maps a function over the fields in the sequence.
   The function should take one argument. The result is a new sequence
   constructed from the values returned by the function. 
 - `s.foreach': the `foreach' form is equivalent to `map', but with
   altered syntax.
   <<   s.foreach(<var>)
           <body>
        >>
 
 For example, the following function prints all the elements of the
   sequence.
   <<   PrintSequence(s) =
           s.foreach(x)
              println(Elem = $(x))
        >>
 
 The `export' form is valid in a `foreach' body. The following function
   counts the number of zeros in the sequence.
   <<   Zeros(s) =
           count = $(int 0)
           s.foreach(v)
              if $(equal $(v), 0)
                 count = $(add $(count), 1)
                 export
              export
           return $(count)
        >>
   

Node: Subsection 11-1-7,	Next: Subsection 11-1-8,	Prev: Subsection 11-1-6,	Up: Section 11-1
  

11.1.7   Array
==============

  Parent objects: `Sequence'.
  The `Array' is a random-access sequence. It provides the following
additional methods.
  
  
 - `$(s.nth <i>)': returns element `i' of the sequence. 
 - `$(s.rev <i>)': returns the reversed sequence. 
  

Node: Subsection 11-1-8,	Next: Subsection 11-1-9,	Prev: Subsection 11-1-7,	Up: Section 11-1
  

11.1.8   String
===============

  Parent objects: `Array'. 

Node: Subsection 11-1-9,	Next: Subsection 11-1-10,	Prev: Subsection 11-1-8,	Up: Section 11-1
  

11.1.9   Fun
============

  Parent objects: `Object'.
  The `Fun' object provides the following methods. 
  
 - `$(f.arity)': the arity if the function. 
   

Node: Subsection 11-1-10,	Next: Subsection 11-1-11,	Prev: Subsection 11-1-9,	Up: Section 11-1
  

11.1.10   Rule
==============

  Parent objects: `Object'.
  The `Rule' object represents a build rule. It does not currently have
any methods. 

Node: Subsection 11-1-11,	Next: Subsection 11-1-12,	Prev: Subsection 11-1-10,	Up: Section 11-1
  

11.1.11   Target
================

  Parent object: `Object'.
  The `Target' object contains information collected for a specific
target file.
  
  
 - `target': the target file. 
 - `effects': the files that may be modified by a side-effect when this
   target is built. 
 - `scanner_deps': static dependencies that must be built before this
   target can be scanned. 
 - `static-deps': statically-defined build dependencies of this target. 
 - `build-deps': all the build dependencies for the target, including
   static and scanned dependencies. 
 - `build-values': all the value dependencies associated with the build.
   
 - `build-commands': the commands to build the target. 
 - `output-file': if output was diverted to a file, with one of the
   `--output-*' options A*Note Appendix A::, this field names
   that file. Otherwise it is `false'. 
  
  The object supports the following methods.
  
  
 - `find(file)': returns a Target object for the given file. Raises a
   `RuntimeException' if the specified target is not part of the
   project. 
 - `find-optional(file)': returns a `Target' object for the given file,
   or `false' if the file is not part of the project. 
  
  NOTE: the information for a target is constructed dynamically, so it
is possible that the `Target' object for a node will contain different
values in different contexts. The easiest way to make sure that the
`Target' information is complete is to compute it within a rule body,
where the rule depends on the target file, or the dependencies of the
target file. 

Node: Subsection 11-1-12,	Next: Subsection 11-1-13,	Prev: Subsection 11-1-11,	Up: Section 11-1
  

11.1.12   Node
==============

  Parent objects: `Object'.
  The `Node' object is the parent object for files and directories. It
supports the following operations. 
  
 - `$(node.stat)': returns a `stat' object for the file. If the file is
   a symbolic link, the `stat' information is for the destination of the
   link, not the link itself.
 
 - `$(node.lstat)': returns a `stat' object for the file or symbolic
   link. 
 - `$(node.unlink)': removes the file. 
 - `$(node.rename <file>)': renames the file. 
 - `$(node.link <file>)': creates a hard link `<dst>' to this file. 
 - `$(node.symlink <file>)': create a symbolic link `<dst>' to this
   file. 
 - `$(node.chmod <perm>)': change the permission of this file. 
 - `$(node.chown <uid>, <gid>)': change the owner and group id of this
   file. 
   

Node: Subsection 11-1-13,	Next: Subsection 11-1-14,	Prev: Subsection 11-1-12,	Up: Section 11-1
  

11.1.13   File
==============

  Parent objects: `Node'.
  The file object represents the name of a file. 

Node: Subsection 11-1-14,	Next: Subsection 11-1-15,	Prev: Subsection 11-1-13,	Up: Section 11-1
  

11.1.14   Dir
=============

  Parent objects: `Node'.
  The `Dir' object represents the name of a directory. 

Node: Subsection 11-1-15,	Next: Subsection 11-1-16,	Prev: Subsection 11-1-14,	Up: Section 11-1
  

11.1.15   Channel
=================

  Parent objects: `Object'.
  A `Channel' is a generic IO channel. It provides the following
methods. 
  
 - `$(o.close)': close the channel. 
   

Node: Subsection 11-1-16,	Next: Subsection 11-1-17,	Prev: Subsection 11-1-15,	Up: Section 11-1
  

11.1.16   InChannel
===================

  Parent objects: `Channel'.
  A `InChannel' is an input channel. The variable `stdin' is the
standard input channel.
  It provides the following methods. 
  
 - `$(InChannel.fopen <file>)': open a new input channel. 
 - `$(InChannel.of-string <string>)': open a new input channel, using a
   string as input. 
   

Node: Subsection 11-1-17,	Next: Subsection 11-1-18,	Prev: Subsection 11-1-16,	Up: Section 11-1
  

11.1.17   OutChannel
====================

  Parent object: `Channel'.
  A `OutChannel' is an output channel. The variables `stdout' and
`stderr' are the standard output and error channels.
  It provides the following methods. 
  
 - `$(OutChannel.fopen <file>)': open a new output channel. 
 - `$(OutChannel.string)': open a new output channel, writing to a
   string. 
 - `$(OutChannel.to-string)': get the current string of output, for an
   output channel created as `OutChannel.open-string'. 
 - `$(OutChannel.append <file>)': opens a new output channel, appending
   to the file. 
 - `$(c.flush)': flush the output channel. 
 - `$(c.print <string>)': print a string to the channel. 
 - `$(c.println <string>)': print a string to the channel, followed by a
   line terminator. 
   

Node: Subsection 11-1-18,	Next: Subsection 11-1-19,	Prev: Subsection 11-1-17,	Up: Section 11-1
  

11.1.18   Location
==================

  Parent objects: `Location'.
  The `Location' object represents a location in a file. 

Node: Subsection 11-1-19,	Next: Subsection 11-1-20,	Prev: Subsection 11-1-18,	Up: Section 11-1
  

11.1.19   Position
==================

  Parent objects: `Position'.
  The `Position' object represents a stack trace. 

Node: Subsection 11-1-20,	Next: Subsection 11-1-21,	Prev: Subsection 11-1-19,	Up: Section 11-1
  

11.1.20   Exception
===================

  Parent objects: `Object'.
  The `Exception' object is used as the base object for exceptions. It
has no fields. 

Node: Subsection 11-1-21,	Next: Subsection 11-1-22,	Prev: Subsection 11-1-20,	Up: Section 11-1
  

11.1.21   RuntimeException
==========================

  Parent objects: `Exception'.
  The `RuntimeException' object represents an exception from the runtime
system. It has the following fields.
  
  
 - `position': a string representing the location where the exception
   was raised. 
 - `message': a string containing the exception message. 
   

Node: Subsection 11-1-22,	Next: Subsection 11-1-23,	Prev: Subsection 11-1-21,	Up: Section 11-1
  

11.1.22   UnbuildableException
==============================

  Parent objects: `Exception'.
  The `UnbuildableException' object should be used to signal that a
target is not buildable. It will be caught by functions such as
'target-exists'. This exception has the following fields:
  
  
 - `target': indicates which target is not buildable. 
 - `message': a string containing the exception message. 
   

Node: Subsection 11-1-23,	Next: Chapter 12,	Prev: Subsection 11-1-22,	Up: Section 11-1
  

11.1.23   Shell
===============

  Parent objects: `Object'.
  The `Shell' object contains the collection of builtin functions
available as shell commands.
  You can define aliases by extending this object with additional
methods. All methods in this class are called with one argument: a
single array containing an argument list.
  
  
 - `echo'
 The `echo' function prints its arguments to the standard output
   channel. 
 - `jobs'
 The `jobs' method prints the status of currently running commands. 
 - `cd'
 The `cd' function changes the current directory. Note that the current
   directory follows the usual scoping rules. For example, the following
   program lists the files in the `foo' directory, but the current
   directory is not changed.
   <<   section
           echo Listing files in the foo directory...
           cd foo
           ls
     
        echo Listing files in the current directory...
        ls
   >>
 
 - `bg'
 The `bg' method places a job in the background. The job is resumed if
   it has been suspended. 
 - `fg'
 The `fg' method brings a job to the foreground. The job is resumed if
   it has been suspended. 
 - `stop'
 The `stop' method suspends a running job. 
 - `wait'
 The `wait' function waits for a running job to terminate. It is not
   possible to wait for a suspended job.
 The job is not brought to the foreground. If the `wait' is interrupted,
   the job continues to run in the background. 
 - `kill'
 The `kill' function signal a job.
 `kill [signal] <pid...>'.
 The signals are either numeric, or symbolic. The symbolic signals are
   named as follows.
 ABRT, ALRM, HUP, ILL, KILL, QUIT, SEGV, TERM, USR1, USR2, CHLD, STOP,
   TSTP, TTIN, TTOU, VTALRM, PROF. 
 - `exit'
 The `exit' function terminates the current session. 
 - `which', `where'
 See the documentation for the corresponding functions. 
 - `rehash'
 Reset the search path. 
 - `ln-or-cp' src dst
 Links or copies src to dst, overwriting dst. Namely, `ln-or-cp' would
   first delete the dst file (unless it is a directory), if it exists.
   Next it would try to create a symbolic link dst poiting to src (it
   will make all the necessary adjustmnents of relative paths). If
   symbolic link can not be created (e.g. the OS or the filesystem does
   not support symbolic links), it will try to create a hard link. If
   that fails too, it will try to forcibly copy src to dst. 
 - `history'
 Print the current command-line history. 
 - `digest'
 Print the digests of the given files. 
 - Win32 functions.
 Win32 doesn't provide very many programs for scripting, except for the
   functions that are builtin to the DOS `cmd.exe'. The following
   functions are defined on Win32 and only on Win32. On other systems,
   it is expected that these programs already exist.
 
     
    - `grep'
      <<   grep [-q] [-n] pattern files...
      >>
    
    The `grep' function calls the omake `grep' function. 
  
 - Internal versions of standard system commands.
 By default, omake uses internal versions of the following commands:
   `cp', `mv', `cat', `rm', `mkdir', `chmod', `test', `find'. If you
   really want to use the standard system versions of these commands,
   set the `USE_SYSTEM_COMMANDS' as one of the first definitions in your
   `OMakeroot' file.
 
     
    - `mkdir'
      <<    mkdir [-m <mode>] [-p] files
      >>
    
    The `mkdir' function is used to create directories. The -verb+-m+
      option can be used to specify the permission mode of the created
      directory. If the `-p' option is specified, the full path is
      created. 
    - `cp' 
    - `mv'
      <<    cp [-f] [-i] [-v] src dst
            cp [-f] [-i] [-v] files dst
            mv [-f] [-i] [-v] src dst
            mv [-f] [-i] [-v] files dst
      >>
    
    The `cp' function copies a `src' file to a `dst' file, overwriting
      it if it already exists. If more than one source file is
      specified, the final file must be a directory, and the source
      files are copied into the directory.
    
        
       -f  Copy files forcibly, do not prompt. 
       -i  Prompt before removing destination files. 
       -v  Explain what is happening. 
     
    - `rm'
      <<   rm [-f] [-i] [-v] [-r] files
           rmdir [-f] [-i] [-v] [-r] dirs
      >>
    
    The `rm' function removes a set of files. No warnings are issued if
      the files do not exist, or if they cannot be removed.
    Options: 
        
       -f  Forcibly remove files, do not prompt. 
       -i  Prompt before removal. 
       -v  Explain what is happening. 
       -r  Remove contents of directories recursively. 
     
    - `chmod'
      <<    chmod [-r] [-v] [-f] mode files
      >>
    
    The `chmod' function changes the permissions on a set of files or
      directories. This function does nothing on Win32. The `mode' may
      be specified as an octal number, or in symbolic form
      `[ugoa]*['-=][rwxXstugo]+. See the man page for `chmod' for
      details.
    Options: 
        
       -r  Change permissions of all files in a directory recursively. 
       -v  Explain what is happening. 
       -f  Continue on errors. 
     
    - `cat'
      <<   cat files...
      >>
    
    The `cat' function prints the contents of the files to stdout 
    - `test'
    `test' expression
     `[' expression +]+
     `[ --help'
     `[ --version'
     See the documentation for the 'test' function.
    
    - `find'
      <<   find \emph{expression}
      >>
    
    See the documentation for the 'find' function.