Text Wrap

Text Processing Formatting

Synopsis

Wraps text to specified widths by inserting line breaks.

Schema

- text_wrap:
    field: <ident>
    width: <integer>
    target_field: <ident>
    indent: <string>
    line_separator: <string>
    break_long_words: <boolean>
    preserve_lines: <boolean>
    trim_whitespace: <boolean>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing text to wrap
width	Y	-	Maximum line width in characters
target_field	N	Same as field	Target field to store wrapped text
indent	N	-	String to indent each line (e.g., " " for spaces)
line_separator	N	\n	Line separator character
break_long_words	N	false	Break words longer than width
preserve_lines	N	false	Preserve existing line breaks
trim_whitespace	N	false	Trim whitespace from lines
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if wrapping fails
ignore_missing	N	false	Skip processing if referenced field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Details

Formats text by inserting line breaks at specified intervals to ensure lines don't exceed the maximum width. The processor can break at word boundaries for readability or at exact character positions for fixed-width requirements.

The processor supports various formatting options including custom indentation, line break characters, and word-boundary preservation.

note

When break_long_words is disabled (default), words longer than the specified width will not be broken. When enabled, long words will be split to fit within the width limit.

Width is counted in bytes, not characters. A line of accented or non-Latin text therefore wraps earlier than its character count suggests, and break_long_words can split a multi-byte character in half. Use it on ASCII text.

indent is applied after wrapping, so an indented line is longer than width by the length of the indent — subtract it from width yourself if the total matters.

With preserve_lines off (the default) all existing whitespace, newlines included, is collapsed to single spaces before wrapping. Turn it on to wrap each existing line independently and keep the blank ones.

warning

Very long words that exceed the specified width will remain unbroken unless break_long_words is enabled.

Examples

Basic Text Wrapping

Wrapping long text to 40-character lines...	{ "description": "This is a very long description that needs to be formatted for better readability in documentation or display purposes." } - text_wrap: field: description width: 40 target_field: formatted_text
creates formatted multi-line text:	{ "description": "This is a very long description...", "formatted_text": "This is a very long description that\nneeds to be formatted for better\nreadability in documentation or display\npurposes." }

Code Comment Formatting

Formatting code comments with indentation...	{ "comment": "This function processes user authentication requests and validates credentials against the database before returning access tokens." } - text_wrap: field: comment width: 50 indent: "// " target_field: code_comment
creates indented code comments:	{ "comment": "This function processes user authentication...", "code_comment": "// This function processes user authentication\n// requests and validates credentials against the\n// database before returning access tokens." }

Fixed-width Formatting

Splitting a word that is longer than the width...	{ "log_message": "SystemStartupInitializationCompleted" } - text_wrap: field: log_message width: 15 break_long_words: true target_field: wrapped_log
breaks at exact character positions:	{ "log_message": "SystemStartupInitializationCompleted", "wrapped_log": "SystemStartupIn\nitializationCom\npleted" }

Custom Line Breaks

Using custom line break characters...	{ "tags": "authentication authorization logging monitoring security audit compliance" } - text_wrap: field: tags width: 20 line_separator: " | " target_field: tag_list
uses custom separator:	{ "tags": "authentication authorization logging monitoring security audit compliance", "tag_list": "authentication | authorization | logging monitoring | security audit | compliance" }

Email Formatting

Formatting email content with line length limits...	{ "email_body": "Dear customer, we are writing to inform you about important changes to our service terms and conditions that will take effect next month." } - text_wrap: field: email_body width: 72 target_field: formatted_email
formats for email standards:	{ "email_body": "Dear customer, we are writing to inform you about important...", "formatted_email": "Dear customer, we are writing to inform you about important changes to\nour service terms and conditions that will take effect next month." }