properties

.properties parser/stringifier

.properties specification

This module implements the Java .properties specification and adds additional features like ini sections, variables (key referencing), namespaces, importing files and much more.

Quick example

# file
a = 1
b: 2
c 3

var properties = require ("properties");

properties.parse ("file", { path: true }, function (error, obj){
  if (error) return console.error (error);
  
  console.log (obj);
  //{ a: 1, b: 2, b: 3 }
});

Documentation

• Sections
• Variables
  • Environment
• Namespaces
• INI
• Importing files
• Useful options that you should always use

Functions

• module.parse(data[, options][, callback]) : undefined | Object
• module.createStringifier() : Stringifier
• module.stringify(obj[, options][, callback]) : undefined | String

Objects

• Stringifier

Sections

INI sections can be enabled with the sections option. With them you can better organize your configuration data.

app_name App

[web]
hostname 10.10.10.10
port 1234

[db]
hostname 10.10.10.20
port 4321

Creates:

{
  app_name: "App",
  web: {
    hostname: "10.10.10.10",
    port: 1234
  },
  db: {
    hostname: "10.10.10.20",
    port: 4321
  }
}

Variables

When the variables option is enabled you can get the value of another key. The value is read before the type conversion. Imagine them like the C macros. They simply copy the characters, they don't care if the value is a number or a string.

a = 1
# b = 1
b = ${a}

Note: If you are using the include option, take into account that the variables are local to the file, they cannot be used to access the properties of other files.

If you need to get the value of a key that belongs to a section, prefix the key with the section followed by |.

a = 1
[section]
a = 2
# b = 2
b = ${section|a}

You can use the variables anywhere including the variable itself. Look at the variables example for further details.

a = 1
# s1
[s${a}]
a = b
b = c
# d = c
d = ${s${a}|${s${a}|a}}

Environment

You can also pass external variables with the vars option and use their value while the file is being parsed. This is an extremly useful feature because you don't need to change anything from your configuration files if you want to dynamically assign the value of the properties. It could be used to load different configurations depending on the environment. Look at the vars and environment-vars examples for further details.

Namespaces

When the namespaces option is enabled dot separated keys and sections are parsed as namespaces, that is, they are interpreted as JavaScript objects.

a.b = 1
a.c.d = 2

These properties create the following object:

{
  a: {
    b: 1,
    c: {
      d: 2
    }
  }
}

You can also use sections and variables:

[s1.x]
a.b = 1
# a.c.d = 1
a.c.d = ${s1.x|a.b}

{
  s1: {
    x: {
      a: {
        b: 1,
        c: {
          d: 1
        }
      }
    }
  }
}

The external variables can be also read using namespaces:

var options = {
  vars: {
    a: {
      b: 1
    }
  }
};

# a = 1
a = ${a.b}

Look at the namespaces example for further details.

INI

This module implements the .properties specification but there are some options that can be enabled, some of them are the sections, comments, separators and strict. With these four options this module can parse INI files. There isn't an official INI specification, each program implements its own features, but there is a de facto standard that says that INI files are just .properties files with sections and the = token as a separator.

If you want to parse INI files, then enable these options:

var options = {
  sections: true,
  comments: ";", //Some INI files also consider # as a comment, if so, add it, comments: [";", "#"]
  separators: "=",
  strict: true
};

The strict option says that only the tokens that are specified in the comments and separators options are used to parse the file. If strict is not enabled, the default .properties comment (#, !) and separator (=, :) tokens are also used to parse comments and separators. Look at the ini examples for further details.

Note: The whitespace (<space>, \t, \f) is still considered a separator even if strict is true.

Importing files

When the include option is enabled, the include key allow you import files. If the path is a directory, it tries to load the file index.properties. The paths are relative to the current .properties file.

The imported files are merged with the current file, they can replace old data.

The include keyword cannot appear inside a section, it must be a global property.

include a/file

# Load a/dir/index.properties
include a/dir

Note: You can include files using a simple key-value string:

properties.parse ("include my/file", function (error, data){
  ...
})

In this case the files are always relative to .. You cannot use __dirname like this: "include " + __dirname + "/my/file".

Useful options that you should always use

There are too many options that you can enable but, which of them should you use? Well, this depends on what you need but I like to enable the following ones:

• namespaces: Extremly useful if you want to organize your configuration files using namespaces and access the data using JavaScript objects. For example:

  db.pool.min 5
  db.pool.max 10

  Instead of:

  db_pool_min 5
  db_pool_max 10

• sections: More organization. You don't need to write all the namespace chain. For example:

  [db]
  host 1.2.3.4
  port 1234
    
  [db.pool]
  min 5
  max 10

  Instead of:

  db.host 1.2.3.4
  db.port 1234
  db.pool.min 5
  db.pool.max 10

• variables: Writing the same thing again and again is a bad practice. Write it once and use a variable to copy the value wherever you want. With the variables enabled you can pass external variables to the file using the vars option, which is pretty useful as shown in the environment-vars example.

• include: Even more organization. I don't like to have a huge configuration file, I tend to have multiple smaller files. With this option I don't need to load all the files, I simply load the index file which includes all the files.

Wrapping this module it's also a good idea. This is a good starting point:

//config.js

var properties = require ("properties");

var options = {
  path: true,
  namespaces: true,
  sections: true,
  variables: true,
  include: true
};

var configDir = "./path/to/config/dir";

module.exports.load = function (path, cb){
  //NODE_ENV can be "production" or "development"
  //Load specific configuration depending on the environment
  properties.parse (configDir + "/" + process.env.NODE_ENV, options,
      function (error, env){
    if (error) return cb (error);
    
    //Pass the specific configuration as external variables to the common
    //configuration
    options.vars = env;
    
    //If the path is a directory it tries to load the "index.properties" file
    properties.parse (configDir, options, cb);
  });
};

Usage:

var config = require ("./config");

config.load (function (error, obj){
  if (error) return console.error (error);
  
  ...
});

Note: You can also use a configuration loader like seraphim.

module.parse(data[, options][, callback]) : undefined | Object

Parses a .properties string.

If a callback is given, the result is returned as the second parameter. Some options will require a callback.

try{
  //Certain options can throw errors, so if the callback is not used, try-catch
  //the function
  obj = properties.parse ({ ... });
}catch (error){
  ...
}

properties.parse ({ ... }, function (error, obj){
  //The callback must be used if the "path" option is used
});

Options:

• path - Boolean
  By default parse() reads a String. If you want to read a file, set this option to true. If this option is used, the callback is mandatory. It gets 2 parameters, a possible error and the object with all the properties.

• comments - String | Array
  Allows you to add additional comment tokens. The token must be a single printable non-whitespae ascii character. If the strict option is not set, the tokens # and ! are parsed as comment tokens.

  comments: ";"
  comments: [";", "@"]

• separators - String | Array
  Allows you to add additional separator tokens. The token must be a single printable non-whitespae ascii character. If the strict option is not set, the tokens = and : are parsed as comment tokens.

  separators: "-"
  separators: ["-", ">"]

• strict - Boolean
  This option can be used with the comments and separators options. If true, only the tokens specified in these options are used to parse comments and separators.

• sections - Boolean
  Parses INI sections. Read the INI section for further details.

• namespaces - Boolean
  Parses dot separated keys as JavaScript objects. Look at the namespaces section for further details.

• variables - Boolean
  Allows you to read the value of a key while the file is being parsed. Look at the variables section for further details.

• vars - Boolean
  External variables can be passed to the file if the variables option is enabled. Look at the variables section for further details.

• include - Boolean
  Files can be linked and imported with the include key. If this option is used, the callback is mandatory. Look at the include section for further details.

• reviver - Function
  Each property or section can be removed or modified from the final object. It's similar to the reviver of the JSON.parse() function.

  The reviver it's exactly the same as the replacer from stringify(). The same function can be reused.

  The callback gets 3 parameters: key, value and section.

  A property has a key and a value and can belong to a section. If it's a global property, the section is set to null. If undefined is returned, the property will be removed from the final object, otherwise the returned value will be used as the property value.

  If the key and the value are set to null, then it's a section line. If it returns a falsy value, it won't be added to the final object, the entire section -including all the properties- will be discarded. If it returns a truthy value, the section is parsed.

  For your convenience, to know whether the line is a property or section you can access to this.isProperty and this.isSection from inside the replacer function. Also, this.assert() can be used to return the default value, the unmodified value that will be used to parse the line.

  this.assert() it's the same as:

  if (this.isProperty){
    return value;
  }else{
    //isSection
    return true;
  }

  For example, a reviver that does nothing and a reviver that removes all the lines:

  function (key, value, section){
    //Returns all the lines
    return this.assert ();
  }

  function (key, value, section){
    //Removes all the lines
  }

  The reviver is called just after the value is casted to the proper data type. This means that the value parameter can be null, true, false or any data type.

  This module doesn't parse arrays but you can actually parse comma-separated values using a reviver:

  var options = {
    sections: true,
    reviver: function (key, value, section){
      //Do not split section lines
      if (this.isSection) return this.assert ();
        
      //Split all the string values by a comma
      if (typeof value === "string"){
        var values = value.split (",");
        return values.length === 1 ? value : values;
      }
        
      //Do not split the rest of the lines
      return this.assert ();
    }
  };
    
  /*
  [sec,tion]
  key1 a,b,c
  key2 true
  */
  console.log (properties.parse ("[sec,tion]\n key1 a,b,c\n key2 true", options));
    
  /*
  {
    "sec,tion": {
      key1: ["a", "b", "c" ],
      key2: true
    }
  }
  */

  Look at the reviver example for further details.

module.createStringifier() : Stringifier

Returns a new Stringifier instance.

module.stringify(obj[, options][, callback]) : undefined | String

Stringifies an object or a Stringifier.

If you don't need to add sections or comments simply pass an object, otherwise use a Stringifier.

The callback is only necessary when the path option is used.

Nested objects and arrays cannot be stringified like in JSON.stringify:

properties.stringify ({
  a: [1, "a"],
  b: {}
});

/*
a = 1,a
b = [object Object]
*/

This also applies to the Stringifier keys and values.

Options:

• path - String
  By default stringify() returns a string. If you want to write it to a file, use this option and pass the path of a file. If this option is used, the callback is mandatory. It gets two parameters, a possible error and the string.

• comment - String
  The token to use to write comments. It must be a single printable non-whitespace ascii character. Default is #.

• separator - String
  The token to use to separate keys from values. It must be a single printable non-whitespace ascii character. Default is =.

• unicode - Boolean
  The .properties specification uses iso 8859-1 (latin-1) as a default encoding. In the other hand, Node.js has a utf8 default encoding. This means that if you want a full compatibility with Java, that is, you are generating a .properties file that is going to be read by a Java program, then set this option to true. This will encode all ascii extended and multibyte characters to their unicode string representation (\uXXXX).

  Non-printable control codes (control sets 0 and 1) are always encoded as unicode strings except \t, \n, \f and \r.

  If you are in a platform that can handle utf8 strings, e.g. Node.js, you don't need to use this option.

• replacer - Function
  Each property or section can be removed or modified from the final string. It's similar to the replacer of the JSON.stringify() function.

  The replacer it's exatcly the same as the reviver from parse(). The same function can be reused.

  The callback gets three parameters: key, value and section.

  A property has a key and a value and can belong to a section. If it's a global property, the section is set to null. If undefined is returned, the property won't be stringified, otherwise the returned value will be used as the property value.

  If the key and the value are set to null, then it's a section line. If it returns a falsy value, it won't be added to the final string, the entire section -including all the properties- will be discarded. If it returns a truthy value, the section is stringified.

  For your convenience, to know whether the line is a property or section you can access to this.isProperty and this.isSection from inside the replacer function. Also, this.assert() can be used to return the default value, the unmodified value that will be used to stringify the line.

  this.assert() it's the same as:

  if (this.isProperty){
    return value;
  }else{
    //isSection
    return true;
  }

  For example, a replacer that does nothing and a replacer that removes all the lines:

  function (key, value, section){
    //Returns all the lines
    return this.assert ();
  }

  function (key, value, section){
    //Removes all the lines
  }

  Look at the replacer example for further details.

Stringifier

This class is used when you want to add sections or comments to the final string.

To create a Stringifier use the createStringifier() function.

Methods

• Stringifier#header(comment) : Stringifier
• Stringifier#property(obj) : Stringifier
• Stringifier#section(obj) : Stringifier

Stringifier#header(comment) : Stringifier

Writes a header comment. It will be written to the top of the final string. Returns the Stringifier being used.

Stringifier#property(obj) : Stringifier

Writes a property line. It takes an object with three options: key, value and comment. Both the key and the value are converted into a string automatically. Returns the Stringifier being used.

stringifier
  //No value
  .property ({ key: "a" })
  .property ({ key: "b", value: [1, 2, 3] })
  //No key and no value
  .property ({ comment: "empty" })

/*
a = 
b = 1,2,3
# empty
 = 
*/

Stringifier#section(obj) : Stringifier

Writes a section line. It gets an object with two options: name and comment. The name is converted into a string. If you don't need to write a comment, you can pass the name instead of an object. Returns the stringifier being used.

stringifier.section ("my section");

/*
[my section]
*/

stringifier.section ({ name: "my section", comment: "My Section" });

/*
# My Section
[my section]
*/

Look at the stringify-ini example for further details.