This file has been translated from LaTeX by HeVeA.

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

9.3.46   random, random-init
============================

<<    random-init(i)
          i : Int
      random() : Int
>>
  
  Produce a random number. The numbers are pseudo-random, and are not
cryptographically secure.
  The generator is initialized from semi-random system data. Subsequent
runs should produce different results. The 'rando-init' function can be
used to return the generator to a known state. 

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

9.4   Arithmetic
*=*=*=*=*=*=*=*=

   
* Menu:

* Subsection 9-4-1::	int
* Subsection 9-4-2::	float
* Subsection 9-4-3::	Basic arithmetic
* Subsection 9-4-4::	Comparisons


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

9.4.1   int
===========

  The 'int' function can be used to create integers. It returns an 'Int'
object.
  '$(int 17)'.

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

9.4.2   float
=============
 The 'float'
function can be used to create floating-point numbers. It returns a
'Float' object.
  '$(float 3.1415926)'. 

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

9.4.3   Basic arithmetic
========================
   














  The following functions can be used to perform basic arithmetic.
  
  
   - '$(neg <numbers>)': arithmetic inverse 
   - '$(add <numbers>)': addition. 
   - '$(sub <numbers>)': subtraction. 
   - '$(mul <numbers>)': multiplication. 
   - '$(div <numbers>)': division. 
   - '$(mod <numbers>)': remainder. 
   - '$(lnot <numbers>)': bitwise inverse. 
   - '$(land <numbers>)': bitwise and. 
   - '$(lor <numbers>)': bitwise or. 
   - '$(lxor <numbers>)': bitwise exclusive-or. 
   - '$(lsl <numbers>)': logical shift left. 
   - '$(lsr <numbers>)': logical shift right. 
   - '$(asr <numbers>)': arithmetic shift right. 
   - '$(min <numbers>)': smallest element. 
   - '$(max <numbers>)': largest element. 
   

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

9.4.4   Comparisons
===================
   








  The following functions can be used to perform numerical comparisons.
  
  
   - '$(lt <numbers>)': less then. 
   - '$(le <numbers>)': no more than. 
   - '$(eq <numbers>)': equal. 
   - '$(ge <numbers>)': no less than. 
   - '$(gt <numbers>)': greater than. 
   - '$(ult <numbers>)': unsigned less than. 
   - '$(ule <numbers>)': unsigned greater than. 
   - '$(uge <numbers>)': unsigned greater than or equal. 
   - '$(ugt <numbers>)': unsigned greater than. 
   

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

9.5   First-class functions
*=*=*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 9-5-1::	fun
* Subsection 9-5-2::	apply
* Subsection 9-5-3::	applya
* Subsection 9-5-4::	create-map, create-lazy-map


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

9.5.1   fun
===========

  The 'fun' form introduces anonymous functions.
  '$(fun <v1>, ..., <vn> => <body>)'
  The last argument is the body of the function. The other arguments are
the parameter names.
  The three following definitions are equivalent.
<<    F(X, Y) =
         return($(addsuffix $(Y), $(X)))
  
      F = $(fun X, Y => $(addsuffix $(Y), $(X)))
  
      F =
         fun(X, Y) =>
            value $(addsuffix $(Y), $(X))
>>

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

9.5.2   apply
=============

  The 'apply' operator is used to apply a function.
  '$(apply <fun>, <args>)'
  Suppose we have the following function definition.
<<    F(X, Y) =
         return($(addsuffix $(Y), $(X)))
>>
  
  The the two expressions below are equivalent.
<<    X = F(a b c, .c)
      X = $(apply $(F), a b c, .c)
>>
  
  The 'apply' form can also be used for partial applications, where a
function is passed fewer arguments than it expects. The result is a
function that takes the remaining arguments, and calls the function with
the full set of arguments.
<<    add2(i, j) =
         add($i, $j)
      succ = $(apply $(add2), 1)
      i = $(succ 5)   # Computes 1+5
>>

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

9.5.3   applya
==============

  The 'applya' operator is used to apply a function to an array of
arguments.
  '$(applya <fun>, <args>)'
  For example, in the following program, the value of 'Z' is 'file.c'.
<<    F(X, Y) =
         return($(addsuffix $(Y), $(X)))
      args[] =
         file
         .c
      Z = $(applya $(F), $(args))
>>
  
  The 'applya' form can also be used for partial applications. 

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

9.5.4   create-map, create-lazy-map
===================================

  The 'create-map' is a simplified form for creating 'Map' objects. The
'create-map' function takes an even number of arguments that specify
key/value pairs. For example, the following values are equivalent.
<<    X = $(create-map name1, xxx, name2, yyy)
  
      X. =
          extends $(Map)
          $|name1| = xxx
          $|name2| = yyy
>>
  
  The 'create-lazy-map' function is similar, but the values are computed
lazily. The following two definitions are equivalent.
<<    Y = $(create-lazy-map name1, $(xxx), name2, $(yyy))
  
      Y. =
          extends $(Map)
          $|name1| = $`(xxx)
          $|name2| = $`(yyy)
>>
  
  The 'create-lazy-map' function is used in rule construction. 

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

9.6   Iteration and mapping
*=*=*=*=*=*=*=*=*=*=*=*=*=*

  
* Menu:

* Subsection 9-6-1::	foreach


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

9.6.1   foreach
===============

  The 'foreach' function maps a function over a sequence.
<<    $(foreach <fun>, <args>)
  
      foreach(<var> => <args>)
         <body>
>>
  
  For example, the following program defines the variable 'X' as an
array 'a.c b.c c.c'.
<<    X =
         foreach(x => a b c)
            value $(x).c
  
      # Equivalent expression
      X = $(foreach $(fun x => $(x).c), a b c)
>>
  
  There is also an abbreviated syntax.
  The 'export' form can also be used in a 'foreach' body. The final
value of 'X' is 'a.c b.c c.c'.
<<    X =
      foreach(x => a b c)
         X += $(x).c
         export
>>
  
  The 'break' function can be used to break out of the loop early. 

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

9.7   Boolean tests
*=*=*=*=*=*=*=*=*=*

  
* Menu:

* Subsection 9-7-1::	sequence-forall
* Subsection 9-7-2::	sequence-exists
* Subsection 9-7-3::	sequence-sort
* Subsection 9-7-4::	compare


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

9.7.1   sequence-forall
=======================

  The 'forall' function tests whether a predicate holds for each element
of a sequence.
<<    $(sequence-forall <fun>, <args>)
  
      sequence-forall(<var> => ..., <args>)
         <body>
>>

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

9.7.2   sequence-exists
=======================
  
  The 'exists' function tests whether a predicate holds for some element
of a sequence.
<<    $(sequence-exists <fun>, <args>)
  
      sequence-exists(<var> => ..., <args>)
         <body>
>>

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

9.7.3   sequence-sort
=====================

  The 'sort' function sorts the elements in an array, given a comparison
function. Given two elements (x, y), the comparison should return a
negative number if x < y; a positive number if x > y; and 0 if x = y.
<<    $(sequence-sort <fun>, <args>)
  
      sort(<var>, <var> => ..., <args>)
         <body>
>>

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

9.7.4   compare
===============

  The 'compare' function compares two values (x, y) generically
returning a negative number if x < y; a positive number if x > y; and 0
if x = y.
<<    $(compare x, y) : Int
>>

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

Chapter 10     File, I/O and system operations
**********************************************
     
* Menu:

* Section 10-1::	File names
* Section 10-2::	Path search
* Section 10-3::	File stats
* Section 10-4::	Globbing and file listings
* Section 10-5::	Filesystem operations
* Section 10-6::	vmount
* Section 10-7::	File predicates
* Section 10-8::	IO functions
* Section 10-9::	Printing functions
* Section 10-10::	Value printing functions
* Section 10-11::	Higher-level IO functions


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

10.1   File names
*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 10-1-1::	file, dir
* Subsection 10-1-2::	tmpfile
* Subsection 10-1-3::	in
* Subsection 10-1-4::	basename
* Subsection 10-1-5::	dirname
* Subsection 10-1-6::	rootname
* Subsection 10-1-7::	dirof
* Subsection 10-1-8::	fullname
* Subsection 10-1-9::	absname
* Subsection 10-1-10::	homename
* Subsection 10-1-11::	suffix


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

10.1.1   file, dir
==================

<<   $(file sequence) : File Sequence
        sequence : Sequence
     $(dir sequence) : Dir Sequence
        sequence : Sequence
>>
  
  The 'file' and 'dir' functions define location-independent references
to files and directories. In omake, the commands to build a target are
executed in the target's directory. Since there may be many directories
in an omake project, the build system provides a way to construct a
reference to a file in one directory, and use it in another without
explicitly modifying the file name. The functions have the following
syntax, where the name should refer to a file or directory.
  For example, we can construct a reference to a file 'foo' in the
current directory.
<<   FOO = $(file foo)
     .SUBDIRS: bar
>>
  
  If the 'FOO' variable is expanded in the 'bar' subdirectory, it will
expand to '../foo'.
  These commands are often used in the top-level OMakefile to provide
location-independent references to top-level directories, so that build
commands may refer to these directories as if they were absolute.
<<   ROOT = $(dir .)
     LIB  = $(dir lib)
     BIN  = $(dir bin)
>>
  
  Once these variables are defined, they can be used in build commands
in subdirectories as follows, where '$(BIN)' will expand to the location
of the 'bin' directory relative to the command being executed.
<<   install: hello
   cp hello $(BIN)
>>

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

10.1.2   tmpfile
================

<<    $(tmpfile prefix) : File
      $(tmpfile prefix, suffix) : File
          prefix : String
          suffix : String
>>
  
  The 'tmpfile' function returns the name of a fresh temporary file in
the temporary directory. 

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

10.1.3   in
===========

<<   $(in dir, exp) : String Array
        dir : Dir
        exp : expression
>>
  
  The 'in' function is closely related to the 'dir' and 'file'
functions. It takes a directory and an expression, and evaluates the
expression in that effective directory. For example, one common way to
install a file is to define a symbol link, where the value of the link
is relative to the directory where the link is created.
  The following commands create links in the '$(LIB)' directory.
<<    FOO = $(file foo)
      install:
         ln -s $(in $(LIB), $(FOO)) $(LIB)/foo
>>
  
  Note that the 'in' function only affects the expansion of 'Node'
('File' and 'Dir') values. 

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

10.1.4   basename
=================

<<   $(basename files) : String Sequence
        files : String Sequence
>>
  
  The 'basename' function returns the base names for a list of files.
The basename is the filename with any leading directory components
removed.
  For example, the expression '$(basename dir1/dir2/a.out
/etc/modules.conf /foo.ml)' evaluates to 'a.out modules.conf foo.ml'. 

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

10.1.5   dirname
================

<<   $(dirname files) : String Sequence
        files : String Sequence
>>
  
  The 'dirname' function returns the directory name for a list of files.
The directory name is the filename with the basename removed. If a name
does not have a directory part, the directory is "."
  For example, the expression '$(dirname dir1\dir2\a.out
/etc/modules.conf /foo.ml bar.ml)' evaluates to 'dir1/dir2 /etc / .'.
  Note: this function is different from the 'dirof' function. The
function 'dirname' is simple a function over strings, while 'dirof' is a
function on filenames. 

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

10.1.6   rootname
=================

<<   $(rootname files) : String Sequence
        files : String Sequence
>>
  
  The 'rootname' function returns the root name for a list of files. The
rootname is the filename with the final suffix removed.
  For example, the expression '$(rootname dir1/dir2/a.out /etc/a.b.c
/foo.ml)' evaluates to 'dir1/dir2/a /etc/a.b /foo'. 

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

10.1.7   dirof
==============

<<   $(dirof files) : Dir Sequence
        files : File Sequence
>>
  
  The 'dirof' function returns the directory for each of the listed
files.
  For example, the expression '$(dirof dir/dir2/a.out /etc/modules.conf
/foo.ml)' evaluates to the directories 'dir1/dir2 /etc /'. 

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

10.1.8   fullname
=================

<<   $(fullname files) : String Sequence
        files : File Sequence
>>
  
  The 'fullname' function returns the pathname relative to the project
root for each of the files or directories. 

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

10.1.9   absname
================

<<   $(absname files) : String Sequence
        files : File Sequence
>>
  
  The 'absname' function returns the absolute pathname for each of the
files or directories. 

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

10.1.10   homename
==================

<<   $(homename files) : String Sequence
        files : File Sequence
>>
  
  The 'homename' function returns the name of a file in tilde form, if
possible. The unexpanded forms are computed lazily: the 'homename'
function will usually evaluate to an absolute pathname until the first
tilde-expansion for the same directory. 

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

10.1.11   suffix
================

<<   $(suffix files) : String Sequence
        files : StringSequence
>>
  
  The 'suffix' function returns the suffixes for a list of files. If a
file has no suffix, the function returns the empty string.
  For example, the expression '$(suffix dir1/dir2/a.out /etc/a /foo.ml)'
evaluates to '.out .ml'. 

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

10.2   Path search
*=*=*=*=*=*=*=*=*=

   
* Menu:

* Subsection 10-2-1::	which
* Subsection 10-2-2::	where
* Subsection 10-2-3::	rehash
* Subsection 10-2-4::	exists-in-path
* Subsection 10-2-5::	digest, digest-optional, digest-string
* Subsection 10-2-6::	find-in-path, find-in-path-optional
* Subsection 10-2-7::	digest-in-path, digest-in-path-optional


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

10.2.1   which
==============

<<   $(which files) : File Sequence
        files : String Sequence
>>
  
  The 'which' function searches for executables in the current command
search path, and returns 'file' values for each of the commands. It is
an error if a command is not found. 

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

10.2.2   where
==============

  The 'where' function is similar to which, except it returns the list
of all the locations of the given executable (in the order in which the
corresponding directories appear in '$PATH'). In case a command is
handled internally by the 'Shell' object, the first string in the output
will describe the command as a built-in function.
<<    % where echo
      echo is a Shell object method (a built-in function)
      /bin/echo
>>

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

10.2.3   rehash
===============

<<    rehash()
>>
  
  The 'rehash' function resets all search paths. 

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

10.2.4   exists-in-path
=======================

<<   $(exists-in-path files) : String
        files : String Sequence
>>
  
  The 'exists-in-path' function tests whether all executables are
present in the current search path. 

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

10.2.5   digest, digest-optional, digest-string
===============================================

<<     $(digest files) : String Array
          file : File Array
       raises RuntimeException
  
       $(digest-optional files) : String Array
          file : File Array
  
       $(digest-string s) : String
          s : String
>>
  
  The 'digest' and 'digest-optional' functions compute MD5 digests of
files. The 'digest' function raises an exception if a file does no
exist. The 'digest-optional' returns 'false' if a file does no exist.
MD5 digests are cached. 

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

10.2.6   find-in-path, find-in-path-optional
============================================

<<    $(find-in-path path, files) : File Array
         path : Dir Array
         files : String Array
      raises RuntimeException
  
      $(find-in-path-optional path, files) : File Array
>>
  
  The 'find-in-path' function searches for the files in a search path.
Only the tail of the filename is significant. The 'find-in-path'
function raises an exception if the file can't be found. The
'find-in-path-optional' function silently removes files that can't be
found. 

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

10.2.7   digest-in-path, digest-in-path-optional
================================================

<<    $(digest-in-path path, files) : String/File Array
         path : Dir Array
         files : String Array
      raises RuntimeException
  
      $(digest-in-path-optional path, files) : String/File Array
>>
  
  The 'digest-in-path' function searches for the files in a search path
and returns the file and digest for each file. Only the tail of the
filename is significant. The 'digest-in-path' function raises an
exception if the file can't be found. The 'digest-in-path-optional'
function silently removes elements that can't be found. 

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

10.3   File stats
*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 10-3-1::	file-exists, target-exists, target-is-proper
* Subsection 10-3-2::	stat-reset
* Subsection 10-3-3::	filter-exists, filter-targets, filter-proper-targets
* Subsection 10-3-4::	find-targets-in-path, find-targets-in-path-optional
* Subsection 10-3-5::	find-ocaml-targets-in-path-optional
* Subsection 10-3-6::	file-sort
* Subsection 10-3-7::	file-check-sort


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

10.3.1   file-exists, target-exists, target-is-proper
=====================================================

<<   $(file-exists files) : String
     $(target-exists files) : String
     $(target-is-proper files) : String
         files : File Sequence
>>
  
  The 'file-exists' function checks whether the files listed exist. The
'target-exists' function is similar to the 'file-exists' function.
However, it returns true if the file exists or if it can be built by the
current project. The 'target-is-proper' returns true only if the file
can be generated in the current project. 

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

10.3.2   stat-reset
===================

<<   $(stat-reset files) : String
         files : File Sequence
>>
  
  OMake uses a stat-cache. The 'stat-reset' function reset the 'stat'
information for the given files, forcing the 'stat' information to be
recomputed the next time it is requested. 

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

10.3.3   filter-exists, filter-targets, filter-proper-targets
=============================================================

<<   $(filter-exists files) : File Sequence
     $(filter-targets files) : File Sequence
     $(filter-proper-targets) : File Sequence
        files : File Sequence
>>
  
  The 'filter-exists', 'filter-targets', and 'filter-proper-targets'
functions remove files from a list of files. 
  
   - 'filter-exists': the result is the list of files that exist. 
   - 'filter-targets': the result is the list of files either exist, or
   can be built by the current project. 
   - 'filter-proper-targets': the result is the list of files that can
   be built in the current project. 
  
 Creating a "distclean" target
   
  One way to create a simple "'distclean'" rule that removes generated
files from the project is by removing all files that can be built in the
current project.
  CAUTION: you should be careful before you do this. The rule removes
any file that can potentially be reconstructed. There is no check to
make sure that the commands to rebuild the file would actually succeed.
Also, note that no file outside the current project will be deleted.
<<    .PHONY: distclean
  
      distclean:
          rm $(filter-proper-targets $(ls R, .))
>>
  
  If you use CVS, you may wish to utilize the 'cvs_realclean' program
that is distributed with OMake in order to create a "'distclean'" rule
that would delete all the files thare are not known to CVS. For example,
if you already have a more traditional "'clean'" target defined in your
project, and if you want the "'distclean'" rule to be interactive by
default, you can write the following:
<<    if $(not $(defined FORCE_REALCLEAN))
          FORCE_REALCLEAN = false
          export
  
      distclean: clean
          cvs_realclean $(if $(FORCE_REALCLEAN), -f) -i .omakedb -i
.omakedb.lock
>>
  
  You can add more files that you want to always keep (such as
configuration files) with the -i option.
  Similarly, if you use Subversion, you utilize the
'build/svn_realclean.om' script that comes with OMake:
<<    if $(not $(defined FORCE_REALCLEAN))
          FORCE_REALCLEAN = false
          export
  
      open build/svn_realclean
  
      distclean: clean
          svn_realclean $(if $(FORCE_REALCLEAN), -f) -i .omakedb -i
.omakedb.lock
>>
  
  See also the 'dependencies-proper' function for an alternate method
for removing intermediate files. 

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

10.3.4   find-targets-in-path, find-targets-in-path-optional
============================================================
\
@name{function:find-targets-in-path-optional}
<<    $(find-targets-in-path path files) : File Array
      $(find-targets-in-path-optional path, files) : File Array
          path : Dir Array
          files : File Sequence
>>
  
  The 'find-target-in-path' function searches for targets in the search
path. For each file 'file' in the file list, the path is searched
sequentially for a directory 'dir' such that the target 'dir/file'
exists. If so, the file 'dir/file' is returned.
  For example, suppose you are building a C project, and project
contains a subdirectory 'src/' containing only the files 'fee.c' and
'foo.c'. The following expression evaluates to the files 'src/fee.o'
'src/foo.o' even if the files have not already been built.
<<    $(find-targets-in-path lib src, fee.o foo.o)
  
      # Evaluates to
      src/fee.o src/foo.o
>>
  
  The 'find-targets-in-path' function raises an exception if the file
can't be found. The 'find-targets-in-path-optional' function silently
removes targets that can't be found.
<<    $(find-targets-in-path-optional lib src, fee.o foo.o fum.o)
  
      # Evaluates to
      src/fee.o src/foo.o
>>
  

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

10.3.5   find-ocaml-targets-in-path-optional
============================================
\
@name{@fun146} The 'find-ocaml-targets-in-path-optional' function is
very similar to the 'find-targets-in-path-optional' one, except an
OCaml-style search is used, where for every element of the search path
and for every name being searched for, first the uncapitalized version
is tried and if it is not buildable, then the capitalized version is
tried next. 

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

10.3.6   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. 
  
  

10.3.6.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 10-3-7,	Next: Section 10-4,	Prev: Subsection 10-3-6,	Up: Section 10-3
  

10.3.7   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 10-4,	Next: Subsection 10-4-1,	Prev: Section 10-3,	Up: Chapter 10
  

10.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 10-4-1::	glob
* Subsection 10-4-2::	ls
* Subsection 10-4-3::	subdirs


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

10.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 10-4-2,	Next: Subsection 10-4-3,	Prev: Subsection 10-4-1,	Up: Section 10-4
  

10.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 10-4-3,	Next: Section 10-5,	Prev: Subsection 10-4-2,	Up: Section 10-4
  

10.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 10-5,	Next: Subsection 10-5-1,	Prev: Section 10-4,	Up: Chapter 10
  

10.5   Filesystem operations
*=*=*=*=*=*=*=*=*=*=*=*=*=*=

   
* Menu:

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


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

10.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 10-5-2,	Next: Subsection 10-5-3,	Prev: Subsection 10-5-1,	Up: Section 10-5
  

10.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 10-5-3,	Next: Subsection 10-5-4,	Prev: Subsection 10-5-2,	Up: Section 10-5
  

10.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 10-5-4,	Next: Subsection 10-5-5,	Prev: Subsection 10-5-3,	Up: Section 10-5
  

10.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 10-5-5,	Next: Subsection 10-5-6,	Prev: Subsection 10-5-4,	Up: Section 10-5
  

10.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 10-5-6,	Next: Subsection 10-5-7,	Prev: Subsection 10-5-5,	Up: Section 10-5
  

10.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 10-5-7,	Next: Subsection 10-5-8,	Prev: Subsection 10-5-6,	Up: Section 10-5
  

10.5.7   symlink, symlink-raw
=============================

<<   symlink(src, dst)
        src : Node
        dst : Node
     symlink-raw(src, dst)
        src : String
        dst : Node
     raises RuntimeException
>>
  
  The 'symlink' function creates a symbolic link 'dst' that points to
the 'src' file.
  For 'symlink', 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'.
  The function 'symlink-raw' performs no translation. The symbolic link
is set to the 'src' string.
  Symbolic links are not supported in Win32. Consider using the
'ln-or-cp' 'Shell' alias for cross-platform portable linking/copying. 

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

10.5.8   readlink, readlink-raw
===============================

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

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

10.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 10-5-10,	Next: Subsection 10-5-11,	Prev: Subsection 10-5-9,	Up: Section 10-5
  

10.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 10-5-11,	Next: Subsection 10-5-12,	Prev: Subsection 10-5-10,	Up: Section 10-5
  

10.5.11   utimes
================

<<   utimes(atime, mtime, node...)
        atime : Float
        mtime : Float
        node : Node
     raises RuntimeException
>>
  
  The 'utimes' function changes the access and modification times of the
files. 

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

10.5.12   truncate
==================

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

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

10.5.13   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 10-6,	Next: Subsection 10-6-1,	Prev: Section 10-5,	Up: Chapter 10
  

10.6   vmount
*=*=*=*=*=*=*

   
* Menu:

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


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

10.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 10-6-2,	Next: Subsection 10-6-3,	Prev: Subsection 10-6-1,	Up: Section 10-6
  

10.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 10-6-3,	Next: Section 10-7,	Prev: Subsection 10-6-2,	Up: Section 10-6
  

10.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 10-7,	Next: Subsection 10-7-1,	Prev: Section 10-6,	Up: Chapter 10
  

10.7   File predicates
*=*=*=*=*=*=*=*=*=*=*=

   
* Menu:

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


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

10.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 has a non-zero size 
   - '-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 10-7-2,	Next: Section 10-8,	Prev: Subsection 10-7-1,	Up: Section 10-7
  

10.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 10.4*Note Section 10-4::). 
   - '-regex' string : The current file matches the regular expression 
  
  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>
>>
   
