wordwrap

Documentation

Overview

Package wordwrap wraps text to a fixed width, modeled on the npm "word-wrap" package. It is a standard-library-only Go port that reflows a paragraph of text so that no output line exceeds a chosen width, which is useful for rendering help text, log messages, email bodies, terminal output, and any other place where a long run of prose must fit inside a bounded column.

Wrapping is greedy and whitespace-based. The input is split into words on runs of whitespace, and words are packed onto the current line one at a time until adding the next word (plus the single space that would join it) would push the line past Width; at that point the current line is emitted and the word starts a new line. Width is measured in runes and counts only the text, excluding the per-line Indent, so multibyte and accented characters count as one column each and the indent does not eat into the usable width.

Line structure is controlled by three fields. Indent is prefixed to every output line, which makes it easy to produce block-quoted or nested text. Newline is the separator placed between lines, defaulting to "\n". Existing newlines in the input are treated as hard paragraph breaks: the text is split on "\n" first and each paragraph is wrapped independently, so intentional line breaks in the source survive while over-long lines within a paragraph are reflowed. A blank paragraph is preserved as an indented empty line.

Long words are handled by the Cut option. Normally a single word longer than Width is left intact and simply overflows its line, because breaking a word changes its meaning; when Cut is true such words are instead chopped into Width-sized pieces so the hard width limit is never exceeded. The TrimTrailing option removes trailing spaces and tabs from every emitted line, which is handy when the wrapped text is compared byte-for-byte or embedded where trailing whitespace is undesirable.

Configuration is via the Options struct, and the zero value is usable: a Width of zero or less is treated as DefaultWidth (50) and an empty Newline as DefaultNewline ("\n"). Note the one subtlety with defaults — a zero-value Options has an empty Indent, whereas the npm library defaults to a two-space indent, so NewOptions is provided to build an Options carrying all three package defaults (Width 50, Indent two spaces, Newline "\n"). Parity with the Node original covers the greedy whitespace wrapping, indent, newline, trailing trim, and cut behavior; callers wanting the JavaScript defaults exactly should start from NewOptions rather than a bare struct literal.

Index

• Constants
• func Wrap(text string, opts Options) string
• type Options
  • func NewOptions() Options

Examples

• Wrap
• Wrap (Cut)

Constants

const (
	// DefaultWidth is the default maximum line width in characters.
	DefaultWidth = 50
	// DefaultIndent is the default per-line indent prefix.
	DefaultIndent = "  "
	// DefaultNewline is the default line separator used in output.
	DefaultNewline = "\n"
)

Default option values, matching the npm word-wrap defaults.

Functions

func Wrap

func Wrap(text string, opts Options) string

Wrap wraps text according to opts and returns the wrapped result.

Example

ExampleWrap reflows a sentence so that no line exceeds the chosen width. With a Width of 20 and no indent, words are packed greedily onto each line until the next word would push it past the limit, at which point a new line begins. Width is measured in runes and counts only the text, excluding any indent. Existing newlines would be treated as hard paragraph breaks, but this input has none. The result is three wrapped lines joined by the default "\n".

package main

import (
	"fmt"

	"github.com/malcolmston/express/wordwrap"
)

func main() {
	text := "The quick brown fox jumps over the lazy dog"
	fmt.Println(wordwrap.Wrap(text, wordwrap.Options{Width: 20}))
}

Output:
The quick brown fox
jumps over the lazy
dog

Example (Cut)

ExampleWrap_cut demonstrates the Cut option, which breaks words that are longer than the width instead of letting them overflow. Here the eight-letter run is chopped into four-character pieces before wrapping, so the hard width limit is never exceeded. Without Cut such a word would be emitted whole on its own line. The shorter trailing word then wraps normally. This is useful when a strict column limit must be honored even for unbroken tokens.

package main

import (
	"fmt"

	"github.com/malcolmston/express/wordwrap"
)

func main() {
	fmt.Println(wordwrap.Wrap("aaaaaaaa bb", wordwrap.Options{Width: 4, Cut: true}))
}

Output:
aaaa
aaaa
bb

Types

type Options

type Options struct {
	// Width is the maximum line length excluding the indent. Values <= 0 are
	// treated as DefaultWidth (50).
	Width int
	// Indent is prefixed to every output line. The zero value is no indent.
	Indent string
	// Newline is the separator placed between output lines. An empty value is
	// treated as DefaultNewline ("\n").
	Newline string
	// TrimTrailing removes trailing spaces and tabs from every output line when
	// true.
	TrimTrailing bool
	// Cut breaks words longer than Width into Width-sized pieces when true.
	Cut bool
}

Options configures Wrap.

A zero-value Options is usable: Width <= 0 is treated as DefaultWidth and an empty Newline is treated as DefaultNewline. Note that a zero-value Indent is the empty string (no indentation); to obtain the two-space default indent, build options with NewOptions rather than a bare Options literal.

func NewOptions

func NewOptions() Options

NewOptions returns an Options populated with the package defaults: Width 50, Indent two spaces, and Newline "\n".