traf

Transform between various data serialization formats

Demo

• Installation
  • npm
  • bower
• Usage
  • CLI
  • Node JS
  • Browser
• Code organization
  • Formats
  • Backends
  • Method suffixes
    • Sync
    • Async
• Supported formats
• API
  • parseSync(str, opts)
  • parseAsync(str, opts, cb)
  • stringifySync(data, opts)
  • stringifyAsync(data, opts, cb)
  • parseFileSync(filename, opts)
  • parseFileAsync(filename, opts, cb)
  • stringifyFileSync(data, opts)
  • stringifyFileAsync(data, opts, cb)
  • guessFiletype(filename, opts={})
  • guessMimetypeFormat(mimetype, opts={})
  • guessFilename(filename, opts)

Installation

npm

npm install traf

bower

bower install https://github.com/kba/traf

Usage

CLI

Install the package globally (npm install -g traf)

Usage: traf [options...] <input-file> [<output-file>]

Transform between different serialization formats

Options:
    -h --help                   Show this help
    -i --input-format FORMAT    Input format
    -o --output-format FORMAT   Output format
    -f --force                  Overwrite existing files
    -I --indent INDENT          Indent data with INDENT spaces per level

Arguments:
    <input-file>    Input filename.
                    Can be '-' to read from STDIN. Specify input format then.
    <output-file>   Output filename.
                    If omitted, derive output filename from input filename.
                    Can be '-' to write to STDOUT. Specify output format then.

Node JS

var t = new(require('traf'))();
console.log(t.parseSync("- 'foo'", {"format": "YAML"}));

Browser

<script src="./path/to/traf.js"></script>
<!-- or -->
<script src="https://kba.github.io/traf/dist/traf-latest.js"></script>
<script>
var t = new traf();
console.log(parseSync("- 'foo'", {"format": "YAML"}));
</script>

Code organization

Formats

A format is a set of rules how to serialize and deserialize data.

Every format has a subfolder in ./src/lib/backend.

Backends

Every format has one or more backends, extending the Backend base class.

Method suffixes

All functions are suffixed with the mechanism to execute them:

Sync

Method takes argument and options and returns the result or throws an exception.

try {
  data = traf.parseSync(str, {"format": "JSON"})
  // do stuff with data
} catch (e) {
  // handle error
}

Async

Method takes argument, options and returns a callback with arguments err and result.

traf.parseAsync(str, {"format":"JSON"}, function(err, data) {
  if (err) {
    // handle error
  }
  // handle data
});

Supported formats

API

parseSync(str, opts)

parseAsync(str, opts, cb)

Load a file in any of the supported serialization formats.

Options:

• format: Input format

stringifySync(data, opts)

stringifyAsync(data, opts, cb)

Serializes the data passed to a string.

Options:

• format: Output format

parseFileSync(filename, [opts])

parseFileAsync(filename, [opts], cb)

Options:

• format: Input format
• extensions: List of extensions to add to the filename in case it does not exist.

By default, input format is determined by extension.

Not available in the browser version.

stringifyFileSync(data, opts)

stringifyFileAsync(data, opts, cb)

Serializes the data passed to a string and writes it to a file.

Options:

• filename: The filename to write to
• format: If not given explicitly, determined by extension.

guessFiletype(filename, opts={})

Guess parser options by looking at the filename.

Will add information to opts, at least the format if it was recognized and possibly further options that can be guessed from the filename.

console.log(traf.guessFilename('foo.json'))
// {"format":"JSON"}
console.log(traf.guessFilename('foo.tsv'))
// {"format":"CSV", "delimiter": "\t"}

guessMimetypeFormat(mimetype, opts={})

Derive the format (e.g. JSON) from the MIME type (e.g. application/json)

Will return the found format

guessFilename(filename, opts)

Guess output filename by changing the extension to the outputExtension of the format in opts.