Usage

A value of type "Cached a" should be understood as a value of type "a" that is read from a file, or that is produced from data stored in one or more files, or from arbitrary IO actions.

Cached values can be created from pure values,

>>> let a = cache' "/tmp/cached-ex/a" (pure 1) :: Cached Int

or from files stored on disk.

>>> let b = source' "/tmp/cached-ex/b" :: Cached Int

Use the functor and applicative instances to use cached values in new computations.

>>> let bigA = fmap (* 2) a
>>> let c = (+) <$> a <*> b

The cached value "c" represents a value produced by summing together the values stored in "/tmp/cached-ex/a" and "/tmp/cached-ex/b". It is not yet associated to its own cache file. To actually store it into a cache file, use cache' (or cache for values that are not instances of Show and Read or when you want to control the file format, e.g. writing arrays to CSV files)

>>> let c' = cache' "/tmp/cached-ex/c" c

Running the cached computation "c'" will execute all necessary computations and write results to files as expected:

>>> -- Before running, let's make sure the target directory is clean.
>>> :!mkdir -p /tmp/cached-ex
>>> :!rm -f /tmp/cached-ex/*
>>> :!echo 2 > /tmp/cached-ex/b
>>> 
>>> runShake "/tmp/cached-ex/.shake" c'
# Writing cache (for /tmp/cached-ex/a)
# Writing cache (for /tmp/cached-ex/c)
Build completed ...
...

Running it again won't run anything. Since none of the cached or source files have changed, there is nothing to re-compute.

>>> runShake "/tmp/cached-ex/.shake" c'
Build completed ...
...

If we modify the content of "/tmp/cached-ex/b", running "c'" again will only re-run the computation for "c'", and not for "a" since it does not depend on "b".

>>> :! echo 3 > /tmp/cached-ex/b
>>> runShake "/tmp/cached-ex/.shake" c'
# Writing cache (for /tmp/cached-ex/c)
Build completed ...
...

The cache files and dependencies can be inspected with prettyCached.

>>> prettyCached c' >>= putStr
Cached Value = 4
Cached Needs:
  /tmp/cached-ex/c
Cached Build:
  /tmp/cached-ex/a
  /tmp/cached-ex/c
    /tmp/cached-ex/a
    /tmp/cached-ex/b

The previous output means that the value carried by "c'" is 4, and that in order to be computed, it needs the file "/tmp/cached-ex/c". The last field, "Cached Build", lists each file that is to be built by the cache system and their dependencies: "/tmp/cache-ex/a" and "/tmp/cache-ex/c" are created by the cache system, and the latter depends on "/tmp/cache-ex/a" and "/tmp/cache-ex/b"

To put together different independent cached values into a single one so that they all get built together, use <>. However, "Cached a" is an instance of Semigroup only if "a" is. You can "sink" the cached values first, which will turn a "Cache a" into a "Cache ()", satisfying the Semigroup constraint.

>>> let d = sink' "/tmp/cached-ex/d" (pure 'd')
>>> let e = sink' "/tmp/cached-ex/e" (pure 'e')
>>> let de = d <> e
>>> prettyCached de >>= putStr
Cached Value = ()
Cached Needs:
Cached Build:
  /tmp/cached-ex/d
  /tmp/cached-ex/e

To create cached values from pure values, use pure.

>>> let a = pure 1 :: Cached Int
>>> prettyCached a >>= putStr
Cached Value = 1
Cached Needs:
Cached Build:

Newly created cached values won't actually be written to files or attached to IO actions yet, as denoted by the empty "Cached Build" field. To associate them with actual cache files on disk, see section "Caching values" below.

The following functions offer additionnal creation possibilities.

These functions associate cached values to files on disk or IO actions.