Flourish interpreter

Interpret the types of data represented in string format.

How to install

npm install -s @flourish/interpreter

Then:

import { createInterpreter } from "@flourish/interpreter";

Quick use

Create an interpreter using createInterpreter. You can then immediately start interpreting arrays with the resultant function.

var interpreter = createInterpreter();
var interpretations = interpreter(["-787", "1246,83", "203", "1.340.201"]) // Returns array of interpretation objects that match with the array

createInterpreter([interpretation_types])

Create a new interpreter function using an optional interpretation_types argument. interpretation_types can be either an array of strings or a single string where each string matches ones of the supported interpretation types. Currently those types are "datetime", "number" and "string". The first three of these have a number of subtypes. Array order is important as it determines the output order of tied interpretations when sorting is enabled (see interpreter.sort below) and all passing interpretations when it is not. The exception to this is that the (catch-all) "string" type always appears at the end of the array. If interpretation_types is not specified then a default of ["datetime", "number", "string"] is used.

interpreter(input_array, [accessor])

Interpret the input_array passed in.

If accessor is undefined then the interpreter acts directly on each element of the array. If accessor is a function then the interpeter acts on the result of calling that function with the array value as the first argument and the array index as the second argument. Otherwise, the interpreter acts on the property equal to the value of accessor for each element of the input_array.

Returns an array of interpretation objects (see the section on Interpretation objects below). Each object in the array has passed through the interpretation proceedure and can be though of a as a valid interpretation for the data, given the conditions specified using methods of the interpreter function.

If input_array is an empty array or an array of empty strings then no useful interpretation can take place. In this case the returned array will only contain the catch-all string-type object - if it is one of the allowed interpretation types - or nothing at all - if it is not.

interpreter methods

Each method of an interpreter function acts as both as a setter and a getter depending on whether or not a (non-undefined) argument is supplied. The functionality of these methods is described below.

interpreter.nMax([value])

The maximum number of non-empty strings that should be interpreted from the array_of_strings. Defaults to 250, set to Infinity to ensure all non-empty strings are interpreted.

interpreter.nFailingValues([value])

The maximum number of unique failing values that should be allowed before an interpreter is deemed to have failed. Defaults to 0.

interpreter.failureFraction([value])

The maximum fraction of failing values allowed before an interpreter is deemed to have failed. Defaults to 0.05. However, unless interpreter.nFailingValues is changed to a positive number, this value is largely irrelevant, as a single failing value will be enough to conclude that the interpreter has failed.

interpreter.sort([value])

Whether (true) or not (false) to sort the output interpretation objects based on (descending) failure fraction. Defaults to true, though sorting will only actually make any difference if both nFailingValues and failureFraction are positive numbers. The catch-all "string" interpretation type is never sorted and will always appear last in the output array if present.

Interpretation objects

All interpretation objects contain the following properties/methods:

interpretation.desciption

A text description of the interpretation.

interpretation.parse(str)

Parses the string, str, and tries to return a value of the relevant type (eg a number if the interpreter is of "number" type, though the result could be NaN). Throws an error if str is not a string.

interpretation.test(str)

Tests whether the string, str, could be interpreted as being of the correct subtype. Returns a Boolean. Throws an error if str is not a string.

interpretation.type

A text description of the interpreter type, ie "datetime", "number" or "string".

createInterpreter.DATETIME_IDS

A frozen array of the ids of the datetime subtypes. Can be used with createInterpreter.getInterpretation.

createInterpreter.NUMBER_IDS

A frozen array of the ids of the number subtypes. Can be used with createInterpreter.getInterpretation.

createInterpreter.STRING_IDS

A frozen array of the ids of the string subtypes (currently only a single subtype). Can be used with createInterpreter.getInterpretation.

createInterpreter.getInterpretation(id)

Get the interpretation with the given id.

recognised_formats

To reference a list of data type formats that can be interpreted by @flourish/interpreter, import recognised_formats:

import { recognised_formats } from "@flourish/interpreter";

recognised_formats is an object containing arrays of the different number and datetime data formats that are recognised by Flourish. You can access them like so:

var recognised_number_formats = recognised_formats.number;
var recognised_datetime_formats = recognised_formats.datetime;

Each array contains objects with information about a recognised data format.