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 one  argument.  The  result  is  a  new
              sequence constructed from the values returned by the function.

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

          s.foreach(<var>)
             <body>


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

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


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

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



   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,
       mv,  cat,  rm, mkdir, chmod, test, find.  If you really want to use the
       standard system versions of these commands, set the USE_SYSTEM_COMMANDS
       as one of the first definitions in your OMakeroot file.


       *      mkdir

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


              The mkdir function is used to create directories.  The -verb+-m+
              option can be used to specify the permission mode of the created
              directory.  If the -p option is specified, the full path is 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.


       *      cat

                 cat files...


              The cat function prints the contents of the files to stdout

       *      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.9 of April 11, 2006.


   LICENSE AND COPYRIGHT
       (C)2003-2006, Mojave Group, Caltech

       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 et. al..br Caltech 256-80
       Pasadena, CA 91125, USA
       Email: omake-devel@metaprl.org
       WWW: http://www.cs.caltech.edu/~jyh




Build Tools                     April 11, 2006             OMAKE-PERVASIVES(1)
