The standard objects

Jump to: | ‍ ‍ | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: | ‍ ‍ | All • Variables • Functions • Objects • Targets • Options

# Chapter ‍12 The standard objects

- Pervasives objects

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

## 12.1 Pervasives objects

### 12.1.1 Object

Parent objects: none.

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

It provides the following fields:

- `$(o.object-length)`: the number of fields and methods in the object.
- `$(o.object-mem <var>)`: returns `true` iff the `<var>` is a field or method of the object.
- `$(o.object-add <var>, <value>)`: adds the field to the object, returning a new object.
- `$(o.object-find <var>)`: fetches the field or method from the object; it is equivalent to `$(o.<var>)`, but the variable can be non-constant.
- `$(o.object-map <fun>)`: maps a function over the object. The function should take two arguments; the first is a field name, the second is the value of that field. The result is a new object constructed from the values returned by the function.
- `o.object-foreach`: the `object-foreach` form is equivalent to `object-map`, but with altered syntax.

         o.object-foreach(<var1>, <var2>) =>
            <body>

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

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

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

         FieldNames(o) =
            names[] =
            o.object-foreach(v, x) =>
               names[] += $(v)
               export
            return $(names)

### 12.1.2 Map

Parent objects: `Object`.

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

The Map object provides the following methods.

- `$(o.length)`: the number of items in the map.
- `$(o.mem <key>)`: returns `true` iff the `<key>` is defined in the map.
- `$(o.add <key>, <value>)`: adds the field to the map, returning a new map.
- `$(o.find <key>)`: fetches the field from the map.
- `$(o.keys)`: fetches an array of all the keys in the map, in alphabetical order.
- `$(o.values)`: fetches an array of all the values in the map, in the alphabetical order of the corresponding keys.
- `$(o.map <fun>)`: maps a function over the map. The function should take two arguments; the first is a field name, the second is the value of that field. The result is a new object constructed from the values returned by the function.
- `o.foreach`: the `foreach` form is equivalent to `map`, but with altered syntax.

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

  For example, the following function prints all the fields of a map `o`.

         PrintMap(o) =
            o.foreach(v, x) =>
               println($(v) = $(x))

  The `export` form is valid in a `foreach` body. The following function reimplements the `key` method.

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

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

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

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

### 12.1.3 Number

Parent objects: `Object`.

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

### 12.1.4 Int

Parent objects: `Number`.

The `Int` object represents integer values.

### 12.1.5 Float

Parent objects: `Number`.

The `Float` object represents floating-point numbers.

### 12.1.6 Sequence

Parent objects: `Object`.

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

- `$(s.length)`: the number of elements in the sequence.
- `$(s.is-nonempty)`: true iff the expression `$(s.nth 0)` will complete without failure.
- `$(s.nth <i>)`: return the n’th element of the sequence.
- `$(s.nth-tl <i>)`: return the n’th tail of 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)

- `$(s.forall <fun>)`: tests whether each element of the sequence satifies a predicate.
- `$(s.exists <fun>)`: tests whether the sequence contains an element that satisfies a predicate.
- `$(s.sort <fun>)`: sorts a sequence. The `<fun>` is a comparison function. It takes two elements `(x, y)` of the sequence, compares them, and returns a negative number if x < y, a positive number if x > y, and zero if the two elements are equal.

        osh> items = $(int 0 3 -2)
        osh> items.forall(x => $(gt $x, 0))
        - : bool = false
        osh> items.exists(x => $(gt $x, 0))
        - : bool = true
        osh> items.sort($(compare))
        - : Array = -2 3 0

### 12.1.7 Array

Parent objects: `Sequence`.

The `Array` is a random-access sequence. It provides the following additional methods.

- `$(s.nth <i>)`: returns element `i` of the sequence.
- `$(s.rev <i>)`: returns the reversed sequence.

### 12.1.8 String

Parent objects: `Array`.

### 12.1.9 Fun

Parent objects: `Object`.

The `Fun` object provides the following methods.

- `$(f.arity)`: the arity if the function.

### 12.1.10 Rule

Parent objects: `Object`.

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

### 12.1.11 Target

Parent object: `Object`.

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

- `target`: the target file.
- `effects`: the files that may be modified by a side-effect when this target is built.
- `scanner_deps`: static dependencies that must be built before this target can be scanned.
- `static-deps`: statically-defined build dependencies of this target.
- `build-deps`: all the build dependencies for the target, including static and scanned dependencies.
- `build-values`: all the value dependencies associated with the build.
- `build-commands`: the commands to build the target.
- `output-file`: if output was diverted to a file, with one of the `--output-*` options ‍A, this field names that file. Otherwise it is `false`.

The object supports the following methods.

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

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

### 12.1.12 Node

Parent objects: `Object`.

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

- `$(node.stat)`: returns a `stat` object for the file. If the file is a symbolic link, the `stat` information is for the destination of the link, not the link itself.
- `$(node.lstat)`: returns a `stat` object for the file or symbolic link.
- `$(node.unlink)`: removes the file.
- `$(node.rename <file>)`: renames the file.
- `$(node.link <file>)`: creates a hard link `<dst>` to this file.
- `$(node.symlink <file>)`: create a symbolic link `<dst>` to this file.
- `$(node.chmod <perm>)`: change the permission of this file.
- `$(node.chown <uid>, <gid>)`: change the owner and group id of this file.

### 12.1.13 File

Parent objects: `Node`.

The file object represents the name of a file.

### 12.1.14 Dir

Parent objects: `Node`.

The `Dir` object represents the name of a directory.

### 12.1.15 Channel

Parent objects: `Object`.

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

- `$(o.close)`: close the channel.
- `$(o.name)`: returns the file name associated with the channel.

### 12.1.16 InChannel

Parent objects: `Channel`.

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

It provides the following methods.

- `$(InChannel.fopen <file>)`: open a new input channel.
- `$(InChannel.of-string <string>)`: open a new input channel, using a string as input.
- `$(o.read <number>)`: reads the given number of characters from the channel
- `$(o.readln)`: reads a line from the channel

### 12.1.17 OutChannel

Parent object: `Channel`.

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

It provides the following methods.

- `$(OutChannel.fopen <file>)`: open a new output channel.
- `$(OutChannel.string)`: open a new output channel, writing to a string.
- `$(OutChannel.to-string)`: get the current string of output, for an output channel created as `OutChannel.open-string`.
- `$(OutChannel.append <file>)`: opens a new output channel, appending to the file.
- `$(c.flush)`: flush the output channel.
- `$(c.print <string>)`: print a string to the channel.
- `$(c.println <string>)`: print a string to the channel, followed by a line terminator.

### 12.1.18 Location

Parent objects: `Location`.

The `Location` object represents a location in a file.

### 12.1.19 Exception

Parent objects: `Object`.

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

### 12.1.20 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.

### 12.1.21 UnbuildableException

Parent objects: `Exception`.

The `UnbuildableException` object should be used to signal that a target is not buildable. It will be caught by functions such as `target-exists`. This exception has the following fields:

- `target`: indicates which target is not buildable.
- `message`: a string containing the exception message.

### 12.1.22 Shell

Parent objects: `Object`.

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

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

- `echo`

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

- `jobs`

  The `jobs` method prints the status of currently running commands.

- `cd`

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

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

         echo Listing files in the current directory...
         ls

- `bg`

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

- `fg`

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

- `stop`

  The `stop` method suspends a running job.

- `wait`

  The `wait` function waits for a running job to terminate. It is not possible to wait for a suspended job.

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

- `kill`

  The `kill` function signal a job.

  `kill [signal] <pid...>`.

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

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

- `exit`

  The `exit` function terminates the current session.

- `which`, `where`

  See the documentation for the corresponding functions.

- `rehash`

  Reset the search path.

- `ln-or-cp` src dst

  Links or copies src to dst, overwriting dst. Namely, `ln-or-cp` would first delete the dst file (unless it is a directory), if it exists. Next it would try to create a symbolic link dst poiting to src (it will make all the necessary adjustmnents of relative paths). If symbolic link can not be created (e.g. the OS or the filesystem does not support symbolic links), it will try to create a hard link. If that fails too, it will try to forcibly copy src to dst.

- `history`

  Print the current command-line history.

- `digest`

  Print the digests of the given files.

- Win32 functions.

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

  - `grep`

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

    The `grep` alias calls the omake’s internal `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.

  - `pwd`

            pwd

    The `pwd` alias would print the absolute path to current directory.

  - `mkdir`

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

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

  - `cp`, `mv`

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

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

    -f
      Copy files forcibly, do not prompt.
    -i
      Prompt before removing destination files.
    -v
      Explain what is happening.
  - `rm`

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

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

    Options:

    -f
      Forcibly remove files, do not prompt.
    -i
      Prompt before removal.
    -v
      Explain what is happening.
    -r
      Remove contents of directories recursively.
  - `chmod`

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

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

    Options:

    -r
      Change permissions of all files in a directory recursively.
    -v
      Explain what is happening.
    -f
      Continue on errors.
  - `cat`

           cat files...

    The `cat` function prints the contents of the files to stdout

  - `test`

    `test` expression
    `[` expression +]+
    `[ --help`
    `[ --version`
    See the documentation for the `test` function.

  - `find`

    `find` expression

    See the documentation for the `find` function.

Jump to: | ‍ ‍ | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: | ‍ ‍ | All • Variables • Functions • Objects • Targets • Options