RNotebook API Reference

Version 0.00.00
Preliminary Draft
Subject to change without notice.

Introduction

RNotebook is designed as a scripting platform offering a set of useful tools, available in the form Java objects. This document describes application programming interface for these tools.
The tools are grouped in the following categories:

Built-in Objects
FS - File system
IO - Input/Output subsystem
NB - Notebook functions
NET - Network access functions
OS - Operating system functions
UT - Utility functions

In addition, full set of Java runtime classes are available for scripts via Mozilla Rhino Java bindings.

Built-in Objects

The benefit of RNotebook is intended to come from a set of tools and utility classes that simplify writing scripts for common tasks. These classes are:

DTable
DTableReader
JImage
JsFileSyncTool

DTable

DTable provides storage for columnar data.

addColumn(name)

Add a named column.

addRow([val], ...)

Adds row of values. The table creates additional columns when necessary.

copy()

Creates a new copy of the table.

getColumnCount()
columnCount

Returns the number of columns.

getColumnName(columnIndex)

Returns the name of the specified column.

getDataRow(row)

Returns the specified data row in the form of an Object[].

getRowCount()
rowCount

Returns the number of rows in the table.

getValue(row, column)

Returns the value stored in the specified row and column.

setColumns(columns)

Sets all column names in one operation. Expects a String[].

setValue(row, column)

Store a value in the specified row and column. Additional empty rows or columns are created when necessary. Keep in mind that a limited set of data objects can be persisted [TODO:explain which] in a notebook file.

DTableReader

DTableReader should be used to import CSV or TSV file, where custom parsing of numeric and date/time values is required.

readFile(file)

Reads and parses the file. Returns an instance of DTable.

setColumnName(column, name)

Sets the name of the specified column. This method should not be called together with setFirstRowContainsColumnNames().

setColumnType(column, type)

Sets the column type for the column. Valid types are: 'string', 'date', 'time', 'date_time', 'float', 'double', 'int', 'long'.

setDateFormat(format)

Sets the date format (using SimpleDateFormat pattern notation).

setDateTimeFormat(format)

Sets the date_time format (using SimpleDateFormat pattern notation).

setDecimalSeparator(sep)

Sets decimal separator character to be used for parsing numeric types. Accepted values are '.' and ','. When parsing, only the decimal separator is used, all other symbols will be silently ignored.

setEncoding(encoding)

Sets the file encoding, using Java Charset patterns.

setFirstRowContainsColumnNames(bool)

Informs the reader whether to expect column names in the first row.

setLenient(bool)

When set, cells with parsing errors will be set to the string value read from the file.

setTimeFormat(format)

Sets the time format (using SimpleDateFormat pattern notation).

JImage

JImage instance contains a BufferedImage along with a number of methods designed to simplify programmatic creation of images and icons.

copy()

Creates a copy of the image.

fillRect(x, y, width, height)

Fills the specified rectangle with the color previously set by setColor().

getBufferedImage()
bufferedImage

Returns a copy of underlying BufferedImage.

getHeight()
height

Returns the image height in pixels.

getWidth()
width

Returns the image width in pixels.

invert()
width

Inverts image RGB channels.

scale(factor)
width

Resizes the image.

setColor(name)
setColor(red, green, blue)
setColor(red, green, blue, alpha)

Sets current color. Accepted color names are either #RGB, #RRGGBB, or valid SVG names.

JsFileSyncTool

JsFileSyncTool provides directory synchronization functionality. The result of the sync process is to make target directory contain the same files and subdirectories as the source, less the files blocked by the optional filter.

addJob(source, target)

Adds a pair of source and target directories to be synchronized.

addJob(source, target, filter)

Adds a pair of source and target directories to be synchronized with the specified filter.
See also setFilter().

addSource(source)

Adds a source directory.

addSource(source, filter)

Adds a source directory along with a filter.
See also setFilter().

getGui()
gui

Creates and returns a GUI component for the associated sync operation. This component can be displayed with NB.display() function to provide real time information.

setFilter(spec)

Sets the global file filter for the synchronization operation. Filter spec is either a single string containing newline (\n) separated items or a JavaScript array of items in the following format:
"-hidden": excludes hidden files and folders
"-system": excludes system files and folders
"- A/": excludes folders named A
"+ A/": includes folders named A, overriding previously specified exclusions
"- B": excludes files named B
"+ B": includes files named B, overriding previously specified exclusions
"- /PATH": excludes paths specified relative to the current source folder
"+ /PATH": includes paths specified relative to the current source folder

setGranularity(ms)

Sets maximum difference in milliseconds to consider when comparing file timestamps.

setIgnoreFailures(bool)

Determines whether errors should be ignored during the process.

setTarget(target)

Sets the default target directory.

sync()

Performs the syncronization.

FS - File System

There are two ways of accessing the filesystem in RNotebook: using standard java.io.File class or via a set of methods provided by the top-level FS object.

FS.exists(file)

Tests whether the file exists.

FS.freeSpace
FS.getFreeSpace(path)

Returns the amount of free space on a disk represented by the path.

FS.isDirectory(path)

Tests whether the file denoted by this path is a directory.

FS.isFile(path)

Tests whether the file denoted by this path is a normal file.

FS.isHidden(path)

Tests whether the file denoted by this path is a hidden file

FS.lastModified(file)

Returns the file timestamp in milliseconds.

FS.ls([path],...)

Lists files.

FS.newSync()

Creates an instance of directory synchronization tool object JsFileStynTool.

FS.pwd()

Returns the current directory.

FS.sync(source, target)

Synchronizes target directory with the source, ignoring any errors. Use FS.newSync() when more control of directory synchronization process is required.

FS.tempFile(prefix, suffix)

Creates a temporary file.

FS.totalSpace, getTotalSpace(path)

Returns the amount of total space.

FS.touch(file)

Updates the timestamp of a file, creating it if necessary

IO - Input/Output Subsystem

IO.loadImage(file)

Loads image file. This method returns an instance of JImage class.

IO.loadTable(file)

Loads table from CSV, XLS, or XLSX file. This method should be used to deal with simple tables.
In situations where custom dates, numbers, or encodings are involved it is better to configure a custom table reader obtained with IO.newTableReader().

IO.newTableReader()

Creates a table reader, an instance of DTableReader class.

IO.readBytes(file)

Reads byte array from a file.

IO.readText(file)

Reads text from a UTF-8 encoded file.

IO.readText(file, encoding)

Reads text from a file with the specified encoding.

IO.writeBytes(bytes, file)

Writes byte array to a file.

IO.writeText(text, file)

Writes text to a file in UTF-8 encoding.

IO.writeText(text, encoding, file)

Writes text to a file with the specified encoding.

NB - Notebook Functions

NB.display(x)

Displays an object in the code output section of the notebook. The notebook creates an immutable copy of the underlying data object, except for JComponents.

NB.getValue(key)

Returns a string value from the internal data storage.

NB.setValue(key, value)

Stores a string value in the internal data storage.

NET - Network Access Functions

NET.email(address, subject, text)

Sends a simple email. For other cases, please use NET.newMailMessage() method. (To be implemented).

NET.get(url)

Returns content specified by the URL. The exact type of the object returned depends on the content-type of the response. A java.lang.String or JSImage can ne returned.

NET.inBrowser(url)

Opens a link in a browser. The result may depend on whether an underlying OS is configured to open a link in a browser.

NET.newMailMessage()

Creates an instance of email message. (To be implemented).

NET.post(url, data)

Uploads an object to the URL via HTTP POST request. (To be implemented).

OS - Operating System Functions

OS.arch

Returns the OS architecture.

OS.cpuCount

Returns number of available processor cores.

OS.exec(cmd, [arg], ...)

Executes an external executable waiting for it to finish.

OS.freeMem

Returns the amount of free memory in the JVM.

OS.hostName

Returns the host name.

OS.launch(cmd, [arg], ...)

Launches an external executable without waiting for it to finish.

OS.maxMem

Returns the maximum amount of memory that the JVM will attempt to use.

OS.name

Returns the OS name.

OS.time

Returns the current time in milliseconds.

OS.totalMem

Returns the total amount of memory in the JVM.

OS.usedMem

Returns the amount of memory currently being used.

OS.userName

Returns the user name.

OS.version

Returns the OS version.

UT - Utility Functions

UT.decodeBase64(string)

Decodes Base64-encoded string.

UT.decodeHex(string)

Decodes a hexadecimal string.

UT.encodeBase64(bytes)

Encodes a byte array using Base64.

UT.encodeHex(bytes)

Encodes a byte array into a hexadecimal string.

UT.hslColor(hue,saturation,luminocity)

Create color with the specified HSL values.

UT.parse(html)

Parses HTML document. Returns Jsoup Document instance.

UT.sleep(ms)

Sleeps for the specified number of milliseconds.