Naming improvements for the Dhall module

[sjakobi]

@Gabriel439 had mentioned that Interpret should be renamed to FromDhall, and Inject to ToDhall. This was implemented in #1437.

IMHO there are more things in the Dhall module that deserve better names:

• Type and InputType.
• input suggests a link to InputType but is actually more related to Interpret.
• InterpretOptions are used both by Interpret and by Inject.

This renaming would be a large breaking change, so we should try find a naming scheme that we're happy with and then implement it within a single version bump.

Here's what I perceive to be the "big" names and exports from Dhall:

Dhall to Haskell

class FromDhall a where
    autoWith :: InterpretOptions -> Decoder a

auto :: FromDhall a => Decoder a

data Decoder a = Decoder
    { extract  :: Expr Src X -> Extractor Src X a
    , expected :: Expr Src X
    }

input :: Decoder a -> Text -> IO a

Haskell to Dhall

class ToDhall a where
    injectWith :: InterpretOptions -> Encoder a

inject :: ToDhall a => Encoder a

data Encoder a = 
    { embed    :: a -> Expr Src X
    , declared :: Expr Src X
    }

[sjakobi]

Here's an initial idea for a better naming scheme:

Dhall to Haskell

class FromDhall a where
    decoderWith :: MarshalOptions -> Decoder a

defaultDecoder :: FromDhall a => Decoder a

data Decoder a = Decoder
    { decode   :: Expr Src X -> Extractor Src X a -- or keep 'extract'?
    , expected :: Expr Src X
    }

decodeIO :: Decoder a -> Text -> IO a

Haskell to Dhall

class ToDhall a where
    encoderWith :: MarshalOptions -> Encoder a

defaultEncoder :: ToDhall a => Encoder a

data Encoder a = Encoder
    { encode   :: a -> Expr Src X
    , declared :: Expr Src X
    }

[Gabriella439]

@sjakobi: We don't need to rename everything at once. In fact, I think it's actually better if we spread breaking changes over time as I discuss here:

• Release early and often

I think the first step should be just renaming the classes to FromDhall and ToDhall

[sjakobi]

I have updated the issue description with the changes from #1437. What should be the next step?

I still like the idea of renaming Type on the FromDhall side to Decoder and InputType on the ToDhall side to Encoder.

[Gabriella439]

@sjakobi: Yeah, that seems reasonable to me, although we might want to postpone that second breaking change to the next release

[sjakobi]

that second breaking change

Are you referring to both Type -> Decoder and InputType -> Encoder here or just to InputType -> Encoder? I.e. would it be ok to include both in the upcoming v1.28?

[Gabriella439]

@sjakobi: It's fine to bundle both of those changes in the same release

[sjakobi]

I have updated the issue description again with the changes from #1485.

#1485 spawned #1492 which could help fix the somewhat unfair naming of field, encodeField etc.

I'd eventually like to get rid of the inject[With] names which seem redundant now that we have ToDhall, Encode[r] and embed. But let's maybe wait for what #1492 brings.