Expresso.Element.Diagram.Tool (expresso v0.1.0)

Finds and runs the tool that draws a graph, such as Graphviz, or Node for the MathML of a formula

Expresso and the binary of Burrito do not hold the tools. The function find/3 looks for the program of a tool on the PATH, and a variable of the environment, such as EXPRESSO_DOT, gives a different path. A tool that is not present stops the render with a message that names the tool and the way to install it.

System.cmd/3 cannot keep the standard error apart from the standard output. Therefore the tool writes the SVG to a file in a private directory, and the standard error goes into the standard output. A tool that fails stops the render with that output, which holds the message of the tool, such as a syntax error and its line. A tool that succeeds can also write a warning, such as a color that it does not know. The render does not show that warning, so a test does not write to the standard error.

Summary

Types

subject()

The thing that a tool draws, for a message: the path of a diagram, or {:subject, text} with the words of the message, such as {:subject, "the formulas of the deck"}

t()

A tool: its name for the user, its program and its variable of the environment

Functions

find(tool, src, env \\ System.get_env())

Find the program of a tool

identity(tool, src)

The identity of the program of a tool, for the key of a cache

run!(tool, src, command, files \\ [], output \\ "graph.svg")

Run a tool, and return the SVG that it writes

Types

subject()

@type subject() :: Path.t() | {:subject, String.t()}

The thing that a tool draws, for a message: the path of a diagram, or {:subject, text} with the words of the message, such as {:subject, "the formulas of the deck"}

t()

@type t() :: %{
  name: String.t(),
  program: String.t(),
  variable: String.t(),
  install: String.t()
}

A tool: its name for the user, its program and its variable of the environment

Functions

find(tool, src, env \\ System.get_env())

@spec find(t(), subject(), %{required(String.t()) => String.t()}) ::
  {:ok, Path.t()} | {:error, String.t()}

Find the program of a tool

The variable of the tool in env gives the path of the program. Without the variable, the function looks for the program on the PATH. src is the path of the source or a subject, for the message.

identity(tool, src)

@spec identity(t(), subject()) :: {Path.t(), integer(), non_neg_integer()} | nil

The identity of the program of a tool, for the key of a cache

The identity is the path of the program and the time and the size of its file, so a new version of the tool gives a new identity. The function returns nil for a tool that is not present.

run!(tool, src, command, files \\ [], output \\ "graph.svg")

@spec run!(
  t(),
  subject(),
  (Path.t() -> {[String.t()], [{String.t(), String.t()}]}),
  [{String.t(), binary()}],
  String.t()
) :: String.t()

Run a tool, and return the SVG that it writes

command is a function that takes the private directory of the run and returns the arguments of the program and its variables of the environment. The tool writes its result to output in that directory, graph.svg by default, and the function returns the text of that file. files go into the directory before the run, such as the files of a font. The function raises an ArgumentError for a tool that is not present and for a tool that fails.