Diagrams.Util

Some miscellaneous utilities provided by the diagrams-lib package.

Utilities for users

with :: Default d => d

Several functions exported by the diagrams library take a number of arguments giving the user control to "tweak" various aspects of their behavior. Rather than give such functions a long list of arguments, and to make it possible for the user to selectively override only certain arguments and use default values for others, such sets of arguments are collected into a record with named fields (see PolygonOpts in Diagrams.TwoD.Shapes for an example). Such record types are made instances of the Default class, which provides a single record structure (def) collecting the "default" arguments to the function. with is a synonym for def, which provides nice-looking syntax for simulating optional, named arguments in Haskell. For example,

  polygon with {sides = 7, edgeSkip = 2}
  

calls the polygon function with a single argument (note that record update binds more tightly than function application!), namely, with (the record of default arguments) where the sides and edgeSkip fields have been updated.

applyAll :: [a -> a] -> a -> a

applyAll takes a list of functions and applies them all to a value, in sequence from the last function in the list to the first. For example, applyAll [f1, f2, f3] a == f1 . f2 . f3 $ a.

(#) :: a -> (a -> b) -> b infixl 8

Postfix function application, for conveniently applying attributes. Unlike ($), (#) has a high precedence (8), so d # foo # bar can be combined with other things using operators like (|||) or (<>) without needing parentheses.

(##) :: AReview t b -> b -> t infixr 8

A replacement for lenses' # operator.

iterateN :: Int -> (a -> a) -> a -> [a]

iterateN n f x returns the list of the first n iterates of f starting at x, that is, the list [x, f x, f (f x), ...] of length n. (Note that the last element of the list will be f applied to x (n-1) times.)

tau :: Floating a => a

The circle constant, the ratio of a circle's circumference to its radius. Note that pi = tau/2.

For more information and a well-reasoned argument why we should all be using tau instead of pi, see The Tau Manifesto, http://tauday.com/.

To hear what it sounds like (and to easily memorize the first 30 digits or so), try http://youtu.be/3174T-3-59Q.

Finding files

findHsFile :: FilePath -> IO (Maybe FilePath)

Given some file (no extension or otherwise) try to find a haskell source file.

Finding sandboxes

findSandbox :: [FilePath] -> IO (Maybe FilePath)

Search for a sandbox in the following order:

• Test given FilePaths if they point directly to a database or contain a cabal config file (or any parent directory containing a config file).
• Same test for DIAGRAMS_SANDBOX environment value
• Environment values of GHC_PACKAGE_PATH, HSENV and PACKAGE_DB_FOR_GHC that point to a database.
• Test for config file (cabal.sandbox.config) in the current directory and its parents.

globalPackage :: IO FilePath

Find ghc's global package database. Throws an error if it isn't found.

Internal utilities

foldB :: (a -> a -> a) -> a -> [a] -> a

Given an associative binary operation and a default value to use in the case of an empty list, perform a balanced fold over a list. For example,

  foldB (+) z [a,b,c,d,e,f] == ((a+b) + (c+d)) + (e+f)