Standard library

io

ballerina/io

Overview

This module provides file read/write APIs and console print/read APIs. The file APIs allow read and write operations on different kinds of file types such as bytes, text, CSV, JSON, and XML. Further, these file APIs can be categorized as streaming and non-streaming APIs.

The file I/O operations can be categorized further based on the serialization and deserialization types such as:

  • Bytes I/O
  • Strings I/O
  • CSV I/O
  • JSON I/O
  • XML I/O

Console I/O

The console I/O APIs, which help you to read from the console as well as write to the console are as follows.

  • io:print
  • io:println
  • io:readln

Bytes I/O

The bytes I/O APIs provide the reading and writing APIs in both streaming and non-streaming ways. Those APIs are,

  • io:fileReadBytes
  • io:fileReadBlocksAsStream
  • io:fileWriteBytes
  • io:fileWriteBlocksFromStream

Strings I/O

The strings I/O APIs provide the reading and writing APIs in 3 different ways:

  1. Read the complete file content as a string and write a given string to a file
  2. Read the complete file content as a set of lines and write a given set of lines to a file
  3. Read the complete file content as a stream of lines and write a given stream of lines to a file

The strings I/O APIs are as follows:

  • io:fileReadString
  • io:fileReadLines
  • io:fileReadLinesAsStream
  • io:fileWriteLines
  • io:fileWriteLinesFromStream

CSV I/O

The CSV I/O APIs provide the reading and writing APIs in both streaming and non-streaming ways. Those APIs are:

  • io:fileReadCsv
  • io:fileReadCsvAsStream
  • io:fileWriteCsv
  • io:fileWriteCsvFromStream

JSON I/O

The JSON I/O APIs provide the reading and writing APIs for JSON content. Those APIs are:

  • io:fileReadJson
  • io:fileWriteJson

XML I/O

The XML I/O APIs provide the reading and writing APIs for XML content. Those APIs are:

  • io:fileReadXml
  • io:fileWriteXml

Functions

[28]

createReadableChannel

Creates an in-memory channel, which will be a reference stream of bytes.

fileReadBlocksAsStream

Read the entire file content as a stream of blocks.

fileReadBytes

Read the entire file content as a byte array.

fileReadCsv

Read file content as a CSV.

fileReadCsvAsStream

Read file content as a CSV.

fileReadJson

Reads file content as a JSON.

fileReadLines

Reads the entire file content as a list of lines.

fileReadLinesAsStream

Reads file content as a stream of lines.

fileReadString

Reads the entire file content as a string.

fileReadXml

Reads file content as an XML.

fileWriteBlocksFromStream

Write a byte stream to a file.

fileWriteBytes

Write a set of bytes to a file.

fileWriteCsv

Write CSV content to a file.

fileWriteCsvFromStream

Write CSV record stream to a file.

fileWriteJson

Write a JSON to a file.

fileWriteLines

Write an array of lines to a file.

fileWriteLinesFromStream

Write stream of lines to a file.

fileWriteString

Write a string content to a file.

fileWriteXml

Write XML content to a file.

fprint

Prints any, error, or string templates(such as The respective int value is ${val}) value(s) to a given stream(STDOUT or STDERR).

fprintln

Prints any, error, or string templates(such as The respective int value is ${val}) value(s) to a given stream(STDOUT or STDERR) followed by a new line.

openReadableCsvFile

Retrieves a readable CSV channel from a given file path.

openReadableFile

Retrieves a ReadableByteChannel from a given file path.

openWritableCsvFile

Retrieves a writable CSV channel from a given file path.

openWritableFile

Retrieves a WritableByteChannel from a given file path.

print

Prints any, error, or string templates (such as The respective int value is ${val}) value(s) to the STDOUT.

println

Prints any, error or string templates(such as The respective int value is ${val}) value(s) to the STDOUT followed by a new line.

readln

Retrieves the input read from the STDIN.

Classes

[14]

BlockStream

The BlockStream is used to initialize a stream of type Block.

CSVStream

The io:CSVStream is used to initialize a stream of type CSV records.

LineStream

The io:LineStream is used to initialize a stream of the type strings(lines).

ReadableByteChannel

ReadableByteChannel represents an input resource (i.e file), which could be used to source bytes.

ReadableCharacterChannel

Represents a channel, which could be used to read characters through a given ReadableByteChannel.

ReadableCSVChannel

Represents a ReadableCSVChannel which could be used to read records from CSV file.

ReadableDataChannel

Represents a data channel for reading data.

ReadableTextRecordChannel

Represents a channel which will allow to read.

StringReader

Represents a reader which will wrap string content as a channel.

WritableByteChannel

WritableByteChannel represents an output resource (i.e file) which could be used to sink bytes A file path can be used to obtain an io:WritableByteChannel.

WritableCharacterChannel

Represents a channel which could be used to write characters through a given WritableCharacterChannel.

WritableCSVChannel

Represents a WritableCSVChannel, which could be used to write records from the CSV file.

WritableDataChannel

Represents a WritableDataChannel for writing data.

WritableTextRecordChannel

Represents a channel, which will allow to write records through a given WritableCharacterChannel.

Object types

[1]

PrintableRawTemplate

Represents raw templates.

Records

[2]

XmlDoctype

Represents the XML DOCTYPE entity.

XmlWriteOptions

The writing options of an XML.

Constants

[15]

BIG_ENDIAN

Specifies the bytes to be in the order of most significant byte first.

COLON

Colon (:) will be use as the field separator.

COMMA

Comma (,) will be used as the field separator.

CSV

Field separator will be "," and the record separator will be a new line.

CSV_RECORD_SEPARATOR

Represents the record separator of the CSV file.

DEFAULT

The default value is the format specified by the CSVChannel.

DEFAULT_ENCODING

Default encoding for the abstract read/write APIs.

FS_COLON

Represents the colon separator, which should be used to identify colon-separated files.

LITTLE_ENDIAN

Specifies the byte order to be the least significant byte first.

MINIMUM_HEADER_COUNT

Represents the minimum number of headers, which will be included in the CSV.

NEW_LINE

New line character.

stderr

Represents the standard error stream.

stdout

Represents the standard output stream.

TAB

Tab (/t) will be use as the field separator.

TDF

Field separator will be a tab and the record separator will be a new line.

Enums

[2]

FileWriteOption

Represents a file opening options for writing.

XmlEntityType

Represents the XML entity type that needs to be written.

Types

[6]

Block

The read-only byte array that is used to read the byte content from the streams.

ByteOrder

Represents network byte order.

FileOutputStream

Defines the output streaming types.

Format

The format, which will be used to represent the CSV.

Printable

Defines all the printable types.

Separator

Field separators, which are supported by the DelimitedTextRecordChannel.

Errors

[8]

AccessDeniedError

This will get returned due to file permission issues.

ConfigurationError

This will get returned if there is an invalid configuration.

ConnectionTimedOutError

This will return when connection timed out happen when try to connect to a remote host.

EofError

This will get returned if read operations are performed on a channel after it closed.

Error

Represents IO module related errors.

FileNotFoundError

This will get returned if the file is not available in the given file path.

GenericError

Represents generic IO error.

TypeMismatchError

This will get returned when there is an mismatch of given type and the expected type.