npm.io
2.0.0 • Published 2 years ago

calimari

Licence
Apache-2.0
Version
2.0.0
Deps
0
Size
111 kB
Vulns
0
Weekly
0

Calimari

The lean-ient number range & set parser, now in TypeScript. No dependencies, no fuss.

Usage • Features • Configuration • Source Code

Usage

// es6
import calimari from "calimari";
// commonjs
const calimari = require("calimari");

calimari("5-7, 9 || -5-6");
/*
[
    [5, 6, 7, 9],
    [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6]
]
*/

calimari("12, 15, 17-20 ^ 18", { allGroups: false });
/* [12, 15, 17, 19, 20] */

calimari("1-3 \n 4-6 \n 7-9", { groupSeparator: '\n' });
/*
[
    [ 1, 2, 3 ],
    [ 4, 5, 6 ],
    [ 7, 8, 9 ]
]
*/

calimari("(5 - 10, 11, 12, 13) ^ (8-11)");
/* [ [ 5, 6, 7, 12, 13 ] ] */

calimari("1, 2, 3, (4 - 5", { minValue: 2 });
/*
[
  [ 2, 3, 4, 5 ],
  errors: [
    {
      type: 3,
      group: 0,
      location: 1,
      message: 'Value 1 is less than min bound 2'
    },
    {
      type: 2,
      group: 0,
      location: 15,
      message: 'Expected ending closure symbol'
    }
  ]
]
*/

Features

Ranges

The dash - is considered the "range" operator since it expects a number before & after between which to create a range. Once a range is created, each integer between the low and high bound becomes part of the output group.

Unions

The comma , is considered the "union" operator since it joins together numbers, ranges and enclosures. If two numbers are separated by whitespace with no union operator, a union operator is inferred and an error is generated.

Groups

The double pipe || is the default "group separator" (can be overrided in the config). Each group will be returned as a separate array in the output 2D array, or if allGroups is set to false, each group is unionised to create the output 1D array.

Closures

The open & closing parenthesis () are the opening and closing closure operators respectively. Within a closure, the state of the parser is reset. Each closure is evaluated seperately, and then either added or subtracted to eachother depending on the state of the parser (see Difference).

Difference

The ^ is considered the "difference" operator. It works like the union operator, except where C = A ^ B, C contains all values that are contained within A but not B.

Errors

The result will have the errors property set to an array of error objects if at least 1 error was encountered during parsing. All errors can be safely ignored. If an error is generated, parsing will not halt unless strict is set in the config. The errors object is structured as follows:

Property Type Description
type number A number corresponding to the internal type of the error. See Error Types.
group number The group that was being processed when the error was generated.
location number The location within the group string where the error was generated.
message string Message describing the problem.
Error Types
Type Code Type Name Description
0 OK No error.
1 BAD_CONFIG The configuration given to the parser is malformed.
2 BAD_FORMAT The input to the parser is inconsistent; e.g. a closure was opened without being closed.
3 BAD_VALUE The parser expected a number, but the number was malformed or unacceptable.
4 BAD_SYMBOL The parser expected a symbol (e.g. -,^()) but received a non-symbol.

Configuration

All config keys are optional. If a configuration option with no default is left unset, its associated behavior is disabled.

Key Type Description
allGroups boolean If set to false, Calimari will return a 1D array containing the union of all groups.
strict boolean If set to true, Calimari will throw an error if any errors were generated.
groupSeparator string | RegExp The pattern that divides groups. Default is ||.
minValue number Enforces that all numbers are greater than or equal to this.
maxValue number Enforces that all numbers are less than or equal to this.
onlyWhole boolean If set to true, only whole numbers (integers) are allowed.

License

   Copyright 2024 Wasabi Codes

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Keywords