qualified-imports-plugin: GHC plugin to automatically insert qualified imports

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

The 'description' field should be longer than the 'synopsis' field. It's useful to provide an informative 'description' to allow Haskell programmers who have never heard about your package to understand the purpose of your package. The 'description' field content is typically shown by tooling (e.g. 'cabal info', Haddock, Hackage) below the 'synopsis' which serves as a headline. Please refer to <https://www.haskell.org/cabal/users-guide/developing-packages.html#package-properties> for more details.

Please see README.md.

[Skip to Readme]

Properties

Versions	0.0.1, 0.0.1
Change log	None available
Dependencies	base (>=4.11 && <5), containers, ghc (>=8.10), syb [details]
License	BSD-3-Clause
Copyright	Utku Demir
Author	Utku Demir
Maintainer	Utku Demir
Category	Relude
Home page	https://github.com/utdemir/qualified-imports-plugin
Uploaded	by utdemir at 2021-03-27T00:08:39Z

Modules

[Index] [Quick Jump]

QualifiedImportsPlugin

Downloads

qualified-imports-plugin-0.0.1.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

utdemir

For package maintainers and hackage trustees

edit package information

Readme for qualified-imports-plugin-0.0.1

[back to package description]

qualified-imports-plugin

A GHC plugin to automatically insert common qualified imports. Supports GHC 8.10 and GHC 9.

Example

This plugin, alongside with relude, allows below code to compile, without requiring explicit qualified imports.

module Main where

countChars :: Text -> [(Char, Int)]
countChars txt =
  txt
    & Text.foldl
        (\m chr -> Map.alter (Just . maybe 1 (+1)) chr m)
        Map.empty
    & Map.toList
    & sortOn (Down . snd)

main :: IO ()
main =
  countChars (Text.pack "a peck of pickled peppers")
    & mapM_ print

With a cabal stanza like:

executable example
  main-is:          Main.hs
  ghc-options:      -fplugin=QualifiedImportsPlugin
  mixins:           base hiding (Prelude)
                  , relude (Relude as Prelude)
  build-depends:    base ^>=4.15.0.0
                  , relude
                  , text
                  , containers
                  , qualified-imports-plugin
  default-language: Haskell2010

See the complete example.

It comes with (hopefully) sane defaults, but these can be extended, eg: -fplugin-opt=QualifiedImportsPlugin:Data.Graph:Graph. The defaults can also be ommitted via -fplugin-opt=QualifiedImportsPlugin:no-defaults.

Background

The best practice when using Haskell modules these days is qualified imports. This solves name clashes (without resorting to ad-hoc polymorphism), and make the code easier to follow through.

However, this also ends up introducing a bunch of import statements to most real-world modules, it is not uncommon to see sections like:

import qualified Data.Map as Map
import qualified Data.Text as Text
import qualified Data.Aeson as Aeson

This gets tedious to both read and write after a while.

This plugin is a PoC to see what would it look like if we could omit some of those.

My main use case in mind is using this alongside with the excellent relude; so, the default names reflect the naming convention there (eg. relude has LText for Data.Text.Lazy (Text) hence this plugin has import qualified Data.Text.Lazy as LText as a default).

Details

One still needs to add required packages to the .cabal file.
The plugin imports the defined modules, regardless if they are used or not. This is to allow the suggestion in error messages to contain the available modules:

    Not in scope: ‘Teext.pack’
    Perhaps you meant one of these:
      ‘Text.pack’ (imported from Data.Text),
      ‘LText.pack’ (imported from Data.Text.Lazy),
      ‘Text.unpack’ (imported from Data.Text)
    No module named ‘Teext’ is imported.

In the presence of orphan/overlapping instances this can break/change the meaning of code.

It also adds the imports if an abbreviation used, but not possible to import. This again to get easier to understand errors:

    Could not load module ‘Data.Text’
    It is a member of the hidden package ‘text-1.2.4.1’.
    Perhaps you need to add ‘text’ to the build-depends in your .cabal file.
    Use -v (or `:set -v` in ghci) to see a list of the files searched for.
  |
4 | test1 = Text.pack "test1"
  |         ^^^^^^^^^