truwrap

> A node module for text wrapping into streams that supports 24bit color SGR codes.

##### Publishing Status

 
 

##### Development Status

 
  

##### Documentation/Help


> v4 Breaking change The CLI command has been seperated into it's own repo [truwrap-cli][2]

Many current tty text wrapping solutions have issues with the 'long' and currently 'non-standard' RGB SGR codes (i.e ^[38;2;204;51;66m). This meant that, while it's possible to have wonderful, rich, full gamut colours and the aesthetic data visualisations it entails, it comes at the price of painful typography and corrupted console displays as text is broken up, unnaturally wrapped and becoming unreadable as the SGR codes are dashed against the rocks of 1980's shortsightedness, confusing your terminal and ever so slightly breaking the heart of design aware coders and administrators everywhere.

_Clearly this is unnacceptable!_

Previously, the only solution was to take a last, long whistful look at how great console colour could be, before going back to the, at best, 256 colours of the xterm pallette, with it's lack of useful greens and overly dark purples, or, for some, the even more cruelly devastating 16 colours of the ansi pallette, before heading to the stationary cupboard for a bit of a cry.

But weep no more!

Developed as part of our internal data visualisation system, where having the fidelity of 24 bit colour and embedded images (currently macOS iTerm only) was a huge advantage.

Usage

#### Installation

``shell
npm install --save @thebespokepixel/truwrap
`

`js
import {truwrap} from '@thebespokepixel/truwrap'

var writer = truwrap({
left: 2,
right: 2,
mode: 'soft',
outStream: process.stderr
})

var contentWidth = writer.getWidth()

writer.write("Some text to write...", "...and some more.")
writer.write("A new paragraph, if not implicitly present.")
writer.end() // Close the stream
`

mode can be set to the following values:

- soft: words are broken before the column width, giving a left justified appearance.
- hard: words are split at the column width.
- keep: lines longer than the column width are kept.
- container: left and right margins are ignored, giving a full width line.

As outStream was specified, wrapped output is written directly to the stream.

$3

If your terminal suppots them, you can add images into the wrapped output text.

To ensure that images are not used by default you need to set the env var TERM_IMAGES=enabled in your shell. See [term-ng for details.

`js
import {truwrap, createImage} from '@thebespokepixel/truwrap'

const image = createImage({
name: 'test',
file: join(dirname(fileURLToPath(import.meta.url)), '../media/test.png'),
width: 'auto', // Number of chars wide you'd like image. 'auto' to take it from the image/set height.
height: 1, // Number of lines the image will take
space: ' ' // A text string that is printed under the image so you can flow the wrapped text around it.
})

var renderer = truwrap({
mode: 'container'
})

truwrap.write(image.render({
nobreak: true, // Don't add a linebreak after the image.
stretch: false, // If true, distort the image the image to fit the width/height
align: 1 // How many lines to move back up after printing the image.
spacing: ' ' // A string to print after realigning the cursor after printing the image.
}))

console.log(truwrap.end())
`

As no outStream was specified truwrap.end() returns the wrapped text.

$3

`js
import {truwrap, parsePanel} from '@thebespokepixel/truwrap'

var writer = truwrap({
left: 2,
right: 2,
mode: 'soft',
outStream: process.stderr
})

const panelSource = parsePanel(
'One|Two|Three|Four', //Input text with column delimiters
'|', // Column delimiter
writer.getWidth() // Total width (chars) to make columns across
)

const panelOptions = {
maxLineWidth: writer.getWidth(), // Maximum line width
showHeaders: false, // Show colum headers
truncate: false, // Truncate columns if too wide
config: panelSource.configuration // Get config information from parsePanel()
}

writer.panel(panelSource.content, panelOptions)
writer.end() //Close stream
``

$3

For advanced 24bit colour handling see thebespokepixel/trucolor and npm trucolor.

Documentation

Full documentation can be found at [https://thebespokepixel.github.io/truwrap/][1]

[1]: https://thebespokepixel.github.io/truwrap/
[2]: https://github.com/thebespokepixel/truwrap-cli