cabal-docspec: can it do CPP preprocessing before running examples?

[harendra-kumar]

Is there some way to be able to use CPP to produce code for the setup section?

-- $setup
#include "DataFoldImports.hs"

This works with haddock, but cabal-docspec does not seem to be able to use the #include. Is there some option that I can use, or this just cannot work.

[phadej]

I'd say it just cannot work reliably. proper cpp will at least insert #line pragmas in between, which needs to be stripped etc. As with #97, that would require some parsing of the source file (instead of just lexing), and that's tricky (EDIT: the only "reasonable" parsing option is to depend on e.g. ghc-lib-parser which I'd rather not).

[phadej]

Actually, cabal-docspec uses cpphs to preprocess files. I'm not sure why the comments are not merged. Probably something gets in between

Maybe

{- $setup
#include "DataFoldImports.hs"
-}

will work.

[harendra-kumar]

I was assuming CPP extension specified in the cabal file might work. But it seems I have to specify LANGUAGE CPP in the file for it to work. Also, I pushed the -- $setup line inside the included file instead of using block comments.

And then it worked! Thanks!

[phadej]

I was assuming CPP extension specified in the cabal file might work.

Well, that is a bug. I will fix that.

(though in general I advice against having CPP enabled if you don't actually need it everywhere, it ruins incremental compilation).

[harendra-kumar]

it ruins incremental compilation

Thanks, will keep that in mind. Did not notice it till now.

[harendra-kumar]

I used {-# OPTIONS_GHC -optP-P #-} to suppress the CPP line number generation so that I could generate doctest snippets using conditional macros.

[phadej]

{-# OPTIONS_GHC -optP-P #-}

but that messes up error reporting (as it reports invalid lines then). It's really not perfect.

I'd suggest to not go too crazy with CPPing tests. You make your own (and my) life harder.

[harendra-kumar]

Not going crazy, there is just one reason to use it. Our released module imports an internal module and doctests are in the internal module which has a setup section. Now I want to expose this setup section to users who may want to run the examples. I do not want to duplicate the setup section because it will always lead to inconsistency.

You can see what I did here.

If I do not use block comments, the problem was that the ifdef in the setup section was causing a blank line breaking the setup section. If I use block comments then it caused CPP line number info to go into the setup section. It showed up in haddocks.

Another alternative is that I duplicate the full setup section in the two parts of the conditional.

I am getting correct line number info in error messages. Maybe the GHC option is not affecting docspec? And it is able to handle the line number stuff? I first saw the line numbers showing up in haddock when I suppressed it. Maybe docspec was dealing with it fine?

[phadej]

I am getting correct line number info in error messages.

In error messages GHC produces

I still think you try to do too fancy stuff with CPP, and run into limitations of CPP not being "haskell preprocessor". Sadly, GHC folks don't try to design solutions to problems like these (ghc-proposals/ghc-proposals#283 is dormant (bit opened in 2019!), but if something like that is implemented one could exports qualified modules, so a Haskell language construct could be used to do what you try to do with CPP).

I'm not going to spend time on problems better solved elsewhere. CPP is a band-aid at best.

[harendra-kumar]

You are right about the GHC error messages. It's a no go. So there is really no good solution to this problem.