Should we make CommonState opaque or perhaps not expose it at all?

[jgm]

Currently the (non-public) T.P.Class.CommonState exposes CommonState(..), and T.P.Class exports this in the public API.

I propose that we do not export the details of CommonState (and perhaps we don't need to expose CommonState at all). We have functions like getVerbosity that interact with CommonState, but there is no reason to expose the internals in the public API.

And here is a reason against exposing them: I have just added stManager, which caches an HTTP client manager. This is something that has a purely internal use -- openURL uses the cached Manager to avoid creating it anew on each request. If we did want to create a cabal flag that turns off network features, then this would block it as long as stManager is in the public API (given the policy that cabal flags can't alter the API).

I don't think anything in pandoc itself would break if we didn't expose CommonState. pandoc-lua-engine has code that exposes CommonState externals (read-only I think) in the Lua interface; this would have to be removed. Do people depend on that?

@tarleb thoughts?

[tarleb]

In general I'd be in favor of that, but I think we'll first need to provide a better interface for Lua. A quick code search on GitHub shows that there are 250 hits for PANDOC_STATE in Lua code. It's debatable whether Lua filters need to know about the input files and output path, but accessing the resource path seems useful. Removing access to those input and output files would force a cleaner separation between filters, readers, and writers, so that would be a positive – if rather disruptive – change.

Maybe we should start adding more functions to the pandoc module, e.g., pandoc.resource_path()?

[jgm]

If we removed CommonState from the Haskell API, we could still provide reader functions that get this information, and the Lua interface could, in addition to exporting these functions, still support accessing this information through a PANDOC_STATE table. So, I think we could be fully backwards compatible on the Lua side.

[tarleb]

That's true. Yes, let's do it.

[jgm]

I've made the pandoc changes in the opaque-commonstate branch (pushed to this repository).
I have not attempted to make the necessary changes in pandoc-lua-engine -- I will leave that to you.

One note: the getLog function will return the log mesages in temporal order. The current Lua docs say the log field of commonstate returns the messages in reverse order. I suggest simply changes the docs for this.