wrap-text-plus
v1.0.0-alpha.15
Published
Library and CLI to wrap text for any width with handling for invisible formatting, smart list indentation, and more.
Downloads
3
Maintainers
Readme
liquid-labs/wrap-text
Library and CLI to wrap text for any width with handling for invisible formatting, smart list indentation, and more.
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.|