core-program-0.2.4.2: Opinionated Haskell Interoperability

Safe HaskellNone
LanguageHaskell2010

Core.Program.Metadata

Contents

Description

Dig metadata out of the description of your project.

This uses the evil Template Haskell to run code at compile time that parses the .cabal file for your Haskell project and extracts various meaningful fields.

Synopsis

Documentation

data Version Source #

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 (simple ...

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
Show Version Source # 
Instance details

Defined in Core.Program.Metadata

IsString Version Source # 
Instance details

Defined in Core.Program.Metadata

Methods

fromString :: String -> Version #

Lift Version Source # 
Instance details

Defined in Core.Program.Metadata

Methods

lift :: Version -> Q Exp #

Splice

fromPackage :: Q Exp Source #

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).

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 (simple ...

(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)

Internals