Module globals

RingoJS adopts some of the global properties from the Rhino shell and adds a few of its own.

Note that this module must and can not be imported like an ordinary module. It is evaluated only once upon RingoJS startup.

Functions

addToClasspath(path)
clearInterval(id)
clearTimeout(id)
defineClass(className)
export(name...)
gc()
getRepository(path)
getResource(path)
include(moduleId)
load(filename...)
module.resolve(path)
module.singleton(id, factory)
print(arg...)
privileged(func)
quit()
require(moduleId)
seal(obj)
setInterval(callback, delay, args)
setTimeout(callback, delay, [args])
spawn(func)
sync(func, [obj])

addToClasspath (path)

Adds path to the RingoJS application class path.

Parameters

String|Resource|Repository

path

a directory or jar path

arguments

The arguments array contains the command line arguments RingoJS was started with.

Note that this variable is shadowed by the arguments object inside functions which is why it is usually safer to use [system.args][system#args] instead.

clearInterval (id)

Cancel a timeout previously scheduled with [setInterval()][#setInterval].

Parameters

object

the id object returned by setInterval()

See

setInterval

clearTimeout (id)

Cancel a timeout previously scheduled with [setTimeout()][#setTimeout].

Parameters

object

the id object returned by setTimeout()

See

setTimeout

console

Firebug-like debug console, preloaded for your convenience.

See

console

defineClass (className)

Define an extension using the Java class named with the string argument className. Uses ScriptableObject.defineClass() to define the extension.

Parameters

String

className

a Java class

environment

The environment object contains the Java system properties.

export (name...)

Takes any number of top-level names to be exported from this module.

This is a non-standard alternative to the [exports][#exports] object for exporting values in a less verbose and intrusive way.

Parameters

null

name...

one or more names of exported properties

exports

The exports object as defined in the CommonJS Modules 1.1.1 specification.

Define properties on the exports object to make them available to other modules [requiring][#require] this module.

gc ()

Runs the garbage collector.

getRepository (path)

Resolve path following the same logic [require][#require] uses for module ids and return an instance of org.ringojs.repository.Repository representing the resolved path.

Parameters

String

path

the repository path

Returns

org.ringojs.repository.Repository

a repository

See

getResource

getResource (path)

Resolve path following the same logic [require][#require] uses for module ids and return an instance of org.ringojs.repository.Resource representing the resolved path.

Parameters

String

path

the resource path

Returns

org.ringojs.repository.Resource

a resource

See

getRepository

global

A reference to the global object itself.

When a module is evaluated in RingoJS it uses its own private module scope which in turn uses this shared global object as prototype. Therefore, properties of the global object are visible in every module.

Since the global object is hidden in the prototype chain of module scopes it cannot normally be accessed directly. This reference allows you to do so, defining real global variables if you want to do so.

include (moduleId)

Load a module and include all its properties in the calling scope.

Parameters

String

moduleId

the id or path of the module to load

load (filename...)

Load JavaScript source files named by string arguments. If multiple arguments are given, each file is read in and executed in turn.

Parameters

String

filename...

one or more file names

module

The module object as defined in the CommonJS Modules 1.1.1 specification.

The RingoJS module object has the following properties:

[directory][#module.directory]
[exports][#module.exports]
[id][#module.id]
[path][#module.path]
[uri][#module.uri]
[resolve][#module.resolve]
[singleton][#module.singleton]

module.directory

The directory that contains this module.

module.exports

By default, module.exports refers to [exports][#exports] object. Setting this property to a different value will cause that value to be used as exports object instead.

module.id

The module id of this module.

module.path

The absolute path of this module's source.

module.resolve (path)

Resolve path relative to this module, like when calling [require][#require] with a moduleId starting with './' or '../'.

This returns an absolute path if the current module is a regular file. For other types of modules such as those residing in a .jar file it returs a relative path relative to the module's module path root.

Parameters

String path

Returns

String

the resolved path

module.singleton (id, factory)

module.singleton enables the creation of singletons across all workers using the same module. This means that a value within a module will be instantiated at most once for all concurrent worker threads even though workers usually operate on their own private scopes and variables.

The id argument identifies the singleton within the module. When module.singleton is called with an id that has not been initialized yet and the factory argument is defined, factory is invoked and its return value is henceforth used as singleton value for the given id.

Once the value of a singleton has been set, the factory function is never called again and all calls to module.singleton with that id return that original value.

module.singleton supports lazy initialization. A singleton can remain undefined if module.singleton is called without factory argument. In this case module.singleton returns undefined until it is first called with a factory argument.

Parameters

String	id	the singleton id
Function	factory	(optional) factory function for the singleton

Returns

the singleton value

module.uri

This module's URI.

print (arg...)

Converts each argument to a string and prints it.

Parameters

null

arg...

one ore more arguments

privileged (func)

Calls func with the privileges of the current code base instead of the privileges of the code in the call stack.

This is useful when running with Java security manager enabled using the -P or --policy command line switches.

Parameters

Function

func

a function

Returns

Object

the return value of the function

quit ()

Quit the RingoJS shell. The shell will also quit in interactive mode if an end-of-file character (CTRL-D) is typed at the prompt.

require (moduleId)

The require function as defined in the CommonJS Modules 1.1.1 specification.

moduleId is resolved following these rules:

If moduleId starts with './' or '../' it is resolved relative to the current module.
If moduleId is relative (starting with a file or directory name), it is resolve relative to the module search path.
If path is absolute (e.g. starting with '/') it is interpreted as absolute file name.

The RingoJS require function has the following properties:

[extensions][#require.extensions]
[main][#require.main]
[paths][#require.paths]

Parameters

String

moduleId

the id or path of the module to load

Returns

Object

the exports object of the required module

require.extensions

An object used to extend the way [require][#require] loads modules.

Use a file extension as key and a function as value. The function should accept a Resource object as argument and return either a string to be used as JavaScript module source or an object which will be directly returned by require.

For example, the following one-liner will enable require() to load XML files as E4X modules:

require.extensions['.xml'] = function(r) new XML(r.content);

require.main

If RingoJS was started with a command line script, require.main contains the module object of the main module. Otherwise, this property is defined but has the value undefined.

require.paths

An array that contains the module search path. You can add or remove paths items to or from this array in order to change the places where RingoJS will look for modules.

seal (obj)

Seal the specified object so any attempt to add, delete or modify its properties would throw an exception.

Parameters

Object

obj

a JavaScript object

setInterval (callback, delay, args)

Calls a function repeatedly, with a fixed time delay between each call to that function. The function will be called in the thread of the local event loop. This means it will only run after the currently executing code and other code running before it have terminated.

Parameters

function	callback	a function
number	delay	the delay in milliseconds
...	args	optional arguments to pass to the function

Returns

object

an id object useful for cancelling the scheduled invocation

See

clearInterval

setTimeout (callback, delay, [args])

Executes a function after specified delay. The function will be called in the thread of the local event loop. This means it will only run after the currently executing code and other code running before it have terminated.

Parameters

function	callback	a function
number	delay	the delay in milliseconds
...	[args]	optional arguments to pass to the function

Returns

object

an id object useful for cancelling the scheduled invocation

See

clearTimeout

spawn (func)

Calls func in a new thread from an internal thread pool and returns immediately.

Parameters

Function

func

a function

sync (func, [obj])

Returns a wrapper around a function that synchronizes on the original function or, if provided, on the second argument.

When multiple threads call functions that are synchronized on the same object, only one function call is allowed to execute at a time.

Parameters

Function	func	a function
Object	[obj]	optional object to synchronize on

Returns

Function

a synchronized wrapper around the function

RingoJS 0.9

• Overview • Module Index