shell-source
Version:
Source environment variables from a shell script into a Node.js process.
82 lines (64 loc) • 4.34 kB
Markdown
# shell-source
Source environment variables from a shell script into a [Node.js](http://nodejs.org/) process.
[](http://www.npmjs.org/shell-source)
[](https://travis-ci.org/jessetane/shell-source)
[](https://coveralls.io/r/jessetane/shell-source)
#### Dragons:
> Since sourcing a shell script allows it to execute arbitrary code, you should be 100% sure its contents are not malicious!
## Why
You have some configuration data stored in a sourcable shell script, but need access to that data from a JavaScript program. You could try to parse the file as text, but that would only work if the script does not execute code or expand any variables.
## How
Spawns the process owner's default shell and executes a [POSIX](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#dot) compliant wrapper script that in turn [sources](http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x237.html) the file of your choosing. The wrapper then calls [`printenv`](http://www.tldp.org/LDP/Bash-Beginners-Guide/html/sect_03_02.html) which writes the child process' updated environment to stdout. The parent (Node.js) process then parses this output and updates `process.env`.
## Example
Consider the script below that needs to execute code before its variables can be evaluated:
```bash
export SERVER_HOST="$(hostname)"
export SERVER_PORT="$(grep -m1 '# HTTP Alternate' < /etc/services | sed 's/[^0-9]*\(.*\)\/.*/\1/')"
export PATH="node_modules/.bin:$PATH"
```
A Node.js process can use `shell-source` to emulate the behavior of `sh`'s `.` built-in, executing the script before absorbing any enviroment changes it effects:
```javascript
var source = require('shell-source');
source(__dirname + '/env.sh', function(err) {
if (err) return console.error(err);
console.log(process.env.SERVER_HOST); // ::
console.log(process.env.SERVER_PORT); // 8080
console.log(process.env.PATH); // node_modules/.bin:/usr/local/bin
});
```
## Install
```bash
$ npm install shell-source
```
## Test
```bash
$ npm test
```
## Require
#### `var source = require('shell-source');`
## Use
#### `source(filepath, [opts,] callback);`
* `filepath` The full path to the shell script that should be sourced.
* `opts` An options object which can contain:
* `source` A boolean. Defaults to `true`. If set to `false`, the callback can receive the evironment object as its second argument and `process.env` will be left unmolested.
* `wrapper` Use your own wrapper script. [`source.sh`](https://github.com/jessetane/shell-source/blob/master/source.sh) is used by default.
* `reserved` An object to merge with the default [blacklist](https://github.com/jessetane/shell-source/blob/master/index.js#L5) where `SHLVL` and `_` are already set to `true`.
* `callback` A callback with signature:
```javascript
function(err, environment) {
// console.log(err, environment);
}
```
## Notes
Obviously it would be nice if this could be done synchronously. However, until something like [this](http://strongloop.com/strongblog/whats-new-in-node-js-v0-12-execsync-a-synchronous-api-for-child-processes) lands on stable, I'm not sure if there is a sane way to accomplish it. If there is, please let me know.
## Releases
The latest stable release is published to [npm](https://www.npmjs.org/package/shell-source). Tarballs for each release can be found [here](https://github.com/jessetane/shell-source/releases).
* [1.1.0](https://github.com/jessetane/shell-source/releases/tag/1.1.0)
* xtend is not a dev dependency (thanks @sparkleholic)
* [1.0.x](https://github.com/jessetane/shell-source/releases/tag/1.0.1)
* First release.
## License
Copyright © 2014 Jesse Tane <jesse.tane@gmail.com>
This work is free. You can redistribute it and/or modify it under the
terms of the [WTFPL](http://www.wtfpl.net/txt/copying).
No Warranty. The Software is provided "as is" without warranty of any kind, either express or implied, including without limitation any implied warranties of condition, uninterrupted use, merchantability, fitness for a particular purpose, or non-infringement.