Saucexages v0.2.0 Saucexages.IO.BinaryReader View Source

Reads SAUCE data from binaries according to the SAUCE specification.

SAUCE data is decoded decoded according to the SAUCE spec.

If you need to read files from the local file system directly in a more efficient manner, see Saucexages.IO.FileReader.

General Usage

The general use-case for the binary reader is to work with binaries that you can fit in memory. You should prefer this use-case whenever possible to free yourself from problems that may arise when working directly with another underlying medium such as the FileSystem.

Most files that were commonly used for SAUCE are very small (ex: ANSi graphics) and an ideal fit for the binary reader. This also implies that this reader is suitable for use perhaps in a network service, streaming process, or similar context where loading the entire binary would not be a burden on the rest of the system.

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

File.read!("LD-ACID2.ANS") |> BinaryReader.sauce()

Layout

Binaries are generally assumed to take the following forms in pseudo-code below.

Sauce with No comments

<<contents::binary, eof_character::binary, sauce::binary-size(128)>>

Sauce with Comments

<<contents::binary, eof_character::binary, comments::binary-size(line_count), sauce::binary-size(128)>>

No SAUCE with EOF character

<<contents::binary, eof_charter::binary>>

No SAUCE with no EOF character

<<contents::binary>>

Notes

The operations within this module take the approach of tolerant reading while still following the SAUCE spec as closely as possible.

For example, comments with a SAUCE are only read according to the comment lines value specified in a SAUCE record. A binary may have a comments block buried within it, but if the SAUCE record does not agree, no effort is made to find the binary.

If you wish to work with SAUCE-related binaries at a lower-level or build your own binary reader, see Saucexages.SauceBinary. This module can also be used to build readers that relax or constrain the SAUCE spec, such as in the case of reading comment blocks.

Link to this section Summary

Functions

comments(bin)

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

comments?(bin)

Reads a binary and returns whether or not a SAUCE comments block exists within the SAUCE block

contents(bin)

Reads a binary and returns the contents without the SAUCE block

raw(bin)

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

sauce(bin)

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

sauce?(bin)

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

Link to this section Functions

comments(bin)

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

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

comments?(bin)

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

Reads a binary 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(bin)

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

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

raw(bin)

raw(binary()) ::
  {: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(bin)

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

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

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

sauce?(bin)

sauce?(binary()) :: boolean()

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

Will match both binary that is a SAUCE record and binary that contains a SAUCE record.