filepather

Computations that depend on a file path, and named build steps that record the files they make.

FilePather

newtype FilePather f a = FilePather (FilePath -> f a)
type FilePather' a = FilePather Identity a

A FilePather is isomorphic to ReaderT FilePath f a, with the same instances, and ask is the file path being operated on. System.FilePather.Combinators builds larger FilePather values from smaller ones:

• p ~> q runs q on the file path that p produces, and p ~>> q runs q on each of the file paths that p produces.
• onFile runs on another file path, and hoistFilePather changes f.
• A Rule f a is a FilePather that applies to some file paths and not others. Make one with rule predicate x, and combine rules with <|>, where the first rule that applies is used.
• everyFile directoryFiles r applies the rule r to every file in the directory being operated on.

Tracked

newtype Tracked f a = Tracked (FilePather (ReaderT Trail (ExceptT Cycle f)) (Outputs, a))
type Outputs = [(FilePath, Step)]

A Tracked value is a build step, or several, run on a file path with the Trail of that file: the Steps that built it, nearest first, back to its source file. It produces its result and the files it made, each with the step that made it.

• step name outputs x names the FilePather x, which makes the files outputs gives for its input. Before x runs, the step is checked against the trail: a step whose name is already in the trail (RepeatsStep), or that would make a file already in the trail (ReproducesInput), is stopped with a Cycle, and x does not run.
• step' name x names a FilePather that returns the files it made, for a step whose outputs are known only after it runs. It is checked after it runs.
• stepWith Repeatable allows a step to appear more than once in a trail.
• whenPath, whenTrail, onPath, askTrail and untracked choose files, and run FilePather values that make no files.
• displayCycle describes the chain of a Cycle:

src/a.md → markdown to pdf → public/a.pdf → pdf page 1 → public/a_page1.pdf → pdf page 1 again

Tracked is separate from FilePather, so that FilePather keeps all of its instances (Distributive, Representable, Selective, Decidable, and the MonadError and MonadWriter of f). Tracked has Functor, Apply, Applicative, Bind, Monad, Selective, Alt, Plus, Alternative, MonadPlus, Semigroup, Monoid, Filterable, MonadTrans, MonadIO, MonadFail, MonadReader FilePath, MonadState, MonadError, MonadWriter and Contravariant instances. <> runs both steps and keeps the outputs of both; <|> and catchError alternate in f; and a Cycle is never caught or discarded by any of them.

Development

This package is built and tested with document-build, which uses it:

cabal build all
cabal test all
bin/lint.sh --check