nugrant 2.0.0.dev2 → 2.0.0.pre1

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MTc4MzNjMDg2Mzk2MDU0MTFkODU5M2NmY2Y3ZmNjMWEzZjUyNDJlYg==
-  data.tar.gz: !binary |-
-    ODg2OWRhZDJkN2ZmYTU3ZmYyODg5YjAxZWI5NjhmNTFjZGU3M2E4Mw==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    OTc5ZDY1N2IzZGYwN2M5Y2IxOWEzYmMxODFjYjlkMmY0ODEzNWIzMTA3MGY2
-    YzYyZGIxOWRlYjc0N2E0MGYyNjdhZDZlNzg5YzlkMzM5NGJlYjg4OTljYTM1
-    NjhkZDYzODJiYjA0MGE3MWQ0MTcyOThmYTMzYzUwMTU5YjY0ODE=
-  data.tar.gz: !binary |-
-    ZjQyNzc2M2Q2YjdlZTc0YzE1ZDFlNjFlMzY1M2UwOTQzZjU2ZWM5ZGQ5ZDc4
-    ZDVlZmQwZjEwMDk5Yzk1YjlhNjgxNjlmZWU0NDQyYmZjNjc4MjQxMDA3NmRj
-    MTlmYWQ4NjFiYjJjNWI5YTRmYzNmM2RiYTQ2NmFhZDg2YWUxMzY=
+SHA1:
+  metadata.gz: 9f14bf2a70810293d967c9e9d24b60408880e5b0
+  data.tar.gz: 1d24d5cfa15fde530b4daab7743adb9b29bf74a4
+SHA512:
+  metadata.gz: 4ade947b4d55e761d3ec22065b34b680cac998f9544fa98e30a309ce9c65d4f2a76bde76233633e9eb630725c0fc622ea6c8b163332af8401347af8d0dd409d9
+  data.tar.gz: 20d4f38d519f1e15f487d0bdecd6d74246a8b748d4933f98285504587360c24cd5936c111fb85dfb578079abb9a28a47e7f8dccf7b22655510aa77a87a91725b

data/.gitignore

@@ -18,4 +18,5 @@ test/tmp
 test/version_tmp
 tmp
 
-test/resources/Vagrantfile
+test/resources/vagrantfiles/Vagrantfile
+test/resources/vagrantfiles/.vagrantuser

data/.travis.yml

@@ -1,6 +1,6 @@
 language: ruby
+
 rvm:
-  - "1.8.7"
-  - "1.9.2"
   - "1.9.3"
   - "2.0.0"
+  - "2.1.0"

data/CHANGELOG.md

@@ -1,12 +1,146 @@
-# 1.1.1 (unreleased)
+# 2.0.0 (In progress)
+
+* It is now possible to customize key error handling by passing
+  an options hash with key `:key_error` and a `Proc` value.
+
+* Improved command `vagrant user parameters`. The command now checks if
+  restricted keys are used and prints a warning when it's the case.
+
+* Added a new command `vagrant user restricted-keys` that prints the keys that
+  are restricted, i.e. that cannot be accessed using method access
+  syntax.
+
+* Added possibility to specify merge strategy to use when merging
+  two arrays together.
+
+### Backward Incompatibilities
+
+* Removed deprecated `--script` argument from `vagrant user env` command.
+
+* Support for Ruby <= 1.9.2 has been dropped. This is not a problem when using
+  Nugrant as a Vagrant plugin. Use branch `1.x` if you can't upgrade to
+  Ruby >= 1.9.3.
+
+* Support for Vagrant 0.x has been dropped. This means that Nugrant 2.x will not
+  load if installed in a Vagrant 0.x environment. Use branch `1.x` if you can't
+  upgrade to Vagrant 1.x.
+
+* `Bag` and `Parameters` and Vagrant configuration object `config.user` are now
+  [Enumerable](http://ruby-doc.org/core-2.0.0/Enumerable.html).
+
+  This change has implications on the resolving process of the variables
+  that are stored in the `Bag` when using the dot syntax `(config.user.email)`
+  in your code and `Vagrantfiles`. By using this syntax with version 2.0, some keys
+  will collapse with the internal object's methods. In fact, it was already the
+  case before but to a much smaller scope because object were not enumerable.
+
+  The number of conflicts should be rather low because the restricted keys
+  are not commonly used as parameter name. The list of the restricted keys
+  is the following:
+
+      !, !=, !~, <=>, ==, ===, =~, [], __all, __current, __defaults,
+      __id__, __send__, __system, __user, _detected_errors, _finalize!,
+      all?, any?, chunk, class, clear!, clone, collect, collect_concat,
+      compute_all!, compute_bags!, count, cycle, defaults, defaults=,
+      define_singleton_method, detect, display, drop, drop_while, dup,
+      each, each_cons, each_entry, each_slice, each_with_index,
+      each_with_object, empty?, entries, enum_for, eql?, equal?, extend,
+      finalize!, find, find_all, find_index, first, flat_map, freeze,
+      frozen?, gem, grep, group_by, has?, hash, include?, inject,
+      inspect, instance_eval, instance_exec, instance_of?,
+      instance_variable_defined?, instance_variable_get,
+      instance_variable_set, instance_variables, instance_variables_hash,
+      is_a?, kind_of?, lazy, map, max, max_by, member?, merge, merge!,
+      method, method_missing, methods, min, min_by, minmax, minmax_by,
+      nil?, none?, object_id, one?, partition, private_methods,
+      protected_methods, psych_to_yaml, public_method, public_methods,
+      public_send, reduce, reject, remove_instance_variable, respond_to?,
+      reverse_each, select, send, set_options, singleton_class,
+      singleton_methods, slice_before, sort, sort_by, suppress_warnings,
+      taint, tainted?, take, take_while, tap, to_a, to_enum, to_hash,
+      to_json, to_s, to_set, to_yaml, to_yaml_properties, trust, untaint,
+      untrust, untrusted?, validate, zip
+
+* The `Parameter` class has a new API.
+
+* The `Bag` class has a new API.
+
+# 1.4.3 (In progess)
+
+# 1.4.2 (January 11th, 2014)
+
+* Fixed Vagrant `user` config class to make the `has?` method
+  available to people using Vagrant. This considered has a bug
+  fix because using `has?` was not working anyway before.
+
+# 1.4.1 (December 15th, 2013)
+
+* Fixed a superfluous warning message when using ruby >= 2.0.0 which is now the
+  default when installing Vagrant >= 1.4.0 (at least on Windows).
+
+# 1.4.0 (November 28th, 2013)
+
+* Adding support to export to an [autoenv](https://github.com/kennethreitz/autoenv)
+  file. See [GH-13](https://github.com/maoueh/nugrant/issues/13).
+
+* Deprecated usage of `-s, --script` option for command
+  `vagrant user env`. This was replaced by the more generic
+  and extensible `-f, --format FORMAT` option. The
+  `-s, --script` option will be removed in 2.0.
+
+# 1.3.0 (November 19th, 2013)
+
+* Now using [minitest](https://github.com/seattlerb/minitest) as our
+  testing library.
+
+* Added a new command that can be used either standalone or via
+  a small bash script to easily export environment variables
+  from your currently set parameters. See
+  [GH-13](https://github.com/maoueh/nugrant/issues/13).
+
+* Keys associated to a null value are considered as being missing
+  by the merge process. It is still possible to define a null
+  parameter, but it will be overridden by any parameter and will not
+  override any. See [GH-12](https://github.com/maoueh/nugrant/issues/12).
+
+* Fixed output of command `vagrant user parameters`, the keys were
+  serialized as symbol instead of string.
+
+# 1.2.0 (October 24th, 2013)
+
+* Now showing better error message to the end-user when a parameter
+  cannot be found. The message displays which key could not be found.
+  Moreover, we show the context within the Vagrantfile where we think
+  the error occurred:
+
+  ```
+  Nugrant: Parameter 'param' was not found, is it defined in
+  your .vagrantuser file? Here where we think the error
+  could be in your Vagrantfile:
+
+   1:     Vagrant.configure("2") do |config|
+   2:>>     puts config.user.param
+   3:     end
+  ```
+
+  See [GH-8] (https://github.com/maoueh/nugrant/issues/8).
+
+* Ensured that keys used within a `Bag` are always symbol. This make
+  sure that it is possible to retrieve a value with any access method.
+  See [GH-9](https://github.com/maoueh/nugrant/issues/9).
+
+* Now using [multi_json](https://rubygems.org/gems/multi_json)
+  for JSON handling.
 
 # 1.1.0 (May 17th, 2013)
 
 * Rewrite completely classes `Parameters` and `Bag`.
 * Reduced chances to have a parameter name collapsing with an
   implementation method.
+
 * Removed dependency on `deep_merge`. We do now perform
   our own merge.
+
 * Added possibility to iterate through keys by using
   `.each`:
 
@@ -19,6 +153,7 @@
 ### Backward Incompatibilities
 
 * `Parameters` is not extending the `Bag` class anymore.
+
 * `Parameters` and `Bag` attributes and methods are now almost
   all prefixed with __ to reduce clashes to a minimum when
   accessing parameters with method-like syntax
@@ -27,7 +162,8 @@
 # 1.0.1 (April 9th, 2013)
 
 * Fixed a crash when `user` config value is `nil` preventing `vagrant user parameters`
-  from working as expected. [GH-4](https://github.com/maoueh/nugrant/issues/4)
+  from working as expected. See [GH-4](https://github.com/maoueh/nugrant/issues/4).
+
 * Fixed a bug preventing the version from being printed when doing `vagrant user -v`.
 
 # 1.0.0 (March 21th, 2013)
@@ -39,6 +175,7 @@
 # 0.0.14
 
 * Renamed `ParameterBag` to `Bag`
+
 * Cleanup `Bag` api
  * Renamed method `has_param?` to `has_key?` in `Bag`
  * Removed method `get_params` from `Bag`
@@ -48,6 +185,7 @@
 * Cleanup `Parameters` and `ParameterBag` interface
  * The method `defaults` has been removed from the bag
  * Setting defaults on `Parameters` now recompute the final bag
+
 * Improved `vagrant user parameters` command
  * Now using the exact config as seen by Vagrant, this includes defaults parameters
  * An option has been added to only see defaults parameters
@@ -55,8 +193,11 @@
 # 0.0.12
 
 * Added travis configuration file
+
 * Added travis build status icon to readme
+
 * Fixed a bug when `.vagrantuser` file is empty or not a hash type
+
 * Improved parameters command
  * The parameters command is now a proper subcommand
  * An option has been added to see system parameters
@@ -70,6 +211,7 @@
 # 0.0.10
 
 * Added a subcommand `parameters` for vagrant command `user`
+
 * Added a vagrant command `vagrant user subcommand [options]`
 
 # 0.0.9
@@ -79,7 +221,9 @@
 # 0.0.8
 
 * Introduced possibility to set default values
-* Introduced restricted keys (For now, restricted keys are [`defaults`])
+
+* Introduced restricted keys (For now, restricted keys are [`defaults`]).
+
 * Fixed a bug with system-wide parameters
 
 # 0.0.7
@@ -97,4 +241,5 @@
 # 0.0.4
 
 * JSON is now the default file format for parameters (due to problem with YAML)
+
 * It is now possible to store parameters in the JSON format

data/Gemfile

@@ -1,27 +1,15 @@
 source 'https://rubygems.org'
 
-gemspec
-
 group :development do
-  vagrant_dependencies = {
-    'v1' => {
-        'home' => "~/.vagrant.d.v1",
-        'gem' => Proc.new do
-            gem "vagrant", "~> 1.0.7"
-        end,
-    },
-    'v2' => {
-        'home' => "~/.vagrant.d",
-        'gem' => Proc.new do
-            gem "vagrant", :git => "git://github.com/mitchellh/vagrant.git"
-        end,
-    },
-  }
+  gem "rake", "~> 10.1"
+  gem "minitest", "~> 5.2"
+  gem "minitest-reporters", "~> 1.0"
 
-  vagrant_plugin_version = ENV['VAGRANT_PLUGIN_VERSION'] || "v2"
-  vagrant_dependency = vagrant_dependencies[vagrant_plugin_version]
+  gem "win32console", :platforms => ['mswin', 'mingw', :'x64_mingw']
 
-  ENV['VAGRANT_HOME'] = File.expand_path(vagrant_dependency['home'])
+  gem "vagrant", :git => "https://github.com/mitchellh/vagrant.git", :tag => "v1.5.1"
+end
 
-  vagrant_dependency['gem'].call()
+group :plugins do
+  gem "nugrant", path: "."
 end

data/README.md

@@ -1,80 +1,113 @@
-# Nugrant [![Build Status](https://travis-ci.org/maoueh/nugrant.png)](https://travis-ci.org/maoueh/nugrant)
+# 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).
+current, defaults). But foremost, a Vagrant plug-in that will enhance
+Vagrantfile to allow user specific configuration values.
 
-But Nugrant is foremost a Vagrant plugin that will enhance
-Vagrantfile to allow user specific configuration values. The plugin
-will let users define a `.vagrantuser` file at different locations. This
-file will contain parameters that will be injected into the Vagrantfile.
+Supported platforms:
 
-## Installation
+ * Vagrant 1.x
+ * Ruby 1.9.3+
 
-### Library
+## Overview
 
-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.
+Using Nugrant as a plug-in provides an easy and hierarchical system to manage
+machine and user specific parameters.
 
-    nugrant ~> 1.0.1
+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`.
 
-### Vagrant
+To achieve this, simply create a file named `.vagrantuser` in the project directory with
+the following content:
+
+    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|
+      ...
 
-If you would like to use Nugrant as a Vagrant plugin, the
-detailed installation steps are provided below. Without a
-doubt, you need Vagrant installed for those steps to work ;)
+      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
 
-First of all, Vagrant's plugin system is very well done and
-Nugrant supports version `v1` (1.0.z branch, like 1.0.7) and
-`v2` (1.y.z branch, like 1.1.3). However, the installation
-procedure between the two versions is different.
+        ...
+      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 know which version you currently have installed, type
-`vagrant -v` in a terminal.
+Moreover, there is a hierarchy of `.vagrantuser` files that you can leverage.
+The order is project `.vagrantuser` overrides `$HOME/.vagrantuser` overrides
+`$SYSTEM/.vagrantuser` where `$HOME` is the user's home directory and `$SYSTEM`
+is the platform dependent folder where system global parameters are set.
 
-#### Version 1.0.z (latest version tested 1.0.7)
+We use it in our team to specify the various parameters required for
+Vagrant `chef-solo` provisioner by putting the a `.vagrantuser` in our
+home directory under a key `chef`. It gets merged with the project's
+`.vagrantuser` file (if it exists), so it they can be overridden there.
+
+Please refer to section [Usage](#usage) for all details and explanations
+needed to fully use and understand Nugrant.
+
+## Installation
 
-In this version, there is two different ways to install Nugrant.
-You can install it via Vagrant or directly via the system gem
-container.
+### Vagrant
 
-When you install via Vagrant, the main benefit is that
-it's decoupled from other system gems. There is less
-chance for this gem's dependencies, even if they are minimal,
-to clash with gems already installed on your system. This is the
-recommended installation method. To install, simply run in
-a terminal:
+Vagrant's plug-in system is very well done and Nugrant supports
+the following plug-in API versions:
 
-    > vagrant gem install nugrant
+ * V2 => Vagrant 1.x
 
-If you prefer to install the gem in via the system gem
-container, please use this command instead:
+To install the Nugrant as a Vagrant plug-in, simply type the following
+command in a terminal:
 
-    > gem install nugrant
+    vagrant plugin install nugrant
 
-#### Version 1.y.z (latest version tested 1.1.3)
+#### Vagrant 0.x
 
-In those versions, probably until 2.y.z is out, there
-is a new way to install and register plugin with the Vagrant
-environment.
+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)).
 
-To install when using one of this versions, simply run in a
-terminal:
+### Library
 
-    > vagrant plugin install nugrant
+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.
 
-Since the plugin system has been completely rewritten in those
-versions, it is not possible anymore to make the plugin available
-within Vagrant when installing Nugrant in the system
-gem container.
+    "nugrant", "~> 2.0"
 
 ## Usage
 
-Whether used as a library or a Vagrant plugin, Nugrant has some
+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.
@@ -93,20 +126,10 @@ In text, this means that current parameters overrides user
 parameters, user parameters overrides system parameters and
 finally system parameters overrides defaults parameters.
 
-### 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.
-
 ### Vagrant
 
 All examples shown here are for Vagrant 1.1+. They have
-been tested with Vagrant 1.2.2. Keep this in mind when
+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
@@ -123,14 +146,14 @@ Your `Vagrantfile` would look like this:
 
 However, what happens when multiple developers
 need to share the same `Vagrantfile`? This is the main
-use case this plugin try to address.
+use case this plug-in try to address.
 
-When Vagrant starts, it loads all vagrant plugins it knows
-about. If you installed the plugin with one of the two
+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 plugin, first create a YAML file named
+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:
 
@@ -201,10 +224,10 @@ Here the list of locations where Nugrant looks for parameters:
  3. Home (`~/.vagrantuser`)
  4. current (`.vagrantuser` within the same folder as the `Vagrantfile`)
 
-### Paths
+#### Paths
 
 When you want to specify paths on, specially on Windows, it's probably
-better to only use foward slash (`/`). The main reason for this is because
+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
@@ -213,7 +236,19 @@ forget to properly escape it!
     value: "C:/Users/user/work/git"
     value: "C:\\Users\\user\\work\\git"
 
-### Parameters access
+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.
@@ -229,9 +264,35 @@ it since its always better to be consistent:
 
 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 plugin but by Vagrant itself.
+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. Since this object is also
+[Enumerable](http://ruby-doc.org/core-2.0/Enumerable.html), you can do neat things
+like iterating over your values or filtering them.
+
+##### 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.
 
-### Default values
+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
@@ -262,12 +323,12 @@ 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.
 
-### Vagrant commands
+#### Commands
 
 In this section, we describe the various vagrant commands defined
-by this plugin that can be used to interact with it.
+by this plug-in that can be used to interact with it.
 
-#### Parameters
+##### Parameters
 
 This command will print the currently defined parameters at the
 given location. All rules are respected when using this command.
@@ -285,6 +346,139 @@ Usage:
           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
+command is meant is exactly for this.
+
+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
+
+And the unset command:
+
+    unset DB_USER
+
+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.
+
+###### Method #1
+
+If you plan to use frequently 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.
+
+### 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
@@ -293,5 +487,5 @@ 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 plugin. I will evaluate
+you think should be included in this plug-in. I will evaluate
 each of them and merge them as fast as possible.