Add the `todo` function

[MangoIV]

Dear Haskell core library committee.

Currently there are multiple ways of describing something as unimplemented

• undefined
• error "not implemented yet"
• various other, similar functions from external libraries, such as the ones in alternative preludes like Relude placeholders or the todo package
• typed holes

problems of the above solutions

1. Problems of the functions currently in base:
   • undefined:
   • doesn't give you a warning if it remains in code
   • doesn't read as "this is open, I will definitely implement it soon"
   • a lot to type for "please compiler, be quiet for the second, I will come back to this"
   • error:
   • also doesn't give you a warning if it remains in code
   • may read as "this is open, I will definitely implement it soon" but this is a lot to type
   • even more to type for "please compiler, be quiet for the second, I will come back to this", sometimes even needs paranthesis
2. external dependencies:
   • just for doing a quick debugging todo, it doesn't seem worth adding an alternative Prelude or even add a dependency just for the sake of this
3. typed holes
   • they are, by default, errors, not warnings
   • they are very noisy (by default they produce a lot of output)
   • they are slow (by default)

That's why propose a function todo that has the following properties:

• has a warning annotation "todo remains in code" in group x-todo so that it can be used with WError for e.g. CI
• has the same type as undefined
• gets (re)exported by base:Prelude
• is to be used whenever there is a place in the code where we want to temporary fill holes
• the warning message is not fixed as shown in the example implementation and may be adjusted, similar things hold for the documentation

implementation of the solution

{-# LANGUAGE ImplicitParams #-}
{-# LANGUAGE MagicHash #-}
{-# OPTIONS_GHC -Wall #-}

module Todo (todo) where

import GHC.Base (raise#, TYPE, RuntimeRep)
import GHC.Exception (errorCallWithCallStackException)
import GHC.Stack (HasCallStack)

{- | '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'
@
-}
todo :: forall {r :: RuntimeRep} (a :: TYPE r). (HasCallStack) => a
todo = raise# (errorCallWithCallStackException "Prelude.todo: not yet implemented" ?callStack)
{-# WARNING in "x-todo" todo "todo remains in code" #-}

try it out in a separate module, as such:

module TodoExample where

import Todo

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

This implementation will work from >= ghc981

impact

on hoogle I currently find 4 functions which this would break, two of which have similar semantics to this one, making it improbable that they will be found in code out there.

Another advantage of this function is that there will be no need of a *-compat package because code that does contain this function is not supposed to live anywhere or compile with more than the compiler than the base version this is going to be shipped with supports.

I will obviously run a proper impact assessment though.

why I think this belongs in Prelude

The main reason I think this belongs into Prelude is because it is not possible to replace this with the same level of simplicity with any other solution

• libraries add technical issues like unused packages warnings by cabal and/ or the overhead of having to define mixins or add new imports; Additionally already having to add an additional dependency to use this, would, I think, be too much effort for many people to use it
• external tools are external tools, they require additional installation, they don't ship with GHC, they are not supported first class by GHC, with the advent of the {-# WARNING -#} we have first class support for these kinds of things that don't add any additional overhead
• error and undefined don't have WARNINGs attached to them and I don't think they should have; they have been as they are for a long time, it would impose a great cost to change their semantics; even though it is debatable whether you should, people use undefined in their code to signify unreachable or permanently unimplemented parts of their code, if we want to add a warning, I think it should be on something that clearly tells the programmer and the reader of the code "this is not done yet"

I think this will also have the positive impact of offering a real alternative to dangerous uses of undefined

also look at

rust std's todo! and unimplemented! macros

rendered docs

some more screenshots

• how it looks, loading a module using todo into GHCi:

• how it looks when trying to load a module using todo with {-# OPTIONS_GHC -Werror=x-todo #-} into GHCi:

Amendment to this proposal (28 Mar 2024)

After what I consider a very productive and diverse discussion, I think the most prominent conclusion is that this might not make the jump into Prelude all at once. I still want to proceed with this proposal for the following two reasons:

1. accessibility and visibility as well as usefulness in general (least overhead, least tooling issues, least possibility of divergence, etc.) will be greatest if this is in base
2. and most importantly: I still want this is Prelude eventually; this seems to be only possible when something has been in base for a long time and one has to start at some point ;)

a new module, Debug.Placeholder Develop.Placeholder

There will be a new module Debug.Placeholder Develop.Placeholder that will contain both the

• todo function as described above and implemented in ekmett's placeholder library (thank you for throwing this together) (except some improvements I will propose wrt type applications)
• the TODO pattern synonym as is implemented in the placeholder library (except some improvements I will propose wrt type applications)

These implementations include many useful improvements to the function described above, which is really awesome.

The name of the module is justified as follows:

• I don't think that this belongs into Control or the like because it's only temporarily, you do something with the definitions in the process of programming, but don't really intend to keep the definitions
• Debug is the namespace that I think most fits the semantics of these functions intuitively, after all, todo is something you insert in the code while "writing code" which is closest to "debugging", I'd say @tbidne has proposed the namespace Develop which I think is the most fitting until now

Note: if people think that the proposed namespace is incorrect, I would like to hear convincing arguments and am happy to adjust accordingly.

out of scope for this proposal

While there were some really nice suggestions to make the proposal "more complete", I will consider the following out of scope for this proposal while expressing the strong intention to later add them in a follow-up proposal:

• the {u,U}nimplemented function and patterns: the reason why I want to avoid them for now is that they will spark additional discussions on whether you really need both of these and what the semantics of them should really be, whether they require warnings, etc.
• the {unimplemented,todo}IO variations of these: the reason why I want to avoid these is that I think it will spark discussion on whether we will need these in the case of only todo existing, as it may never remain in code
• adding a new module Develop that will export many useful functions that you need only for work-in-progress code, such as the todo family of functions as well as the trace* family of functions

[MangoIV]

There is already a standalone package on ekmett/placeholder. It just needs to be published on hackage.

[Bodigrim]

Additionally, adding the -fdefer-typed-holes flag has one (minor?major?) drawback: I can now no longer use typed holes as an error alongside with typed holes as a warning.

This. That's why I never considered typed holes as an alternative for todo, I'm an ardent adept of hole-driven development, so suppressing the warning is not an option for me. I feel that holes are much more widerly used for HDD than for -fdefer-typed-holes.

[Bodigrim]

@MangoIV thanks for the proposal, I greatly appreciate all work and effort you put into it.

...it's quite a good testimony of how cumbersome any substantial improvements, many of which are even somewhat universally agreed on, will be, just for the reason of them creating a lot of churn in the ecosystem. Mind that this is no criticism but instead a pledge for a more glorious future after the base split.

I'm not quite sure what you refer by "the base split" and how it would help to evolve base faster. If anything, splitting ghc-internal is to make base more stable by excluding the volatile GHC component.

---

While the fact that CLC votes against vox populi might be perceived by some as worrying, I strongly believe that it's not. Let me remind that everyone wishing to affect CLC decisions is most welcome to nominate themselves at the next CLC elections (which is January 2025) and help us together make the world a better place to write Haskell.

[tomjaguarpaw]

There is already a standalone package on ekmett/placeholder. It just needs to be published on hackage.

It has now been published: https://hackage.haskell.org/package/placeholder

Thanks to @MangoIV and @ekmett for making this idea into a package