Specification: Ballerina I/O Library

Owners: @daneshk @BuddhiWathsala
Reviewers: @daneshk
Created: 2021/12/04
Updated: 2022/02/17
Edition: Swan Lake

Introduction

This is the specification for the I/O standard library of Ballerina language, which provides file related I/O operations.

The I/O library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in GitHub.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

Contents

  1. Overview
  2. Console I/O
  3. Bytes I/O
  4. Strings I/O
  5. CSV I/O
  6. JSON I/O
  7. XML I/O

1. Overview

Ballerina I/O standard library has six aspects of I/O operations.

  1. Console I/O
  2. Bytes I/O
  3. Strings I/O
  4. CSV I/O
  5. JSON I/O
  6. XML I/O

2. Console I/O

Console I/O contains APIs to read from the console, write to the console, and write to given output streams.

The following API reads content from standard input and return it as a string to the user.

The following two APIs write a given input to the standard output.

Here, the print API prints the given values as it is and the println API prints the input followed by a new line. In addition, both these print APIs support string templates as inputs like the following example.

The following two APIs allow users to write a given set of inputs to a specific output stream (STDOUT or STDERR).

As the print APIs, the fprint APIs also support string templates.

3. Bytes I/O

The bytes I/O APIs can be further categorized based on their streaming capabilities as streaming and non-streaming APIs.

Non-Streaming APIs

The following API reads the content of a given input file as a read-only bytes array and return it.

The following API writes given bytes content to a given file.

In write APIs, users can specify the option, either overwriting the existing file or appending it to the given file.

Streaming APIs

The following API reads the content of a given input file as a stream of blocks. Here, a block defines as a read-only bytes array.

The following API writes a given byte stream to a given file.

4. Strings I/O

Non-Streaming APIs

The following API reads the content of a given input file as a string.

The following API writes given string content to a given file.

The following API reads the content of a given input file line by line and return a string array, and the string array contains each line as a string.

The following API writes a given array of lines to a given file.

Streaming APIs

The following API reads the content of a given input file as a stream of lines.

The following API writes a given line stream to a given file.

5. CSV I/O

Non-Streaming APIs

The following API reads the content of a given CSV file as a string array of arrays. Here, each CSV record represents as a string array.

The following API writes given CSV content to a given file.

The following API reads the content of a given CSV file as a stream of string arrays. Here, each CSV record represents as a string array.

The following API writes a given CSV stream to a given file.

6. JSON I/O

The following API reads the content of a given JSON file and returns a Ballerina JSON object.

The following API writes given JSON to a given file.

7. XML I/O

The following API reads the content of a given XML file and returns a Ballerina XML object.

The following API writes given XML to a given file.

The XML entity type details can pass to the fileWriteXml using the XmlWriteOptions.