README.md

Gleam File Streams

This Gleam library provides access to file streams for reading and writing files. If you don't require streaming behavior then consider using simplifile instead.

Usage

Add this library to your project:

gleam add file_streams

The 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 (not currently
  // supported on JavaScript)
  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)
}

Working with Text Encodings

Note

Text encodings are not currently supported on the JavaScript target.

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

API documentation can be found at https://hexdocs.pm/file_streams/.

License

This library is published under the MIT license, a copy of which is included.