liquid-labs/wrap-text

Library and CLI to wrap text for any width with handling for invisible formatting, smart list indentation, and more.

• Installation
• Usage
  • Library usage
  • CLI usage
• Examples
  • Basic wrapping
  • Wrap ignoring formatting
  • Wrap ignoring tags
  • Smart list indentation
  • Hanging indentation
  • Absolute indentation
  • Line-prefixing
• User reference
  • API reference
  • CLI reference

Installation

npm i @liquid-labs/wrap-text

Usage

Library usage

import { wrap } from '@liquid-labs/wrap-text'
//                      0        1         2         3         4         5         6
//                      12345678901234567890123456789012345678901234567890123456789012
const someTaggedText = "Hey! Here's some <i>text</i> with <em>tags</em> embedded in it."
console.log('Default wrapping:\n')
console.log(wrap(someTaggedText, { width: 40 }))

console.log('Tag-ignoring wrapping:\n')
console.log(wrap(someTaggedText, { ignoreTags: true, width: 40 }))

See Examples section for output.

CLI usage

cat 'some text' | wrap
wrap a-text-file.txt

Examples

The numbers are given as a visual aid, only the text is actually printed.

Basic wrapping

By default, tags don't get special treatment.

text = "Hey! Here's some <i>text</i> with <em>tags</em> embedded in it."
wrap(text, { width: 40 })

yields:

0        1         2         3         4
1234567890123456789012345678901234567890
Hey! Here's some <i>text<rst> with 
<em>tags<rst> embedded in it.

Wrap ignoring formatting

const text = "Hey! Here's some \u001b[1mtext\u0000 with \u001b[106mformatting\u0000 embedded in it."
wrap(text, { width: 40 })

yields:

0        1                  2                            3               4
12345678901234567         8901       23456            789012345      67890
Hey! Here's some \u001b[1mtext\u0000 with \u001b[106mformatting\u0000
embedded in it.

Wrap ignoring tags

text = "Hey! Here's some <i>text</i> with <em>tags</em> embedded in it."
wrap(text, { ignoreTags: true,  width: 40 })

yields:

0        1            2                 3              4
12345678901234567   8901     234567    8901     234567890
Hey! Here's some <i>text<rst> with <em>tags<rst>
embedded in it.

• Tags are simple and cannot contain any spaces. I.e., these are not full HTML/XML tags.
• The tags wrapping is meant to be compitible with @liquid-labs/terminal-text.

Smart list indentation

const text = `- We'll indent the entire item to match the list.
  - And same goes for this sub item!
Now back to normal.`
wrap(text, { smartIndent: true, width: 30 })

yields:

0        1         2         3
123456789012345678901234567890
- We'll indent the entire item
  to match the list.
  - And same goes for this sub 
    item!
Now back to normal.

Of course you can combine smartIndent with ignoreTags. But not hangingIndent or indent.

Hanging indentation

const text = `Hi there my friend!
This is a hanging indent.`
wrap(text, { hangingIndent: 2, width: 12 })

yields:

0        1
123456789012
Hi there my
  friend!
This is a
  hanging
  indent.

Cannot be combined with smartIndent or indent

Absolute indentation

const text = `Hi there my friend!
This is absolute indent.`
wrap(text, { indent: 2, width: 12 })

yields:

0        1
123456789012
  Hi there
  my friend!
  This shows
  off the
  absolute
  indent.

Line prefixing

const text = `Hi there my friend!
This is what prefixing looks like.`
wrap(text, { prefix: '(!) ', width: 12 })

yields:

    0        1
    123456789012
(!) Hi there my
(!) friend!
(!) This is what
(!) prefixing
(!) looks like.

Notice that unlike the indentation schemes, the prefix is in addition to the width.

User reference

API reference

wrap(text, option): Wraps the specified text to the specified or default width.

• text: The text to wrap.
• options.hangingIndent: The amount to indent all but the first line of a paragraph. Incompatible with other indent modes.
• options.ignoreTags: Treat any tags ('<...>') in the text as 'invisible' and adjust wrapping accordingly.
• options.indent: Indent each line by the spcified amount. Incompatible with other indent modes.
• options.prefix: Prefixes each wrapped line with the indicated prefix. Note this happens after the lines are wrapped according to the specified width. If you need the line to be a specific width in total, you must subtract the length of the indent yourself.
• options.width: The width to wrap to. Defaults to 80. Use '0' to default to 'process.stdout.columns' and -1 for no wrapping.

CLI reference

Usage

wrap <options> <input-file>

Options

Option	Description
<input-file>	(main argument,optional) The file to process and wrap.
--document	Creates documentation for self.
--document-section-depth	Sets the initial section-depth for generated docuemnation.
--document-title	Sets the title for generated documentation.
--hanging-indent	The amount to indent all but the first line of a paragraph. Incompatible with other indent modes.
--ignore-tags	Treat any tags ('<...>') in the text as 'invisible' and adjust wrapping accordingly.
--indent	Indent each line by the spcified amount. Incompatible with other indent modes.
--prefix	Prefixes each wrapped line with the indicated prefix. Note this happens after the lines are wrapped according to the specified width. If you need the line to be a specific width in total, you must subtract the length of the indent yourself.
--smart-indent	Ignores tags (treats as zero-width string) when wrapping.
--width	The width to wrap to. Defaults to 80. Use '0' to default to 'process.stdout.columns' and -1 for no wrapping.