string-dashes^1.4.0

Installation

Quick Take

Examples

• Parsers can supply the logical character separately from their source text.

Idea

A hyphen (-) is not a dash. Typographically-correct English text uses three different characters:

This program finds hyphens and dashes which are in the wrong place and reports what to replace them with. It reads the surrounding characters to decide, so it does not need you to mark anything up.

This is a sibling of string-apostrophes; both are used by detergent.

Sources used in rules logic and unit tests:

• Oxford A–Z of Grammar and Punctuation 2nd Ed., 2009, ISBN 978–0199564675
• Butterick’s Practical Typography 2nd Ed., “Hyphens and dashes” chapter

The rules

The program applies three rules. In each, the character being evaluated is a hyphen, an en dash or an em dash.

1. Number range or A-Z range → en dash. A hyphen with a digit on each side (1880-1912) becomes an en dash. So does a hyphen between two standalone uppercase letters (A-Z).
2. Whitespace on both sides → em dash. - becomes —. The exception is arithmetic: if the nearest non-whitespace characters on both sides are digits or currency symbols (1 - 2, $5 - $2), the hyphen is a minus sign, so it becomes an en dash instead.
3. Cut-off speech → em dash. A letter, then a hyphen, then a quote ("I was just abo-") becomes an em dash.

Anything the rules don’t recognise is left alone.

API — convertAll()

The main function convertAll() is imported like this:

It’s a function which takes two input arguments:

The Optional Options Object has the following shape:

convertAll() also accepts from, to, value and offsetBy, but it sets from itself while looping, so there’s little point passing them. Use convertOne() when you want to drive the indexes yourself.

Here are all defaults in one place for copying:

The function will return a plain object:

For example:

import { convertAll } from "string-dashes";

console.log(
  convertAll("Dashes come in two sizes - the en dash and the em dash.", {
    convertEntities: true,
  }),
);
// => {
//      result: "Dashes come in two sizes — the en dash and the em dash.",
//      ranges: [[25, 26, "—"]],
//    }

API — convertOne()

The main function convertOne() is imported like this:

It’s a function which takes two input arguments:

The Obligatory Options Object has the following shape:

opts.from is obligatory — that’s how you tell the program which character to process. It throws if from is missing, negative, or beyond the end of str.

The function returns ranges: an array of range arrays or null. Later you can use them in ranges-apply to process a string using those ranges (in other words, “to apply those ranges”).

import { convertOne } from "string-dashes";

console.log(
  convertOne("Dashes come in two sizes - the en dash and the em dash.", {
    from: 25,
    convertEntities: true,
  }),
);
// => [[25, 26, "—"]]

opts.value

Use opts.value when the character sits in the string encoded, or represented by something other than a literal -, – or —. You tell the program where the “symbol” starts (from) and ends (to), and what it stands for (value); the program then evaluates the surroundings as if a real dash were there:

import { convertOne } from "string-dashes";

console.log(
  convertOne("Dashes come in two sizes - the en dash.", {
    from: 25,
    to: 30,
    value: "-", // tell the program indexes 25-30 represent a hyphen
  }),
);
// => [[25, 30, "—"]]

That’s how detergent uses this package.

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.

These defaults are applicable for both convertOne() and convertAll() functions.

API — version

You can import version:

API — types

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

import type { Opts, Range, Ranges } from "string-dashes";

Changelog