README
¶
Stringwrap is a Go package for wrapping strings by visual width with optional word splitting and full ANSI + grapheme cluster support. Designed for precision line-wrapping, ideal for terminal output, formatted logs, or editors that require accurate metadata per line segment.
✨ Features
This library offers robust string wrapping capabilities with a focus on accurate visual representation and detailed metadata:
- Intelligent Wrapping: Adapts to the viewable width by leveraging the
runewidthlibrary for precise character width calculation. - Comprehensive Text Handling:
- Ignores ANSI escape codes for width calculations while preserving them in the output.
- Correctly processes Unicode grapheme clusters, ensuring accurate wrapping of emojis and accented characters.
- Supports configurable tab sizes.
- Respects hard breaks (
\n) in the input string. - Provides optional word splitting for finer-grained control.
- Handles non-breaking spaces (
\u00A0) to prevent unwanted line breaks.
- Detailed Line Metadata: For each wrapped line, the library provides valuable information:
- Byte and rune offsets within the original string.
- The visual width of the wrapped line.
- The index of the segment from the original line that this wrapped line belongs to.
- An indication of whether the line ended due to a hard break or soft wrapping.
- A flag indicating if the segment ends with a word that was split during wrapping.
🚀 Getting Started
go get github.com/galactixx/stringwrap@latest
📚 Usage
Regular String Wrapping
import "github.com/galactixx/stringwrap"
wrapped, meta, err := stringwrap.StringWrap("Hello world! 🌟", 10, 4)
fmt.Println(wrapped)
Output:
Hello
world!
🌟
String Wrapping with Word Splitting
wrapped, meta, err := stringwrap.StringWrapSplit("Supercalifragilisticexpialidocious", 10, 4)
fmt.Println(wrapped)
Output:
Super-
calif-
ragili-
sticex-
pialid-
ocious
Accessing the Metadata
for _, line := range meta.WrappedLines {
fmt.Printf(
"Line %d: width=%d, byteOffset=%v\n",
line.CurLineNum,
line.Width,
line.OrigByteOffset
)
}
🔍 API
func StringWrap(str string, limit int, tabSize int) (string, *WrappedStringSeq, error)
Wraps a string at a visual width limit. Words are not split.
func StringWrapSplit(str string, limit int, tabSize int) (string, *WrappedStringSeq, error)
Same as StringWrap, but allows splitting words across lines if needed.
type WrappedString struct
Metadata for one wrapped segment.
type WrappedString struct {
CurLineNum int
OrigLineNum int
OrigByteOffset LineOffset
OrigRuneOffset LineOffset
SegmentInOrig int
NotWithinLimit bool
IsHardBreak bool
Width int
EndsWithSplitWord bool
}
type WrappedStringSeq struct
Contains all wrapped lines and wrap configuration.
type WrappedStringSeq struct {
WrappedLines []WrappedString
WordSplitAllowed bool
TabSize int
Limit int
}
🤝 License
This project is licensed under the MIT License. See the LICENSE file for more details.
📞 Contact
If you have any questions or need support, feel free to reach out by opening an issue on the GitHub repository.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LineOffset ¶
LineOffset represents a half-open interval [Start, End) that describes either the byte offset or rune offset range of a wrapped segment in the original unwrapped string.
type WrappedString ¶
type WrappedString struct {
// The current wrapped line number (after wrapping).
CurLineNum int
// The original unwrapped line number this segment came
// from.
OrigLineNum int
// The byte start and end offsets of this segment in the
// original unwrapped string.
OrigByteOffset LineOffset
// The rune start and end offsets of this segment in the
// original unwrapped string.
OrigRuneOffset LineOffset
// Which segment number this is within the original line
// (first, second, etc.).
SegmentInOrig int
// Whether the segment fits entirely within the wrapping
// limit.
NotWithinLimit bool
// Whether the wrap was due to a hard break (newline)
// instead of word wrapping.
IsHardBreak bool
// The viewable width of the wrapped string.
Width int
// Whether this wrapped segment ends with a split word due
// to reaching the wrapping limit
// (e.g., a hyphen may be added).
EndsWithSplitWord bool
}
type WrappedStringSeq ¶
type WrappedStringSeq struct {
// WrappedLines is the list of individual wrapped segments with
// metadata.
WrappedLines []WrappedString
// WordSplitAllowed indicates whether splitting words across
// lines is permitted.
WordSplitAllowed bool
// TabSize defines how many spaces a tab character expands to.
TabSize int
// Limit is the maximum viewable width allowed per line.
Limit int
}
WrappedStringSeq holds the sequence of wrapped lines produced by the string wrapping process, along with the configuration used.
func StringWrap ¶
StringWrap wraps the input string to the specified viewable width limit, expanding tabs using the given tab size. It preserves word boundaries and does not split words across lines.
ANSI escape sequences are preserved without contributing to visual width. returns the wrapped string and a metadata sequence describing each wrapped line.
func StringWrapSplit ¶
StringWrapSplit wraps the input string to the specified viewable width limit, expanding tabs using the given tab size. Unlike StringWrap, this function allows words to be split across lines if they exceed the wrapping limit.
ANSI escape sequences are preserved without contributing to visual width. returns the wrapped string and a metadata sequence describing each wrapped line.
Source Files