Script Input Stream

Script Input Stream represents a stream that can be used to read a file.

Script Input Stream can be created using the Script Application method newInputStream(), passing it the file storage key of the file you want to read, or use method newStringInputStream(), passing it a string that you want to read as a stream.

The methods raise exceptions if there are errors, and should be called within a try .. finally block to ensure the stream is closed, as in the following example.

var inputStream = application.newInputStream(storageKey);
var contents;
try {
contents = inputStream.readAll();
} finally {
inputStream.close();
}
char = read() Read a single character string from the input stream. Return null at the end of the stream.
line = readLine() Read a single line from the input stream. Return null at the end of the stream.
string = readAll() Read all of the input stream. This may return an empty string.
object = readJSON(default)

Read the entire stream as a JSON object. This is equivalent to JSON.parse(inputStream.readAll()), but may be more efficient.

If there is an error, if the default result is passed, that is used as the result. If default is not passed, an exception is raised.

nextJSONToken(callback[,raiseException])

Read the next JSON token from the stream and call the callback function with it.

If raiseException is set to false, the callback will be passed errors. If omitted or set to true, errors will result in exceptions.

The callback function is passed three arguments of type string: tokenType, tokenName and tokenValue. The token types are described below. Within an object, tokenName will contain the property name of the token. tokenValue contains the string value of the token.

The callback should return true to signal that processing should continue, or false to continue that processing should stop.

The call to nextJSONToken() will return true if processing should continue, or false if processing should stop, for example at the end of the stream. This will generally be the same as the return from the callback, but END and ERROR always return false.

START Start of the stream.
START_OBJECT A start object has been read.
END_OBJECT An end object has been read.
START_ARRAY A start array has been read.
END_ARRAY An end array has been read.
VALUE_STRING A string has been read into tokenValue.
VALUE_NUMBER A number has been read into tokenValue.
VALUE_TRUE A true value has been read into tokenValue.
VALUE_FALSE A false value has been read into tokenValue.
VALUE_NULL A null value has been read into tokenValue.
END End of the stream.
ERROR An error has been encountered. The error message will be in tokenValue. Errors are only passed to the callback if raiseException is set to false.
parseJSONStream(callback[,raiseException]);

Like nextJSONToken(), except that the callback is called for each JSON token.

Return true from the callback to continue processing the JSON, or false to abandon processing.

readCurrentJSONObject([raiseException])

When a callback has received a START_OBJECT or START_ARRAY type, calling this will parse and return the entire object or array.

This would typically be used with nextJSONToken(), but could be used with parseJSONStream().

The method will raise an exception if it does not immediately follow the retrieval of a START_OBJECT or START_ARRAY token.

If raiseException is set to false, the method will return null rather then an exception. However, the stream will be in an error state and no further reading should be attempted.

copyTo(outputStream) Copy all of this input stream to an output stream.
close() Close the stream. Close should be called in a finally block to release resources if there are exceptions.