OMAKE-PERVASIVES(1)              Build Tools               OMAKE-PERVASIVES(1)



NAME
       omake  is  a flexible build system designed for building a wide variety
       of projects.  This document describes the built-in objects available to
       all programs.  For an overview of omake, see the omake(1) man page.


PERVASIVES
       Pervasives  defines  the  objects that are defined in all programs. The
       following objects are defined.


   OBJECT
       Parent objects: none.

       The Object object is the root object.  Every class  is  a  subclass  of
       Object.

       It provides the following fields:


       *      $(o.object-length):  the  number  of  fields  and methods in the
              object.

       *      $(o.object-mem <var>): returns true iff the <var> is a field  or
              method of the object.

       *      $(o.object-add  <var>,  <value>):  adds the field to the object,
              returning a new object.

       *      $(o.object-find <var>): fetches the field  or  method  from  the
              object;  it is equivalent to $(o.<var>), but the variable can be
              non-constant.

       *      $(o.object-map <fun>): maps a  function  over  the  object.  The
              function  should  take two arguments; the first is a field name,
              the second is the value of that  field.  The  result  is  a  new
              object constructed from the values returned by the function.

       *      o.object-foreach:  the  foreach  form  is equivalent to map, but
              with altered syntax.

          o.foreach(<var1>, <var2>)
             <body>


       For example, the following function prints all the fields of an  object
       o.

          PrintObject(o) =
             o.foreach(v, x)
                println($(v) = $(x))


       The export form is valid in a foreach body. The following function col-
       lects just the field names of an object.

          FieldNames(o) =
             names =
             o.foreach(v, x)
                names += $(v)
                export
             return $(names)



   MAP
       Parent objects: Object.

       A Map object is a dictionary from values to values.  The  <key>  values
       are  restricted  to  simple  values:  integers, floating-point numbers,
       strings, files, directories, and arrays of simple values.

       The Map object provides the following methods.


       *      $(o.mem <key>): returns true iff the <key>  is  defined  in  the
              map.

       *      $(o.add  <key>, <value>): adds the field to the map, returning a
              new map.

       *      $(o.find <key>): fetches the field from the map.

       *      $(o.map <fun>): maps a  function  over  the  map.  The  function
              should take two arguments; the first is a field name, the second
              is the value of that field. The result  is  a  new  object  con-
              structed from the values returned by the function.

       *      o.foreach:  the  foreach  form  is  equivalent  to map, but with
              altered syntax.

          o.foreach(<var1>, <var2>)
             <body>


       For example, the following function prints all the fields of an  object
       o.

          PrintObject(o) =
             o.foreach(v, x)
                println($(v) = $(x))


       The export form is valid in a foreach body. The following function col-
       lects just the field names of the map.

          FieldNames(o) =
             names =
             o.foreach(v, x)
                names += $(v)
                export
             return $(names)


       There is also simpler syntax when the key is a string. The table can be
       defined using definitions with the form $|key| (the number of pipe sym-
       bols | is allowed to vary).

           $|key 1| = value1
           $||key1|key2|| = value2    # The key is key1|key2
           X = $|key 1|               # Define X to be the value of field $|key 1|


       The usual modifiers are also allowed. The expression $`|key| represents
       lazy evaluation of the key, and $,|key| is normal evaluation.


   NUMBER
       Parent objects: Object.

       The  Number object is the parent object for integers and floating-point
       numbers.

   INT
       Parent objects: Number.

       The Int object represents integer values.

   FLOAT
       Parent objects: Number.

       The Float object represents floating-point numbers.

   SEQUENCE
       Parent objects: Object.

       The Sequence object represents a generic object  containing  sequential
       elements. It provides the following methods.


       *      $(s.length): the number of elements in the sequence.

       *      $(s.map <fun>): maps a function over the fields in the sequence.
              The function should take two arguments; the  first  is  a  field
              name, the second is the value of that field. The result is a new
              sequence constructed from the values returned by the function.

       *      s.foreach: the foreach form  is  equivalent  to  map,  but  with
              altered syntax.

          s.foreach(<var>)
             <body>


       For  example,  the  following  function  prints all the elements of the
       sequence.

          PrintSequence(s) =
             s.foreach(x)
                println(Elem = $(x))


       The export form is valid in a  foreach  body.  The  following  function
       counts the number of zeros in the sequence.

          Zeros(s) =
             count = $(int 0)
             s.foreach(v)
                if $(equal $(v), 0)
                   count = $(add $(count), 1)
                   export
                export
             return $(count)



   ARRAY
       Parent objects: Sequence.

       The Array is a random-access sequence.  It provides the following addi-
       tional methods.


       *      $(s.nth <i>): returns element i of the sequence.

       *      $(s.rev <i>): returns the reversed sequence.


   STRING
       Parent objects: Array.

   FUN
       Parent objects: Object.

       The Fun object provides the following methods.

       *      $(f.arity): the arity if the function.


   RULE
       Parent objects: Object.

       The Rule object represents a build rule.  It does  not  currently  have
       any methods.

   TARGET
       Parent object: Object.

       The  Target object contains information collected for a specific target
       file.


       *      target: the target file.

       *      effects: the files that may be modified by  a  side-effect  when
              this target is built.

       *      scanner_deps: static dependencies that must be built before this
              target can be scanned.

       *      static-deps: statically-defined build dependencies of this  tar-
              get.

       *      build-deps: all the build dependencies for the target, including
              static and scanned dependencies.

       *      build-values: all the value  dependencies  associated  with  the
              build.

       *      build-commands: the commands to build the target.

       The object supports the following methods.


       *      find(file):  returns a Target object for the given file.  Raises
              a RuntimeException if the specified target is not  part  of  the
              project.

       *      find-optional(file): returns a Target object for the given file,
              or false if the file is not part of the project.

       NOTE: the information for a target is constructed dynamically, so it is
       possible  that the Target object for a node will contain different val-
       ues in different contexts. The easiest way to make sure that the Target
       information  is complete is to compute it within a rule body, where the
       rule depends on the target file, or  the  dependencies  of  the  target
       file.

   NODE
       Parent objects: Object.

       The  Node  object  is  the parent object for files and directories.  It
       supports the following operations.

       *      $(node.stat): returns a stat object for the file. If the file is
              a  symbolic link, the stat information is for the destination of
              the link, not the link itself.


       *      $(node.lstat): returns a stat object for the  file  or  symbolic
              link.

       *      $(node.unlink): removes the file.

       *      $(node.rename <file>): renames the file.

       *      $(node.link <file>): creates a hard link <dst> to this file.

       *      $(node.symlink  <file>):  create  a  symbolic link <dst> to this
              file.

       *      $(node.chmod <perm>): change the permission of this file.

       *      $(node.chown <uid>, <gid>): change the owner  and  group  id  of
              this file.


   FILE
       Parent objects: Node.

       The file object represents the name of a file.

   DIR
       Parent objects: Node.

       The Dir object represents the name of a directory.

   CHANNEL
       Parent objects: Object.

       A  Channel is a generic IO channel.  It provides the following methods.

       *      $(o.close): close the channel.


   INCHANNEL
       Parent objects: Channel.

       A InChannel is an input channel. The variable  stdin  is  the  standard
       input channel.

       It provides the following methods.

       *      $(InChannel.fopen <file>): open a new input channel.


   OUTCHANNEL
       Parent object: Channel.

       A  OutChannel is an output channel. The variables stdout and stderr are
       the standard output and error channels.

       It provides the following methods.

       *      $(OutChannel.fopen <file>): open a new output channel.

       *      $(OutChannel.append <file>): opens a new output channel, append-
              ing to the file.

       *      $(c.flush): flush the output channel.

       *      $(c.print <string>): print a string to the channel.

       *      $(c.println  <string>):  print a string to the channel, followed
              by a line terminator.


   LOCATION
       Parent objects: Location.

       The Location object represents a location in a file.

   POSITION
       Parent objects: Position.

       The Position object represents a stack trace.

   EXCEPTION
       Parent objects: Object.

       The Exception object is used as the base object for exceptions.  It has
       no fields.

   RUNTIMEEXCEPTION
       Parent objects: Exception.

       The  RuntimeException  object  represents an exception from the runtime
       system. It has the following fields.


       *      position: a string representing the location where the exception
              was raised.

       *      message: a string containing the exception message.


   SHELL
       Parent objects: Object.

       The Shell object contains the collection of builtin functions available
       as shell commands.

       You can define aliases by extending this object with  additional  meth-
       ods.   All methods in this class are called with one argument: a single
       array containing an argument list.


       *      echo

       The echo function prints its arguments to the standard output  channel.

       *      jobs

       The jobs method prints the status of currently running commands.

       *      cd

       The  cd  function changes the current directory.  Note that the current
       directory follows the usual scoping rules. For example,  the  following
       program lists the files in the foo directory, but the current directory
       is not changed.

          section
             echo Listing files in the foo directory...
             cd foo
             ls

          echo Listing files in the current directory...
          ls


       *      bg

       The bg method places a job in the background.  The job is resumed if it
       has been suspended.

       *      fg

       The fg method brings a job to the foreground.  The job is resumed if it
       has been suspended.

       *      stop

       The stop method suspends a running job.

       *      wait

       The wait function waits for a running job to terminate.  It is not pos-
       sible to wait for a suspended job.

       The  job  is not brought to the foreground. If the wait is interrupted,
       the job continues to run in the background.

       *      kill

       The kill function signal a job.

       kill [signal] <pid...>.

       The signals are either numeric, or symbolic.  The symbolic signals  are
       named as follows.

       ABRT,  ALRM,  HUP, ILL, KILL, QUIT, SEGV, TERM, USR1, USR2, CHLD, STOP,
       TSTP, TTIN, TTOU, VTALRM, PROF.

       *      exit

       The exit function terminates the current session.

       *      which, where

       See the documentation for the corresponding functions.

       *      rehash

       Reset the search path.

       *      history

       Print the current command-line history.

       *      Win32 functions.

       Win32 doesn't provide very many programs for scripting, except for  the
       functions that are builtin to the DOS cmd.exe.  The following functions
       are defined on Win32 and only  on  Win32.   On  other  systems,  it  is
       expected that these programs already exist.


              *      grep

                        grep [-q] [-n] pattern files...


                     The grep function calls the omake grep function.

       By default, omake uses internal versions of the following commands: cp,
       rm, mkdir, chmod, test, find.  If you really want to use  the  standard
       system  versions  of these commands, set the USE_SYSTEM_COMMANDS as one
       of the first definitions in your OMakeroot file.


       *      mkdir

                  mkdir [-m <mode>] [-p] files


              The mkdir function is used to create directories.  The -verb+-m+
              option can be used to specify the permission mode of the created
              directory. If the -p option is specified, the full path is  cre-
              ated.

       *      cp

       *      mv

                  cp [-f] [-i] [-v] src dst
                  cp [-f] [-i] [-v] files dst
                  mv [-f] [-i] [-v] src dst
                  mv [-f] [-i] [-v] files dst


              The  cp function copies a src file to a dst file, overwriting it
              if it already exists.  If more than one source  file  is  speci-
              fied,  the  final file must be a directory, and the source files
              are copied into the directory.


              -f     Copy files forcibly, do not prompt.

              -i     Prompt before removing destination files.

              -v     Explain what is happening.


       *      rm

                 rm [-f] [-i] [-v] [-r] files
                 rmdir [-f] [-i] [-v] [-r] dirs


              The rm function removes a set of files.  No warnings are  issued
              if the files do not exist, or if they cannot be removed.

              Options:

              -f     Forcibly remove files, do not prompt.

              -i     Prompt before removal.

              -v     Explain what is happening.

              -r     Remove contents of directories recursively.


       *      chmod

                  chmod [-r] [-v] [-f] mode files


              The  chmod function changes the permissions on a set of files or
              directories. This function does nothing on Win32.  The mode  may
              be   specified   as   an  octal  number,  or  in  symbolic  form
              [ugoa]*[-=][rwxXstugo]+.   See  the  man  page  for  chmod   for
              details.

              Options:

              -r     Change  permissions  of  all  files in a directory recur-
                     sively.

              -v     Explain what is happening.

              -f     Continue on errors.


       *      test

                 test \emph{expression}
                 \verb+[+ \emph{expression} +]+
                 \verb+[ --help+
                 \verb+[ --version+


              See the documentation for the test function.


       *      find

                 find \emph{expression}


              See the documentation for the find function.




REFERENCES
   SEE ALSO
       omake(1),   omake-quickstart(1),    omake-options(1),    omake-root(1),
       omake-language(1),   omake-shell(1),   omake-rules(1),   omake-base(1),
       omake-system(1), omake-pervasives(1), osh(1), make(1)


   VERSION
       Version: 0.9.6.7 of December 28, 2005.


   LICENSE AND COPYRIGHT
       (C)2003-2005, Jason Hickey, Caltech 256-80, Pasadena, CA 91125, USA

       This program is free software; you can redistribute it and/or modify it
       under  the  terms of the GNU General Public License as published by the
       Free Software Foundation; either version 2 of the License, or (at  your
       option) any later version.

       This  program  is  distributed  in the hope that it will be useful, but
       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER-
       CHANTABILITY  or  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
       Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       675 Mass Ave, Cambridge, MA 02139, USA.


   AUTHOR
       Jason Hickey
       Caltech 256-80
       Pasadena, CA 91125, USA
       Email: jyh@cs.caltech.edu
       WWW: http://www.cs.caltech.edu/~jyh




Build Tools                    December 28, 2005           OMAKE-PERVASIVES(1)
