Node tjd-configuration
A Simple Runtime Configuration File Processor
When all you need are a few runtime options, such as database connection parameters and TCP port numbers, you just need a simple text file that you can easily edit. This module provides that. It reads a file in the current working directory called 'configuration.txt' and processes it line by line.
Installation
Use NPM to install:
npm install tjd-configuration
Usage
Assuming a configuration.txt file that contains the following line:
listenport = 8080;
You would use the following code to read configuration.txt and retrieve the runtime parameter that you needed.
var config = require('tjd-configuration');
config.read();
var listenport = config.get('listenport');
Alternatively, you could specify the configuration file name as an argument to the read() method, thus:
config.read('dbparams.config');
Conventions
Configuration File Name
If you call the read() method without supplying the name of a configuration file, then the read() method will first look for a localized configuration file that is named according to this pattern: 'configuration-' + hostname + '.txt'.
If you are not sure exactly what your hostname is, you can call the getLocalizedFilename() method and it will return to you a string that contains the name of the localized configuration file that the read() method will look for first.
If the read() method cannot find a localized configuration file, then it will look for 'configuration.txt' and process that file if it is found.
Alternatively, you can supply a full file name to the read() method, such as .read('dbparams.txt');
File Format
- Blank lines are ignored
- Lines starting with # are ignored (must have # as very first character)
- All other lines are treated as key=value pairs.
On a key=value pair line, all white space up to the beginning of the value is ignored. Therefore 'key=value' and ' key = value' are processed identically. That lets you use indentation and spacing to make your files easier to comprehend.
Error Handling
If the named configuration file (or configuration.txt, if no argument is given to the read() method) is missing or otherwise can't be read, an uncaught exception will be thrown.
If the read() function encounters a line it doesn't understand, it will log that fact to the console but continue processing the rest of the file.
API
get(paramName)
Retrieves the requested parameter value.
getLocalizedFilename()
Returns a string containing the name of the localized configuration file that will be searched for. Hostnames can be a strange thing to deal with on flippantly-configured servers. Knowing what this package is looking for can help you properly name your localized configuration file, if you want one.
put(paramName, value)
Sets a parameter to a new value or adds a new parameter with a value. In a future version, we'll have a write() or save() method that will write out a new configuration file with these added or revised values.
read([filename])
Reads and processes a configuration file. If a filename value is provided, then this method looks for that file and tries to process it. If no filename is given, then first we look for a localized configuration contained in a file named {hostname}-configuration.txt. For example, docs.jdreview.com-configuration.txt. If a localized file is not found, then it looks for a file named configuration.txt. If that file is not found, it throws an exception.
Changelog
0.0.9 - Updated documentation
0.0.8 - Updated documentation. Added put() method. Added to GitHub.
0.0.7 - Reveresed the __dirname change because it raised errors under PM2
0.0.6 - Prepended __dirname to beginning of configuration file name.
0.0.5 - Added ability to look for localized configuration file along with getLocalizedFilename() method.
0.0.4 - Fixed installation problem.
0.0.3 - Added optional argument to read() method to provide a filename.
0.0.2 - Updated README.md
0.0.1 - Initial release
License
(The MIT License)
Copyright (c) 2015 by Thomas J. Daley <tjd@powerdaley.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.