# Nugrant

[![Gem Version](https://badge.fury.io/rb/nugrant.png)][gem]
[![Build Status](https://secure.travis-ci.org/maoueh/nugrant.png?branch=master)][travis]
[![Dependency Status](https://gemnasium.com/maoueh/nugrant.png?travis)][gemnasium]
[![Code Climate](https://codeclimate.com/github/maoueh/nugrant.png)][codeclimate]

[gem]: https://rubygems.org/gems/nugrant
[travis]: http://travis-ci.org/maoueh/nugrant
[gemnasium]: https://gemnasium.com/maoueh/nugrant
[codeclimate]: https://codeclimate.com/github/maoueh/nugrant

Nugrant is a library to easily handle parameters that need to be
injected into an application via different sources (system, user,
current, defaults). But foremost, a Vagrant plug-in that will enhance
Vagrantfile to allow user specific configuration values.

Supported platforms:

 * Vagrant 1.x
 * Ruby 1.9.3+

## Quick Start

Using Nugrant as a plug-in provides an easy and hierarchical system to manage
machine and user specific parameters.

Let's start with an example. You need to distribute among your enterprise a
`Vagrantfile` to start and provision an AWS EC2 instance (or for an open-source project).
The `aws_access_key` and `aws_secret_key` should be configurable depending on the user
running `vagrant up`.

To achieve this, simply create a file named `.vagrantuser` that resides in the directory
as your `Vagrantfile`:

    aws:
      access_key: "123456"
      secret_key: "abcdef"

In your `Vagrantfile`, `Nugrant` will let you access the parameters via the
`config.user` object:

    Vagrant.configure("2") do |config|
      ...

      config.vm.provider :aws do |aws, override|
        aws.access_key_id = config.user.aws.access_key
        aws.secret_access_key = config.user.aws.secret_key

        ...
      end
    end

You then ignore the `.vagrantuser` file in your revision control, so each developer
as a specific one with their own values. People often commit a `.vagrantuser.example`
file in project's repository as an easy startup for the various parameters that
must be filled in, something like:

    aws:
      access_key: "<ACCESS_KEY_HERE>"
      secret_key: "<SECRET_KEY_HERE>"

To find where your project `.vagrantuser` is located, Nugrant uses the directory
where the `Vagrantfile` is located. It achieves this using the same set of
rules as Vagrant meaning you can be in a nested directory and parameters
will still be fetched correctly.

Moreover, like other similar system, there is a hierarchy of `.vagrantuser` files
that you can leverage:

| Name     | Location                                | Priority  | Overrides                |
| ---------|-----------------------------------------|:---------:|--------------------------|
| Defaults | [config.user.defaults](#default-values) | 4         | -                        |
| System   | $SYSTEM/.vagrantuser                    | 3         | Defaults                 |
| User     | ~/.vagrantuser                          | 2         | Defaults & System        |
| Project  | .vagrantuser                            | 1         | Defaults & System & User |

The project level directory is always the same as the directory where your
`Vagrantfile` resides and same rules as Vagrant are used to find it.
The `~` is the user's home directory and `$SYSTEM` is the platform dependent
folder where system global can be put. Check [Hierarchy](#hierarchy) section
for where `$SYSTEM` maps exactly.

You can use the command `vagrant user parameters` to see the final merged
hierarchy seen by Nugrant. This command also prints [restricted keys](#restricted-keys)
defined in your hierarchy.

Accessing parameters in your `Vagrantfile` can be done either by method access
(i.e. `config.user.<key>`) or by array access (i.e. `config.user[<key>]`).
This support is working for any deepness, only `config.user` is different
because provided directly by `Vagrant` and not by this plugin.

However, a drawback with method access, not present with array access, is its
set of [restricted keys](#restricted-keys) for which usage is prohibited. These
are in facts calls to method defined by the [Bag](lib/nugrant/bag.rb) class
([Bag](lib/nugrant/bag.rb) extends [Hash](http://ruby-doc.org/core-2.0/Hash.html)).
It's plain Ruby, use it at your advantage like iterating through a collection
using the `.each` method.

This is where the quick start end. Continue to section [Installation](#installation)
if you need so help on how to install Nugrant. Or jump to [Usage](#usage) section
which describe in greater details all necessary information needed to deeply
understand Nugrant and use it at its full potential.

## Installation

### Vagrant

Vagrant's plug-in system is very well done and Nugrant supports
the following plug-in API versions:

 * V2 => Vagrant 1.x

To install the Nugrant as a Vagrant plug-in, simply type the following
command in a terminal:

    vagrant plugin install nugrant

#### Vagrant 0.x

Vagrant 0.x is not supported anymore. If you still need support for
Vagrant 0.x, please use release line `1.x` (branch [1.x](https://github.com/maoueh/nugrant/tree/1.x)).

### Library

If you would like to use Nugrant as a library, simply reference
it as a dependency of your application. Probably by adding it to
your `Gemfile` or your `.gemspec` file.

    "nugrant", "~> 2.0"

## Usage

Whether used as a library or a Vagrant plug-in, Nugrant has some
common concepts that apply to both usages. The most important
one is the parameters hierarchy.

### Common

Nugrant can read parameters from various locations and will merge
them all together in a single set. Merging is done in a fairly
standard fashion.

Here the precedence rules that apply when merging parameters
from various location. List index indicate the priority of the
entry. Entry with lower number has lower priority (values at this
priority will be overridden by values defined on higher priorities).

 1. Defaults
 2. System
 3. User
 4. Current

In text, this means that current parameters overrides user
parameters, user parameters overrides system parameters and
finally system parameters overrides defaults parameters.

When two keys that are merged together points to Array values,
the default operation is to replace current Array by
overriding one. The default merge strategy can be customized.

### Vagrant

All examples shown here are for Vagrant 1.1+. They have
been tested with Vagrant 1.4.0. Keep this in mind when
copying examples.

Let start with a small use case. Say the git repository you want
to share with your guest VM is not located under the root folder of
your `Vagrantfile`. That means you will need to specify
an absolute host path to share the folder on the guest VM.

Your `Vagrantfile` would look like this:

    Vagrant.configure("2") do |config|
      config.vm.box = "base"
      config.vm.synced_folder "/home/user/work/git", "/git"
    end

However, what happens when multiple developers
need to share the same `Vagrantfile`? This is the main
use case this plug-in try to address.

When Vagrant starts, it loads all vagrant plug-ins it knows
about. If you installed the plug-in with one of the two
methods we listed above, Vagrant will know about Nugrant
and will load it correctly.

To use the plug-in, first create a YAML file named
`.vagrantuser` in the same folder where your `Vagrantfile` is
located. The file must be a valid YAML file:

    repository:
      project: "/home/user/work/git"

The configuration hierarchy you define in the `.vagrantuser` file
is imported into the `config` object of the `Vagrantfile`
under the key `user`. So, with the `.vagrantuser` file above, you
could have this `Vagrantfile` that abstract absolute paths.

    Vagrant.configure("2") do |config|
      config.vm.box = "base"
      config.vm.synced_folder config.user.repository.project, "/git"
    end

This way, paths can be customized by every developer. They just
have to add a `.vagrantuser` file where user specific configuration
values can be specified. The `.vagrantuser` should be ignored by you
version control system so it is to committed with the project.

Additionally, you can also have a `.vagrantuser` under your user home
directory. This way, you can set parameters that will be
available to all your `Vagrantfile` files. The `.vagrantuser` located
within the same folder as the `Vagrantfile` file will overrides
parameters defined in the `.vagrantuser` file defined in the user
home directory.

For example, you have `.vagrantuser` file located at `~/.vagrantuser`
that has the following content:

    ssh_port: 2223
    repository:
      project: "/home/user/work/git"

And another `.vagrantuser` within the same folder as your `Vagrantfile`:

    ssh_port: 3332
    repository:
      personal: "/home/user/personal/git"

Then, the `Vagrantfile` could be defined like this:

    Vagrant.configure("2") do |config|
      config.ssh.port config.user.ssh_port

      config.vm.synced_folder config.user.repository.project, "/git"
      config.vm.synced_folder config.user.repository.personal, "/personal"
    end

That would be equivalent to:

    Vagrant.configure("2") do |config|
      config.ssh.port 3332

      config.vm.synced_folder "/home/user/work/git", "/git"
      config.vm.synced_folder "/home/user/personal/git", "/personal"
    end

#### Hierarchy

As you can see, the parameters defined in the second `.vagrantuser` file
(the current one) overrides settings defined in the `.vagrantuser` found
in the home directory (the user one).

Here the list of locations where Nugrant looks for parameters:

 1. Defaults (via `config.user.defaults` in `Vagrantfile`)
 2. System (`/etc/.vagrantuser` on Unix, `%PROGRAMDATA%/.vagrantuser` or `%ALLUSERSPROFILE%/.vagrantuser` on Windows)
 3. Home (`~/.vagrantuser`)
 4. Project (`.vagrantuser` within the same folder as the `Vagrantfile`)

#### Paths

When you want to specify paths on, specially on Windows, it's probably
better to only use forward slash (`/`). The main reason for this is because
Ruby, which will be used at the end by Vagrant is able to deal with forward
slash even on Windows. This is great because with this, you can avoid
values escaping in YAML file. If you need to use backward slash (`\`), don't
forget to properly escape it!

    value: "C:/Users/user/work/git"
    value: "C:\\Users\\user\\work\\git"

Moreover, it is preferable that paths are specified in full
(i.e. no `~` for HOME directory for example). Normally, they
should be handled by `Vagrant` but it may happen that it's not
the case. If your have an error with a specific parameter,
either expand it in your config:

    project: "/home/joe/work/ruby/git"

Of expand it in the `Vagrantfile`:

    config.vm.synced_folder File.expand_path(config.user.repository.project), "/git"

#### Parameters access

Parameters in the `Vagrantfile` can be retrieved via method call
of array access.

    config.user['repository']['project'] # Array access
    config.user.repository.project       # Method access

You can even mix the two if you want, but we do not recommend
it since its always better to be consistent:

    config.user['repository'].project # Mixed access
    config.user.repository['project'] # Mixed access

Only the root key, i.e. `config.user`, cannot be access with
both syntax, only the method syntax can be used since this
is not provided by this plug-in but by Vagrant itself.

##### Tips

Each non-final parameter (i.e a parameter that contains other parameters and
not a scalar value) is in fact a [Bag](/lib/nugrant/bag.rb)
object. You can call any defined methods on it. This object extends
[Hash](http://ruby-doc.org/core-2.0/Hash.html) (itself including
module [Enumerable](http://ruby-doc.org/core-2.0/Enumerable.html)). Hence,
you can do neat things like iterating over your values or filtering them:

    config.user.application.users.each do |key, data|
      puts "Key #{key}: #{data}"
    end

##### Restricted keys

Method access has the neat advantage of being beautiful to the
eye. However, the drawback of using this retrieval syntax is
that not all keys are permitted. As explained in the [Tips](#tips)
section, the object you are calling when using method access
is in fact of type [Bag](/lib/nugrant/bag.rb). Hence, if you
are using a key which collapse with ones of Bag's keys, it will
call the method instead of given you the value of you parameter.
At best, you will get a weird behavior and at worst a stack
trace when trying to access the parameter.

If you really want to use one of the restricted keys, simply
ensure to always use array access method.

The list of restricted keys can be accessed using command
`vagrant user restricted-keys`.

#### Default values

When using parameters, it is often needed so set default values
for certain parameters so if the user does not define one, the
default value will be picked up.

For example, say you want a parameter that will hold the ssh
port of the vm. This parameter will be accessible via the
parameter `config.user.vm.ssh_port`.

You can use the following snippet directly within your Vagrantfile
to set a default value for this parameter:

    Vagrant.configure("2") do |config|
      config.user.defaults = {
        "vm" => {
          "ssh_port" => "3335"
        }
      }

      config.ssh.port config.user.vm.ssh_port
    end

With this Vagrantfile, the parameter `config.user.vm.ssh_port`
will default to `3335` in cases where it is not defined by the
user.

If the user decides to change it, he just has to set it in his
own `.vagrantuser` and it will override the default value defined
in the Vagrantfile.

#### Array merge strategies

As stated previously, when two arrays are merged together,
the default strategy is to replace current array with new one.

However, in some certain circumstances, you may need another
behavior. Here the list of strategies that can be used.

 * `:replace` (*default*)
   With this strategy, the new array completely replace the
   current one.

 * `:concat`
   With this strategy, new array is appended to the end
   of current array when merged. The `Array` `+` operator
   is used to concatenante the two arrays.

 * `:extend`
   With this strategy, current array is extended with values
   from new one. The `Array` `|` (union) operator
   is used to extend the array.

You can use the following snippet directly within your Vagrantfile
to change the array merge strategy:

    Vagrant.configure("2") do |config|
      config.user.array_merge_strategy = :extend

      config.ssh.port config.user.vm.ssh_port
    end

Note that you should change the array merge strategy before
you access any keys because it's just once set that values
are computed using the new strategy.

If you specify an unsupported strategy, nothing will happen.

#### Commands

In this section, we describe the various vagrant commands defined
by this plug-in that can be used to interact with it.

##### Parameters

This command will print the currently defined parameters at the
given location. All rules are respected when using this command.
It is usefull to see what parameters are available and what are
the current values of those parameters.

Usage:

    > vagrant user parameters
    ---
    config:
      user:
        chef:
          cookbooks_path: /Users/Chef/kitchen/cookbooks
          nodes_path: /Users/Chef/kitchen/nodes
          roles_path: /Users/Chef/kitchen/roles

Add flag `-h` (or `--help`) for description of the command and a
list of available options.

##### Restricted Keys

This command will print the keys that cannot be accessed using
the method access syntax.

Usage:

    > vagrant user restricted-keys

##### Env

Sometimes, you would like to have acces to the different values
stored in your `.vagrantuser` from environment variables: this is
exactly what this section is meant to show you.

By using one of the three methods below, you will be able to export
(but also unset) environment variables from your current
parameters as seen by Nugrant.

You can see the commands that will be executed by simply
calling the method:

    vagrant user env

The name of the environment will be upper cased and full path of
the key, without the `config.user` prefix, separated
with `_`. For example, the key accessible using
`config.user.db.user` and with value `root` would generate the
export command:

    export DB_USER=root

The value are escaped so it is possible to define value containing
spaces for example.

A last note about generate commands is that pre-existing environment
variable are not taking in consideration by this command. So if
an environment variable with name `DB_USER` already exist, it
would be overwritten by an export command.

Add flag `-h` (or `--help`) for description of the command and a
list of available options.

It's possible to export variables automatically on when Vagrant
provision your VM. Refer to [Automatic Exporting section](#automatic-exporting)
for more information.

###### Method #1

If you plan to frequently use this feature, our best suggestion
is to create a little bash script that will simply delegates
to the real command. By having a bash script that calls the
command, you will be able to easily export environment variables
by sourcing the script.

Create a file named `nugrant2env` somewhere accessible from
the `$PATH` variable with the following content:

    #!/bin/env sh

    $(vagrant user env "$@")

This script will simply delegates to the `vagrant user env`
command and pass all arguments it receives to it. The
magic happens because the command `vagrant user env` outputs
the various export commands to the standard output.

By sourcing the simple delegating bash script, the parameters
seen by Nugrant will be available in your environment:

    . nugrant2env

By default, export commands are generated. But you can pass
some options to the `nugrant2env` script, For example, to
generate the unset ones, add `--unset` (or simply `-u`).

    . nugrant2env --unset

For a list of options, see the help of the command delegated
to:

    vagrant user env -h

###### Method #2

Use the command to generate a base script in the current
directory that you will then source:

    vagrant user env --format script

This will generate a script called `nugrant2env.sh` into the
current directory. You then simply source this script:

    . nugrant2env.sh

Using `vagrant user env -u --format script` will instead generate the bash
script that will unset the environment variables. Don't forget
to source it to unset variables.

###### Method #3

Use the command to generate an [autoenv](https://github.com/kennethreitz/autoenv)
file in the current directory. By using the [autoenv] project, anytime you
will enter the project directory via the `cd` command, variables
exported found in the `.env` file generated will be exported to
your environment.

    vagrant user env --format autoenv

This will generate a file called `.env` in the
current directory. You then simply change to the directory
where the `.env` file was generated to made exported variables
available in your environment.

    cd ..
    cd <project_dir>

Using `vagrant user env -u --format autoenv` will instead generate
the autoenv file that will unset the environment variables.

#### Automatic Exporting

Running the right command each time variables change can be repetive
for nothing. Why not let the computer do the hard work for us, they
have been created for this after all.

You can achieve this using the `config.user.auto_export` parameter.
Defaulting to `false`, you can use it to export the variables
to your desired format. When set to a valid value, each time
vagrant will provision your VM, Nugrant will automatically
export variables for your.

Use the following configuration to export to [autoenv](https://github.com/kennethreitz/autoenv)
script format.

    config.user.auto_export = :autoenv

Use the following configuration to export to bash script.

    config.user.auto_export = :script

You can also pass an array of formats if you would like to export to
multiple formats at the same time.

    config.user.auto_export = [:autoenv, :script]


The default filename for bash script (i.e. when using `:script` value) is
`./nugrant2env.sh`. You can control this by using parameter
`config.user.auto_export_script_path`:

    config.user.auto_export_script_path = "./script/env.sh"

### Library

Using Nugrant as a library to handle parameters from various
location is really easy. Two main classes need to be handled.

First, you need to create a `Nugrant::Config` object. This
configuration holds the values that needs to be customized
by your own application. This includes the different parameters paths
and the format of the parameters file.

## Contributing

You can contribute by filling issues when something goes
wrong or was not what you expected. I will do my best
to fix the issue either in the code or in the documentation,
where applicable.

You can also send pull requests for any feature or improvement
you think should be included in this plug-in. I will evaluate
each of them and merge them as fast as possible.