MDN wants to talk to developers like you: https://qsurvey.mozilla.com/s3/8d22564490d8

io/text-streams

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Experimental

Provides streams for reading and writing text.

function readTextFromFile(filename) {
  var fileIO = require("sdk/io/file");
  var text = null;
  if (fileIO.exists(filename)) {
    var TextReader = fileIO.open(filename, "r");
    if (!TextReader.closed) {
      text = TextReader.read();
      TextReader.close();
    }
  }
  return text;
}
function writeTextToFile(text, filename) {
  var fileIO = require("sdk/io/file");
  var TextWriter = fileIO.open(filename, "w");
  if (!TextWriter.closed) {
    TextWriter.write(text);
    TextWriter.close();
  }
}

Globals

Constructors

TextReader(inputStream, charset)

Creates a buffered input stream that reads text from a backing stream using a given text encoding.

You can also create TextReader objects using io/file's open() function.

Parameters

inputStream : stream
The backing stream, an nsIInputStream. It must already be opened.

charset : string
inputStream is expected to be in the character encoding named by this value. If not specified, "UTF-8" is assumed. See nsICharsetConverterManager.idl for documentation on how to determine other valid values for this.

TextWriter(outputStream, charset)

Creates a buffered output stream that writes text to a backing stream using a given text encoding.

You can also create TextWriter objects using io/file's open() function.

Parameters

outputStream : stream
The backing stream, an nsIOutputStream. It must already be opened.

charset : string
Text will be written to outputStream using the character encoding named by this value. If not specified, "UTF-8" is assumed. See nsICharsetConverterManager.idl for documentation on how to determine other valid values for this.

TextReader

Methods

close()

Closes both the stream and its backing stream.

read(numChars)

Reads and returns a string from the stream. If the stream is closed, an exception is thrown.

Parameters

numChars : number
The number of characters to read. If not given, the remainder of the stream is read.

Returns

string : The string read. If the stream is at the end, the empty string is returned.

Properties

closed

True if the stream is closed.

TextWriter

Methods

close()

Flushes the backing stream's buffer and closes both the stream and the backing stream. If the stream is already closed, an exception is thrown.

flush()

Flushes the backing stream's buffer.

write(str)

Writes a string to the stream. If the stream is closed, an exception is thrown.

Parameters

str : string
The string to write.

writeAsync(str, callback)

Writes a string on a background thread. After the write completes, the backing stream's buffer is flushed, and both the stream and the backing stream are closed, also on the background thread. If the stream is already closed, an exception is thrown immediately.

Parameters

str : string
The string to write.

callback : callback
callback, if given, must be a function. It's called as callback(error) when the write completes. error is an Error object or undefined if there was no error. Inside callback, this is the TextWriter object.

Properties

closed

True if the stream is closed.

Document Tags and Contributors

 Contributors to this page: wbamberg, backy0175
 Last updated by: wbamberg,