Usage

Installation

npm install --save @thebespokepixel/truwrap
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.

Images

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.

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.

Panels

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

Related

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

API

Truwrap - take input from write() and composed a wrapped text block.

new Truwrap($0: Object, options: Object)
Parameters
$0 (Object)
Name Description
$0.left any (default 2)
$0.right any (default 2)
$0.width any
$0.mode any (default 'soft')
$0.tabWidth any (default 4)
$0.outStream any
$0.tokenRegex any
options (Object) options object
Instance Members
end()
getWidth()
panel(content_, configuration)
break(newlines)
clear()
write(content_)

Create a text wrapping instance.

truwrap(options: Object) → Truwrap
Parameters
options (Object) options object
Name Description
options.left number (default 2) Left margin.
options.right number (default 2) Right margin.
options.width number Manually set view width.
options.mode string (default 'soft') [soft | hyphen | hard | keep | container
options.tabWidth number (default 4) Desired width of TAB character.
options.outStream Stream.writable Where to direct output.
options.tokenRegex Regexp Override the tokenisers regexp.
Returns
Truwrap: { description_of_the_return_value }