README.en.md

TextWrap

English

Report Bug · Request Feature

Table of Contents

1. Introduction
2. Features
3. Installation
4. Usage
5. Contribution
6. License
7. Acknowledge
8. Donate
9. Changelog

Introduction

TextWrap is a JavaScript implementation of the textwrap module available in Python, which provides several functions to wrap and format paragraphs of text with a delimited line length. This module is useful for formatting text to make it easier to read or for display needs.

Features

TextWrap offers the following features:

• Wrap Text: Wraps text into multiple lines (with array type) according to the given width.
• Fill Text: Wraps text like wrap, but returns the wrapped text as a single string, with lines separated by the newline character (\n).
• Shorten Text: Wraps the text into a single line with the given maximum width, replacing the end of the text with a placeholder if the text is too long.
• Dedent Text: Removes the common indent from each line in the given text.
• Indent Text: Adds a prefix string (indent) at the beginning of each line of the given text. The predicate option can be used to control which lines will be given the prefix.

Installation

To install TextWrap locally, follow these installation steps:

npm install @barudakrosul/textwrap

Usage

To start using TextWrap, import the module first:

1. CommonJS

const textwrap = require("@barudakrosul/textwrap");

2. ESM (ECMAScript Modules)

import textwrap from "@barudakrosul/textwrap";

Example of usage:

Wrap Text

console.log(textwrap.wrap("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", 11))

// Result:
//   [
//     'Lorem ipsum', 'dolor sit',
//     'amet,',       'consectetur',
//     'adipisicing', 'elit, sed',
//     'do eiusmod',  'tempor',
//     'incididunt',  'ut labore',
//     'et dolore',   'magna',
//     'aliqua.'
//   ]

Fill Text

console.log(textwrap.fill("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", 11))

// Result:
//   Lorem ipsum
//   dolor sit
//   amet,
//   consectetur
//   adipisicing
//   elit, sed
//   do eiusmod
//   tempor
//   incididunt
//   ut labore
//   et dolore
//   magna
//   aliqua.

Shorten Text

console.log(textwrap.shorten("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", 59))

// Result:
//   Lorem ipsum dolor sit amet, consectetur adipisicing [...]

Dedent Text

console.log(textwrap.dedent("Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\nsed do eiusmod tempor incididunt ut labore et dolore magna aliqua."))

// Result:
//   Lorem ipsum dolor sit amet,
//   consectetur adipisicing elit,
//   sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Indent Text

console.log(textwrap.indent("Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\nsed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "> "))

// Result:
//   > Lorem ipsum dolor sit amet,
//   > consectetur adipisicing elit,
//   > sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The example adds a prefix to every newline, including empty ones:

console.log(textwrap.indent("Lorem ipsum dolor sit amet,\n\n\nconsectetur adipisicing elit,\nsed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "> ", lines => true))

// Result:
//   > Lorem ipsum dolor sit amet,
//   >
//   >
//   > consectetur adipisicing elit,
//   > sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The example adds a prefix to each line that starts with a specific string:

console.log(textwrap.indent("Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\nsed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "> ", lines => lines.startsWith("Lorem")))

// Result:
//   > Lorem ipsum dolor sit amet,
//   consectetur adipisicing elit,
//   sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The example adds a prefix to each line that contains a specific string:

console.log(textwrap.indent("Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\nsed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "> ", lines => lines.includes(",")))

// Result:
//   > Lorem ipsum dolor sit amet,
//   consectetur adipisicing elit,
//   sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The example adds a prefix to each line that has a certain length limit:

console.log(textwrap.indent("Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\nsed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "> ", lines => lines.length > 28))

// Result:
//   Lorem ipsum dolor sit amet,
//   > consectetur adipisicing elit,
//   > sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

For the functions wrap(), fill(), and shorten() have additional options. The supported options include:

Name	Description	Type	Default value
width	Maximum width of wrapped lines (unless break_long_words is false)).	number	70
initial_indent	The indent string for the first line.	string	""
subsequent_indent	The indentation string for the next lines.	string	""
expand_tabs	If true, tabs will be replaced with spaces.	boolean	true
replace_whitespace	If true, the whitespace character will be replaced with a space.	boolean	true
fix_sentence_endings	If true, two spaces will be added after the period at the end of the sentence.	boolean	false
break_long_words	If true, words longer than the line width will be split.	boolean	true
drop_whitespace	If true, whitespace at the beginning and end of the line will be removed.	boolean	true
break_on_hyphens	If true, the text will be broken at the hyphen.	boolean	true
tabsize	Tab size in characters.	number	8
max_lines	Maximum number of rows.	number | null	null
placeholder	A string used to replace the end of the text if it is too long.	string	[...]

A basic example of using the option:

const text = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
const width = 20;
const options = {
  fix_sentence_endings: true,
  break_long_words: false
};

console.log(textwrap.wrap(text, width, options));

Contribution

Contributions to TextWrap are greatly appreciated! Whether reporting bugs, suggesting new features, or contributing to code improvements.

License

TextWrap is licensed under the MIT License - see the LICENSE file for details.

Acknowledge

TextWrap appreciates the support and contributions of the following individuals and open source projects:

• @FajarKim - Lead developer and creator of the application.
• TextWrap Python module - The original source for developing TextWrap JavaScript.
• Open source community - For valuable contributions to the tools and libraries used in this project.

Donate

We really appreciate your support to continue developing this project. If you find this project useful, you can support us with a donation:

Every donation, no matter the amount, means a lot to us. Thank you for your support! ❤️

Changelog

Keep up with the latest changes and updates of TextWrap by referring to Changelog.

Thank you for choosing TextWrap! We aim to provide an easy solution for formatting text or paragraphs in multiple environments.