system library

Joshua Shinavier edited this page May 21, 2011 · 2 revisions

The system: library contains primitives for scripting, system calls and network operations. These primitives make explicit calls into the environment of the machine running Ripple.

get

This primitive attempts to fetch a document from the Web using HTTP's GET method. It expects a single argument at the top of the stack: the URI of the resource to be fetched. It pops the URI from the stack and, after completing the GET interaction, pushes the retrieved entity in string format.

1)  <http://example.org> get.

  [1]  "<!DOCTYPE html PUBLIC \\"-//W3C//DTD XHTML 1.0 Transitional//EN\\" \\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\\">\n<html xmlns=\\"http://www.w3.org/1999/xhtml\\">\n<head>[...]"

random

This primitive takes any stack and pushes a double-precision, pseudo-random number between 0 (inclusive) and 1 (exclusive).

Example:

1)  random.

  [1]  0.12293217600977935E0

script

This primitive evaluates a script in a language other than Ripple's. Script engines must first be registered by name before they can be accessed from the Ripple scripting environment via script. The primitive expects two arguments at the top of the stack: the script to evaluate and the name of the script engine to evaluate it. It pops the arguments from the stack, finds the registered script engine (if any) with the specified name, and evaluates the script. The script engine may either return a null value, in which case no solution is produced, or a single, native Ripple value, in which case that value is pushed to the rest of the stack.

The semantics of the script engine (i.e. the way in which it maps scripts to native values) is unspecified; each script engine behaves differently.

Since no script engines are registered by default in the Ripple distribution, this primitive normally has no effect. However, for an example of the use of script in connection with Blueprints graphs, see the blueprints library.

system

This primitive issues a system call to the underlying operating system, spawning a process and waiting for it to terminate. It expects a single argument at the top of the stack: a string which is to be interpreted as a system command. It pops the command from the stack and, after the process has terminated, pushes first the exit code of the process, then normal output and error output of the process, in string form. Since this primitive represents a security concern, it is disabled by default (to enable it in the Java implementation, edit the file ExtrasLibrary.java, then re-build Ripple).

Example:

1)  "whoami" system.

  [1]  0 "josh\n" ""

time

This primitive finds the current system time, in milliseconds since the Unix epoch. It takes any stack and pushes the time onto the stack.

Example:

1)  time.

  [1]  "1305540724225"^^xsd:long