The box.js module provides a Box class, which is a wrapper around an array of strings. See Concepts for more details.

The main difference between the Box class and strings (an array of strings) is that the Box class is wrapped around an array of strings of equal size. See strings.js for more details on strings.

box.js

import Box from '../box.js';

Class Box

The class has the following members:

Name	Return	Description
constructor(s, normalized)	Box	Creates a new Box object.
box	strings	The wrapped array of strings.
width	number	The width of the box.
height	number	The height of the box.
toStrings()	strings	Returns box — the wrapped array of strings.
clone()	Box	Clones the Box object.
toBox()	Box	An alias of clone().
clip(width, options)	Box	Returns a new object with strings clipped to width.
removeRows(y, n)	Box	Returns a new object with rows removed: n rows starting at y.
addBottom(box, {symbol = ' ', align = 'left'} = {})	Box	Returns a new object with box added at the bottom.
addRight(box, {symbol = ' ', align = 'top'} = {})	Box	Returns a new object with box added at the right.
flipV()	Box	Returns a new object with strings flipped vertically.

constructor() takes an array of strings as an argument. If normalized is true, the Box object assumes that the strings in the array are all the same size and takes the ownership of the array. If the argument is Box, it will be copied. Otherwise, the Box.make() algorithm is used (see below).

box is the only property of the Box object. It is an array of strings of equal length. All strings-related functions can be used with it:

const text = new Box(strings);
for (const line of text.box) console.log(line);

width and height are the width and height of the box. width is assumed to be a length of the first string in the array. If height is 0, width is assumed to be 0.

toStrings() returns box. This is the provision to convert boxes to strings by the toStrings() function of the strings.js module.

clone() and toBox() create a copy of a box.

clip() clips strings to a given width. Internally it just applies clip() of the strings.js module. See there for more information on arguments.

addBottom() and addRight() stack boxes vertically and horizontally. If boxes are of different sizes, the smaller ones are padded with symbol using the align argument. For example, if we stack vertically a 2 by 2 box and another 1 by 3 box using addBottom() with align: 'left', the result will be a 3 by 3 box. The 2 by 2 box will be padded with symbol on the right side up to 3 characters.

The padding methods:

Name	Return	Description
padLeftRight(left, right, symbol = ' ')	Box	Returns a new object with padded strings horizontally.
padTopBottom(top, bottom, symbol = ' ')	Box	Returns a new object with padded strings vertically.
padLeft(n, symbol = ' ')	Box	Returns a new object with padded strings on the left.
padRight(n, symbol = ' ')	Box	Returns a new object with padded strings on the right.
padTop(n, symbol = ' ')	Box	Returns a new object with padded strings on the top.
padBottom(n, symbol = ' ')	Box	Returns a new object with padded strings on the bottom.
pad(t, r, b, l, symbol = ' ')	Box	Returns a new object with padded strings.

The padding methods pad strings with symbol on specified sides.

padLeftRight() is more efficient than applying padLeft() and padRight() sequentially.

padTopBottom() is more efficient than applying padTop() and padBottom() sequentially.

pad() can apply padding on all sides at once. It is more efficient than applying individual padding methods. It is modeled after the CSS padding algorithm:

• pad(t) is equal to pad(t, 0)
• pad(t, r) is equal to pad(t, r, t, r)
• pad(t, r, b) is equal to pad(t, r, b, r)
• pad(t, r, b, l) uses given values for top, right, bottom, and left padding respectively.

Box defines the following static methods:

Name	Return	Description
Box.make(s, {symbol = ' ', align = 'left'})	Box	Returns a new Box object made out of s.
Box.makeBlank(width, height, symbol = ' ')	Box	Returns a new Box object with width and height filled with symbol.

Box.make() is used to convert its argument to a Box object. Its algorithm is similar to the toStrings() function of the strings.js module:

• A function — calls it with no arguments and reapplies Box.make() to its result.
  • A function could return a function, but Box.make() restricts the recursion to 10 invocations.
• An instance of Box — calls clone() on it and returns the result.
• An object with the toBox() method — calls toBox() on it and returns the result.
• Anything else — passes it through toStrings().

At this point it deals with strings (the array of string values):

• It identifies the longest string in the array.
• All other strings will be aligned and padded to that length.
• Alignment values are:
  • left or l — push strings to the left and pad with symbol on the right
  • right or r — push strings to the right and pad with symbol on the left
  • anything else — center strings and pad on both sides

The resulting strings are used as the normalized box value of a new Box object.

Just like strings, Box instances can represent a rectangle N by M, where N and M are positive integers. It can represent N by 0 and 0 by 0 boxes, but not 0 by M.

Function toBox()

toBox() is an alias of Box.make(). It is used to convert its argument to a Box object.

Exports

The Box class is exported by name and it is also the default export. toBox() is exported by name.