Saucexages v0.2.0 Saucexages.IO.FileReader View Source

Reads SAUCE data from files according to the SAUCE specification.

SAUCE data is decoded decoded according to the SAUCE spec.

If you are working with small files, it is recommended to use Saucexages.IO.BinaryReader instead.

Files are opened with read and binary flags, and as such must be available for reading.

General Usage

The general use-case for the file reader is to work with binaries that you cannot fit in memory or you wish to offload some of the boiler-plate IO to this module.

A general usage pattern on a local machine might be as follows:

FileReader.sauce("LD-ACID2.ANS")

Layout

The layout of the binary read is assumed to be consistent with what is described in Saucexages.IO.BinaryReader.

The SAUCE must exist at the end of a file, per the SAUCE spec. As such, this reader assumes that reading should begin at the end-of-file position (eof position). Note that this is not the same as the end-of-file character (eof character). The difference lies in the fact that the eof character comes before the SAUCE data, while the eof itself is the true termination of the file.

SAUCE Block data itself is limited to 128 bytes for the SAUCE record, and 255 comment lines of 64-bytes each + 5 bytes for a comment ID. Therefore if you are not dealing with corrupted files, you can read a maximum of 128 + (255 * 64) + 5 bytes, or 16,453 bytes before you can give up scanning for a SAUCE. In practice, if you wish to scan a file in this manner, it may be better to follow the spec as this module does, or to scan up to the first eof character, starting from the eof position.

Notes

There are many SAUCE files in the wild that have data written after the SAUCE record, multiple eof characters, and multiple SAUCE records. As such, these cases are dealt with universally by obeying the SAUCE specification. Multiple eof characters is very common as many SAUCE writers have naively appended eof characters on each write instead of truncating the file after the eof character or doing an in-place update.

Specifically, this reader will always read only from the eof position. It is possible to fix these cases using the Saucexages.SauceBinary module as well as some general binary matching, however these fixes should be viewed as outside the scope and concerns of this reader.

Reads often require multiple position changes using the current device. This is because the comments cannot be reliably obtained without first scanning the SAUCE record. The comments block itself is of variable size and cannot reliably be obtained otherwise. If this is a concern, consider using the binary reader and reading the entire file or a feasible chunk that will obtain the SAUCE block data.

Link to this section Summary

Functions

comments(path)

Reads a file containing a SAUCE record and returns the decoded SAUCE comments

comments?(path)

Reads a file with a SAUCE record and returns whether or not a SAUCE comments block exists within the SAUCE block

contents(path)

Reads a binary and returns the contents without the SAUCE block

raw(path)

Reads a binary containing a SAUCE record and returns the raw binary in the form {:ok, {sauce_bin, comments_bin}}

sauce(path)

Reads a file containing a SAUCE record and returns decoded SAUCE information as {:ok, sauce_block}

sauce?(path)

Reads a file and returns whether or not a SAUCE record exists

Link to this section Functions

comments(path)

comments(binary()) ::
  {:ok, [String.t()]}
  | {:error, :no_sauce}
  | {:error, :no_comments}
  | {:error, term()}

Reads a file containing a SAUCE record and returns the decoded SAUCE comments.

comments?(path)

comments?(binary()) :: boolean()

Reads a file with a SAUCE record and returns whether or not a SAUCE comments block exists within the SAUCE block.

Will match a comments block only if it a SAUCE record exists. Comment fragments are not considered to be valid without the presence of a SAUCE record.

contents(path)

contents(Path.t()) :: {:ok, binary()} | {:error, term()}

Reads a binary and returns the contents without the SAUCE block.

It is not recommended to use this function for large files. Instead, get the index of where the SAUCE block starts and read until that point using a stream if you need the file contents.

raw(path)

raw(Path.t()) ::
  {:ok, {binary(), binary()}} | {:error, :no_sauce} | {:error, term()}

Reads a binary containing a SAUCE record and returns the raw binary in the form {:ok, {sauce_bin, comments_bin}}.

If the binary does not contain a SAUCE record, {:error, :no_sauce} is returned.

sauce(path)

sauce(Path.t()) ::
  {:ok, Saucexages.SauceBlock.t()} | {:error, :no_sauce} | {:error, term()}

Reads a file containing a SAUCE record and returns decoded SAUCE information as {:ok, sauce_block}.

If the file does not contain a SAUCE record, {:error, :no_sauce} is returned.

sauce?(path)

sauce?(Path.t()) :: boolean()

Reads a file and returns whether or not a SAUCE record exists.