todo indicates unfinished code.

It is to be used whenever you want to indicate that you are missing a part of the implementation and want to fill that in later.

The main difference to other alternatives like typed holes and undefined or error is, this does not throw an error but only emits a warning.

Similarly to undefined, error and typed holes, this will throw an error if it is evaluated at runtime which can only be caught in IO.

This is intended to *never* stay in code but exists purely for signifying "work in progress" code.

To make the emitted warning error instead (e.g. for the use in CI), add the -Werror=x-todo flag to your OPTIONS_GHC.

Examples

superComplexFunction :: Maybe a -> IO Int
-- we already know how to implement this in the Nothing case
superComplexFunction Nothing = pure 42
-- but the Just case is super complicated, so we leave it as todo for now
superComplexFunction (Just a) = todo

Representation Polymorphism

unimplemented indicates that the relevant code is unimplemented. Unlike todo, it is expected that this _may_ remain in code long term, and so no warning is supplied. Use cases might include places where a typeclass would theoretically require a member to be implemented, but where the resulting violation is actually intended.

TODO indicates unfinished code or an unfinished pattern match

You can use this in most positions where you could pass todo, but it also can be used in pattern position to indicate that there are cases you haven't considered.

There remain some circumstances where you can only use todo, however, they arise when using this in a PolyKinded situation.

This pattern synonym is marked COMPLETE, implying that every match after matching on TODO will emit a redundant pattern match warning. Adding new options to your datatype, similarly to how wildcard patterns (patterns starting with an underscore) work, will not cause any warnings or errors.

Examples

>>> x = []
>>> case x of
...   (x : _) -> x
...   TODO -> 42
*** Exception: Control.Placeholder.todo: not yet implemented

>>> x = []
>>> case x of
...   (x : _) -> x
...   ~TODO -> 42
42

>>> y :: Int = todo
>>> x :: Int = TODO

Representation Polymorphism

Unimplemented can be used in most circumstances unimplemented can, but it can also be used in pattern position to indicate cases haven't been considered yet. Unlike TODO it does not provide a compile-time warning, as it is expected that this _may_ remain in code long term.

todoIO indicates unfinished code that lives in the IO monad.

It should be used similarly to how throwIO should be used rather than throw in IO to throw at the time the IO action is run rather than at the time it is created.

unimplementedIO indicates that the method is unimplemented, but it lives in IO, and so only throws when actually run, rather than when it is constructed. Unlike todoIO it does not provide a compile-time warning, as it is expected that this _may_ remain in code long term.

This is the Exception thrown by todo, TODO and todoIO.

This is the Exception thrown by unimplemented, Unimplemented, and unimplementedIO.