yaml-include
Version:
Custom YAML tag definitions to support modular YAML documents with js-yaml.
145 lines (102 loc) • 6.79 kB
Markdown
# yaml-include
[](https://travis-ci.org/claylo/yaml-include)
[](https://coveralls.io/r/claylo/yaml-include)
[](https://david-dm.org/claylo/yaml-include)
[](https://david-dm.org/claylo/yaml-include#info=devDependencies)
[](http://commitizen.github.io/cz-cli/)
This package provides support custom tags in a [YAML](http://yaml.org/) document that facilitate inclusion of external `.yaml` files, or directories of `.yaml` files. This functionality is of course frowned upon by the YAML core team, but I find YAML too damn useful as a configuration format to _not_ support inclusions. If you feel the same way, these tags will be helpful to you.
## Installation
```shell
$ npm install yaml-include
```
## Usage
A very small script can be created to leverage the `yaml-include` tags. The script would look something like this:
```js
var yaml = require('js-yaml');
var yamlinc = require('yaml-include');
var fs = require('fs');
var p = require('path');
// set the base file for relative includes
yamlinc.setBaseFile(p.join(__dirname, 'yaml-dir', 'base.yaml'));
var src = fs.readFileSync(yamlinc.basefile, 'utf8');
var obj = yaml.load(src, { schema: yamlinc.YAML_INCLUDE_SCHEMA, filename: yamlinc.basefile });
// use your loaded object!
```
A YAML file using these tags might look like this (this file is in `example/swagger/spec.yaml`):
```yaml
swagger: "2.0"
info:
description: |
This is a sample server Petstore server.
[Learn about Swagger](http://swagger.wordnik.com) or join the IRC channel `#swagger` on irc.freenode.net.
For this sample, you can use the api key `special-key` to test the authorization filters
version: "1.0.0"
title: Swagger Petstore
termsOfService: http://helloreverb.com/terms/
contact:
name: apiteam@wordnik.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
host: petstore.swagger.wordnik.com
basePath: /v2
schemes:
- http
paths: !!inc/dir [ 'paths' ]
securityDefinitions: !!inc/file security.yaml
definitions: !!inc/dir [ 'definitions', { recursive: false, allowEmpty: false }]
```
## How It Works
Documents and files discovered during inclusion using the `!!inc/dir` tag are added to a generated YAML segment. Processing considers directory names and file names (before the `.ext`) to be keys, and the contents are mapped onto them. The easiest way to explain is with an example.
Given `base.yaml` looks like this...
```yaml
name: Include Test
included: !!inc/dir [ 'inc' ]
```
with the default settings, you'd wind up with the following:
```
Directory Structure Resulting YAML Equivalent
------------------- -------------------------
somedir/ name: Include Test
|-- base.yaml included:
`-- inc/ /:
|-- -alt-ignore-prefix.yaml foo:
|-- ToLower.yaml ... YAML contents of foo.yaml
|-- _ignored/ ToLower:
| |-- batman.yaml ... YAML contents of ToLower.yaml
| `-- captain-america.yaml '-alt-ignore-prefix':
|-- empty.yaml ... YAML contents of -alt-ignore-prefix.yaml
|-- foo.yaml /sub:
|-- sub/ StillUpper:
| |-- StillUpper.yaml ... contents of StillUpper.yaml
| |-- _SomeVar/ '/{alter-ego}':
| | `-- hello.yaml Superman:
| `-- skip.data ... contents of Superman.yaml
`-- ~alter-ego/
`-- Superman.yaml
```
For a bunch of different examples on each of the subdirectories in this example, look in the [test/fixtures/options](claylo/yaml-include/test/fixtures/options) directory.
## YAML API
**Please note:** There's not much an API at all within the JavaScript files. This package extends the [js-yaml](http://npmjs.com/package/js-yaml) package, and the descriptions that follow are related to usage of the custom YAML tags this package exposes.
### !!inc/dir [ path [, options] ]
Parses `path` as a single directory pathname. `options` is a `mapping` YAML type.
options:
- `allowEmpty` _(default: false)_ - allow an empty file to appear in the generated result. When set to true, an empty file named `empty.yaml` will be represented as `empty: {}`.
- `recursive` _(default: true)_ - Specifies whether or not to recurse into subdirectories.
- `extensions` _(default: ['.yaml', '.yml'])_ - Determines file extensions to consider for inclusion.
- `lowerKeys` _(default: false)_ - Force all keys gleaned from the directory hierarchy to lower case.
- `variableIndicator` _(default: '~')_ - When a file or directory name is prefixed with this character, the representation in the generated output will be wrapped in the `variablePrefix` and `variableSuffix` strings.
- `variablePrefix` _(default: '{')_ - When representing a variable, this string will precede the variable name.
- `variableSuffix` _(default: '}')_ - When representing a variable, this string will follow the variable name.
- `ignoreIndicator` _(default: '\_')_ - When a file or directory name is prefixed with this character, it and whatever contents it may hold will be ignored. **NOTE:** A whitelisted file path overrides this setting.
- `ignoreTopLevelDir` _(default: true)_ - Specifies if the directory being included use its own name as the initial key.
- `whitelist` _(default: [])_ - An array of paths to include regardless of any other settings.
- `blacklist` _(default: [])_ - An array of paths to skip regardless of any other settings.
- `excludeTopLevelDirSeparator` _(default: false)_ - Specifies if documents in the top level of the include path should be put under a key with an empty dir separator, or be added to the top level of the returned result.
- `pathSeparator` _(default: '/')_ - Determines path separator to use when joining subdirectory include paths together.
NOTE: if you want to use an `!!inc/dir` tag within an included file, make sure the inclusion path you enter is relative to the top-level included file.
### !!inc/file path
Parses `path` as a path to a single YAML document. The contents of that document will be a mapping under the key the tag is used on.
NOTE: Files are permitted to include other files or directories. Just make sure any paths within those files are relative to the top-level document.
## License
View the [LICENSE](LICENSE) file (ISC).