Lenses for pandoc api (e.g. for Opts)

[dbaynard]

Hello,

It would be helpful to have lenses to change options when using the pandoc api.
This would not have to incur a dependency on lens, as these simple lenses can be defined using the microlens-th package, or just the microlens package and defining lenses manually as follows:

_optFilters :: Opts `Lens'` [FilePath]
_optFilters f Opt{..} = (\optFilters -> Opt{optFilters, ..}) <$> f optFilters
{-# INLINE _optFilters #-}

This could even be done with a DIY definition of Lens', and no new dependencies.

As a workaround, one can define lenses in programs or libraries that consume the pandoc api (as above), though this then scales poorly.

Would that be welcome?

[jgm]

See #3360.

Are lenses defined using microlens compatible with the full lens library?

[dbaynard]

Thanks, I'd skimmed that issue and thought this was sufficiently different, though I guess microlens may solve that problem.

The lenses are compatible (and edward kmett is one of the maintainers). However, there are many features of lens which microlens cannot provide. There are a number of microlens packages, thought for this change the ones I mentioned would suffice.

[jgm]

I'm not too familiar with lenses. Could you give some concrete examples of things that would be possible/easier with lenses?

[dbaynard]

In this context, lenses would be replacing record syntax, with two (main) advantages: composability, and API stability; that said my reason for asking is for convenience.

Composability

Rather than the lhs, one would write what is on the right.

optFilters opts                                            | opts ^. _optFilters
                                                           |
\x -> opts{ optFilters = x }                               | \x -> opts & optFilters .~ x
                                                           |
\x -> opts{ optFilters = x }                               | \x -> opts &~ do
                                                           |     optFilters .= x
                                                           |
\(f :: a -> b) -> opts{ optFilters = f (optFilters opts) } | \(f :: a -> b) -> opts & optFilters %~ f
                                                           |
\(f :: a -> a) -> opts{ optFilters = f (optFilters opts) } | \(f :: a -> a) -> opts &~ do
                                                           |     optFilters %= f

The form on the right makes it easier to compose behaviour.
These examples are only for quite simple cases, but pick the last case; perhaps f is a function that is best understood if inlined, or needs something in scope.

opts{ optFilters =                                            | opts &~ do
        optFilters opts <>                                    |     ms <- use optMetadata
        maybe [] unlines ("filter" `lookup` optMetadata opts) |     optFilters <>= maybe [] unlines ("filter" `lookup` ms)
    }                                                         |

That sort of code is written differently in convertWithOpts, though, which introduces a binding like filters' (not actual code):

do
    filters' <- optFilters opts <>
        maybe [] unlines ("filter" `lookup` optMetadata opts)

This makes the code more difficult to refactor as it relies on assignment in do notation, whereas using data types enables some of the refactoring I mentioned in #3289.

API stability

Exporting a record type from a module enables all the record syntax; creation, access, and updates.
Users may well write code that uses update syntax, so it is difficult to change the record in a backwards compatible manner.

Lenses do not have to correspond to the underlying records, so exporting lenses from the main module, and optionally the record fields from an internal module, means it is possible to decouple the internal data structures and the external API.

e.g. internal change introducing a new Filter type

data Opt = Opt {          | data Opt = Opt {
  ⋮                       |   ⋮
  , optFilters = [String] |   , optFilters = [Filter]
  ⋮                       |   ⋮
  }                       |   }

With lenses, not accessors, one could create a new lens for the new behaviour, and then next time there is a breaking API change, deprecate the old lenses.

The only difficulty is if there is no sensible default for the data type.

[tarleb]

Artyom, author of microlens, has the following to say about it:

I wrote microlens, but I see no reason to use it for apps and I don't get why people do. For libraries, not having a ton of dependencies feels nice though.

Since pandoc is both a library and an application, going all in and using lens would probably be acceptable.

My personal opinion: optics are both fascinating and convenient, but they also introduce a whole lot of additional complexity. I like that pandoc's Haskell code is (mostly) palpable for beginners. Adding lenses would take away from this.