@flourish/interpreter
v9.1.1
Published
Does a best guess at the type of data supplied
Downloads
2,271
Maintainers
Keywords
Readme
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.