@hackage import-style-plugin0.1.0.0

Helps maintain consistency of imports

Import style GHC plugin

The plugin helps to unify imports style via compile warnings/errors

Tested with:

  • 9.2.7
  • 9.4.8
  • 9.6.4
  • 9.8.2

Usage

Yaml config

Enable plugin in your cabal file:

  build-depends: ..., import-style-plugin, ...

  ghc-options: -fplugin ImportStylePlugin.Yaml -fplugin-opt ImportStylePlugin.Yaml:<path-to-config>

Write config:

qualificationStyle: Post | Pre | null

bannedModules: # can be null
  Module.Name:
    severity: Error | Warning
    why: string with ban reason

importRules: # can be null
  DataModuleName:
    severity: Error | Warning
    rules:
      - qualification: Required | Forbidden | null
        aliases:
          # Either `exactly`, so alias can't be omitted 
          exactly:
            - Module.Alias
            - Alias
          # or just list, so alias can be omitted
          - Module.Alias
          - Alias
          # or null
        importedNames:
          # Either whitelist, so import should be 
          # accompanied with explicit import list 
          whitelist:
            - pattern (:|>) 
            - type (+)
            - foo
          # or blacklist, so import should be 
          # accompanied with explicit hiding list with all these names
          # or explicit import list shouldn't contain any of these names 
          blacklist:
            - pattern (:|>) 
            - type (+)
            - foo
          # or null

Here is example:

qualificationStyle: Post

bannedModules:
  # Forbids Data.Map at all
  Data.Map:
    severity: Error
    why: Use 'Data.Map.Strict'

importRules:
  # Either
  # import Data.Text (Text)
  # or
  # import Data.Text qualified as Text
  Data.Text:
    severity: Warning
    rules:
      - qualification: Required
        aliases:
          exactly: 
            - Text

      - qualification: Forbidden
        importedNames:
          whitelist: 
            - Text

Derived plugin

It can be useful if you have a lot of projects with one style. So you haven't to copy paste config but just use style as library

  1. Create library package
  2. Add to deps import-style-plugin
  3. Create module YourPlugin.hs (or something like that, it's unimportant)
  4. Put there
    module YourPlugin where
    
    import ImportStylePlugin.Derived qualified as Derived
    import ImportStylePlugin.Config as Cfg
    
    -- variable name `plugin` IS important
    -- Configure your style with Haskell types from `ImportStylePlugin.Config`
    plugin = Derived.plugin
      ImportsStyle
        { qualificationStyle = ...
        , bannedModules = ...
        , importRules = ... 
        }
    
  5. Plug in
      build-depends: ..., your-import-style-plugin, ...
    
      ghc-options: -fplugin YourPlugin
    

Tips

Custom warning

Since ghc-9.8 the plugin introduces custom warning x-import-style. So if you set -Werror but still want to style warnings be warnings use ghc option -Wwarn=x-import-style. You also can disable at all warnings with -Wno-x-import-style