Module documentation for 0.1.10.0
Shake+ - Super Powered Shake
Attempt at a batteries included Shake. We reexport replacements for the main utility functions of Shake with the following adjustments whereever possible.
- Well-typed paths using the path
- New type classes
RAction r a = RAction (ReaderT r Action a)and
ShakePlus r a = ShakePlus (ReaderT r Rules a)
Stringwherever it is appropriate.
withinstyle variants of the standard file and directory operations that in some cases return or accept
Within b (Path Rel File)values to keep tags of parent directories.
This is an early release and some things may be missing or broken, but so far the conveniences have been worth it. Some notes on the approach are detailed below.
Using the path library is kind of a
no brainer. I lose a lot of time to problems that could be avoided by using
this library, so it’s everywhere. The names for these functions shadow the
existing names, so you may want to
import qualified Development.Shake while
this library progresses if you have other
FilePath based Shake rules that
you want to mix into your build.
Development.Shake.FilePath functions for directory manipulation
are not re-exported in full, and you should use the functions in the path
library (such as
replaceExtension) and other path-based libraries. This will
FilePatterns are kept as-is, as
Path is strongly normalizing it makes
sense to keep these as
ReaderT r Action a transformer (called
RAction) is similar to the
RIO type and should be used
similarly. In fact, you can reuse the logging functions from
RIO within any
RAction block, which is one of the main motivators for having an
which is also a
MonadReader. If you need to reuse an existing shake
Action in an
One common complaint about Shake is having to keep track of source and output
directories and translating
FilePaths when using the input to an
leading to lots of repetition of the form
(sourceFolder </>) . (-<.> ".ext") . dropDirectory1 which is prone to breakage. Using
Path helps this to some
degree, but in some cases is even more annoying because lots of
MonadThrow, leading to lots of monadic steps inside an
To alleviate this somewhat, we use
Within b (Path Rel File) as a standard
pattern for representing a file within a directory.
Within is a type
available in the within package
that is simply a newtype wrapper over an
Env comonad with the environment
Path b Dir. We provide variants of the file operations and
rules that typically accept or return
Paths or contain callbacks that expect
paths and change these to
Within values. These functions are generally
within. Here is the variant of
getDirectoryFilesWithin' :: MonadAction m => Path b Dir -> [FilePattern] -> m [Within b (Path Rel File)]
You can convert to and from this within-style using
let x = $(mkRelFile "a.txt") `within` $(mkRelDir "foo") -- Within Rel (Path Rel File) fromWithin x -- produces a `Path Rel File`
and you can assert that an existing path lies in a directory by using
asWithin, which throws
if the directory is not a proper prefix of the
$(mkRelFile "foo/a.txt") `asWithin` $(mkRelDir "foo") -- fine $(mkRelFile "a.txt") `asWithin` $(mkRelDir "foo") -- throws error
Filerules such as
(%>) have within-style variants that accept an
(Path b Dir) FilePattern on the left and carry that env to the callback.
(%^>) :: (Partial, MonadReader r m, MonadRules m) => Within Rel FilePattern -> (Within Rel (Path Rel File) -> RAction r ()) -> m ()
You change the underlying filepath with
mapM, whilst you can move
to a new parent directory by using
localDirM which is defined
Within library for when the map between parent directories may throw.
Within library also contains more functions and instances for more
precise changes between output and source directories.
The main entry point to this library is the
runShakePlus function, which
ReaderT r Rules () to a
Rules () and passes the environment to
ShakePlus and the underlying
RActions have to match. A typical setup might look like this.
let r = --setup env here shake shakeOptions $ do -- include some regular shake rules. runShakePlus r $ do -- some shake-plus rules.
Changelog for shake-plus
- Add unlifted versions of
- Add lower bound to aeson.
- Remove hashable dependency.
runSimpleShakePlusfor quickrunning with args and a log function.
Withinstyle functions more consistent in that they actually take
Withinvalues across the board.
batchLoadfunctions more consistent and usable.
wantvariants now take any
- Update to
within-0.1.1.0which changes the data type to an
- Drop the
loadSortFilterApplyloader functions in favour of a simpler
batchLoadset of functions which accepts a loading function which can be cached.
- Add enough documentation to get started.
- Add functions based on Within to better keep track of source and target directories.
- Reexport more shake functions to remove need to import vanilla shake qualified.
- Add convenience functions
loadSortFilterApplyWfor batch loading via
- Add more of the API surface with
Withinincluding variants of