search

vaclavsvejcar / headroom

©️ Manager for license headers in source code files.
https://doc.norcane.com/headroom/latest/
BSD 3-Clause "New" or "Revised" License
48 stars 3 forks source link

Extract dynamic variables from Haskell source code files #25

Closed vaclavsvejcar closed 4 years ago

vaclavsvejcar commented 4 years ago

Goal of this task is to support extracting extra dynamic template variables for Haskell source code files, which would singinicantly simplify work with Haddock module headers.

The Problem

Imagine following template file for Haskell source code files:

{-|
Module      : MODULE NAME ???
Description : SHORT MODULE DESCRIPTION ???
Copyright   : (c) {{ year }} {{ author }}
License     : BSD-3
Maintainer  : {{ email }}
Stability   : experimental
Portability : POSIX

LONG MODULE DESCRIPTION ???
-}

Current version of Headroom will fill in the static variables, such as year and author since those are same for all source code files, but there's no way to define variable values such as Haskell module name or Haddock description, as these differs file by file. This is fine when header is added to the file, as you need to fill these by hand, but when you try to replace this header with Headroom, it will overwrite your hand-written fields again with initial values.

The Solution

This task adds functionality that will support extracting Haskell module name and selected fields from Haddock module header, from the currently processed Haskell source code file. If no such Haddock module is present (i.e. adding header for very first time), you'll need to fill these by hand, but next time you use Headroom to replace header, it will correctly extract and fill these variables from already present header.

In order to apply these changes, header example from above will change to:

{-|
Module      : {{{ _haskell_module_name }}}
Description : {{{ _haskell_module_shortdesc }}}
Copyright   : (c) {{ year }} {{ author }}
License     : BSD-3
Maintainer  : {{ email }}
Stability   : experimental
Portability : POSIX

{{{ _haskell_module_longdesc }}}
-}

where:

chshersh commented 4 years ago

Thanks for writing this project! That would be a really nice feature!

I've tried to run headroom on summoner and here is the diff:

diff --git a/summoner-cli/src/Summoner/License.hs b/summoner-cli/src/Summoner/License.hs
index 1afb6ac..e61a0e5 100644
--- a/summoner-cli/src/Summoner/License.hs
+++ b/summoner-cli/src/Summoner/License.hs
@@ -1,12 +1,14 @@
-{- |
-Copyright: (c) 2017-2020 Kowainik
-SPDX-License-Identifier: MPL-2.0
-Maintainer: Kowainik <xrom.xkov@gmail.com>
-
-Data types that represent license names and license content and functions
-to work with them.
+{-|
+Module      : MODULE_NAME
+Description : SHORT_DESC
+Copyright   : (c) 2020 Kowainik
+License     : MIT
+Maintainer  : xrom.xkov@gmail.com
+Stability   : experimental
+Portability : POSIX
+
+LONG_DESC
 -}

You can notice that it completely removes the top-level module comment, and this makes the tool unusable at the moment.

vaclavsvejcar commented 4 years ago

@chshersh Thank you for your feedback! If I understand correctly your problem, you'd like to keep the very top Haddock module comment untouched by Headroom and instead Headroom should put somewhere second comment containing that license text only? Because right now the built in Haskell support actually renders the top level module Haddock comment, with the license mentioned on the License row (as you can see in the diff). Question is then, what should be the default behaviour, do we want to keep only one comment, which will serve as both Haddock module and license comment, or do we want to manage two different comments, where Headroom will ignore the Haddock one and manage its own license comment placed somewhere below? Do you have any opinion on this?

chshersh commented 4 years ago

@vaclavsvejcar I'd like to have a single top-level Haddock comment which contains both license information and top-level Haddock. Licensing information renders nicely on Hackage, so I'd like to keep it. At the same time, I don't want to have the same information duplicated in the module. So in the best case, it would be nice if Headroom could recognize existing top-level Haddock and update it.

To be more precise, a diff like below would be the most desirable:

diff --git a/summoner-cli/src/Summoner/License.hs b/summoner-cli/src/Summoner/License.hs
index 1afb6ac..e61a0e5 100644
--- a/summoner-cli/src/Summoner/License.hs
+++ b/summoner-cli/src/Summoner/License.hs
@@ -1,12 +1,14 @@
-Copyright: (c) 2017-2019 Kowainik
-SPDX-License-Identifier: MPL-2.0
-Maintainer: Kowainik <xrom.xkov@gmail.com>
+Copyright               : (c) 2017-2020 Kowainik
+SPDX-License-Identifier : MPL-2.0
+Maintainer              : Kowainik <xrom.xkov@gmail.com>

Ability to specify/ignore the Stability and Portability (and other fields) would be nice as well.

vaclavsvejcar commented 4 years ago

@chshersh Speaking about the Stability and Portability fields, you can do this right now by adding them to your haskell.mustache template (either the generated one or custom one) so you can have:

Template

{-|
Copyright               : (c) {{ year }} {{ author }}
SPDX-License-Identifier : MPL-2.0
Maintainer              : {{ email }}
Stability               : {{ stability }}
Portability             : {{ portability}}
-}

YAML config

variables:
  year: "2017-2020"
  author: Kowainik
  email: "Kowainik <xrom.xkov@gmail.com>"
  portability: POSIX
  stability: stable

But to your main point - right now, the current logic for replacing headers is unfortunately pretty dumb and works in these steps:

  1. correct file type is detected (Haskell in this case)
  2. selected implementation (Headroom.Header.Impl.Haskell) check if any license header is present and if yes, returns the integer with number of lines from the file start that contains the license header (this is the dumb part)
  3. That number of lines is drop at the beginning of the file, new license header is generated using the correct template file and variables from YAML file and this one is pasted that the very first line of the file.

So not only that Headroom cannot do any partial replacements of existing license header, it also cannot work with license headers that are in between the code, not before any code (I think this will be issue for #28). Unfortunately for Haskell the situation is more complex than for many other languages (Java, Scala), where the license header is usually just dummy very first comment of the source code file.

Surely I'm willing to fix/extend/enhance this detection logic, but haven't yet found any nice generic approach that would cover at least these requirements:

vaclavsvejcar commented 4 years ago

Implemented and released as part of v0.3.0.0.