This file has been translated from LaTeX by HeVeA.

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

9.3.5   file-sort
=================
 

<<   $(file-sort order, files) : File Sequence
        order : String
        files : File Sequence
>>
  
The `file-sort' function
sorts a list of filenames by build order augmented by a set of sort
rules. Sort rules are declared using the `.ORDER' target. The
`.BUILDORDER' defines the default order.
  `$(file-sort <order>, <files>)'
  For example, suppose we have the following set of rules.
<<   a: b c
     b: d
     c: d
  
     .DEFAULT: a b c d
        echo $(file-sort .BUILDORDER, a b c d)
>>
  
  In the case, the sorter produces the result `d b c a'. That is, a
target is sorted after its dependencies. The sorter is frequently used
to sort files that are to be linked by their dependencies (for languages
where this matters).
  There are three important restrictions to the sorter: 
  
 - The sorter can be used only within a rule body. The reason for this
   is that all dependencies must be known before the sort is performed. 
 - The sorter can only sort files that are buildable in the current
   project. 
 - The sorter will fail if the dependencies are cyclic. 
  
  

9.3.5.1   sort rule
-------------------
  
  It is possible to further constrain the sorter through the use of sort
rules. A sort rule is declared in two steps. The target must be listed
as an `.ORDER' target; and then a set of sort rules must be given. A
sort rule defines a pattern constraint.
<<   .ORDER: .MYORDER
  
     .MYORDER: %.foo: %.bar
     .MYORDER: %.bar: %.baz
  
     .DEFAULT: a.foo b.bar c.baz d.baz
        echo $(sort .MYORDER, a.foo b.bar c.baz d.baz)
>>
  
  In this example, the `.MYORDER' sort rule specifies that any file with
a suffix `.foo' should be placed after any file with suffix `.bar', and
any file with suffix `.bar' should be placed after a file with suffix
`.baz'.
  In this example, the result of the sort is `d.baz c.baz b.bar a.foo'. 

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

9.3.6   file-check-sort
=======================

<<   file-check-sort(files)
        files : File Sequence
     raises RuntimeException
>>
  
  The `file-check-sort' function checks whether a list of files is in
sort order. If so, the list is returned unchanged. If not, the function
raises an exception.
  `$(file-check-sort <order>, <files>)' 

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

9.4   Globbing and file listings
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

   
  OMake commands are "glob-expanded" before being executed. That is,
names may contain patterns that are expanded to sequences of file and
directory names. The syntax follows the standard bash(1), csh(1),
syntax, with the following rules.
  
  
 - A pathname is a sequence of directory and file names separated by one
   of the `/' or `\' characters. For example, the following pathnames
   refer to the same file: `/home/jyh/OMakefile' and
   `/home\jyh/OMakefile'.
 
 - Glob-expansion is performed on the components of a path. If a path
   contains occurrences of special characters (listed below), the path
   is viewed as a pattern to be matched against the actual files in the
   system. The expansion produces a sequence of all file/directory names
   that match.
 For the following examples, suppose that a directory `/dir' contains
   files named `a', `-a', `a.b', and `b.c'.
 
     
    *  Matches any sequence of zero-or-more characters. For example, the
      pattern `/dir/a*' expands to `/dir/a /dir/aa /dir/a.b'.
    
    ?  Matches exactly one character. The pattern `/dir/?a' expands the
      filename `/dir/-a'.
    
    [...]  Square brackets denote character sets and ranges in the ASCII
      character set. The pattern may contain individual characters c or
      character ranges c_1-c_2. The pattern matches any of the
      individual characters specified, or any characters in the range. A
      leading "hat" inverts the send of the pattern. To specify a
      pattern that contains the literal characters `-', the `-' should
      occur as the first character in the range.
                                        
              Pattern        Expansion                          
             ---------------------------------------------------
              `/dir/[a-b]*'  `/dir/a /dir/a.b /dir/b.c'         
              `/dir/[-a-b]*' `/dir/a /dir/-a /dir/a.b /dir/b.c' 
              `/dir/[-a]*'   `/dir/a /dir/-a /dir/a.b'          
                                        
    
    
    {s1,...,sN}  Braces indicate brace-expansion. The braces delimit a
      sequence of strings separated by commas. Given N strings, the
      result produces N copies of the pattern, one for each of the
      strings s_i.
                                        
                      Pattern           Expansion        
                     ------------------------------------
                      `a{b,c,d}'        `ab ac ad'       
                      `a{b{c,d},e}'     `abc abd ae'     
                      `a{?{[A-Z],d},*}' `a?[A-Z] a?d a*' 
                                        
    
    
       The tilde is used to specify home directories. Depending on your
      system, these might be possible expansions.
                                        
               Pattern    Expansion                             
              --------------------------------------------------
               `~jyh'     `/home/jyh'                           
               `~bob/*.c' `c:\Documents and Settings\users\bob' 
                                        
    
    
    
      The `\' character is both a pathname separator and an escape
      character. If followed by a special glob character, the `\'
      changes the sense of the following character to non-special
      status. Otherwise, `\' is viewed as a pathname separator.
                                        
       Pattern                  Expansion                               
                                           
      ------------------------------------------------------------------
                                  ---------
       `~jyh/\*'                `~jyh/*' (`*' is literal)               
                                           
        `/dir/\[a-z?'            `/dir/[a-z?' (`[' is literal, `?' is a
                                  pattern). 
       `c:\Program Files\[A-z]' `c:\Program Files[A-z]*'                
                                           
                                        
    
    Note that the final case might be considered to be ambiguous (where
      `\' should be viewed as a pathname separator, not as an escape for
      the subsequent `[' character. If you want to avoid this ambiguity
      on Win32, you should use the forward slash `/' even for Win32
      pathnames (the `/' is translated to `\' in the output).
                                        
        Pattern                   Expansion                            
       ----------------------------------------------------------------
        `c:/Program Files/[A-z]*' `c:\Program Files\WindowsUpdate ...' 
                                        
     
  
  
* Menu:

* Subsection 9-4-1::	glob
* Subsection 9-4-2::	ls
* Subsection 9-4-3::	subdirs


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

9.4.1   glob
============

<<   $(glob strings) : Node Array
        strings : String Sequence
     $(glob options, strings) : Node Array
        options : String
        strings : String Sequence
>>
  
  The `glob' function performs glob-expansion.
  The . and .. entries are always ignored.
  The options are: 
  
 b  Do not perform csh(1)-style brace expansion. 
 e  The `\' character does not escape special characters. 
 n  If an expansion fails, return the expansion literally instead of
   aborting. 
 i  If an expansion fails, it expands to nothing. 
 .  Allow wildcard patterns to match files beginning with a . 
 A  Return all files, including files that begin with a . 
 F  Match only normal files (any file that is not a directory). 
 D  Match only directory files. 
 C  Ignore files according to cvs(1) rules. 
 P  Include only proper subdirectories. 
  
  In addition, the following variables may be defined that affect the
behavior of `glob'.
  
  
 GLOB_OPTIONS  A string containing default options. 
 GLOB_IGNORE  A list of shell patterns for filenames that `glob' should
   ignore. 
 GLOB_ALLOW  A list of shell patterns. If a file does not match a
   pattern in `GLOB_ALLOW', it is ignored. 
  
  The returned files are sorted by name. 

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

9.4.2   ls
==========

<<   $(ls files) : Node Array
        files : String Sequence
     $(ls options, files) : Node Array
        files : String Sequence
>>
  
  The `ls' function returns the filenames in a directory.
  The . and .. entries are always ignored. The patterns are shell-style
patterns, and are glob-expanded.
  The options include all of the options to the `glob' function, plus
the following.
  
  
 R  Perform a recursive listing. 
  
  The `GLOB_ALLOW' and `GLOB_IGNORE' variables can be defined to control
the globbing behavior. The returned files are sorted by name. 

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

9.4.3   subdirs
===============

<<   $(subdirs dirs) : Dir Array
        dirs : String Sequence
     $(subdirs options, dirs) : Dir Array
        options : String
        dirs : String Sequence
>>
  
  The `subdirs' function returns all the subdirectories of a list of
directories, recursively.
  The possible options are the following: 
  
 A  Return directories that begin with a . 
 C  Ignore files according to .cvsignore rules. 
 P  Include only proper subdirectories. 
   

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

9.5   Filesystem operations
*=*=*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 9-5-1::	mkdir
* Subsection 9-5-2::	Stat
* Subsection 9-5-3::	stat, lstat
* Subsection 9-5-4::	unlink
* Subsection 9-5-5::	rename
* Subsection 9-5-6::	link
* Subsection 9-5-7::	symlink
* Subsection 9-5-8::	readlink
* Subsection 9-5-9::	chmod
* Subsection 9-5-10::	chown
* Subsection 9-5-11::	truncate
* Subsection 9-5-12::	umask


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

9.5.1   mkdir
=============

<<   mkdir(mode, node...)
        mode : Int
        node : Node
     raises RuntimeException
  
     mkdir(node...)
        node : Node
     raises RuntimeException
>>
  
  The `mkdir' function creates a directory, or a set of directories. The
following options are supported. 
  
 -m mode  Specify the permissions of the created directory. 
 -p  Create parent directories if they do not exist. 
 --  Interpret the remaining names literally. 
   

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

9.5.2   Stat
============

  The `Stat' object represents an information about a filesystem node,
as returned by the `stat' and `lstat' functions.  It contains the
following fields.
  
  
 dev : the device number. 
 ino : the inode number. 
 kind : the kind of the file, one of the following: `REG' (regular
   file), `DIR' (directory), `CHR' (character device), `BLK' (block
   device), `LNK' (symbolic link), `FIFO' (named pipe), `SOCK' (socket).
   
 perm : access rights, represented as an integer. 
 nlink : number of links. 
 uid : user id of the owner. 
 gid : group id of the file's group. 
 rdev : device minor number. 
 size : size in bytes. 
 atime : last access time, as a floating point number. 
 mtime : last modification time, as a floating point number. 
 ctime : last status change time, as a floating point number. 
  
  Not all of the fields will have meaning on all operating systems.

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

9.5.3   stat, lstat
===================

<<    $(stat node...) : Stat
         node : Node or Channel
      $(lstat node...) : Stat
         node : Node or Channel
      raises RuntimeException
>>
  
  The `stat' functions return file information. If the file is a
symbolic link, the `stat' function refers to the destination of the
link; the `lstat' function refers to the link itself. 

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

9.5.4   unlink
==============

<<   $(unlink file...)
        file : File
     #(rm file...)
        file : File
     $(rmdir dir...)
        dir : Dir
     raises RuntimeException
>>
  
  The `unlink' and `rm' functions remove a file. The `rmdir' function
removes a directory.
  The following options are supported for `rm' and `rmdir'. 
  
 -f  ignore nonexistent files, never prompt. 
 -i  prompt before removal. 
 -r  remove the contents of directories recursively. 
 -v  explain what is going on. 
 --  the rest of the values are interpreted literally. 
   

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

9.5.5   rename
==============

<<    rename(old, new)
         old : Node
         new : Node
      mv(nodes... dir)
         nodes : Node Sequence
         dir   : Dir
      cp(nodes... dir)
         nodes : Node Sequence
         dir   : Dir
      raises RuntimeException
>>
  
  The `rename' function changes the name of a file or directory named
`old' to `new'.
  The `mv' function is similar, but if `new' is a directory, and it
exists, then the files specified by the sequence are moved into the
directory. If not, the behavior of `mv' is identical to `rename'. The
`cp' function is similar, but the original file is not removed.
  The `mv' and `cp' functions take the following options. 
  
 -f  Do not prompt before overwriting. 
 -i  Prompt before overwriting. 
 -v  Explain what it happening. 
 -r  Copy the contents of directories recursively. 
 --  Interpret the remaining arguments literally. 
   

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

9.5.6   link
============

<<   link(src, dst)
        src : Node
        dst : Node
     raises RuntimeException
>>
  
  The `link' function creates a hard link named `dst' to the file or
directory `src'.
  Hard links may work under Win32 when NTFS is used.
  Normally, only the superuser can create hard links to directories. 

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

9.5.7   symlink
===============

<<   symlink(src, dst)
        src : Node
        dst : Node
     raises RuntimeException
>>
  
  The `symlink' function creates a symbolic link `dst' that points to
the `src' file.
  The link name is computed relative to the target directory. For
example, the expression `$(symlink a/b, c/d)' creates a link named `c/d
-> ../a/b'.
  Symbolic links are not supported in Win32. Consider using the
`ln-or-cp' `Shell' alias for cross-platform portable linking/copying. 

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

9.5.8   readlink
================

<<   $(readlink node...) : Node
        node : Node
>>
  
  The `readlink' function reads the value of a symbolic link. 

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

9.5.9   chmod
=============

<<   chmod(mode, dst...)
        mode : Int
        dst : Node or Channel
     chmod(mode dst...)
        mode : String
        dst : Node Sequence
     raises RuntimeException
>>
  
  The `chmod' function changes the permissions of the targets.
  Options: 
  
 -v  Explain what is happening. 
 -r  Change files and directories recursively. 
 -f  Continue on errors. 
 --  Interpret the remaining argument literally. 
   

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

9.5.10   chown
==============

<<   chown(uid, gid, node...)
        uid : Int
        gid : Int
        node : Node or Channel
     chown(uid, node...)
        uid : Int
        node : Node or Channel
     raises RuntimeException
>>
  
  The `chown' function changes the user and group id of the file. If the
`gid' is not specified, it is not changed. If either id is -1, that id
is not changed. 

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

9.5.11   truncate
=================

<<   truncate(length, node...)
         length : Int
         node : Node or Channel
     raises RuntimeException
>>
  
  The `truncate' function truncates a file to the given length. 

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

9.5.12   umask
==============

<<    $(umask mode) : Int
         mode : Int
      raises RuntimeException
>>
  
  Sets the file mode creation mask. The previous mask is returned. This
value is not scoped, changes have global effect. 

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

9.6   vmount
*=*=*=*=*=*=

   
* Menu:

* Subsection 9-6-1::	vmount
* Subsection 9-6-2::	add-project-directories
* Subsection 9-6-3::	remove-project-directories


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

9.6.1   vmount
==============

<<    vmount(src, dst)
         src, dst : Dir
      vmount(flags, src, dst)
         flags : String
         src, dst : Dir
>>
  
  "Mount" the `src' directory on the `dst' directory. This is a virtual
mount, changing the behavior of the `$(file ...)' function. When the
`$(file str)' function is used, the resulting file is taken relative to
the `src' directory if the file exists. Otherwise, the file is relative
to the current directory.
  The main purpose of the `vmount' function is to support multiple
builds with separate configurations or architectures.
  The options are as follows. 
  
 l  Create symbolic links to files in the `src' directory. 
 c  Copy files from the `src' directory. 
  
  Mount operations are scoped. 

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

9.6.2   add-project-directories
===============================

<<    add-project-directories(dirs)
         dirs : Dir Array
>>
  
  Add the directories to the set of directories that omake considers to
be part of the project. This is mainly used to avoid omake complaining
that the current directory is not part of the project. 

Node: Subsection 9-6-3,	Next: Section 9-7,	Prev: Subsection 9-6-2,	Up: Section 9-6
  

9.6.3   remove-project-directories
==================================

<<    remove-project-directories(dirs)
         dirs : Dir Array
>>
  
  Removed the directories from the set of directories that omake
considers to be part of the project. This is mainly used to cancel a
`.SUBDIRS' from including a directory if it is determined that the
directory does not need to be compiled. 

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

9.7   File predicates
*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 9-7-1::	test
* Subsection 9-7-2::	find


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

9.7.1   test
============

<<   test(exp) : Bool
        exp : String Sequence
>>
  
  The expression grammar is as follows:
  
  
 - `!' expression : expression is not true 
 - expression1 `-a' expression2 : both expressions are true 
 - expression1 `-o' expression2 : at least one expression is true 
 - `(' expression `)' : expression is true 
  
  The base expressions are:
  
  
 - `-n' string : The string has nonzero length 
 - `-z' string : The string has zero length 
 - string `=' string : The strings are equal 
 - string `!=' string : The strings are not equal
 
 - int1 `-eq' int2 : The integers are equal 
 - int1 `-ne' int2 : The integers are not equal 
 - int1 `-gt' int2 : int1 is larger than int2 
 - int1 `-ge' int2 : int2 is not larger than int1 
 - int1 `-lt' int2 : int1 is smaller than int2 
 - int1 `-le' int2 : int1 is not larger than int2
 
 - file1 `-ef' file2 : On Unix, file1 and file2 have the same device and
   inode number. On Win32, file1 and file2 have the same name. 
 - file1 `-nt' file2 : file1 is newer than file2 
 - file1 `-ot' file2 : file1 is older than file2
 
 - `-b' file : The file is a block special file 
 - `-c' file : The file is a character special file 
 - `-d' file : The file is a directory 
 - `-e' file : The file exists 
 - `-f' file : The file is a normal file 
 - `-g' file : The set`-group'`-id' bit is set on the file 
 - `-G' file : The file's group is the current effective group 
 - `-h' file : The file is a symbolic link (also `-L') 
 - `-k' file : The file's sticky bit is set 
 - `-L' file : The file is a symbolic link (also `-h') 
 - `-O' file : The file's owner is the current effective user 
 - `-p' file : The file is a named pipe 
 - `-r' file : The file is readable 
 - `-s' file : The file is empty 
 - `-S' file : The file is a socket 
 - `-u' file : The set`-user'`-id' bit is set on the file 
 - `-w' file : The file is writable 
 - `-x' file : The file is executable 
  
  A string is any sequence of characters; leading `-' characters are
allowed.
  An int is a string that can be interpreted as an integer. Unlike
traditional versions of the test program, the leading characters may
specify an arity. The prefix `0b' means the numbers is in binary; the
prefix `0o' means the number is in octal; the prefix `0x' means the
number is in hexadecimal. An int can also be specified as `-l' string,
which evaluates to the length of the string.
  A file is a string that represents the name of a file.
  The syntax mirrors that of the test(1) program. If you are on a Unix
system, the man page explains more. Here are some examples.
<<    # Create an empty file
      osh> touch foo
      # Is the file empty?
      osh> test(-e foo)
      - : true
      osh> test(! -e foo)
      - : false
      # Create another file
      osh> touch boo
      # Is the newer file newer?
      osh> test(boo -nt foo)
      - : true
      # A more complex query
      # boo is newer than foo, and foo is empty
      osh> test(\( boo -nt foo \) -a -e foo)
      - : true
>>

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

9.7.2   find
============

<<   find(exp) : Node Array
        exp : String Sequence
>>
  
  The `find' function searches a directory recursively, returning the
files for which the expression evaluates to true.
  The expression argument uses the same syntax as the `test' function,
with the following exceptions.
  
  
 1. The expression may begin with a directory. If not specified, the
   current directory is searched. 
 2. The `{}' string expands to the current file being examined. 
  
  The syntax of the expression is the same as `test', with the following
additions.
  
  
 - `-name' string : The current file matches the glob expression (see
   Section 9.4*Note Section 9-4::). 
  
  The `find' function performs a recursive scan of all subdirectories.
The following call is being run from the root of the `omake' source
directory.
<<    osh> find(. -name fo* )
      - : <array
              /home/jyh/.../omake/mk/.svn/format
              /home/jyh/.../omake/RPM/.svn/format
              ...
             
/home/jyh/.../omake/osx_resources/installer_files/.svn/format>
>>
  
  Another example, listing only those files that are normal files or
symbolic links.
<<    osh> find(. -name fo* -a \( -f {} -o -L {} \))
      - : <array
              /home/jyh/.../omake/mk/.svn/format
              /home/jyh/.../omake/RPM/.svn/format
              ...
             
/home/jyh/.../omake/osx_resources/installer_files/.svn/format>
>>
   

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

9.8   IO functions
*=*=*=*=*=*=*=*=*=

   
* Menu:

* Subsection 9-8-1::	Standard channels
* Subsection 9-8-2::	open-in-string
* Subsection 9-8-3::	open-out-string, out-string
* Subsection 9-8-4::	fopen
* Subsection 9-8-5::	close
* Subsection 9-8-6::	read
* Subsection 9-8-7::	write
* Subsection 9-8-8::	lseek
* Subsection 9-8-9::	rewind
* Subsection 9-8-10::	tell
* Subsection 9-8-11::	flush
* Subsection 9-8-12::	dup
* Subsection 9-8-13::	dup2
* Subsection 9-8-14::	set-nonblock
* Subsection 9-8-15::	set-close-on-exec-mode
* Subsection 9-8-16::	pipe
* Subsection 9-8-17::	mkfifo
* Subsection 9-8-18::	select
* Subsection 9-8-19::	lockf
* Subsection 9-8-20::	InetAddr
* Subsection 9-8-21::	Host
* Subsection 9-8-22::	gethostbyname
* Subsection 9-8-23::	Protocol
* Subsection 9-8-24::	getprotobyname
* Subsection 9-8-25::	Service
* Subsection 9-8-26::	getservbyname
* Subsection 9-8-27::	socket
* Subsection 9-8-28::	bind
* Subsection 9-8-29::	listen
* Subsection 9-8-30::	accept
* Subsection 9-8-31::	connect
* Subsection 9-8-32::	getchar
* Subsection 9-8-33::	gets
* Subsection 9-8-34::	fgets


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

9.8.1   Standard channels
=========================
  
  The following variables define the standard channels.
 stdin

<<stdin : InChannel
>>
  
  The standard input channel, open for reading.
 stdout
 
<<stdout : OutChannel
>>
  
  The standard output channel, open for writing.
 stderr
 
<<stderr : OutChannel
>>
  
  The standard error channel, open for writing. 

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

9.8.2   open-in-string
======================
 The `open-in-string' treats a string
as if it were a file and returns a channel for reading.
<<   $(open-in-string s) : Channel
         s : String
>>

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

9.8.3   open-out-string, out-string
===================================
 The
`open-out-string' creates a channel that writes to a string instead of a
file. The string may be retrieved with the `out-string' function.
<<   $(open-out-string) : Channel
     $(out-string chan) : String
         chan : OutChannel
>>

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

9.8.4   fopen
=============

  The `fopen' function opens a file for reading or writing.
<<   $(fopen file, mode) : Channel
        file : File
        mode : String
>>
  
  The `file' is the name of the file to be opened. The `mode' is a
combination of the following characters. 
  
 r  Open the file for reading; it is an error if the file does not
   exist. 
 w  Open the file for writing; the file is created if it does not exist.
   
 a  Open the file in append mode; the file is created if it does not
   exist. 
 +  Open the file for both reading an writing. 
 t  Open the file in text mode (default). 
 b  Open the file in binary mode. 
 n  Open the file in nonblocking mode. 
 x  Fail if the file already exists. 
  
  Binary mode is not significant on Unix systems, where text and binary
modes are equivalent. 

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

9.8.5   close
=============

<<    $(close channel...)
         channel : Channel
>>
  
  The `close' function closes a file that was previously opened with
`fopen'. 

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

9.8.6   read
============

<<   $(read channel, amount) : String
        channel : InChannel
        amount  : Int
     raises RuntimeException
>>
  
  The `read' function reads up to `amount' bytes from an input channel,
and returns the data that was read. If an end-of-file condition is
reached, the function raises a `RuntimeException' exception. 

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

9.8.7   write
=============

<<   $(write channel, buffer, offset, amount) : String
        channel : OutChannel
        buffer  : String
        offset  : Int
        amount  : Int
     $(write channel, buffer) : String
        channel : OutChannel
        buffer  : String
     raises RuntimeException
>>
  
  In the 4-argument form, the `write' function writes bytes to the
output channel `channel' from the `buffer', starting at position
`offset'. Up to `amount' bytes are written. The function returns the
number of bytes that were written.
  The 3-argument form is similar, but the `offset' is 0.
  In the 2-argument form, the `offset' is 0, and the `amount' if the
length of the `buffer'.
  If an end-of-file condition is reached, the function raises a
`RuntimeException' exception. 

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

9.8.8   lseek
=============

<<    $(lseek channel, offset, whence) : Int
         channel : Channel
         offset  : Int
         whence  : String
      raises RuntimeException
>>
  
  The `lseek' function repositions the offset of the channel `channel'
according to the `whence' directive, as follows:
  
  
 SEEK_SET  The offset is set to `offset'. 
 SEEK_CUR  The offset is set to its current position plus `offset'
   bytes. 
 SEEK_END  The offset is set to the size of the file plus `offset'
   bytes. 
  
  The `lseek' function returns the new position in the file. 

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

9.8.9   rewind
==============

<<   rewind(channel...)
        channel : Channel
>>
  
  The `rewind' function set the current file position to the beginning
of the file. 

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

9.8.10   tell
=============

<<    $(tell channel...) : Int...
         channel : Channel
      raises RuntimeException
>>
  
  The `tell' function returns the current position of the `channel'. 

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

9.8.11   flush
==============

<<   $(flush channel...)
        channel : OutChannel
>>
  
  The `flush' function can be used only on files that are open for
writing. It flushes all pending data to the file. 

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

9.8.12   dup
============

<<    $(dup channel) : Channel
         channel : Channel
      raises RuntimeException
>>
  
  The `dup' function returns a new channel referencing the same file as
the argument. 

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

9.8.13   dup2
=============

<<   dup2(channel1, channel2)
        channel1 : Channel
        channel2 : Channel
     raises RuntimeException
>>
  
  The `dup2' function causes `channel2' to refer to the same file as
`channel1'. 

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

9.8.14   set-nonblock
=====================

<<   set-nonblock-mode(mode, channel...)
        channel : Channel
        mode : String
>>
  
  The `set-nonblock-mode' function sets the nonblocking flag on the
given channel. When IO is performed on the channel, and the operation
cannot be completed immediately, the operations raises a
`RuntimeException'. 

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

9.8.15   set-close-on-exec-mode
===============================

<<   set-close-on-exec-mode(mode, channel...)
        channel : Channel
        mode : String
     raises RuntimeException
>>
  
  The `set-close-on-exec-mode' function sets the close-on-exec flags for
the given channels. If the close-on-exec flag is set, the channel is not
inherited by child processes. Otherwise it is. 

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

9.8.16   pipe
=============

<<   $(pipe) : Pipe
     raises RuntimeException
>>
  
  The `pipe' function creates a `Pipe' object, which has two fields. The
`read' field is a channel that is opened for reading, and the `write'
field is a channel that is opened for writing. 

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

9.8.17   mkfifo
===============

<<   mkfifo(mode, node...)
        mode : Int
        node : Node
>>
  
  The `mkfifo' function creates a named pipe. 

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

9.8.18   select
===============

<<   $(select rfd..., wfd..., wfd..., timeout) : Select
        rfd : InChannel
        wfd : OutChannel
        efd : Channel
        timeout : float
     raises RuntimeException
>>
  
  The `select' function polls for possible IO on a set of channels. The
`rfd' are a sequence of channels for reading, `wfd' are a sequence of
channels for writing, and `efd' are a sequence of channels to poll for
error conditions. The `timeout' specifies the maximum amount of time to
wait for events.
  On successful return, `select' returns a `Select' object, which has
the following fields: 
  
 read  An array of channels available for reading. 
 write  An array of channels available for writing. 
 error  An array of channels on which an error has occurred. 
   

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

9.8.19   lockf
==============

<<    lockf(channel, command, len)
         channel : Channel
         command : String
         len : Int
      raises RuntimeException
>>
  
  The `lockf' function places a lock on a region of the channel. The
region starts at the current position and extends for `len' bytes.
  The possible values for `command' are the following. 
  
 F_ULOCK  Unlock a region. 
 F_LOCK  Lock a region for writing; block if already locked. 
 F_TLOCK  Lock a region for writing; fail if already locked. 
 F_TEST  Test a region for other locks. 
 F_RLOCK  Lock a region for reading; block if already locked. 
 F_TRLOCK  Lock a region for reading; fail is already locked. 
   

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

9.8.20   InetAddr
=================

  The `InetAddr' object describes an Internet address. It contains the
following fields.
  
  
 addr  `String': the Internet address. 
 port  `Int': the port number. 
  

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

9.8.21   Host
=============

  A `Host' object contains the following fields.
  
  
 name  `String': the name of the host. 
 aliases  `String Array': other names by which the host is known. 
 addrtype  `String': the preferred socket domain. 
 addrs  `InetAddr Array': an array of Internet addresses belonging to
   the host. 
  

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

9.8.22   gethostbyname
======================

<<   $(gethostbyname host...) : Host...
        host : String
     raises RuntimeException
>>
  
  The `gethostbyname' function returns a `Host' object for the specified
host. The `host' may specify a domain name or an Internet address.

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

9.8.23   Protocol
=================

  The `Protocol' object represents a protocol entry. It has the
following fields.
  
  
 name  `String': the canonical name of the protocol. 
 aliases  `String Array': aliases for the protocol. 
 proto  `Int': the protocol number. 
  

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

9.8.24   getprotobyname
=======================

<<   $(getprotobyname name...) : Protocol...
        name : Int or String
     raises RuntimeException
>>
  
  The `getprotobyname' function returns a `Protocol' object for the
specified protocol. The `name' may be a protocol name, or a protocol
number. 

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

9.8.25   Service
================

  The `Service' object represents a network service. It has the
following fields.
  
  
 name  `String': the name of the service. 
 aliases  `String Array': aliases for the service. 
 port  `Int': the port number of the service. 
 proto  `Protocol': the protocol for the service. 
  

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

9.8.26   getservbyname
======================

<<   $(getservbyname service...) : Service...
        service : String or Int
     raises RuntimeException
>>
  
  The `getservbyname' function gets the information for a network
service. The `service' may be specified as a service name or number. 

Node: Subsection 9-8-27,	Next: Subsection 9-8-28,	Prev: Subsection 9-8-26,	Up: Section 9-8
  

9.8.27   socket
===============

<<   $(socket domain, type, protocol) : Channel
        domain : String
        type : String
        protocol : String
     raises RuntimeException
>>
  
  The `socket' function creates an unbound socket.
  The possible values for the arguments are as follows.
  The `domain' may have the following values. 
  
 PF_UNIX or unix  Unix domain, available only on Unix systems. 
 PF_INET or inet  Internet domain, IPv4. 
 PF_INET6 or inet6  Internet domain, IPv6. 
  
  The `type' may have the following values. 
  
 SOCK_STREAM or stream  Stream socket. 
 SOCK_DGRAM or dgram  Datagram socket. 
 SOCK_RAW or raw  Raw socket. 
 SOCK_SEQPACKET or seqpacket  Sequenced packets socket 
  
  The `protocol' is an `Int' or `String' that specifies a protocol in
the protocols database. 

Node: Subsection 9-8-28,	Next: Subsection 9-8-29,	Prev: Subsection 9-8-27,	Up: Section 9-8
  

9.8.28   bind
=============

<<   bind(socket, host, port)
        socket : InOutChannel
        host : String
        port : Int
     bind(socket, file)
        socket : InOutChannel
        file : File
     raise RuntimeException
>>
  
  The `bind' function binds a socket to an address.
  The 3-argument form specifies an Internet connection, the `host'
specifies a host name or IP address, and the `port' is a port number.
  The 2-argument form is for `Unix' sockets. The `file' specifies the
filename for the address. 

Node: Subsection 9-8-29,	Next: Subsection 9-8-30,	Prev: Subsection 9-8-28,	Up: Section 9-8
  

9.8.29   listen
===============

<<   listen(socket, requests)
        socket : InOutChannel
        requests : Int
     raises RuntimeException
>>
  
  The `listen' function sets up the socket for receiving up to
`requests' number of pending connection requests. 

Node: Subsection 9-8-30,	Next: Subsection 9-8-31,	Prev: Subsection 9-8-29,	Up: Section 9-8
  

9.8.30   accept
===============

<<   $(accept socket) : InOutChannel
        socket : InOutChannel
     raises RuntimeException
>>
  
  The `accept' function accepts a connection on a socket. 

Node: Subsection 9-8-31,	Next: Subsection 9-8-32,	Prev: Subsection 9-8-30,	Up: Section 9-8
  

9.8.31   connect
================

<<    connect(socket, addr, port)
         socket : InOutChannel
         addr : String
         port : int
      connect(socket, name)
         socket : InOutChannel
         name : File
      raise RuntimeException
>>
  
  The `connect' function connects a socket to a remote address.
  The 3-argument form specifies an Internet connection. The `addr'
argument is the Internet address of the remote host, specified as a
domain name or IP address. The `port' argument is the port number.
  The 2-argument form is for Unix sockets. The `name' argument is the
filename of the socket. 

Node: Subsection 9-8-32,	Next: Subsection 9-8-33,	Prev: Subsection 9-8-31,	Up: Section 9-8
  

9.8.32   getchar
================

<<    $(getc) : String
      $(getc file) : String
         file : InChannel or File
      raises RuntimeException
>>
  
  The `getc' function returns the next character of a file. If the
argument is not specified, `stdin' is used as input. If the end of file
has been reached, the function returns `false'. 

Node: Subsection 9-8-33,	Next: Subsection 9-8-34,	Prev: Subsection 9-8-32,	Up: Section 9-8
  

9.8.33   gets
=============

<<   $(gets) : String
     $(gets channel) : String
        channel : InChannel or File
     raises RuntimeException
>>
  
  The `gets' function returns the next line from a file. The function
returns the empty string if the end of file has been reached. The line
terminator is removed. 

Node: Subsection 9-8-34,	Next: Section 9-9,	Prev: Subsection 9-8-33,	Up: Section 9-8
  

9.8.34   fgets
==============

<<   $(fgets) : String
     $(fgets channel) : String
        channel : InChannel or File
     raises RuntimeException
>>
  
  The `fgets' function returns the next line from a file that has been
opened for reading with `fopen'. The function returns the empty string
if the end of file has been reached. The returned string is returned as
literal data. The line terminator is not removed. 

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

9.9   Printing functions
*=*=*=*=*=*=*=*=*=*=*=*=

    
 
 
  Output is printed with the `print' and `println' functions. The
`println' function adds a terminating newline to the value being
printed, the `print' function does not.
<<    fprint(<file>, <string>)
      print(<string>)
      eprint(<string>)
      fprintln(<file>, <string>)
      println(<string>)
      eprintln(<string>)
>>
  
  The `fprint' functions print to a file that has been previously opened
with `fopen'. The `print' functions print to the standard output
channel, and the `eprint' functions print to the standard error channel.

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

9.10   Value printing functions
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

    
 
 
  Values can be printed with the `printv' and `printvln' functions. The
`printvln' function adds a terminating newline to the value being
printed, the `printv' function does not.
<<    fprintv(<file>, <string>)
      printv(<string>)
      eprintv(<string>)
      fprintvln(<file>, <string>)
      printvln(<string>)
      eprintvln(<string>)
>>
  
  The `fprintv' functions print to a file that has been previously
opened with `fopen'. The `printv' functions print to the standard output
channel, and the `eprintv' functions print to the standard error
channel. 

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

9.11   Higher-level IO functions
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

  
* Menu:

* Subsection 9-11-1::	Regular expressions
* Subsection 9-11-2::	cat
* Subsection 9-11-3::	grep
* Subsection 9-11-4::	scan
* Subsection 9-11-5::	awk
* Subsection 9-11-6::	fsubst
* Subsection 9-11-7::	lex
* Subsection 9-11-8::	lex-search
* Subsection 9-11-9::	Lexer
* Subsection 9-11-10::	Lexer matching
* Subsection 9-11-11::	Extending lexer definitions
* Subsection 9-11-12::	Threading the lexer object
* Subsection 9-11-13::	Parser
* Subsection 9-11-14::	Calling the parser
* Subsection 9-11-15::	Parsing control
* Subsection 9-11-16::	Extending parsers
* Subsection 9-11-17::	Passwd
* Subsection 9-11-18::	getpwnam, getpwuid
* Subsection 9-11-19::	getpwents
* Subsection 9-11-20::	Group
* Subsection 9-11-21::	getgrnam, getgrgid
* Subsection 9-11-22::	tgetstr
* Subsection 9-11-23::	xterm-escape-begin, xterm-escape-end
* Subsection 9-11-24::	xterm-escape
* Subsection 9-11-25::	prompt-invisible-begin, prompt-invisible-end
* Subsection 9-11-26::	prompt-invisible
* Subsection 9-11-27::	gettimeofday


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

9.11.1   Regular expressions
============================
   
  Many of the higher-level functions use regular expressions. Regular
expressions are defined by strings with syntax nearly identical to
awk(1).
  Strings may contain the following character constants.
  
  
 - `\\' : a literal backslash. 
 - `\a' : the alert character `^G'. 
 - `\b' : the backspace character `^H'. 
 - `\f' : the formfeed character `^L'. 
 - `\n' : the newline character `^J'. 
 - `\r' : the carriage return character `^M'. 
 - `\t' : the tab character `^I'. 
 - `\v' : the vertical tab character. 
 - `\xhh...' : the character represented by the string of hexadecimal
   digits `h'. All valid hexadecimal digits following the sequence are
   considered to be part of the sequence. 
 - `\ddd' : the character represented by 1, 2, or 3 octal digits. 
  
  Regular expressions are defined using the special characters
`.\^$[(){}*?'+.
  
  
 - `c' : matches the literal character `c' if `c' is not a special
   character. 
 - `\c' : matches the literal character `c', even if `c' is a special
   character. 
 - `.' : matches any character, including newline. 
 - `^' : matches the beginning of a line. 
 - `$' : matches the end of line. 
 - `[abc...]' : matches any of the characters `abc...' 
 - `[^abc...]' : matches any character except `abc...' 
 - `r1|r2' : matches either `r1' or `r2'. 
 - `r1r2' : matches `r1' and then `r2'. 
 - `r'+ : matches one or more occurrences of `r'. 
 - `r*' : matches zero or more occurrences of `r'. 
 - `r?' : matches zero or one occurrence of `r'. 
 - `(r)' : parentheses are used for grouping; matches `r'. 
 - `\(r\)' : also defines grouping, but the expression matched within
   the parentheses is available to the output processor through one of
   the variables `$1', `$2', ... 
 - `r{n}' : matches exactly `n' occurrences of `r'. 
 - `r{n,}' : matches `n' or more occurrences of `r'. 
 - `r{n,m}' : matches at least `n' occurrences of `r', and no more than
   `m' occurrences. 
 - `\y': matches the empty string at either the beginning or end of a
   word. 
 - `\B': matches the empty string within a word. 
 - `\<': matches the empty string at the beginning of a word. 
 - `\>': matches the empty string at the end of a word. 
 - `\w': matches any character in a word. 
 - `\W': matches any character that does not occur within a word. 
 - `\`': matches the empty string at the beginning of a file. 
 - `\'': matches the empty string at the end of a file. 
  
  Character classes can be used to specify character sequences
abstractly. Some of these sequences can change depending on your LOCALE.
  
  
 - `[:alnum:]' Alphanumeric characters. 
 - `[:alpha:]' Alphabetic characters. 
 - `[:lower:]' Lowercase alphabetic characters. 
 - `[:upper:]' Uppercase alphabetic characters. 
 - `[:cntrl:]' Control characters. 
 - `[:digit:]' Numeric characters. 
 - `[:xdigit:]' Numeric and hexadecimal characters. 
 - `[:graph:]' Characters that are printable and visible. 
 - `[:print:]' Characters that are printable, whether they are visible
   or not. 
 - `[:punct:]' Punctuation characters. 
 - `[:blank:]' Space or tab characters. 
 - `[:space:]' Whitespace characters. 
   

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

9.11.2   cat
============

<<    cat(files) : Sequence
         files : File or InChannel Sequence
>>
  
  The `cat' function concatenates the output from multiple files and
returns it as a string. 

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

9.11.3   grep
=============

<<   grep(pattern) : String  # input from stdin, default options
        pattern : String
     grep(pattern, files) : String  # default options
        pattern : String
        files   : File Sequence
     grep(options, pattern, files) : String
       options : String
       pattern : String
       files   : File Sequence
>>
  
  The `grep' function searches for occurrences of a regular expression
`pattern' in a set of files, and prints lines that match. This is like a
highly-simplified version of grep(1).
  The options are: 
  
 q  If specified, the output from `grep' is not displayed. 
 h  If specified, output lines will not include the filename (default,
   when only one input file is given). 
 n  If specified, output lines include the filename (default, when more
   than one input file is given). 
 v  If specified, search for lines without a match instead of lines with
   a match, 
  
  The `pattern' is a regular expression.
  If successful (`grep' found a match), the function returns `true'.
Otherwise, it returns `false'. 

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

9.11.4   scan
=============

<<   scan(input-files)
     case string1
        body1
     case string2
        body2
     ...
     default
        bodyd
>>
  
  The `scan' function provides input processing in command-line form.
The function takes file/filename arguments. If 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. Output is
always to `stdout'.
  The `scan' function operates by reading the input one line at a time,
and processing it according to the following algorithm.
  For each line, the record is first split into fields, 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, a case expression is selected. If `string_i' matches the token
`$1', 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.
  For example, here is an `scan' function that acts as a simple command
processor.
<<    calc() =
         i = 0
         scan(script.in)
         case print
            println($i)
         case inc
            i = $(add $i, 1)
            export
         case dec
            i = $(sub $i, 1)
            export
         case addconst
            i = $(add $i, $2)
            export
         default
            eprintln($"Unknown command: $1")
>>
  
  The `scan' function also supports several options.
<<    scan(options, files)
      ...
>>
  
  
  
 A  Parse each line as an argument list, where arguments may be quoted.
   For example, the following line has three words, "`ls'", "`-l'",
   "`Program Files'".
   <<       ls -l "Program Files"
        >>
 
 O  Parse each line using white space as the separator, using the usual
   OMake algorithm for string parsing. This is the default. 
 x  Once each line is split, reduce each word using the hex
   representation. This is the usual hex representation used in URL
   specifiers, so the string "Program Files" may be alternately
   represented in the form ProgramProgram+Files. 
  
  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 `calc' function.
<<    calc() =
          stdout = $(fopen script.out, w)
          scan(script.in)
             ...
          close(stdout)
>>