Core.Program.Metadata

Digging metadata out of the description of your project, and other useful helpers.

Documentation

data Version

Information about the version number of this piece of software and other related metadata related to the project it was built from. This is supplied to your program when you call configure. This value is used if the user requests it by specifying the --version option on the command-line.

Simply providing an overloaded string literal such as version "1.0" will give you a Version with that value:

{-# LANGUAGE OverloadedStrings #-}

main :: IO ()
main = do
    context <- configure "1.0" None (simpleConfig ...

For more complex usage you can populate a Version object using the fromPackage splice below. You can then call various accessors like versionNumberFrom to access individual fields.

Instances

IsString Version

Defined in Core.Program.Metadata

Methods

fromString :: String -> Version

Show Version

Defined in Core.Program.Metadata

Methods

showsPrec :: Int -> Version -> ShowS

show :: Version -> String

showList :: [Version] -> ShowS

Lift Version

Defined in Core.Program.Metadata

Methods

lift :: Quote m => Version -> m Exp

liftTyped :: forall (m :: Type -> Type). Quote m => Version -> Code m Version

versionNumberFrom :: Version -> String

projectNameFrom :: Version -> String

projectSynopsisFrom :: Version -> String

Splice

fromPackage :: Q Exp

This is a splice which includes key built-time metadata, including the number from the version field from your project's .cabal file (as written by hand or generated from package.yaml). This uses the evil TemplateHaskell extension.

While we generally discourage the use of Template Haskell by beginners (there are more important things to learn first) it is a way to execute code at compile time and that is what what we need in order to have the version number extracted from the .cabal file rather than requiring the user to specify (and synchronize) it in multiple places.

To use this, enable the Template Haskell language extension in your Main.hs file. Then use the special $( ... ) "insert splice here" syntax that extension provides to get a Version object with the desired metadata about your project:

{-# LANGUAGE TemplateHaskell #-}

version :: Version version = $(fromPackage)

main :: IO ()
main = do
    context <- configure version None (simpleConfig ...

(Using Template Haskell slows down compilation of this file, but the upside of this technique is that it avoids linking the Haskell build machinery into your executable, saving you about 10 MB in the size of the resultant binary)

Source code

__LOCATION__ :: HasCallStack => SrcLoc

Access the source location of the call site.

This is insanely cool, and does not require you to turn on the CPP or TemplateHaskell language extensions! Nevertheless we named it with underscores to compliment the symbols that CPP gives you; the double underscore convention holds across many languages and stands out as a very meta thing, even if it is a proper Haskell value.

We have a Render instance that simply prints the filename and line number. Doing:

main :: IO ()
main = execute $ do
    writeR __LOCATION__

will give you:

tests/Snipppet.hs:32

This isn't the full stack trace, just information about the current line. If you want more comprehensive stack trace you need to add HasCallStack constraints everywhere, and then...

Orphan instances

Render SrcLoc

Associated Types

type Token SrcLoc

Methods

colourize :: Token SrcLoc -> AnsiColour

highlight :: SrcLoc -> Doc (Token SrcLoc)