placeholders-0.1: Placeholders for use while developing Haskell code

Safe HaskellNone
LanguageHaskell98

Development.Placeholders

Contents

Description

This module defines placeholders that you can use while coding to allow incomplete code to compile. They work just like undefined, but with improved error messages and compile-time warnings.

Synopsis

Example

{-# LANGUAGE TemplateHaskell #-}

import Development.Placeholders

theUltimateAnswer :: Int
theUltimateAnswer = $notImplemented

main = do
    putStrLn "The ultimate answer:"
    print theUltimateAnswer

This will compile with a warning about the unimplemented function:

$ ghc --make Simple.hs
...
Simple.hs:6:21: Unimplemented feature
...

At runtime, an exception will be thrown when the placeholder is evaluated, indicating the location of the placeholder.

$ ./Simple
The ultimate answer:
Simple: PlaceholderExcption "Unimplemented feature at Simple.hs:6:21"

If compiled with the GHC flag -Werror, the warning will get turned into an error and compilation will fail. -Werror can therefore be used to verify that you haven't left any unintended placeholders behind.

Placeholders

notImplemented :: Q Exp

Indicates that this piece of code has not yet been implemented.

$notImplemented = $(placeholder "Unimplemented feature")

todo :: String -> Q Exp

Indicates unimplemented code or a known bug with a custom message.

$(todo msg) = $(placeholder ("TODO: " ++ msg))

placeholder :: String -> Q Exp

Generates an expression of any type that, if evaluated at runtime will throw a PlaceholderException. It is therefore similar to error, except that the source location is automatically included. Also, a warning is generated at compile time so you won't forget to replace placeholders before packaging your code.

placeholderNoWarning :: String -> Q Exp

Similar to placeholder, but does not generate a compiler warning. Use with care!

Exceptions

data PlaceholderException

Thrown when attempting to evaluate a placeholder at runtime.