import-style-plugin: Helps maintain consistency of imports

[ development, library, mit ] [ Propose Tags ]
Versions [RSS] 0.1.0.0
Change log CHANGELOG.md
Dependencies aeson, base (>=4.11 && <4.20), containers, ghc (>=9.2 && <9.10), yaml [details]
License MIT
Author goosedb
Maintainer goosedb@yandex.ru
Category Development
Home page https://github.com/goosedb/import-style-plugin
Uploaded by goosedb at 2024-04-30T16:46:40Z
Distributions NixOS:0.1.0.0
Downloads 29 total (2 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for import-style-plugin-0.1.0.0

[back to package description]

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