string-split-by-whitespace^4.2.1

Installation

Quick Take

Examples

• Exclude a template variable range from the returned words
• Split on line breaks, tabs, and repeated spaces

Purpose

When String.split(/\s+) is not enough, for example, when you need to exclude certain substrings, this program will help.

It splits the string by whitespace — definition of “whitespace” being “anything that trims to zero-length” — that’s tabs, line breaks (CR and LF), space character and raw non-breaking space. There are quite few Unicode characters across the whole Unicode range.

API — splitByW()

The main function splitByW() is imported like this:

It’s a function which takes three input arguments:

The Optional Options Object has the following shape:

Here are all defaults in one place for copying:

The function will return an array of zero or more strings. Empty string yields empty array.

opts.ignoreRanges

Some basics first. “Heads” and “tails” here mean some templating literals that wrap a value. “heads” is frontal part, for example {{ below, “tails” is ending part, for example }} below:

Hi {{ firstName }}!

Now imagine you extracted heads and tails and you know their ranges: [[3, 5], [16, 18]]. (If you select {{ and }} from in front of “Hi” to where each head and tail starts and ends, you’ll see that these numbers match).

Now imagine you want to split Hi {{ firstName }}! into array ["Hi", "firstname", "!"].

For that you need to skip two ranges, those of a head and tail.

That’s where opts.ignoreRanges become handy.

In the example below, the library string-find-heads-tails is used to extract the ranges of variables’ heads and tails in a string, then split by whitespace:

const input = "some interesting {{text}} {% and %} {{ some more }} text.";
const headsAndTails = strFindHeadsTails(input, ["{{", "{%"], ["}}", "%}"]).reduce((acc, curr) => {
  acc.push([curr.headsStartAt, curr.headsEndAt]);
  acc.push([curr.tailsStartAt, curr.tailsEndAt]);
  return acc;
}, []);
const res1 = split(input, {
  ignoreRanges: headsAndTails,
});
console.log(`res1 = ${JSON.stringify(res1, null, 4)}`);
// => ['some', 'interesting', 'text', 'and', 'some', 'more', 'text.']

You can ignore whole variables, from heads to tails, including variable’s names:

const input = "some interesting {{text}} {% and %} {{ some more }} text.";
const wholeVariables = strFindHeadsTails(input, ["{{", "{%"], ["}}", "%}"]).reduce((acc, curr) => {
  acc.push([curr.headsStartAt, curr.tailsEndAt]);
  return acc;
}, []);
const res2 = split(input, {
  ignoreRanges: wholeVariables,
});
// => ['some', 'interesting', 'text.']

You need to perform the array.reduce to adapt to the string-find-heads-tails output, which is in format (index numbers are only examples):

[
  {
    headsStartAt: ...,
    headsEndAt: ...,
    tailsStartAt: ...,
    tailsEndAt: ...,
  },
  ...
]

and with the help of array.reduce you turn it into the format this program wants:

(first example with res1)

[
  [headsStartAt, headsEndAt],
  [tailsStartAt, tailsEndAt],
  ...
]

(second example with res2)

[
  [headsStartAt, tailsEndAt],
  ...
]

API — defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — version

You can import version:

API — types

This package is written in TypeScript and exports the following types:

import type { Opts, Range } from "string-split-by-whitespace";

Changelog