headroom-0.1.3.0: README.md

So you are tired of managing license headers in your codebase by hand? Then __Headroom__ is the right tool for you! Now you can define your license header as [Mustache][web:mustache] template, put all the variables (such as author's name, year, etc.) into the [YAML][wiki:yaml] config file and Headroom will take care to add such license headers to all your source code files.

__Table of Contents__

- [1. Main Features](#1-main-features)
- [2. Planned Features](#2-planned-features)
- [3. Installation](#3-installation)
    - [3.1. From Source Code](#31-from-source-code)
        - [3.1.1. Using Cabal](#311-using-cabal)
        - [3.1.2. Using Stack](#312-using-stack)
- [4. Basic Overview](#4-basic-overview)
    - [4.1. Main Concepts](#41-main-concepts)
    - [4.2. License Header Detection](#42-license-header-detection)
- [5. Quick Start Guide](#5-quick-start-guide)
    - [5.1. Initializing Headroom](#51-initializing-headroom)
        - [5.1.1. Automatic Initialization](#511-automatic-initialization)
        - [5.1.2. Manual Initialization](#512-manual-initialization)
    - [5.2. YAML Configuration File](#52-yaml-configuration-file)
    - [5.3. Running Headroom](#53-running-headroom)
- [6. Command Line Interface Overview](#6-command-line-interface-overview)
    - [6.1. Init Command](#61-init-command)
    - [6.2. Run Command](#62-run-command)
    - [6.3. Generator Command](#63-generator-command)
        - [6.3.1. Supported License Types](#631-supported-license-types)
        - [6.3.2. Supported File Types](#632-supported-file-types)

## 1. Main Features
- __License Header Management__ - allows to add, replace or drop license headers in source code files.
- __License Header Autodetection__ - you can even replace or drop license headers that weren't generated by Headroom, as they are automatically detected from source code files, not from template files.
- __Template Generator__ - generates license header templates for most popular _open source_ licenses. You can use these as-is, customize them or ignore them and use your custom templates.
- __Automatic Initialization__ - using the _Init_ command, _Headroom_ can detect what source code files you have in your project and generate initial configuration file and appropriate template skeletons.

## 2. Planned Features
- [[#25]][i25] __Content-aware Templates__ - license header templates will be able to extract some template variables from source code file for which the template is rendered
- __Binary Distribution__ - pre-built binaries will be generated for each release for major OS platforms

## 3. Installation
> Binary distribution will be available soon, there are also plans to add _Headroom_ to popular package managers.

### 3.1. From Source Code
Headroom is written in [Haskell][web:haskell], so you can install it from source code either using [Cabal][web:cabal] or [Stack][web:stack].

#### 3.1.1. Using Cabal
1. install [Cabal][web:cabal] for your platform
1. run `cabal install headroom`
1. add `$HOME/.cabal/bin` to your `$PATH`

#### 3.1.2. Using Stack
1. install [Stack][web:stack] for your platform
1. run `stack install headroom`
1. add `$HOME/.local/bin` to your `$PATH`

## 4. Basic Overview

### 4.1. Main Concepts
1. __Template files__ - Template files contains templates in [Mustache][web:mustache] format, used for rendering license headers. During rendering phase, all variables are replaced by values loaded from _YAML_ configuration file. Each supported source code file has unique template, because license headers may differ for individual programming languages (i.e. different syntax for comments, etc.).
1. __Source Code Files__ - Headroom automatically discovers individual source code files in configured location and can manage (add/remove/drop) license headers in supported types of source code files.
1. __Variables__ - are defined in _YAML_ configuration file and these values are used to replace variables present in the template files.

### 4.2. License Header Detection
Unlike many other tools, Headroom can not only add, but also replace or drop existing license headers in source code files, even if there is already some header not generated by Headroom. This is done by implementing unique detection logic for each individual supported file type, but usually it's expected that the very first block comment is the license header. If you miss support for your favorite file type, please [open new issue][meta:new-issue].

## 5. Quick Start Guide
Let's demonstrate how to use Headroom in real world example: assume you have small source code repository with following structure and you'd like to setup Headroom for it:

```
project/
  └── src/
      ├── scala/
      │   ├── Foo.scala
      │   └── Bar.scala
      └── html/
          └── template1.html
```

### 5.1. Initializing Headroom

#### 5.1.1. Automatic Initialization
Easiest and fastest way how to initialize Headroom for your project is to use the _Init_ command, which generates all the boilerplate for you. The only drawback is that you can use it only in case that you use any supported open source license for which Headroom contains license header templates:

```shell
cd project/
headroom init -l bsd3 -s src/
```

This command will automatically scan source code directories for supported file types and will generate:
1. `.headroom.yaml` configuration file with correctly set path to template files, source codes and will contain dummy values for variables.
1. `headroom-templates/` directory which contains template files for all known file types you use in your project and for open source license you choose.

Now the project structure will be following:

```
project/
  ├── src/
  │   ├── scala/
  │   │   ├── Foo.scala
  │   │   └── Bar.scala
  │   └── html/
  │       └── template1.html
  ├── headroom-templates/
  │   ├── html.mustache
  │   └── scala.mustache
  └── .headroom.yaml
```

#### 5.1.2. Manual Initialization
If you for some reason don't want to use the automatic initialization using the steps above, you can either create all the required files (_YAML_ configuration and template files) by hand, or you can use the _Generator_ command to do that in semi-automatic way:

```shell
cd project/
headroom gen -c >./.headroom.yaml

mkdir headroom-templates/
cd headroom-templates/

headroom gen -l bsd3:css >./css.mustache
headroom gen -l bsd3:html >./html.mustache
headroom gen -l bsd3:scala >./scala.mustache
```

After these steps, make sure you set correctly the paths to template files and source code files in the _YAML_ configuration file.

### 5.2. YAML Configuration File
Headroom's _YAML_ configuration file must be placed in root of your project and called `.headroom.yaml`. The configuration itself is pretty simple and consists of following keys:

```yaml
run-mode: add
source-paths:
  - .
template-paths:
  - headroom-templates
variables:
  author: John Smith
  email: john.smith@example.com
  project: My project
  year: '2020'
```

- `run-mode` - sets the default behaviour of _Run_ command (`headroom run`). Possible options are:
  - `add` - Headroom will only add license headers to source code where these are missing, but won't touch files with existing headers
  - `drop` - Headroom will drop existing license headers without any replacement
  - `replace` - Headroom will add missing or replace existing license headers
- `source-paths` - paths to source code files (either files or directories)
- `template-paths` - paths to template files (either files or directories)
- `variables` - variables (key-value) to replace in templates

These settings can be then overriden by corresponding command line optionss. See more details about these settings in command line interface overview section below.

### 5.3. Running Headroom
Now we're ready to run Headroom:

```shell
cd project/
headroom run      # adds license headers to source code files
headroom run -r   # adds or replaces existing license headers
headroom run -d   # drops existing license headers from files
```

## 6. Command Line Interface Overview
Headroom provides various commands for different use cases. You can check commands overview by performing following command:

```
$ headroom --help
headroom v0.1.3.0 :: https://github.com/vaclavsvejcar/headroom

Usage: headroom COMMAND
  manage your source code license headers

Available options:
  -h,--help                Show this help text

Available commands:
  run                      add or replace source code headers
  gen                      generate stub configuration and template files
  init                     initialize current project for Headroom
```

### 6.1. Init Command
Init command is used to initialize Headroom for project by generating all the required files (_YAML_ config file and template files). You can display available options by running following command:

```
$ headroom init --help
Usage: headroom init (-l|--license-type LICENSE_TYPE) (-s|--source-path PATH)
  initialize current project for Headroom

Available options:
  -l,--license-type LICENSE_TYPE
                           type of open source license
  -s,--source-path PATH    path to source code file/directory
  -h,--help                Show this help text
```

### 6.2. Run Command
Run command is used to manipulate (add, replace or drop) license headers in source code files. You can display available options by running following command:

```
$ headroom run --help
Usage: headroom run [-s|--source-path PATH] [-t|--template-path PATH]
                    [-v|--variable KEY=VALUE] ([-r|--replace-headers] |
                    [-d|--drop-headers]) [--debug]
  add or replace source code headers

Available options:
  -s,--source-path PATH    path to source code file/directory
  -t,--template-path PATH  path to header template file/directory
  -v,--variable KEY=VALUE
                           values for template variables
  -r,--replace-headers     force replace existing license headers
  -d,--drop-headers        drop existing license headers only
  --debug                  produce more verbose output
  -h,--help                Show this help text
```

Note that command line options override options set in the configuration _YAML_ file. Relation between command line options and _YAML_ configuration options is below:

| YAML option         | Command Line Option       |
|---------------------|---------------------------|
| `run-mode: add`     | _(default mode)_          |
| `run-mode: drop`    | `-d`, `--drop-headers`    |
| `run-mode: replace` | `-r`, `--replace-headers` |
| `source-paths`      | `-s`, `--source-path`     |
| `template-paths`    | `-t`, `--template-path`   |


### 6.3. Generator Command
Generator command is used to generate stubs for license header template and _YAML_ configuration file. You can display available options by running following command:

```
$ headroom gen --help
Usage: headroom gen [-c|--config-file] [-l|--license name:type]
  generate stub configuration and template files

Available options:
  -c,--config-file         generate stub YAML config file to stdout
  -l,--license name:type   generate template for license and file type
  -h,--help                Show this help text
```

When using the `-l,--license` option, you need to select the _license type_ and _file type_ from the list of supported ones listed bellow. For example to generate template for _Apache 2.0_ license and _Haskell_ file type, you need to use the `headroom gen -l apache2:haskell`.

#### 6.3.1. Supported License Types
Below is the list of supported _open source_ license types. If you miss support for license you use, feel free to [open new issue][meta:new-issue].

| License        | Used Name |
|----------------|-----------|
| _Apache 2.0_   | `apache2` |
| _BSD 3-Clause_ | `bsd3`    |
| _GPLv2_        | `gpl2`    |
| _GPLv3_        | `gpl3`    |
| _MIT_          | `mit`     |

#### 6.3.2. Supported File Types
Below is the list of supported source code file types. If you miss support for programming language you use, feel free to [open new issue][meta:new-issue].

| Language     | Used Name | Supported Extensions |
|--------------|-----------|----------------------|
| _CSS_        | `css`     | `.css`               |
| _Haskell_    | `haskell` | `.hs`                |
| _HTML_       | `html`    | `.html`, `.htm`      |
| _Java_       | `java`    | `.java`              |
| _JavaScript_ | `js`      | `.js`                |
| _Scala_      | `scala`   | `.scala`             |


[i25]: https://github.com/vaclavsvejcar/headroom/issues/25
[meta:new-issue]: https://github.com/vaclavsvejcar/headroom/issues/new
[web:bsd-3]: https://opensource.org/licenses/BSD-3-Clause
[web:cabal]: https://www.haskell.org/cabal/
[web:haskell]: https://haskell.org
[web:mustache]: https://mustache.github.io
[web:stack]: https://www.haskellstack.org
[wiki:yaml]: https://en.wikipedia.org/wiki/YAML