# 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:
```cabal
  build-depends: ..., import-style-plugin, ...

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

```yaml
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:
```yaml
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 
      ```haskell
      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
      ```cabal
        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`