nugrant 2.1.2 → 2.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. checksums.yaml +5 -5
  2. data/.gitignore +23 -23
  3. data/.travis.yml +15 -10
  4. data/CHANGELOG.md +347 -338
  5. data/CONTRIBUTORS.md +7 -5
  6. data/Gemfile +13 -13
  7. data/README.md +601 -601
  8. data/lib/nugrant/bag.rb +264 -264
  9. data/lib/nugrant/config.rb +201 -201
  10. data/lib/nugrant/helper/bag.rb +38 -38
  11. data/lib/nugrant/helper/env/exporter.rb +195 -195
  12. data/lib/nugrant/helper/env/namer.rb +47 -47
  13. data/lib/nugrant/helper/parameters.rb +12 -12
  14. data/lib/nugrant/helper/stack.rb +86 -86
  15. data/lib/nugrant/mixin/parameters.rb +178 -178
  16. data/lib/nugrant/parameters.rb +29 -29
  17. data/lib/nugrant/vagrant/errors.rb +35 -35
  18. data/lib/nugrant/vagrant/v2/action/auto_export.rb +45 -45
  19. data/lib/nugrant/vagrant/v2/action.rb +17 -17
  20. data/lib/nugrant/vagrant/v2/command/env.rb +118 -118
  21. data/lib/nugrant/vagrant/v2/command/parameters.rb +153 -153
  22. data/lib/nugrant/vagrant/v2/command/restricted_keys.rb +64 -64
  23. data/lib/nugrant/vagrant/v2/command/root.rb +95 -95
  24. data/lib/nugrant/vagrant/v2/config/user.rb +29 -29
  25. data/lib/nugrant/vagrant/v2/helper.rb +96 -96
  26. data/lib/nugrant/vagrant/v2/plugin.rb +34 -34
  27. data/lib/nugrant/version.rb +3 -3
  28. data/lib/nugrant.rb +31 -31
  29. data/locales/en.yml +24 -24
  30. data/locales/fr.yml +24 -24
  31. data/nugrant.gemspec +32 -32
  32. data/test/lib/nugrant/helper/env/test_exporter.rb +238 -238
  33. data/test/lib/nugrant/helper/test_bag.rb +16 -16
  34. data/test/lib/nugrant/helper/test_parameters.rb +17 -17
  35. data/test/lib/nugrant/helper/test_stack.rb +152 -152
  36. data/test/lib/nugrant/test_bag.rb +450 -450
  37. data/test/lib/nugrant/test_config.rb +201 -201
  38. data/test/lib/nugrant/test_parameters.rb +438 -438
  39. data/test/lib/test_helper.rb +3 -3
  40. data/test/resources/README.md +52 -52
  41. data/test/resources/json/params_current_1.json +6 -6
  42. data/test/resources/json/params_current_2.json +29 -29
  43. data/test/resources/json/params_user_nil_values.json +9 -9
  44. data/test/resources/vagrantfiles/v2.auto_export +13 -13
  45. data/test/resources/vagrantfiles/v2.bag_inside_array +15 -15
  46. data/test/resources/vagrantfiles/v2.defaults_mixed_string_symbols +18 -18
  47. data/test/resources/vagrantfiles/v2.defaults_null_values_in_vagrantuser +23 -23
  48. data/test/resources/vagrantfiles/v2.defaults_using_string +18 -18
  49. data/test/resources/vagrantfiles/v2.defaults_using_symbol +18 -18
  50. data/test/resources/vagrantfiles/v2.empty +2 -2
  51. data/test/resources/vagrantfiles/v2.fake +29 -29
  52. data/test/resources/vagrantfiles/v2.missing_parameter +3 -3
  53. data/test/resources/vagrantfiles/v2.real +22 -22
  54. data/test/resources/yaml/params_array.yml +5 -5
  55. data/test/resources/yaml/params_boolean.yml +1 -1
  56. data/test/resources/yaml/params_combinations.yml +72 -72
  57. data/test/resources/yaml/params_current_1.yml +4 -4
  58. data/test/resources/yaml/params_current_2.yml +23 -23
  59. data/test/resources/yaml/params_defaults_at_root.yml +1 -1
  60. data/test/resources/yaml/params_defaults_not_at_root.yml +2 -2
  61. data/test/resources/yaml/params_list.yml +2 -2
  62. data/test/resources/yaml/params_numeric_key.yml +3 -3
  63. data/test/resources/yaml/params_simple.yml +1 -1
  64. data/test/resources/yaml/params_system_1.yml +4 -4
  65. data/test/resources/yaml/params_system_2.yml +25 -25
  66. data/test/resources/yaml/params_unix_eol.yml +3 -3
  67. data/test/resources/yaml/params_user_1.yml +4 -4
  68. data/test/resources/yaml/params_user_2.yml +23 -23
  69. data/test/resources/yaml/params_user_nil_values.yml +5 -5
  70. data/test/resources/yaml/params_windows_eol.yml +3 -3
  71. metadata +12 -13
data/README.md CHANGED
@@ -1,601 +1,601 @@
1
- # Nugrant
2
-
3
- [![Gem Version](https://badge.fury.io/rb/nugrant.png)][gem]
4
- [![Build Status](https://secure.travis-ci.org/maoueh/nugrant.png?branch=master)][travis]
5
- [![Dependency Status](https://gemnasium.com/maoueh/nugrant.png?travis)][gemnasium]
6
- [![Code Climate](https://codeclimate.com/github/maoueh/nugrant.png)][codeclimate]
7
-
8
- [gem]: https://rubygems.org/gems/nugrant
9
- [travis]: http://travis-ci.org/maoueh/nugrant
10
- [gemnasium]: https://gemnasium.com/maoueh/nugrant
11
- [codeclimate]: https://codeclimate.com/github/maoueh/nugrant
12
-
13
- Nugrant is a library to easily handle parameters that need to be
14
- injected into an application via different sources (system, user,
15
- current, defaults). But foremost, a Vagrant plug-in that will enhance
16
- Vagrantfile to allow user specific configuration values.
17
-
18
- Supported platforms:
19
-
20
- * Vagrant 1.x
21
- * Ruby 1.9.3+
22
-
23
- ## Quick Start
24
-
25
- Using Nugrant as a plug-in provides an easy and hierarchical system to manage
26
- machine and user specific parameters.
27
-
28
- Let's start with an example. You need to distribute among your enterprise a
29
- `Vagrantfile` to start and provision an AWS EC2 instance (or for an open-source project).
30
- The `aws_access_key` and `aws_secret_key` should be configurable depending on the user
31
- running `vagrant up`.
32
-
33
- To achieve this, simply create a file named `.vagrantuser` that resides in the directory
34
- as your `Vagrantfile`:
35
-
36
- aws:
37
- access_key: "123456"
38
- secret_key: "abcdef"
39
-
40
- In your `Vagrantfile`, `Nugrant` will let you access the parameters via the
41
- `config.user` object:
42
-
43
- Vagrant.configure("2") do |config|
44
- ...
45
-
46
- config.vm.provider :aws do |aws, override|
47
- aws.access_key_id = config.user.aws.access_key
48
- aws.secret_access_key = config.user.aws.secret_key
49
-
50
- ...
51
- end
52
- end
53
-
54
- You then ignore the `.vagrantuser` file in your revision control, so each developer
55
- as a specific one with their own values. People often commit a `.vagrantuser.example`
56
- file in project's repository as an easy startup for the various parameters that
57
- must be filled in, something like:
58
-
59
- aws:
60
- access_key: "<ACCESS_KEY_HERE>"
61
- secret_key: "<SECRET_KEY_HERE>"
62
-
63
- To find where your project `.vagrantuser` is located, Nugrant uses the directory
64
- where the `Vagrantfile` is located. It achieves this using the same set of
65
- rules as Vagrant meaning you can be in a nested directory and parameters
66
- will still be fetched correctly.
67
-
68
- Moreover, like other similar system, there is a hierarchy of `.vagrantuser` files
69
- that you can leverage:
70
-
71
- | Name | Location | Priority | Overrides |
72
- | ---------|-----------------------------------------|:---------:|--------------------------|
73
- | Defaults | [config.user.defaults](#default-values) | 4 | - |
74
- | System | $SYSTEM/.vagrantuser | 3 | Defaults |
75
- | User | ~/.vagrantuser | 2 | Defaults & System |
76
- | Project | .vagrantuser | 1 | Defaults & System & User |
77
-
78
- The project level directory is always the same as the directory where your
79
- `Vagrantfile` resides and same rules as Vagrant are used to find it.
80
- The `~` is the user's home directory and `$SYSTEM` is the platform dependent
81
- folder where system global can be put. Check [Hierarchy](#hierarchy) section
82
- for where `$SYSTEM` maps exactly.
83
-
84
- You can use the command `vagrant user parameters` to see the final merged
85
- hierarchy seen by Nugrant. This command also prints [restricted keys](#restricted-keys)
86
- defined in your hierarchy.
87
-
88
- Accessing parameters in your `Vagrantfile` can be done either by method access
89
- (i.e. `config.user.<key>`) or by array access (i.e. `config.user[<key>]`).
90
- This support is working for any deepness, only `config.user` is different
91
- because provided directly by `Vagrant` and not by this plugin.
92
-
93
- However, a drawback with method access, not present with array access, is its
94
- set of [restricted keys](#restricted-keys) for which usage is prohibited. These
95
- are in facts calls to method defined by the [Bag](lib/nugrant/bag.rb) class
96
- ([Bag](lib/nugrant/bag.rb) extends [Hash](http://ruby-doc.org/core-2.0/Hash.html)).
97
- It's plain Ruby, use it at your advantage like iterating through a collection
98
- using the `.each` method.
99
-
100
- This is where the quick start end. Continue to section [Installation](#installation)
101
- if you need so help on how to install Nugrant. Or jump to [Usage](#usage) section
102
- which describe in greater details all necessary information needed to deeply
103
- understand Nugrant and use it at its full potential.
104
-
105
- ## Installation
106
-
107
- ### Vagrant
108
-
109
- Vagrant's plug-in system is very well done and Nugrant supports
110
- the following plug-in API versions:
111
-
112
- * V2 => Vagrant 1.x
113
-
114
- To install the Nugrant as a Vagrant plug-in, simply type the following
115
- command in a terminal:
116
-
117
- vagrant plugin install nugrant
118
-
119
- #### Vagrant 0.x
120
-
121
- Vagrant 0.x is not supported anymore. If you still need support for
122
- Vagrant 0.x, please use release line `1.x` (branch [1.x](https://github.com/maoueh/nugrant/tree/1.x)).
123
-
124
- ### Library
125
-
126
- If you would like to use Nugrant as a library, simply reference
127
- it as a dependency of your application. Probably by adding it to
128
- your `Gemfile` or your `.gemspec` file.
129
-
130
- "nugrant", "~> 2.0"
131
-
132
- ## Usage
133
-
134
- Whether used as a library or a Vagrant plug-in, Nugrant has some
135
- common concepts that apply to both usages. The most important
136
- one is the parameters hierarchy.
137
-
138
- ### Common
139
-
140
- Nugrant can read parameters from various locations and will merge
141
- them all together in a single set. Merging is done in a fairly
142
- standard fashion.
143
-
144
- Here the precedence rules that apply when merging parameters
145
- from various location. List index indicate the priority of the
146
- entry. Entry with lower number has lower priority (values at this
147
- priority will be overridden by values defined on higher priorities).
148
-
149
- 1. Defaults
150
- 2. System
151
- 3. User
152
- 4. Current
153
-
154
- In text, this means that current parameters overrides user
155
- parameters, user parameters overrides system parameters and
156
- finally system parameters overrides defaults parameters.
157
-
158
- When two keys that are merged together points to Array values,
159
- the default operation is to replace current Array by
160
- overriding one. The default merge strategy can be customized.
161
-
162
- ### Vagrant
163
-
164
- All examples shown here are for Vagrant 1.1+. They have
165
- been tested with Vagrant 1.4.0. Keep this in mind when
166
- copying examples.
167
-
168
- Let start with a small use case. Say the git repository you want
169
- to share with your guest VM is not located under the root folder of
170
- your `Vagrantfile`. That means you will need to specify
171
- an absolute host path to share the folder on the guest VM.
172
-
173
- Your `Vagrantfile` would look like this:
174
-
175
- Vagrant.configure("2") do |config|
176
- config.vm.box = "base"
177
- config.vm.synced_folder "/home/user/work/git", "/git"
178
- end
179
-
180
- However, what happens when multiple developers
181
- need to share the same `Vagrantfile`? This is the main
182
- use case this plug-in try to address.
183
-
184
- When Vagrant starts, it loads all vagrant plug-ins it knows
185
- about. If you installed the plug-in with one of the two
186
- methods we listed above, Vagrant will know about Nugrant
187
- and will load it correctly.
188
-
189
- To use the plug-in, first create a YAML file named
190
- `.vagrantuser` in the same folder where your `Vagrantfile` is
191
- located. The file must be a valid YAML file:
192
-
193
- repository:
194
- project: "/home/user/work/git"
195
-
196
- The configuration hierarchy you define in the `.vagrantuser` file
197
- is imported into the `config` object of the `Vagrantfile`
198
- under the key `user`. So, with the `.vagrantuser` file above, you
199
- could have this `Vagrantfile` that abstract absolute paths.
200
-
201
- Vagrant.configure("2") do |config|
202
- config.vm.box = "base"
203
- config.vm.synced_folder config.user.repository.project, "/git"
204
- end
205
-
206
- This way, paths can be customized by every developer. They just
207
- have to add a `.vagrantuser` file where user specific configuration
208
- values can be specified. The `.vagrantuser` should be ignored by you
209
- version control system so it is to committed with the project.
210
-
211
- Additionally, you can also have a `.vagrantuser` under your user home
212
- directory. This way, you can set parameters that will be
213
- available to all your `Vagrantfile'. The `.vagrantuser` located
214
- within the same folder as the `Vagrantfile` file will overrides
215
- parameters defined in the `.vagrantuser` file defined in the user
216
- home directory.
217
-
218
- For example, you have `.vagrantuser` file located at `~/.vagrantuser`
219
- that has the following content:
220
-
221
- ssh_port: 2223
222
- repository:
223
- project: "/home/user/work/git"
224
-
225
- And another `.vagrantuser` within the same folder as your `Vagrantfile`:
226
-
227
- ssh_port: 3332
228
- repository:
229
- personal: "/home/user/personal/git"
230
-
231
- Then, the `Vagrantfile` could be defined like this:
232
-
233
- Vagrant.configure("2") do |config|
234
- config.ssh.port config.user.ssh_port
235
-
236
- config.vm.synced_folder config.user.repository.project, "/git"
237
- config.vm.synced_folder config.user.repository.personal, "/personal"
238
- end
239
-
240
- That would be equivalent to:
241
-
242
- Vagrant.configure("2") do |config|
243
- config.ssh.port 3332
244
-
245
- config.vm.synced_folder "/home/user/work/git", "/git"
246
- config.vm.synced_folder "/home/user/personal/git", "/personal"
247
- end
248
-
249
- #### Hierarchy
250
-
251
- As you can see, the parameters defined in the second `.vagrantuser` file
252
- (the current one) overrides settings defined in the `.vagrantuser` found
253
- in the home directory (the user one).
254
-
255
- Here the list of locations where Nugrant looks for parameters:
256
-
257
- 1. Defaults (via `config.user.defaults` in `Vagrantfile`)
258
- 2. System (`/etc/.vagrantuser` on Unix, `%PROGRAMDATA%/.vagrantuser` or `%ALLUSERSPROFILE%/.vagrantuser` on Windows)
259
- 3. Home (`~/.vagrantuser`)
260
- 4. Project (`.vagrantuser` within the same folder as the `Vagrantfile`)
261
-
262
- #### Paths
263
-
264
- When you want to specify paths on, specially on Windows, it's probably
265
- better to only use forward slash (`/`). The main reason for this is because
266
- Ruby, which will be used at the end by Vagrant is able to deal with forward
267
- slash even on Windows. This is great because with this, you can avoid
268
- values escaping in YAML file. If you need to use backward slash (`\`), don't
269
- forget to properly escape it!
270
-
271
- value: "C:/Users/user/work/git"
272
- value: "C:\\Users\\user\\work\\git"
273
-
274
- Moreover, it is preferable that paths are specified in full
275
- (i.e. no `~` for HOME directory for example). Normally, they
276
- should be handled by `Vagrant` but it may happen that it's not
277
- the case. If your have an error with a specific parameter,
278
- either expand it in your config:
279
-
280
- project: "/home/joe/work/ruby/git"
281
-
282
- Of expand it in the `Vagrantfile`:
283
-
284
- config.vm.synced_folder File.expand_path(config.user.repository.project), "/git"
285
-
286
- #### Parameters access
287
-
288
- Parameters in the `Vagrantfile` can be retrieved via method call
289
- of array access.
290
-
291
- config.user['repository']['project'] # Array access
292
- config.user.repository.project # Method access
293
-
294
- You can even mix the two if you want, but we do not recommend
295
- it since its always better to be consistent:
296
-
297
- config.user['repository'].project # Mixed access
298
- config.user.repository['project'] # Mixed access
299
-
300
- Only the root key, i.e. `config.user`, cannot be access with
301
- both syntax, only the method syntax can be used since this
302
- is not provided by this plug-in but by Vagrant itself.
303
-
304
- ##### Tips
305
-
306
- Each non-final parameter (i.e a parameter that contains other parameters and
307
- not a scalar value) is in fact a [Bag](/lib/nugrant/bag.rb)
308
- object. You can call any defined methods on it. This object extends
309
- [Hash](http://ruby-doc.org/core-2.0/Hash.html) (itself including
310
- module [Enumerable](http://ruby-doc.org/core-2.0/Enumerable.html)). Hence,
311
- you can do neat things like iterating over your values or filtering them:
312
-
313
- config.user.application.users.each do |key, data|
314
- puts "Key #{key}: #{data}"
315
- end
316
-
317
- ##### Restricted keys
318
-
319
- Method access has the neat advantage of being beautiful to the
320
- eye. However, the drawback of using this retrieval syntax is
321
- that not all keys are permitted. As explained in the [Tips](#tips)
322
- section, the object you are calling when using method access
323
- is in fact of type [Bag](/lib/nugrant/bag.rb). Hence, if you
324
- are using a key which collapse with ones of Bag's keys, it will
325
- call the method instead of given you the value of you parameter.
326
- At best, you will get a weird behavior and at worst a stack
327
- trace when trying to access the parameter.
328
-
329
- If you really want to use one of the restricted keys, simply
330
- ensure to always use array access method.
331
-
332
- The list of restricted keys can be accessed using command
333
- `vagrant user restricted-keys`.
334
-
335
- #### Default values
336
-
337
- When using parameters, it is often needed so set default values
338
- for certain parameters so if the user does not define one, the
339
- default value will be picked up.
340
-
341
- For example, say you want a parameter that will hold the ssh
342
- port of the vm. This parameter will be accessible via the
343
- parameter `config.user.vm.ssh_port`.
344
-
345
- You can use the following snippet directly within your Vagrantfile
346
- to set a default value for this parameter:
347
-
348
- Vagrant.configure("2") do |config|
349
- config.user.defaults = {
350
- "vm" => {
351
- "ssh_port" => "3335"
352
- }
353
- }
354
-
355
- config.ssh.port config.user.vm.ssh_port
356
- end
357
-
358
- With this Vagrantfile, the parameter `config.user.vm.ssh_port`
359
- will default to `3335` in cases where it is not defined by the
360
- user.
361
-
362
- If the user decides to change it, he just has to set it in his
363
- own `.vagrantuser` and it will override the default value defined
364
- in the Vagrantfile.
365
-
366
- #### Array merge strategies
367
-
368
- As stated previously, when two arrays are merged together,
369
- the default strategy is to replace current array with new one.
370
-
371
- However, in some certain circumstances, you may need another
372
- behavior. Here the list of strategies that can be used.
373
-
374
- * `:replace` (*default*)
375
- With this strategy, the new array completely replace the
376
- current one.
377
-
378
- * `:concat`
379
- With this strategy, new array is appended to the end
380
- of current array when merged. The `Array` `+` operator
381
- is used to concatenante the two arrays.
382
-
383
- * `:extend`
384
- With this strategy, current array is extended with values
385
- from new one. The `Array` `|` (union) operator
386
- is used to extend the array.
387
-
388
- You can use the following snippet directly within your Vagrantfile
389
- to change the array merge strategy:
390
-
391
- Vagrant.configure("2") do |config|
392
- config.user.array_merge_strategy = :extend
393
-
394
- config.ssh.port config.user.vm.ssh_port
395
- end
396
-
397
- Note that you should change the array merge strategy before
398
- you access any keys because it's just once set that values
399
- are computed using the new strategy.
400
-
401
- If you specify an unsupported strategy, nothing will happen.
402
-
403
- #### Commands
404
-
405
- In this section, we describe the various vagrant commands defined
406
- by this plug-in that can be used to interact with it.
407
-
408
- ##### Parameters
409
-
410
- This command will print the currently defined parameters at the
411
- given location. All rules are respected when using this command.
412
- It is usefull to see what parameters are available and what are
413
- the current values of those parameters.
414
-
415
- Usage:
416
-
417
- > vagrant user parameters
418
- ---
419
- config:
420
- user:
421
- chef:
422
- cookbooks_path: /Users/Chef/kitchen/cookbooks
423
- nodes_path: /Users/Chef/kitchen/nodes
424
- roles_path: /Users/Chef/kitchen/roles
425
-
426
- Add flag `-h` (or `--help`) for description of the command and a
427
- list of available options.
428
-
429
- ##### Restricted Keys
430
-
431
- This command will print the keys that cannot be accessed using
432
- the method access syntax.
433
-
434
- Usage:
435
-
436
- > vagrant user restricted-keys
437
-
438
- ##### Env
439
-
440
- Sometimes, you would like to have acces to the different values
441
- stored in your `.vagrantuser` from environment variables: this is
442
- exactly what this section is meant to show you.
443
-
444
- By using one of the three methods below, you will be able to export
445
- (but also unset) environment variables from your current
446
- parameters as seen by Nugrant.
447
-
448
- You can see the commands that will be executed by simply
449
- calling the method:
450
-
451
- vagrant user env
452
-
453
- The name of the environment will be upper cased and full path of
454
- the key, without the `config.user` prefix, separated
455
- with `_`. For example, the key accessible using
456
- `config.user.db.user` and with value `root` would generate the
457
- export command:
458
-
459
- export DB_USER=root
460
-
461
- The value are escaped so it is possible to define value containing
462
- spaces for example.
463
-
464
- A last note about generate commands is that pre-existing environment
465
- variable are not taking in consideration by this command. So if
466
- an environment variable with name `DB_USER` already exist, it
467
- would be overwritten by an export command.
468
-
469
- Add flag `-h` (or `--help`) for description of the command and a
470
- list of available options.
471
-
472
- It's possible to export variables automatically on when Vagrant
473
- provision your VM. Refer to [Automatic Exporting section](#automatic-exporting)
474
- for more information.
475
-
476
- ###### Method #1
477
-
478
- If you plan to frequently use this feature, our best suggestion
479
- is to create a little bash script that will simply delegates
480
- to the real command. By having a bash script that calls the
481
- command, you will be able to easily export environment variables
482
- by sourcing the script.
483
-
484
- Create a file named `nugrant2env` somewhere accessible from
485
- the `$PATH` variable with the following content:
486
-
487
- #!/bin/env sh
488
-
489
- $(vagrant user env "$@")
490
-
491
- This script will simply delegates to the `vagrant user env`
492
- command and pass all arguments it receives to it. The
493
- magic happens because the command `vagrant user env` outputs
494
- the various export commands to the standard output.
495
-
496
- By sourcing the simple delegating bash script, the parameters
497
- seen by Nugrant will be available in your environment:
498
-
499
- . nugrant2env
500
-
501
- By default, export commands are generated. But you can pass
502
- some options to the `nugrant2env` script, For example, to
503
- generate the unset ones, add `--unset` (or simply `-u`).
504
-
505
- . nugrant2env --unset
506
-
507
- For a list of options, see the help of the command delegated
508
- to:
509
-
510
- vagrant user env -h
511
-
512
- ###### Method #2
513
-
514
- Use the command to generate a base script in the current
515
- directory that you will then source:
516
-
517
- vagrant user env --format script
518
-
519
- This will generate a script called `nugrant2env.sh` into the
520
- current directory. You then simply source this script:
521
-
522
- . nugrant2env.sh
523
-
524
- Using `vagrant user env -u --format script` will instead generate the bash
525
- script that will unset the environment variables. Don't forget
526
- to source it to unset variables.
527
-
528
- ###### Method #3
529
-
530
- Use the command to generate an [autoenv](https://github.com/kennethreitz/autoenv)
531
- file in the current directory. By using the [autoenv] project, anytime you
532
- will enter the project directory via the `cd` command, variables
533
- exported found in the `.env` file generated will be exported to
534
- your environment.
535
-
536
- vagrant user env --format autoenv
537
-
538
- This will generate a file called `.env` in the
539
- current directory. You then simply change to the directory
540
- where the `.env` file was generated to made exported variables
541
- available in your environment.
542
-
543
- cd ..
544
- cd <project_dir>
545
-
546
- Using `vagrant user env -u --format autoenv` will instead generate
547
- the autoenv file that will unset the environment variables.
548
-
549
- #### Automatic Exporting
550
-
551
- Running the right command each time variables change can be repetive
552
- for nothing. Why not let the computer do the hard work for us, they
553
- have been created for this after all.
554
-
555
- You can achieve this using the `config.user.auto_export` parameter.
556
- Defaulting to `false`, you can use it to export the variables
557
- to your desired format. When set to a valid value, each time
558
- vagrant will provision your VM, Nugrant will automatically
559
- export variables for your.
560
-
561
- Use the following configuration to export to [autoenv](https://github.com/kennethreitz/autoenv)
562
- script format.
563
-
564
- config.user.auto_export = :autoenv
565
-
566
- Use the following configuration to export to bash script.
567
-
568
- config.user.auto_export = :script
569
-
570
- You can also pass an array of formats if you would like to export to
571
- multiple formats at the same time.
572
-
573
- config.user.auto_export = [:autoenv, :script]
574
-
575
-
576
- The default filename for bash script (i.e. when using `:script` value) is
577
- `./nugrant2env.sh`. You can control this by using parameter
578
- `config.user.auto_export_script_path`:
579
-
580
- config.user.auto_export_script_path = "./script/env.sh"
581
-
582
- ### Library
583
-
584
- Using Nugrant as a library to handle parameters from various
585
- location is really easy. Two main classes need to be handled.
586
-
587
- First, you need to create a `Nugrant::Config` object. This
588
- configuration holds the values that needs to be customized
589
- by your own application. This includes the different parameters paths
590
- and the format of the parameters file.
591
-
592
- ## Contributing
593
-
594
- You can contribute by filling issues when something goes
595
- wrong or was not what you expected. I will do my best
596
- to fix the issue either in the code or in the documentation,
597
- where applicable.
598
-
599
- You can also send pull requests for any feature or improvement
600
- you think should be included in this plug-in. I will evaluate
601
- each of them and merge them as fast as possible.
1
+ # Nugrant
2
+
3
+ [![Gem Version](https://badge.fury.io/rb/nugrant.png)][gem]
4
+ [![Build Status](https://secure.travis-ci.org/maoueh/nugrant.png?branch=master)][travis]
5
+ [![Dependency Status](https://gemnasium.com/maoueh/nugrant.png?travis)][gemnasium]
6
+ [![Code Climate](https://codeclimate.com/github/maoueh/nugrant.png)][codeclimate]
7
+
8
+ [gem]: https://rubygems.org/gems/nugrant
9
+ [travis]: http://travis-ci.org/maoueh/nugrant
10
+ [gemnasium]: https://gemnasium.com/maoueh/nugrant
11
+ [codeclimate]: https://codeclimate.com/github/maoueh/nugrant
12
+
13
+ Nugrant is a library to easily handle parameters that need to be
14
+ injected into an application via different sources (system, user,
15
+ current, defaults). But foremost, a Vagrant plug-in that will enhance
16
+ Vagrantfile to allow user specific configuration values.
17
+
18
+ Supported platforms:
19
+
20
+ * Vagrant 1.x
21
+ * Ruby 1.9.3+
22
+
23
+ ## Quick Start
24
+
25
+ Using Nugrant as a plug-in provides an easy and hierarchical system to manage
26
+ machine and user specific parameters.
27
+
28
+ Let's start with an example. You need to distribute among your enterprise a
29
+ `Vagrantfile` to start and provision an AWS EC2 instance (or for an open-source project).
30
+ The `aws_access_key` and `aws_secret_key` should be configurable depending on the user
31
+ running `vagrant up`.
32
+
33
+ To achieve this, simply create a file named `.vagrantuser` that resides in the directory
34
+ as your `Vagrantfile`:
35
+
36
+ aws:
37
+ access_key: "123456"
38
+ secret_key: "abcdef"
39
+
40
+ In your `Vagrantfile`, `Nugrant` will let you access the parameters via the
41
+ `config.user` object:
42
+
43
+ Vagrant.configure("2") do |config|
44
+ ...
45
+
46
+ config.vm.provider :aws do |aws, override|
47
+ aws.access_key_id = config.user.aws.access_key
48
+ aws.secret_access_key = config.user.aws.secret_key
49
+
50
+ ...
51
+ end
52
+ end
53
+
54
+ You then ignore the `.vagrantuser` file in your revision control, so each developer
55
+ as a specific one with their own values. People often commit a `.vagrantuser.example`
56
+ file in project's repository as an easy startup for the various parameters that
57
+ must be filled in, something like:
58
+
59
+ aws:
60
+ access_key: "<ACCESS_KEY_HERE>"
61
+ secret_key: "<SECRET_KEY_HERE>"
62
+
63
+ To find where your project `.vagrantuser` is located, Nugrant uses the directory
64
+ where the `Vagrantfile` is located. It achieves this using the same set of
65
+ rules as Vagrant meaning you can be in a nested directory and parameters
66
+ will still be fetched correctly.
67
+
68
+ Moreover, like other similar system, there is a hierarchy of `.vagrantuser` files
69
+ that you can leverage:
70
+
71
+ | Name | Location | Priority | Overrides |
72
+ | ---------|-----------------------------------------|:---------:|--------------------------|
73
+ | Defaults | [config.user.defaults](#default-values) | 4 | - |
74
+ | System | $SYSTEM/.vagrantuser | 3 | Defaults |
75
+ | User | ~/.vagrantuser | 2 | Defaults & System |
76
+ | Project | .vagrantuser | 1 | Defaults & System & User |
77
+
78
+ The project level directory is always the same as the directory where your
79
+ `Vagrantfile` resides and same rules as Vagrant are used to find it.
80
+ The `~` is the user's home directory and `$SYSTEM` is the platform dependent
81
+ folder where system global can be put. Check [Hierarchy](#hierarchy) section
82
+ for where `$SYSTEM` maps exactly.
83
+
84
+ You can use the command `vagrant user parameters` to see the final merged
85
+ hierarchy seen by Nugrant. This command also prints [restricted keys](#restricted-keys)
86
+ defined in your hierarchy.
87
+
88
+ Accessing parameters in your `Vagrantfile` can be done either by method access
89
+ (i.e. `config.user.<key>`) or by array access (i.e. `config.user[<key>]`).
90
+ This support is working for any deepness, only `config.user` is different
91
+ because provided directly by `Vagrant` and not by this plugin.
92
+
93
+ However, a drawback with method access, not present with array access, is its
94
+ set of [restricted keys](#restricted-keys) for which usage is prohibited. These
95
+ are in facts calls to method defined by the [Bag](lib/nugrant/bag.rb) class
96
+ ([Bag](lib/nugrant/bag.rb) extends [Hash](http://ruby-doc.org/core-2.0/Hash.html)).
97
+ It's plain Ruby, use it at your advantage like iterating through a collection
98
+ using the `.each` method.
99
+
100
+ This is where the quick start end. Continue to section [Installation](#installation)
101
+ if you need so help on how to install Nugrant. Or jump to [Usage](#usage) section
102
+ which describe in greater details all necessary information needed to deeply
103
+ understand Nugrant and use it at its full potential.
104
+
105
+ ## Installation
106
+
107
+ ### Vagrant
108
+
109
+ Vagrant's plug-in system is very well done and Nugrant supports
110
+ the following plug-in API versions:
111
+
112
+ * V2 => Vagrant 1.x
113
+
114
+ To install the Nugrant as a Vagrant plug-in, simply type the following
115
+ command in a terminal:
116
+
117
+ vagrant plugin install nugrant
118
+
119
+ #### Vagrant 0.x
120
+
121
+ Vagrant 0.x is not supported anymore. If you still need support for
122
+ Vagrant 0.x, please use release line `1.x` (branch [1.x](https://github.com/maoueh/nugrant/tree/1.x)).
123
+
124
+ ### Library
125
+
126
+ If you would like to use Nugrant as a library, simply reference
127
+ it as a dependency of your application. Probably by adding it to
128
+ your `Gemfile` or your `.gemspec` file.
129
+
130
+ "nugrant", "~> 2.0"
131
+
132
+ ## Usage
133
+
134
+ Whether used as a library or a Vagrant plug-in, Nugrant has some
135
+ common concepts that apply to both usages. The most important
136
+ one is the parameters hierarchy.
137
+
138
+ ### Common
139
+
140
+ Nugrant can read parameters from various locations and will merge
141
+ them all together in a single set. Merging is done in a fairly
142
+ standard fashion.
143
+
144
+ Here the precedence rules that apply when merging parameters
145
+ from various location. List index indicate the priority of the
146
+ entry. Entry with lower number has lower priority (values at this
147
+ priority will be overridden by values defined on higher priorities).
148
+
149
+ 1. Defaults
150
+ 2. System
151
+ 3. User
152
+ 4. Current
153
+
154
+ In text, this means that current parameters overrides user
155
+ parameters, user parameters overrides system parameters and
156
+ finally system parameters overrides defaults parameters.
157
+
158
+ When two keys that are merged together points to Array values,
159
+ the default operation is to replace current Array by
160
+ overriding one. The default merge strategy can be customized.
161
+
162
+ ### Vagrant
163
+
164
+ All examples shown here are for Vagrant 1.1+. They have
165
+ been tested with Vagrant 1.4.0. Keep this in mind when
166
+ copying examples.
167
+
168
+ Let start with a small use case. Say the git repository you want
169
+ to share with your guest VM is not located under the root folder of
170
+ your `Vagrantfile`. That means you will need to specify
171
+ an absolute host path to share the folder on the guest VM.
172
+
173
+ Your `Vagrantfile` would look like this:
174
+
175
+ Vagrant.configure("2") do |config|
176
+ config.vm.box = "base"
177
+ config.vm.synced_folder "/home/user/work/git", "/git"
178
+ end
179
+
180
+ However, what happens when multiple developers
181
+ need to share the same `Vagrantfile`? This is the main
182
+ use case this plug-in try to address.
183
+
184
+ When Vagrant starts, it loads all vagrant plug-ins it knows
185
+ about. If you installed the plug-in with one of the two
186
+ methods we listed above, Vagrant will know about Nugrant
187
+ and will load it correctly.
188
+
189
+ To use the plug-in, first create a YAML file named
190
+ `.vagrantuser` in the same folder where your `Vagrantfile` is
191
+ located. The file must be a valid YAML file:
192
+
193
+ repository:
194
+ project: "/home/user/work/git"
195
+
196
+ The configuration hierarchy you define in the `.vagrantuser` file
197
+ is imported into the `config` object of the `Vagrantfile`
198
+ under the key `user`. So, with the `.vagrantuser` file above, you
199
+ could have this `Vagrantfile` that abstract absolute paths.
200
+
201
+ Vagrant.configure("2") do |config|
202
+ config.vm.box = "base"
203
+ config.vm.synced_folder config.user.repository.project, "/git"
204
+ end
205
+
206
+ This way, paths can be customized by every developer. They just
207
+ have to add a `.vagrantuser` file where user specific configuration
208
+ values can be specified. The `.vagrantuser` should be ignored by you
209
+ version control system so it is to committed with the project.
210
+
211
+ Additionally, you can also have a `.vagrantuser` under your user home
212
+ directory. This way, you can set parameters that will be
213
+ available to all your `Vagrantfile` files. The `.vagrantuser` located
214
+ within the same folder as the `Vagrantfile` file will overrides
215
+ parameters defined in the `.vagrantuser` file defined in the user
216
+ home directory.
217
+
218
+ For example, you have `.vagrantuser` file located at `~/.vagrantuser`
219
+ that has the following content:
220
+
221
+ ssh_port: 2223
222
+ repository:
223
+ project: "/home/user/work/git"
224
+
225
+ And another `.vagrantuser` within the same folder as your `Vagrantfile`:
226
+
227
+ ssh_port: 3332
228
+ repository:
229
+ personal: "/home/user/personal/git"
230
+
231
+ Then, the `Vagrantfile` could be defined like this:
232
+
233
+ Vagrant.configure("2") do |config|
234
+ config.ssh.port config.user.ssh_port
235
+
236
+ config.vm.synced_folder config.user.repository.project, "/git"
237
+ config.vm.synced_folder config.user.repository.personal, "/personal"
238
+ end
239
+
240
+ That would be equivalent to:
241
+
242
+ Vagrant.configure("2") do |config|
243
+ config.ssh.port 3332
244
+
245
+ config.vm.synced_folder "/home/user/work/git", "/git"
246
+ config.vm.synced_folder "/home/user/personal/git", "/personal"
247
+ end
248
+
249
+ #### Hierarchy
250
+
251
+ As you can see, the parameters defined in the second `.vagrantuser` file
252
+ (the current one) overrides settings defined in the `.vagrantuser` found
253
+ in the home directory (the user one).
254
+
255
+ Here the list of locations where Nugrant looks for parameters:
256
+
257
+ 1. Defaults (via `config.user.defaults` in `Vagrantfile`)
258
+ 2. System (`/etc/.vagrantuser` on Unix, `%PROGRAMDATA%/.vagrantuser` or `%ALLUSERSPROFILE%/.vagrantuser` on Windows)
259
+ 3. Home (`~/.vagrantuser`)
260
+ 4. Project (`.vagrantuser` within the same folder as the `Vagrantfile`)
261
+
262
+ #### Paths
263
+
264
+ When you want to specify paths on, specially on Windows, it's probably
265
+ better to only use forward slash (`/`). The main reason for this is because
266
+ Ruby, which will be used at the end by Vagrant is able to deal with forward
267
+ slash even on Windows. This is great because with this, you can avoid
268
+ values escaping in YAML file. If you need to use backward slash (`\`), don't
269
+ forget to properly escape it!
270
+
271
+ value: "C:/Users/user/work/git"
272
+ value: "C:\\Users\\user\\work\\git"
273
+
274
+ Moreover, it is preferable that paths are specified in full
275
+ (i.e. no `~` for HOME directory for example). Normally, they
276
+ should be handled by `Vagrant` but it may happen that it's not
277
+ the case. If your have an error with a specific parameter,
278
+ either expand it in your config:
279
+
280
+ project: "/home/joe/work/ruby/git"
281
+
282
+ Of expand it in the `Vagrantfile`:
283
+
284
+ config.vm.synced_folder File.expand_path(config.user.repository.project), "/git"
285
+
286
+ #### Parameters access
287
+
288
+ Parameters in the `Vagrantfile` can be retrieved via method call
289
+ of array access.
290
+
291
+ config.user['repository']['project'] # Array access
292
+ config.user.repository.project # Method access
293
+
294
+ You can even mix the two if you want, but we do not recommend
295
+ it since its always better to be consistent:
296
+
297
+ config.user['repository'].project # Mixed access
298
+ config.user.repository['project'] # Mixed access
299
+
300
+ Only the root key, i.e. `config.user`, cannot be access with
301
+ both syntax, only the method syntax can be used since this
302
+ is not provided by this plug-in but by Vagrant itself.
303
+
304
+ ##### Tips
305
+
306
+ Each non-final parameter (i.e a parameter that contains other parameters and
307
+ not a scalar value) is in fact a [Bag](/lib/nugrant/bag.rb)
308
+ object. You can call any defined methods on it. This object extends
309
+ [Hash](http://ruby-doc.org/core-2.0/Hash.html) (itself including
310
+ module [Enumerable](http://ruby-doc.org/core-2.0/Enumerable.html)). Hence,
311
+ you can do neat things like iterating over your values or filtering them:
312
+
313
+ config.user.application.users.each do |key, data|
314
+ puts "Key #{key}: #{data}"
315
+ end
316
+
317
+ ##### Restricted keys
318
+
319
+ Method access has the neat advantage of being beautiful to the
320
+ eye. However, the drawback of using this retrieval syntax is
321
+ that not all keys are permitted. As explained in the [Tips](#tips)
322
+ section, the object you are calling when using method access
323
+ is in fact of type [Bag](/lib/nugrant/bag.rb). Hence, if you
324
+ are using a key which collapse with ones of Bag's keys, it will
325
+ call the method instead of given you the value of you parameter.
326
+ At best, you will get a weird behavior and at worst a stack
327
+ trace when trying to access the parameter.
328
+
329
+ If you really want to use one of the restricted keys, simply
330
+ ensure to always use array access method.
331
+
332
+ The list of restricted keys can be accessed using command
333
+ `vagrant user restricted-keys`.
334
+
335
+ #### Default values
336
+
337
+ When using parameters, it is often needed so set default values
338
+ for certain parameters so if the user does not define one, the
339
+ default value will be picked up.
340
+
341
+ For example, say you want a parameter that will hold the ssh
342
+ port of the vm. This parameter will be accessible via the
343
+ parameter `config.user.vm.ssh_port`.
344
+
345
+ You can use the following snippet directly within your Vagrantfile
346
+ to set a default value for this parameter:
347
+
348
+ Vagrant.configure("2") do |config|
349
+ config.user.defaults = {
350
+ "vm" => {
351
+ "ssh_port" => "3335"
352
+ }
353
+ }
354
+
355
+ config.ssh.port config.user.vm.ssh_port
356
+ end
357
+
358
+ With this Vagrantfile, the parameter `config.user.vm.ssh_port`
359
+ will default to `3335` in cases where it is not defined by the
360
+ user.
361
+
362
+ If the user decides to change it, he just has to set it in his
363
+ own `.vagrantuser` and it will override the default value defined
364
+ in the Vagrantfile.
365
+
366
+ #### Array merge strategies
367
+
368
+ As stated previously, when two arrays are merged together,
369
+ the default strategy is to replace current array with new one.
370
+
371
+ However, in some certain circumstances, you may need another
372
+ behavior. Here the list of strategies that can be used.
373
+
374
+ * `:replace` (*default*)
375
+ With this strategy, the new array completely replace the
376
+ current one.
377
+
378
+ * `:concat`
379
+ With this strategy, new array is appended to the end
380
+ of current array when merged. The `Array` `+` operator
381
+ is used to concatenante the two arrays.
382
+
383
+ * `:extend`
384
+ With this strategy, current array is extended with values
385
+ from new one. The `Array` `|` (union) operator
386
+ is used to extend the array.
387
+
388
+ You can use the following snippet directly within your Vagrantfile
389
+ to change the array merge strategy:
390
+
391
+ Vagrant.configure("2") do |config|
392
+ config.user.array_merge_strategy = :extend
393
+
394
+ config.ssh.port config.user.vm.ssh_port
395
+ end
396
+
397
+ Note that you should change the array merge strategy before
398
+ you access any keys because it's just once set that values
399
+ are computed using the new strategy.
400
+
401
+ If you specify an unsupported strategy, nothing will happen.
402
+
403
+ #### Commands
404
+
405
+ In this section, we describe the various vagrant commands defined
406
+ by this plug-in that can be used to interact with it.
407
+
408
+ ##### Parameters
409
+
410
+ This command will print the currently defined parameters at the
411
+ given location. All rules are respected when using this command.
412
+ It is usefull to see what parameters are available and what are
413
+ the current values of those parameters.
414
+
415
+ Usage:
416
+
417
+ > vagrant user parameters
418
+ ---
419
+ config:
420
+ user:
421
+ chef:
422
+ cookbooks_path: /Users/Chef/kitchen/cookbooks
423
+ nodes_path: /Users/Chef/kitchen/nodes
424
+ roles_path: /Users/Chef/kitchen/roles
425
+
426
+ Add flag `-h` (or `--help`) for description of the command and a
427
+ list of available options.
428
+
429
+ ##### Restricted Keys
430
+
431
+ This command will print the keys that cannot be accessed using
432
+ the method access syntax.
433
+
434
+ Usage:
435
+
436
+ > vagrant user restricted-keys
437
+
438
+ ##### Env
439
+
440
+ Sometimes, you would like to have acces to the different values
441
+ stored in your `.vagrantuser` from environment variables: this is
442
+ exactly what this section is meant to show you.
443
+
444
+ By using one of the three methods below, you will be able to export
445
+ (but also unset) environment variables from your current
446
+ parameters as seen by Nugrant.
447
+
448
+ You can see the commands that will be executed by simply
449
+ calling the method:
450
+
451
+ vagrant user env
452
+
453
+ The name of the environment will be upper cased and full path of
454
+ the key, without the `config.user` prefix, separated
455
+ with `_`. For example, the key accessible using
456
+ `config.user.db.user` and with value `root` would generate the
457
+ export command:
458
+
459
+ export DB_USER=root
460
+
461
+ The value are escaped so it is possible to define value containing
462
+ spaces for example.
463
+
464
+ A last note about generate commands is that pre-existing environment
465
+ variable are not taking in consideration by this command. So if
466
+ an environment variable with name `DB_USER` already exist, it
467
+ would be overwritten by an export command.
468
+
469
+ Add flag `-h` (or `--help`) for description of the command and a
470
+ list of available options.
471
+
472
+ It's possible to export variables automatically on when Vagrant
473
+ provision your VM. Refer to [Automatic Exporting section](#automatic-exporting)
474
+ for more information.
475
+
476
+ ###### Method #1
477
+
478
+ If you plan to frequently use this feature, our best suggestion
479
+ is to create a little bash script that will simply delegates
480
+ to the real command. By having a bash script that calls the
481
+ command, you will be able to easily export environment variables
482
+ by sourcing the script.
483
+
484
+ Create a file named `nugrant2env` somewhere accessible from
485
+ the `$PATH` variable with the following content:
486
+
487
+ #!/bin/env sh
488
+
489
+ $(vagrant user env "$@")
490
+
491
+ This script will simply delegates to the `vagrant user env`
492
+ command and pass all arguments it receives to it. The
493
+ magic happens because the command `vagrant user env` outputs
494
+ the various export commands to the standard output.
495
+
496
+ By sourcing the simple delegating bash script, the parameters
497
+ seen by Nugrant will be available in your environment:
498
+
499
+ . nugrant2env
500
+
501
+ By default, export commands are generated. But you can pass
502
+ some options to the `nugrant2env` script, For example, to
503
+ generate the unset ones, add `--unset` (or simply `-u`).
504
+
505
+ . nugrant2env --unset
506
+
507
+ For a list of options, see the help of the command delegated
508
+ to:
509
+
510
+ vagrant user env -h
511
+
512
+ ###### Method #2
513
+
514
+ Use the command to generate a base script in the current
515
+ directory that you will then source:
516
+
517
+ vagrant user env --format script
518
+
519
+ This will generate a script called `nugrant2env.sh` into the
520
+ current directory. You then simply source this script:
521
+
522
+ . nugrant2env.sh
523
+
524
+ Using `vagrant user env -u --format script` will instead generate the bash
525
+ script that will unset the environment variables. Don't forget
526
+ to source it to unset variables.
527
+
528
+ ###### Method #3
529
+
530
+ Use the command to generate an [autoenv](https://github.com/kennethreitz/autoenv)
531
+ file in the current directory. By using the [autoenv] project, anytime you
532
+ will enter the project directory via the `cd` command, variables
533
+ exported found in the `.env` file generated will be exported to
534
+ your environment.
535
+
536
+ vagrant user env --format autoenv
537
+
538
+ This will generate a file called `.env` in the
539
+ current directory. You then simply change to the directory
540
+ where the `.env` file was generated to made exported variables
541
+ available in your environment.
542
+
543
+ cd ..
544
+ cd <project_dir>
545
+
546
+ Using `vagrant user env -u --format autoenv` will instead generate
547
+ the autoenv file that will unset the environment variables.
548
+
549
+ #### Automatic Exporting
550
+
551
+ Running the right command each time variables change can be repetive
552
+ for nothing. Why not let the computer do the hard work for us, they
553
+ have been created for this after all.
554
+
555
+ You can achieve this using the `config.user.auto_export` parameter.
556
+ Defaulting to `false`, you can use it to export the variables
557
+ to your desired format. When set to a valid value, each time
558
+ vagrant will provision your VM, Nugrant will automatically
559
+ export variables for your.
560
+
561
+ Use the following configuration to export to [autoenv](https://github.com/kennethreitz/autoenv)
562
+ script format.
563
+
564
+ config.user.auto_export = :autoenv
565
+
566
+ Use the following configuration to export to bash script.
567
+
568
+ config.user.auto_export = :script
569
+
570
+ You can also pass an array of formats if you would like to export to
571
+ multiple formats at the same time.
572
+
573
+ config.user.auto_export = [:autoenv, :script]
574
+
575
+
576
+ The default filename for bash script (i.e. when using `:script` value) is
577
+ `./nugrant2env.sh`. You can control this by using parameter
578
+ `config.user.auto_export_script_path`:
579
+
580
+ config.user.auto_export_script_path = "./script/env.sh"
581
+
582
+ ### Library
583
+
584
+ Using Nugrant as a library to handle parameters from various
585
+ location is really easy. Two main classes need to be handled.
586
+
587
+ First, you need to create a `Nugrant::Config` object. This
588
+ configuration holds the values that needs to be customized
589
+ by your own application. This includes the different parameters paths
590
+ and the format of the parameters file.
591
+
592
+ ## Contributing
593
+
594
+ You can contribute by filling issues when something goes
595
+ wrong or was not what you expected. I will do my best
596
+ to fix the issue either in the code or in the documentation,
597
+ where applicable.
598
+
599
+ You can also send pull requests for any feature or improvement
600
+ you think should be included in this plug-in. I will evaluate
601
+ each of them and merge them as fast as possible.