Reads the files that a deck names, and records their paths for the watch mode
A deck can name an image, a diagram, a code file, a page, a style sheet and
a file of a url() of the style sheet. The module of each reads the file
with read/1 or read!/2. A module that puts the file into the document
as text reads it with read_text/1 or read_text!/2, which also make sure
that the file is UTF-8. An element gives the message of read_error/3 for a
file that it cannot read.
Expresso.Watch renders a deck inside track/1. That function returns each
path that read/1 read during the render, so the watch mode knows which
files to watch. Outside track/1, read/1 records nothing. Thus those
modules need no code for the watch mode.
track/1 keeps the paths in the process dictionary. Two renders in two
processes therefore keep their paths apart.
Summary
Functions
Read a file that a deck names
Read a file that a deck names, and raise for a file that it cannot read
Return the message for a file of a deck that cannot be read
Read a text file that a deck names, and make sure that it is UTF-8
Read a text file that a deck names, and raise for a file that it cannot read
Run a function, and return its result with each path that read/1 read
Types
@type reason() :: File.posix() | :not_utf8
The reason that a file of a deck cannot be read
Functions
@spec read(Path.t()) :: {:ok, binary()} | {:error, File.posix()}
Read a file that a deck names
A relative path starts from the working directory of the command.
Expresso.PathTransformer joins each path of a deck with the root option
to that directory first. The function returns the result of File.read/1.
Read a file that a deck names, and raise for a file that it cannot read
The noun names the file in the message, such as "diagram". The message
is the text of read_error/3.
Return the message for a file of a deck that cannot be read
Each element that reads a file gives this message: the noun, the path, the
reason from :file.format_error/1, and where a relative path starts.
iex> Expresso.DeckFile.read_error("a.svg", "diagram", :enoent)
~s(cannot read the diagram "a.svg": no such file or directory. A path is relative to ) <>
"the working directory of the command, or to the root option of the deck."For :not_utf8, the message tells the user to save the file as UTF-8.
iex> Expresso.DeckFile.read_error("legacy.toml", "code file", :not_utf8)
~s(cannot read the code file "legacy.toml": the file is not UTF-8 text. ) <>
"Save the file with the UTF-8 encoding."Read a text file that a deck names, and make sure that it is UTF-8
The document is UTF-8, and the lexers read only UTF-8. The function returns
{:error, :not_utf8} for a file that has a different encoding, such as
Latin-1. A different error is the error of read/1.
Read a text file that a deck names, and raise for a file that it cannot read
The function is read!/2 for a file that must be UTF-8, as read_text/1
tells.
@spec track((-> result)) :: {result, [Path.t()]} when result: var
Run a function, and return its result with each path that read/1 read
The paths are in the order of their first read, and each path is in the list one time. A read that failed is in the list too, because the file can appear later. An exception, an exit or a throw goes on to the caller.