toolbox2json

A Node / JavaScript library for parsing SIL Toolbox dictionary files and optionally converting them to JSON. Useful for any linguist working with a Toolbox dictionary database. Runs as a module or on the command line.

If you use this library for research purposes, please consider citing it using the following model:

Hieber, Daniel W. 2021. @digitallinguistics/toolbox2json. DOI:10.5281/zenodo.4560920.

Contents

• Prerequisites
• Basic Usage
  • Running as a Module
  • Running on the Command Line
• Field Mappings
• Options
• Contributing

Prerequisites

• Basic knowledge of JavaScript OR knowledge of how to run a program from the command line.
• Node.js installed on your system.

Basic Usage

Install using npm or yarn. (npm comes bundled with Node.js when you install it.)

npm install @digitallinguistics/toolbox2json
yarn add @digitallinguistics/toolbox2json

The library can be run as either a JavaScript module or from the command line.

Running as a Module

The JavaScript module exports a single function, toolbox2json, which accepts two arguments:

• the path to the Toolbox file (required)
• an options object (optional)

By default, the library returns a Promise that resolves to an Array of the entries in the Toolbox file.

import convert from '@digitallinguistics/toolbox2json';

const entries = await convert(`./my-data.db`);

You can also save the data to a JSON file by providing the out option:

import convert from '@digitallinguistics/toolbox2json';

await convert(`./my-data.db`, { out: `my-data.json` });

Running on the Command Line

To run the library from the command line, use toolbox2json <filePath>. (The toolbox2json command is added to the PATH when the library is installed.) This will print the results to the console by default. To save the JSON output to a file, use the --out option or -o flag: toolbox2json <filePath> --out <jsonPath>. To see the full list of command line options, run toolbox2json --help.

Field Mappings

The library will use line markers as property names when converting data. For example, if the Toolbox file has a field \txn for transcriptions, that would be converted to { "txn": "<data>" }.

If the Toolbox entry contains multiple instances of the same line marker, they will be converted to an array by default. For example, if the Toolbox file has two \gl fields containing the data fire and light, those would be converted to { "gl": ["fire", "light"] }.

Options

| Module | Command Line | Flag | Type | Default | Description | |--------------|-----------------|------|------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | | --help | -h | | | Display help. | | parseError | --parse-error | -e | String | "warn" | How to handle errors when parsing records. "error": Stop and throw an error. "none": Fail silently and continue. No object is created for that entry. "object": Return a ParseError object for that entry. "warn": Throw a warning and continue (default). | | ndjson | --ndjson | -n | Boolean | false | Outputs newline-delimited JSON. | | out | --out | -o | String | | The path where the JSON file should be saved. If this option is provided, the module will return a Promise that resolves when the operation is complete, and no JSON data will be displayed on the command line. | | pretty | --pretty | -p | Integer / String | false | Whether to pretty-print the JSON input. The value of this option is passed as the third argument to JSON.stringify(). If a value is provided for this option, the ndjson option will be set to false. | | silent | --silent | -s | Boolean | false | Silence console output. | | | --version | -v | | | Output the version number. |

Contributing

• Find a bug? Want to request a feature? Open an issue.
• Pull requests are welcome!
• Tests are run using Mocha and Chai. You can run them locally with npm test.
• Sample data for testing are located in /test.