Module io
API
Declarations
ballerina/io Ballerina library
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:
- Read the complete file content as a string and write a given string to a file
- Read the complete file content as a set of lines and write a given set of lines to a file
- 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![](/images/permalink.svg)
createReadableChannel![](/images/permalink.svg)
function createReadableChannel(byte[] content) returns ReadableByteChannel|Error
Creates an in-memory channel, which will be a reference stream of bytes.
var byteChannel = io:createReadableChannel(content);
Parameters
- content byte[] - Content, which should be exposed as a channel
Return Type
- ReadableByteChannel|Error - The
io:ReadableByteChannel
related to the given bytes or else anio:Error
if any error occurred
fileReadBlocksAsStream![](/images/permalink.svg)
Read the entire file content as a stream of blocks.
stream<io:Block, io:Error?>|io:Error content = io:fileReadBlocksAsStream("./resources/myfile.txt", 1000);
fileReadBytes![](/images/permalink.svg)
Read the entire file content as a byte array.
byte[]|io:Error content = io:fileReadBytes("./resources/myfile.txt");
Parameters
- path string - The path of the file
Return Type
- readonly & byte[]|Error - A read-only byte array or an
io:Error
fileReadCsv![](/images/permalink.svg)
Read file content as a CSV.
string[][]|io:Error content = io:fileReadCsv("./resources/myfile.csv");
fileReadCsvAsStream![](/images/permalink.svg)
Read file content as a CSV.
stream<string[], io:Error?>|io:Error content = io:fileReadCsvAsStream("./resources/myfile.csv");
Parameters
- path string - The CSV file path
fileReadJson![](/images/permalink.svg)
Reads file content as a JSON.
json|io:Error content = io:fileReadJson("./resources/myfile.json");
Parameters
- path string - The path of the JSON file
Return Type
- json|Error - The file content as a JSON object or an
io:Error
fileReadLines![](/images/permalink.svg)
Reads the entire file content as a list of lines.
The resulting string array does not contain the terminal carriage (e.g., \r
or \n
).
string[]|io:Error content = io:fileReadLines("./resources/myfile.txt");
Parameters
- path string - The path of the file
fileReadLinesAsStream![](/images/permalink.svg)
Reads file content as a stream of lines.
The resulting stream does not contain the terminal carriage (e.g., \r
or \n
).
stream<string, io:Error?>|io:Error content = io:fileReadLinesAsStream("./resources/myfile.txt");
Parameters
- path string - The path of the file
fileReadString![](/images/permalink.svg)
Reads the entire file content as a string
.
The resulting string output does not contain the terminal carriage (e.g., \r
or \n
).
string|io:Error content = io:fileReadString("./resources/myfile.txt");
Parameters
- path string - The path of the file
fileReadXml![](/images/permalink.svg)
Reads file content as an XML.
xml|io:Error content = io:fileReadXml("./resources/myfile.xml");
Parameters
- path string - The path of the XML file
fileWriteBlocksFromStream![](/images/permalink.svg)
function fileWriteBlocksFromStream(string path, stream<byte[], Error?> byteStream, FileWriteOption option) returns Error?
Write a byte stream to a file.
byte[] content = [[60, 78, 39, 28]]; stream<byte[], io:Error?> byteStream = content.toStream(); io:Error? result = io:fileWriteBlocksFromStream("./resources/myfile.txt", byteStream);
Parameters
- path string - The path of the file
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- Error? - An
io:Error
or else()
fileWriteBytes![](/images/permalink.svg)
function fileWriteBytes(string path, byte[] content, FileWriteOption option) returns Error?
Write a set of bytes to a file.
byte[] content = [60, 78, 39, 28]; io:Error? result = io:fileWriteBytes("./resources/myfile.txt", content);
Parameters
- path string - The path of the file
- content byte[] - Byte content to write
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- Error? - An
io:Error
or else()
fileWriteCsv![](/images/permalink.svg)
function fileWriteCsv(string path, string[][] content, FileWriteOption option) returns Error?
Write CSV content to a file.
string[][] content = [["Anne", "Johnson", "SE"], ["John", "Cameron", "QA"]]; io:Error? result = io:fileWriteCsv("./resources/myfile.csv", content);
Parameters
- path string - The CSV file path
- content string[][] - CSV content as an array of string arrays
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- Error? - An
io:Error
or()
when the writing was successful
fileWriteCsvFromStream![](/images/permalink.svg)
function fileWriteCsvFromStream(string path, stream<string[], Error?> content, FileWriteOption option) returns Error?
Write CSV record stream to a file.
string[][] content = [["Anne", "Johnson", "SE"], ["John", "Cameron", "QA"]]; stream<string[], io:Error?> recordStream = content.toStream(); io:Error? result = io:fileWriteCsvFromStream("./resources/myfile.csv", recordStream);
Parameters
- path string - The CSV file path
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- Error? - An
io:Error
or()
when the writing was successful
fileWriteJson![](/images/permalink.svg)
Write a JSON to a file.
json content = {"name": "Anne", "age": 30}; io:Error? content = io:fileWriteJson("./resources/myfile.json");
Return Type
- Error? -
()
when the writing was successful or anio:Error
fileWriteLines![](/images/permalink.svg)
function fileWriteLines(string path, string[] content, FileWriteOption option) returns Error?
Write an array of lines to a file.
During the writing operation, a newline character \n
will be added after each line.
string[] content = ["Hello Universe..!!", "How are you?"]; io:Error? result = io:fileWriteLines("./resources/myfile.txt", content);
Parameters
- path string - The path of the file
- content string[] - An array of string lines to write
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- Error? -
()
when the writing was successful or anio:Error
fileWriteLinesFromStream![](/images/permalink.svg)
function fileWriteLinesFromStream(string path, stream<string, Error?> lineStream, FileWriteOption option) returns Error?
Write stream of lines to a file.
During the writing operation, a newline character \n
will be added after each line.
string content = ["Hello Universe..!!", "How are you?"]; stream<string, io:Error?> lineStream = content.toStream(); io:Error? result = io:fileWriteLinesFromStream("./resources/myfile.txt", lineStream);
Parameters
- path string - The path of the file
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- Error? -
()
when the writing was successful or anio:Error
fileWriteString![](/images/permalink.svg)
function fileWriteString(string path, string content, FileWriteOption option) returns Error?
Write a string content to a file.
string content = "Hello Universe..!!"; io:Error? result = io:fileWriteString("./resources/myfile.txt", content);
Parameters
- path string - The path of the file
- content string - String content to write
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- Error? -
()
when the writing was successful or anio:Error
fileWriteXml![](/images/permalink.svg)
function fileWriteXml(string path, xml content, FileWriteOption fileWriteOption, *XmlWriteOptions xmlOptions) returns Error?
Write XML content to a file.
xml content = xml `<book>The Lost World</book>`; io:Error? result = io:fileWriteXml("./resources/myfile.xml", content);
Parameters
- path string - The path of the XML file
- content xml - XML content to write
- fileWriteOption FileWriteOption (default OVERWRITE) - file write option(
OVERWRITE
andAPPEND
are the possible values, and the default value isOVERWRITE
)
- xmlOptions *XmlWriteOptions - XML writing options(XML entity type and DOCTYPE)
Return Type
- Error? -
()
value when the writing was successful or anio:Error
fprint![](/images/permalink.svg)
function fprint(FileOutputStream fileOutputStream, Printable... values)
Prints any
, error
, or string templates(such as The respective int value is ${val}
) value(s) to
a given stream(STDOUT or STDERR).
io:fprint(io:stderr, "Unexpected error occurred");
Parameters
- fileOutputStream FileOutputStream - The output stream (
io:stdout
orio:stderr
) content needs to be printed
- values Printable... - The value(s) to be printed
fprintln![](/images/permalink.svg)
function fprintln(FileOutputStream fileOutputStream, Printable... values)
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.
io:fprintln(io:stderr, "Unexpected error occurred");
Parameters
- fileOutputStream FileOutputStream - The output stream (
io:stdout
orio:stderr
) content needs to be printed
- values Printable... - The value(s) to be printed
openReadableCsvFile![](/images/permalink.svg)
function openReadableCsvFile(string path, Separator fieldSeparator, string charset, int skipHeaders) returns ReadableCSVChannel|Error
Retrieves a readable CSV channel from a given file path.
io:ReadableCSVChannel rCsvChannel = check io:openReadableCsvFile(srcFileName);
Parameters
- path string - File path, which describes the location of the CSV
- fieldSeparator Separator (default ",") - CSV record separator (i.e., comma or tab)
- charset string (default "UTF-8") - Representation of the encoding characters in the file
- skipHeaders int (default 0) - Number of headers, which should be skipped
Return Type
- ReadableCSVChannel|Error - The
io:ReadableCSVChannel
, which could be used to iterate through the CSV records or else anio:Error
if any error occurred
openReadableFile![](/images/permalink.svg)
function openReadableFile(string path) returns ReadableByteChannel|Error
Retrieves a ReadableByteChannel
from a given file path.
io:ReadableByteChannel readableFieldResult = check io:openReadableFile("./files/sample.txt");
Parameters
- path string - Relative/absolute path string to locate the file
Return Type
- ReadableByteChannel|Error - The
io:ReadableByteChannel
related to the given file or else anio:Error
if there is an error while opening
openWritableCsvFile![](/images/permalink.svg)
function openWritableCsvFile(string path, Separator fieldSeparator, string charset, int skipHeaders, FileWriteOption option) returns WritableCSVChannel|Error
Retrieves a writable CSV channel from a given file path.
io:WritableCSVChannel wCsvChannel = check io:openWritableCsvFile(srcFileName);
Parameters
- path string - File path, which describes the location of the CSV
- fieldSeparator Separator (default ",") - CSV record separator (i.e., comma or tab)
- charset string (default "UTF-8") - Representation of the encoding characters in the file
- skipHeaders int (default 0) - Number of headers, which should be skipped
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- WritableCSVChannel|Error - The
WritableCSVChannel
, which could be used to write the CSV records or else anio:Error
if any error occurred
openWritableFile![](/images/permalink.svg)
function openWritableFile(string path, FileWriteOption option) returns WritableByteChannel|Error
Retrieves a WritableByteChannel
from a given file path.
io:WritableByteChannel writableFileResult = check io:openWritableFile("./files/sampleResponse.txt");
Parameters
- path string - Relative/absolute path string to locate the file
- option FileWriteOption (default OVERWRITE) - To indicate whether to overwrite or append the given content
Return Type
- WritableByteChannel|Error - The
io:WritableByteChannel
related to the given file or else anio:Error
if any error occurred
print![](/images/permalink.svg)
function print(Printable... values)
Prints any
, error
, or string templates(such as The respective int value is ${val}
) value(s) to the STDOUT.
io:print("Start processing the CSV file from ", srcFileName);
Parameters
- values Printable... - The value(s) to be printed
println![](/images/permalink.svg)
function println(Printable... values)
Prints any
, error
or string templates(such as The respective int value is ${val}
) value(s) to the STDOUT
followed by a new line.
io:println("Start processing the CSV file from ", srcFileName);
Parameters
- values Printable... - The value(s) to be printed
readln![](/images/permalink.svg)
function readln(any? a) returns string
Retrieves the input read from the STDIN.
string choice = io:readln("Enter choice 1 - 5: "); string choice = io:readln();
Parameters
- a any? (default ()) - Any value to be printed
Return Type
- string - Input read from the STDIN
Classes![](/images/permalink.svg)
io: BlockStream![](/images/permalink.svg)
The BlockStream
is used to initialize a stream of type Block
. This BlockStream
refers to the stream that is embedded to
the I/O byte channels.
Constructor![](/images/permalink.svg)
Initialize a BlockStream
using an io:ReadableByteChannel
.
init (ReadableByteChannel readableByteChannel, int blockSize)
- readableByteChannel ReadableByteChannel - The
io:ReadableByteChannel
that this block stream is referred to
- blockSize int - The size of a block as an integer
next![](/images/permalink.svg)
The next function reads and returns the next block of the related stream.
Return Type
close![](/images/permalink.svg)
function close() returns Error?
Closes the stream. The primary usage of this function is to close the stream without reaching the end
If the stream reaches the end, the BlockStream.next()
will automatically close the stream.
Return Type
- Error? -
()
when the closing was successful or anio:Error
io: CSVStream![](/images/permalink.svg)
The io:CSVStream
is used to initialize a stream of type CSV records. This io:CSVStream
refers to the stream
that is embedded to the I/O record channels.
Constructor![](/images/permalink.svg)
Initialize a CSVStream
using an io:ReadableTextRecordChannel
.
init (ReadableTextRecordChannel readableTextRecordChannel)
- readableTextRecordChannel ReadableTextRecordChannel - The
io:ReadableTextRecordChannel
that this CSV stream is referred to
next![](/images/permalink.svg)
The next function reads and returns the next CSV record of the related stream.
Return Type
close![](/images/permalink.svg)
function close() returns Error?
Close the stream. The primary usage of this function is to close the stream without reaching the end.
If the stream reaches the end, the CSVStream.next()
will automatically close the stream.
Return Type
- Error? -
()
when the closing was successful or anio:Error
io: LineStream![](/images/permalink.svg)
The io:LineStream
is used to initialize a stream of the type strings(lines). This io:LineStream
refers to the
stream that is embedded to the I/O character channels.
Constructor![](/images/permalink.svg)
Initialize an io:LineStream
using an io:ReadableCharacterChannel
.
init (ReadableCharacterChannel readableCharacterChannel)
- readableCharacterChannel ReadableCharacterChannel - The
io:ReadableCharacterChannel
that the line stream is referred to
next![](/images/permalink.svg)
The next function reads and returns the next line of the related stream.
Return Type
close![](/images/permalink.svg)
function close() returns Error?
Closes the stream. The primary usage of this function is to close the stream without reaching the end
If the stream reaches the end, the LineStream.next()
will automatically close the stream.
Return Type
- Error? -
()
when the closing was successful or anio:Error
io: ReadableByteChannel![](/images/permalink.svg)
ReadableByteChannel represents an input resource (i.e file), which could be used to source bytes.
A file path or an in-memory byte
array can be used to obtain an io:ReadableByteChannel
.
An io:ReadableByteChannel
does not support initialization, and it should be obtained using the following methods or implemented natively.
io:openReadableFile("./files/sample.txt")
- used to obtain an io:ReadableByteChannel
from a given file path
io:createReadableChannel(byteArray)
- used to obtain an io:ReadableByteChannel
from a given byte
array
read![](/images/permalink.svg)
Source bytes from a given input resource.
This operation will be asynchronous in which the total number of required bytes might not be returned at a given
time. An io:EofError
will return once the channel reaches the end.
byte[]|io:Error result = readableByteChannel.read(1000);
Parameters
- nBytes int - A positive integer. Represents the number of bytes, which should be read
Return Type
- byte[]|Error - Content (the number of bytes) read, an
EofError
once the channel reaches the end or else anio:Error
readAll![](/images/permalink.svg)
function readAll() returns readonly & byte[]|Error
Read all content of the channel as a byte
array and return a read only byte
array.
byte[]|io:Error result = readableByteChannel.readAll();
Return Type
- readonly & byte[]|Error - A read-only
byte
array or else anio:Error
blockStream![](/images/permalink.svg)
Return a block stream that can be used to read all byte
blocks as a stream.
stream<io:Block, io:Error>|io:Error result = readableByteChannel.blockStream();
Parameters
- blockSize int - A positive integer. Size of the block.
base64Encode![](/images/permalink.svg)
function base64Encode() returns ReadableByteChannel|Error
Encodes a given io:ReadableByteChannel
using the Base64 encoding scheme.
io:ReadableByteChannel|Error encodedChannel = readableByteChannel.base64Encode();
Return Type
- ReadableByteChannel|Error - An encoded
io:ReadableByteChannel
or else anio:Error
base64Decode![](/images/permalink.svg)
function base64Decode() returns ReadableByteChannel|Error
Decodes a given Base64 encoded io:ReadableByteChannel
.
io:ReadableByteChannel|Error encodedChannel = readableByteChannel.base64Decode();
Return Type
- ReadableByteChannel|Error - A decoded
io:ReadableByteChannel
or else anio:Error
close![](/images/permalink.svg)
function close() returns Error?
Closes the io:ReadableByteChannel
.
After a channel is closed, any further reading operations will cause an error.
io:Error? err = readableByteChannel.close();
Return Type
- Error? - Will returns
()
if there is no error
io: ReadableCharacterChannel![](/images/permalink.svg)
Represents a channel, which could be used to read characters through a given ReadableByteChannel.
Constructor![](/images/permalink.svg)
Constructs an io:ReadableCharacterChannel
from a given io:ReadableByteChannel
and Charset
.
init (ReadableByteChannel byteChannel, string charset)
- byteChannel ReadableByteChannel - The
io:ReadableByteChannel
, which would be used to read the characters
- charset string - The character set, which is used to encode/decode the given bytes to characters
read![](/images/permalink.svg)
Reads a given number of characters. This will attempt to read up to the numberOfChars
characters of the channel.
An io:EofError
will return once the channel reaches the end.
string|io:Error result = readableCharChannel.read(1000);
Parameters
- numberOfChars int - Number of characters, which should be read
Return Type
readString![](/images/permalink.svg)
Read the entire channel content as a string.
string|io:Error content = readableCharChannel.readString();
readAllLines![](/images/permalink.svg)
Read the entire channel content as a list of lines.
string[]|io:Error content = readableCharChannel.readAllLines();
Return Type
readJson![](/images/permalink.svg)
function readJson() returns json|Error
Reads a JSON from the given channel.
json|io:Error result = readableCharChannel.readJson();
Return Type
- json|Error - The content that is read as a JSON or else an
io:Error
readXml![](/images/permalink.svg)
Reads an XML from the given channel.
json|io:Error result = readableCharChannel.readXml();
readProperty![](/images/permalink.svg)
Reads a property from a .properties file with a default value.
string|io:Error result = readableCharChannel.readProperty(key, defaultValue);
Parameters
- key string - The property key, which needs to be read
- defaultValue string (default "") - The default value to be returned
lineStream![](/images/permalink.svg)
Return a stream of lines that can be used to read all the lines in a file as a stream.
stream<string, io:Error>|io:Error? result = readableCharChannel.lineStream();
readAllProperties![](/images/permalink.svg)
Reads all properties from a .properties file.
map<string>|io:Error result = readableCharChannel.readAllProperties();
close![](/images/permalink.svg)
function close() returns Error?
Closes the character channel. After a channel is closed, any further reading operations will cause an error.
io:Error? err = readableCharChannel.close();
Return Type
- Error? - An error if something goes wrong while closing
io: ReadableCSVChannel![](/images/permalink.svg)
Represents a ReadableCSVChannel which could be used to read records from CSV file.
Constructor![](/images/permalink.svg)
Constructs a CSV channel from a CharacterChannel to read CSV records.
init (ReadableCharacterChannel byteChannel, Separator fs, int nHeaders)
- byteChannel ReadableCharacterChannel - The CharacterChannel, which will represent the content in the CSV file
- fs Separator "," - Field separator, which will separate between the records in the CSV file
- nHeaders int 0 - Number of headers, which should be skipped prior to reading records
skipHeaders![](/images/permalink.svg)
function skipHeaders(int nHeaders)
Skips the given number of headers.
readableCSVChannel.skipHeaders(5);
Parameters
- nHeaders int - The number of headers, which should be skipped
hasNext![](/images/permalink.svg)
function hasNext() returns boolean
Indicates whether there's another record, which could be read.
boolean hasNext = readableCSVChannel.hasNext();
Return Type
- boolean - True if there is a record
getNext![](/images/permalink.svg)
Gets the next record from the CSV file.
string[]|io:Error? record = readableCSVChannel.getNext();
csvStream![](/images/permalink.svg)
Returns a CSV record stream that can be used to CSV records as a stream.
stream<string[], io:Error>|io:Error? record = readableCSVChannel.csvStream();
close![](/images/permalink.svg)
function close() returns Error?
Closes the io:ReadableCSVChannel
.
After a channel is closed, any further reading operations will cause an error.
io:Error? err = readableCSVChannel.close();
Return Type
- Error? - An
io:Error
if any error occurred
getTable![](/images/permalink.svg)
function getTable(typedesc<record {}> structType, string[] fieldNames) returns table<record { }>|Error
Returns a table, which corresponds to the CSV records.
var tblResult1 = readableCSVChannel.getTable(Employee); var tblResult2 = readableCSVChannel.getTable(Employee, ["id", "name"]);
Parameters
- structType typedesc<record {}> - The object in which the CSV records should be deserialized
- fieldNames string[] (default []) - The names of the fields used as the (composite) key of the table
Return Type
- table<record { }>|Error - Table, which represents the CSV records or else an
io:Error
Deprecated
This function is deprecated due to the introduction ofReadableCSVChannel.toTable()
, making 'fieldNames' a mandatory parameter
toTable![](/images/permalink.svg)
function toTable(typedesc<record {}> structType, string[] keyFieldNames) returns table<record { }>|Error
Returns a table, which corresponds to the CSV records.
var tblResult = readableCSVChannel.toTable(Employee, ["id", "name"]);
Parameters
- structType typedesc<record {}> - The object in which the CSV records should be deserialized
- keyFieldNames string[] - The names of the fields used as the (composite) key of the table
Return Type
- table<record { }>|Error - Table, which represents the CSV records or else an
io:Error
io: ReadableDataChannel![](/images/permalink.svg)
Represents a data channel for reading data.
Constructor![](/images/permalink.svg)
Initializes the data channel.
init (ReadableByteChannel byteChannel, ByteOrder bOrder)
- byteChannel ReadableByteChannel - The channel, which would represent the source to read/write data
- bOrder ByteOrder "BE" - network byte order
readInt16![](/images/permalink.svg)
Reads a 16 bit integer.
int|io:Error result = dataChannel.readInt16();
Return Type
readInt32![](/images/permalink.svg)
Reads a 32 bit integer.
int|io:Error result = dataChannel.readInt32();
Return Type
readInt64![](/images/permalink.svg)
Reads a 64 bit integer.
int|io:Error result = dataChannel.readInt64();
Return Type
readFloat32![](/images/permalink.svg)
Reads a 32 bit float.
float|io:Error result = dataChannel.readFloat32();
Return Type
readFloat64![](/images/permalink.svg)
Reads a 64 bit float.
float|io:Error result = dataChannel.readFloat64();
Return Type
readBool![](/images/permalink.svg)
Reads a byte and convert its value to boolean.
boolean|io:Error result = dataChannel.readBool();
readString![](/images/permalink.svg)
Reads the string value represented through the provided number of bytes.
string|io:Error string = dataChannel.readString(10, "UTF-8");
Parameters
- nBytes int - Specifies the number of bytes, which represents the string
- encoding string - Specifies the char-set encoding of the string
readVarInt![](/images/permalink.svg)
Reads a variable length integer.
int|io:Error result = dataChannel.readVarInt();
Return Type
close![](/images/permalink.svg)
function close() returns Error?
Closes the data channel. After a channel is closed, any further reading operations will cause an error.
io:Error? err = dataChannel.close();
Return Type
- Error? -
()
if the channel is closed successfully or else anio:Error
if any error occurred
io: ReadableTextRecordChannel![](/images/permalink.svg)
Represents a channel which will allow to read.
Constructor![](/images/permalink.svg)
Constructs a ReadableTextRecordChannel from a given ReadableCharacterChannel.
init (ReadableCharacterChannel charChannel, string fs, string rs, string fmt)
- charChannel ReadableCharacterChannel - CharacterChannel which will point to the input/output resource
- fs string "" - Field separator (this could be a regex)
- rs string "" - Record separator (this could be a regex)
- fmt string "default" -
hasNext![](/images/permalink.svg)
function hasNext() returns boolean
Checks whether there is a record left to be read.
boolean hasNext = readableRecChannel.hasNext();
Return Type
- boolean - True if there is a record left to be read
getNext![](/images/permalink.svg)
Get the next record from the input/output resource.
string[]|io:Error record = readableRecChannel.getNext();
close![](/images/permalink.svg)
function close() returns Error?
Closes the record channel. After a channel is closed, any further reading operations will cause an error.
io:Error err = readableRecChannel.close();
Return Type
- Error? - An
io:Error
if the record channel could not be closed properly
io: StringReader![](/images/permalink.svg)
Represents a reader which will wrap string content as a channel.
readJson![](/images/permalink.svg)
function readJson() returns json|Error
Reads string as JSON using the reader.
io:StringReader reader = new("{\"name\": \"Alice\"}"); json|io:Error? person = reader.readJson();
Return Type
- json|Error - JSON or else an
io:Error
if any error occurred
readXml![](/images/permalink.svg)
Reads a string as XML using the reader.
io:StringReader reader = new("<Person><Name>Alice</Name></Person>"); xml|io:Error? person = reader.readXml();
readChar![](/images/permalink.svg)
Reads the characters from the given string.
io:StringReader reader = new("Some text"); string|io:Error? person = reader.readChar(4);
Parameters
- nCharacters int - Number of characters to be read
close![](/images/permalink.svg)
function close() returns Error?
Closes the string reader.
io:Error? err = reader.close();
Return Type
- Error? - An
io:Error
if could not close the channel or else()
io: WritableByteChannel![](/images/permalink.svg)
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
.
An io:WritableByteChannel
can only be obtained using the following method or by providing a native implementation.
It cannot be instantiated.
io:openWritableFile("./files/sample.txt")
- used to obtain an io:WritableByteChannel
from a given file path
write![](/images/permalink.svg)
Sinks bytes from a given input/output resource.
This is an asynchronous operation. The method might return before writing all the content.
int|io:Error result = writableByteChannel.write(record, 0);
Parameters
- content byte[] - Block of bytes to be written
- offset int - Offset of the provided content, which needs to be kept when writing bytes
close![](/images/permalink.svg)
function close() returns Error?
Closes the byte channel. After a channel is closed, any further writing operations will cause an error.
io:Error err = writableByteChannel.close();
Return Type
- Error? - An
io:Error
or else()
io: WritableCharacterChannel![](/images/permalink.svg)
Represents a channel which could be used to write characters through a given WritableCharacterChannel.
Constructor![](/images/permalink.svg)
Constructs an io:WritableByteChannel
from a given io:WritableByteChannel
and Charset
.
init (WritableByteChannel bChannel, string charset)
- bChannel WritableByteChannel - The
io:WritableByteChannel
, which would be used to write the characters
- charset string - The character set, which would be used to encode the given bytes to characters
write![](/images/permalink.svg)
Writes a given sequence of characters (string).
int|io:Error result = writableCharChannel.write("Content", 0);
Parameters
- content string - Content to be written
- startOffset int - Number of characters to be offset when writing the content
writeLine![](/images/permalink.svg)
Writes a string as a line with a following newline character \n
.
io:Error? result = writableCharChannel.writeLine("Content");
Parameters
- content string - Content to be written
Return Type
- Error? -
()
if the writing was successful or anio:Error
writeJson![](/images/permalink.svg)
function writeJson(json content) returns Error?
Writes a given JSON to the given channel.
io:Error? err = writableCharChannel.writeJson(inputJson, 0);
Parameters
- content json - The JSON to be written
Return Type
- Error? -
()
if the writing was successful or anio:Error
writeXml![](/images/permalink.svg)
function writeXml(xml content, XmlDoctype? xmlDoctype) returns Error?
Writes a given XML to the channel.
io:Error? err = writableCharChannel.writeXml(inputXml, 0);
Parameters
- content xml - The XML to be written
- xmlDoctype XmlDoctype? (default ()) - Optional argument to specify the XML DOCTYPE configurations
Return Type
- Error? -
()
or else anio:Error
if any error occurred
writeProperties![](/images/permalink.svg)
Writes a given key-valued pair map<string>
to a property file.
io:Error? err = writableCharChannel.writeProperties(properties);
Parameters
- comment string - Comment describing the property list
Return Type
- Error? -
()
or else anio:Error
if any error occurred
close![](/images/permalink.svg)
function close() returns Error?
Closes the io:WritableCharacterChannel
.
After a channel is closed, any further writing operations will cause an error.
io:Error err = writableCharChannel.close();
Return Type
- Error? -
()
or else anio:Error
if any error occurred
io: WritableCSVChannel![](/images/permalink.svg)
Represents a WritableCSVChannel, which could be used to write records from the CSV file.
Constructor![](/images/permalink.svg)
Constructs a CSV channel from a CharacterChannel
to read/write CSV records.
init (WritableCharacterChannel characterChannel, Separator fs)
- characterChannel WritableCharacterChannel -
- fs Separator "," - Field separator, which will separate the records in the CSV
write![](/images/permalink.svg)
Writes the record to a given CSV file.
io:Error err = csvChannel.write(record);
Parameters
- csvRecord string[] - A record to be written to the channel
Return Type
- Error? - An
io:Error
if the record could not be written properly
close![](/images/permalink.svg)
function close() returns Error?
Closes the io:WritableCSVChannel
.
After a channel is closed, any further writing operations will cause an error.
io:Error? err = csvChannel.close();
Return Type
- Error? -
()
or else anio:Error
if any error occurred
io: WritableDataChannel![](/images/permalink.svg)
Represents a WritableDataChannel for writing data.
Constructor![](/images/permalink.svg)
Initializes data channel.
init (WritableByteChannel byteChannel, ByteOrder bOrder)
- byteChannel WritableByteChannel - channel which would represent the source to read/write data
- bOrder ByteOrder "BE" - network byte order
writeInt16![](/images/permalink.svg)
Writes a 16 bit integer.
io:Error? err = dataChannel.writeInt16(length);
Parameters
- value int - The integer, which will be written
Return Type
- Error? -
()
if the content is written successfully or else anio:Error
if any error occurred
writeInt32![](/images/permalink.svg)
Writes a 32 bit integer.
io:Error? err = dataChannel.writeInt32(length);
Parameters
- value int - The integer, which will be written
Return Type
- Error? -
()
if the content is written successfully or else anio:Error
if any error occurred
writeInt64![](/images/permalink.svg)
Writes a 64 bit integer.
io:Error? err = dataChannel.writeInt64(length);
Parameters
- value int - The integer, which will be written
Return Type
- Error? -
()
if the content is written successfully or else anio:Error
if any error occurred
writeFloat32![](/images/permalink.svg)
Writes a 32 bit float.
io:Error? err = dataChannel.writeFloat32(3.12);
Parameters
- value float - The float, which will be written
Return Type
- Error? -
()
if the float is written successfully or else anio:Error
if any error occurred
writeFloat64![](/images/permalink.svg)
Writes a 64 bit float.
io:Error? err = dataChannel.writeFloat32(3.12);
Parameters
- value float - The float, which will be written
Return Type
- Error? -
()
if the float is written successfully or else anio:Error
if any error occurred
writeBool![](/images/permalink.svg)
Writes a boolean.
io:Error? err = dataChannel.writeInt64(length);
Parameters
- value boolean - The boolean, which will be written
Return Type
- Error? -
()
if the content is written successfully or else anio:Error
if any error occurred
writeString![](/images/permalink.svg)
Writes a given string value to the respective channel.
io:Error? err = dataChannel.writeString(record);
Parameters
- value string - The value, which should be written
- encoding string - The encoding, which will represent the value string
Return Type
- Error? -
()
if the content is written successfully or else anio:Error
if any error occurred
writeVarInt![](/images/permalink.svg)
Writes a variable-length integer.
io:Error? err = dataChannel.writeVarInt(length);
Parameters
- value int - The int, which will be written
Return Type
- Error? - The value of the integer, which is written or else an
io:Error
if any error occurred
close![](/images/permalink.svg)
function close() returns Error?
Closes the data channel. After a channel is closed, any further writing operations will cause an error.
io:Error? err = dataChannel.close();
Return Type
- Error? -
()
if the channel is closed successfully or else anio:Error
if any error occurred
io: WritableTextRecordChannel![](/images/permalink.svg)
Represents a channel, which will allow to write records through a given WritableCharacterChannel.
Constructor![](/images/permalink.svg)
Constructs a DelimitedTextRecordChannel from a given WritableCharacterChannel.
init (WritableCharacterChannel characterChannel, string fs, string rs, string fmt)
- characterChannel WritableCharacterChannel - The
io:WritableCharacterChannel
, which will point to the input/output resource
- fs string "" - Field separator (this could be a regex)
- rs string "" - Record separator (this could be a regex)
- fmt string "default" - The format, which will be used to represent the CSV (this could be "DEFAULT" (the format specified by the CSVChannel), "CSV" (Field separator would be "," and record separator would be a new line) or else "TDF" (Field separator will be a tab and record separator will be a new line)
write![](/images/permalink.svg)
Writes records to a given output resource.
io:Error? err = writableChannel.write(records);
Parameters
- textRecord string[] - List of fields to be written
Return Type
- Error? - An
io:Error
if the records could not be written properly or else()
close![](/images/permalink.svg)
function close() returns Error?
Closes the record channel. After a channel is closed, any further writing operations will cause an error.
io:Error? err = writableChannel.close();
Return Type
- Error? - An
io:Error
if the record channel could not be closed properly or else()
Constants![](/images/permalink.svg)
io: BIG_ENDIAN![](/images/permalink.svg)
Specifies the bytes to be in the order of most significant byte first.
io: COLON![](/images/permalink.svg)
Colon (:) will be use as the field separator.
io: COMMA![](/images/permalink.svg)
Comma (,) will be used as the field separator.
io: CSV![](/images/permalink.svg)
Field separator will be "," and the record separator will be a new line.
io: CSV_RECORD_SEPARATOR![](/images/permalink.svg)
Represents the record separator of the CSV file.
io: DEFAULT![](/images/permalink.svg)
The default value is the format specified by the CSVChannel. Precedence will be given to the field separator and record separator.
io: DEFAULT_ENCODING![](/images/permalink.svg)
Default encoding for the abstract read/write APIs.
io: FS_COLON![](/images/permalink.svg)
Represents the colon separator, which should be used to identify colon-separated files.
io: LITTLE_ENDIAN![](/images/permalink.svg)
Specifies the byte order to be the least significant byte first.
io: MINIMUM_HEADER_COUNT![](/images/permalink.svg)
Represents the minimum number of headers, which will be included in the CSV.
io: NEW_LINE![](/images/permalink.svg)
New line character.
io: stderr![](/images/permalink.svg)
Represents the standard error stream.
io: stdout![](/images/permalink.svg)
Represents the standard output stream.
io: TAB![](/images/permalink.svg)
Tab (/t) will be use as the field separator.
io: TDF![](/images/permalink.svg)
Field separator will be a tab and the record separator will be a new line.
Enums![](/images/permalink.svg)
io: FileWriteOption![](/images/permalink.svg)
Represents a file opening options for writing.
Members
io: XmlEntityType![](/images/permalink.svg)
Represents the XML entity type that needs to be written.
Members
Records![](/images/permalink.svg)
io: XmlDoctype![](/images/permalink.svg)
Represents the XML DOCTYPE entity.
Fields
- system string?(default ()) - the system identifier
- 'public string?(default ()) -
- internalSubset string?(default ()) - internal DTD schema
io: XmlWriteOptions![](/images/permalink.svg)
The writing options of an XML.
Fields
- xmlEntityType XmlEntityType(default DOCUMENT_ENTITY) - the entity type of the XML input (the default value is
DOCUMENT_ENTITY
)
- doctype XmlDoctype?(default ()) - XML DOCTYPE value (the default value is
()
)
Errors![](/images/permalink.svg)
io: AccessDeniedError![](/images/permalink.svg)
This will get returned due to file permission issues.
io: ConfigurationError![](/images/permalink.svg)
This will get returned if there is an invalid configuration.
io: ConnectionTimedOutError![](/images/permalink.svg)
This will return when connection timed out happen when try to connect to a remote host.
io: EofError![](/images/permalink.svg)
This will get returned if read operations are performed on a channel after it closed.
io: Error![](/images/permalink.svg)
Represents IO module related errors.
io: FileNotFoundError![](/images/permalink.svg)
This will get returned if the file is not available in the given file path.
io: GenericError![](/images/permalink.svg)
Represents generic IO error. The detail record contains the information related to the error.
io: TypeMismatchError![](/images/permalink.svg)
This will get returned when there is an mismatch of given type and the expected type.
Object types![](/images/permalink.svg)
io: PrintableRawTemplate![](/images/permalink.svg)
Represents raw templates.
e.g: The respective int value is ${val}
Fields
- strings string[] & readonly - string values of the template as an array
- insertions Printable[] - parameterized values/expressions after evaluations as an array
Union types![](/images/permalink.svg)
io: ByteOrder![](/images/permalink.svg)
ByteOrder
Represents network byte order.
BIG_ENDIAN - specifies the bytes to be in the order of most significant byte first.
LITTLE_ENDIAN - specifies the byte order to be the least significant byte first.
io: FileOutputStream![](/images/permalink.svg)
FileOutputStream
Defines the output streaming types.
stdout
- standard output streamstderr
- standard error stream
io: Format![](/images/permalink.svg)
Format
The format, which will be used to represent the CSV.
DEFAULT - The default value is the format specified by the CSVChannel. Precedence will be given to the field separator and record separator.
CSV - Field separator will be "," and the record separator will be a new line.
TDF - Field separator will be a tab and the record separator will be a new line.
io: Printable![](/images/permalink.svg)
Printable
Defines all the printable types.
- any typed value
- errors
io:PrintableRawTemplate
- an raw templated value
io: Separator![](/images/permalink.svg)
Separator
Field separators, which are supported by the DelimitedTextRecordChannel
.
COMMA - Delimited text records will be separated using a comma
TAB - Delimited text records will be separated using a tab
COLON - Delimited text records will be separated using a colon(:)
Intersection types![](/images/permalink.svg)
io: Block![](/images/permalink.svg)
Block
The read-only byte array that is used to read the byte content from the streams.
Import
import ballerina/io;
Metadata
Released date: over 2 years ago
Version: 1.1.0
License: Apache-2.0
Compatibility
Platform: java11
Ballerina version: slbeta6
GraalVM compatible: Yes
Pull count
Total: 566822
Current verison: 7206
Weekly downloads
Keywords
io
json
xml
csv
file
Contributors