plain-text-data-to-json

Transform a simple plain-text database to JSON

Usage no npm install needed!

<script type="module">
  import plainTextDataToJson from 'https://cdn.skypack.dev/plain-text-data-to-json';
</script>

README

plain-text-data-to-json

Build Coverage Downloads Size

Transform a “database” / basic (word, phrase) list from plain text to JSON.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install plain-text-data-to-json

Use

var fs = require('fs')
var toJSON = require('plain-text-data-to-json')

var doc = fs.readFileSync('input.txt', 'utf8')

var data = toJSON(doc)

fs.writeFileSync('output.json', JSON.stringify(data, null, 2) + '\n')

API

This package exports the following identifiers: toJson. There is no default export.

toJson(value[, options])

Transforms the given value (string) to JSON. Don’t like the default comment and property-value pair delimiters? Specify your own:

options
options.comment

Character(s) to use for line-comments, false turns off comments (string, Array.<string>, or boolean, default: '%')

options.delimiter

Character to use as delimiter between property-value pairs (string, default: ':')

options.forgiving

How relaxed to be ('fix' or boolean, default: false). When true, doesn’t throw for duplicate keys. When 'fix', doesn’t throw for property-value pairs and overwrites (see errors).

options.log

Whether to log when forgiving ignores an error (boolean, default: true).

Why

I found myself rewriting a simple transformation over and over. This (verbosely named) project fixes that. It might not be useful, or too simple for others, but suites my use cases.

“Plain text”

The term plain text might be confusing. It’s actually more of some (sparingly specified) standard.

Comments

Use a percentage sign (by default) to specify a comment. The comment will last until the end of line.

% This is a completely commented line.
unicorn % This is a partially commented line.

Yields:

['unicorn']

Whitespace

Initial or final white space (\s) is trimmed from values.

       unicorn     % some value

Yields:

['unicorn']

Empty lines

Empty lines are striped. This includes blank (whitespace only) lines.

    %%% this file contains a value. %%%

unicorn

Yields:

['unicorn']

Property-value pairs

If a line includes a colon (by default), the library returns an object.

unicorn : magic creature

Yields:

{unicorn: 'magic creature'}

Values

All other lines are treated as array values.

unicorn

Yields:

["unicorn"]

Errors

Some errors are thrown when malformed “plain-text” is found, such as:

  • When lines both with and without colons exist
  • In arrays, when duplicate values exist (unless forgiving: true)
  • In objects, when duplicate properties exist (unless forgiving: true)
  • In objects, when duplicate properties with different values exist (unless forgiving: "fix")

License

MIT © Titus Wormer