This Gleam library provides access to Erlang's file streams for reading and
writing files. If you don't require streaming behaviour then consider using
simplifile instead.
Add this library to your project:
gleam add file_streamsThe following code writes data to a file using a file stream, then reads it back in using a second file stream, first as raw bytes and then as lines of UTF-8 text.
import file_streams/file_stream
import file_streams/file_stream_error
pub fn main() {
let filename = "test.txt"
// Write file
let assert Ok(stream) = file_stream.open_write(filename)
let assert Ok(Nil) = file_stream.write_bytes(stream, <<"Hello!\n":utf8>>)
let assert Ok(Nil) = file_stream.write_chars(stream, "12")
let assert Ok(Nil) = file_stream.close(stream)
// Read file
let assert Ok(stream) = file_stream.open_read(filename)
let assert Ok(<<"Hello!\n":utf8>>) = file_stream.read_bytes(stream, 7)
let assert Ok([49, 50]) =
file_stream.read_list(stream, file_stream.read_uint8, 2)
let assert Error(file_stream_error.Eof) = file_stream.read_bytes(stream, 1)
// Reset file position to the start and read line by line
let assert Ok(0) =
file_stream.position(stream, file_stream.BeginningOfFile(0))
let assert Ok("Hello!\n") = file_stream.read_line(stream)
let assert Ok("12") = file_stream.read_line(stream)
let assert Error(file_stream_error.Eof) = file_stream.read_line(stream)
let assert Ok(Nil) = file_stream.close(stream)
}If a text encoding is specified when opening a file stream it allows for
reading and writing of characters and lines of text stored in that encoding.
To open a text file stream use the file_stream.open_read_text() and
file_stream.open_write_text() functions. The supported encodings are Latin1,
Unicode (UTF-8), Utf16, and Utf32. The default encoding is Latin1.
File streams opened with a text encoding aren't compatible with the Raw file
open mode that significantly improves IO performance on Erlang. Specifying both
Raw and Encoding when calling file_stream.open() returns Error(Enotsup).
Although a text encoding can't be specified with Raw mode, the
file_stream.read_line() and file_stream.write_chars() functions can still be
used to work with UTF-8 data. This means that text encoded as UTF-8 can be
handled with high performance in Raw mode.
When a text encoding other than Latin1 is specified, functions that read and
write raw bytes and other binary data aren't supported and will return
Error(Enotsup).
The following code demonstrates working with a UTF-16 file stream.
import file_streams/file_stream
import file_streams/file_stream_error
import file_streams/text_encoding
pub fn main() {
let filename = "test.txt"
let encoding = text_encoding.Utf16(text_encoding.Little)
// Write UTF-16 text file
let assert Ok(stream) = file_stream.open_write_text(filename, encoding)
let assert Ok(Nil) = file_stream.write_chars(stream, "Hello!\n")
let assert Ok(Nil) = file_stream.write_chars(stream, "Gleam is cool!\n")
let assert Ok(Nil) = file_stream.close(stream)
// Read UTF-16 text file
let assert Ok(stream) = file_stream.open_read_text(filename, encoding)
let assert Ok("Hello!\n") = file_stream.read_line(stream)
let assert Ok("Gleam") = file_stream.read_chars(stream, 5)
let assert Ok(" is cool!\n") = file_stream.read_line(stream)
let assert Error(file_stream_error.Eof) = file_stream.read_line(stream)
let assert Ok(Nil) = file_stream.close(stream)
}API documentation can be found at https://hexdocs.pm/file_streams/.
This library is published under the MIT license, a copy of which is included.