feat: fields and message expansion feature

[pamburus]

Field and message expansion feature

This pull request introduces a new field expansion feature that provides better handling of multi-line content in log messages and field values. This is a simplified version of #320 without the heuristics-based expansion threshold levels.

Overview

The expansion feature gives you control over how hl formats log records containing multi-line content such as stack traces, formatted JSON, or messages with line breaks. Instead of always displaying everything on a single line or always breaking content across multiple lines, you can now choose the behavior that best suits your needs.

New -x / --expansion Option

The feature is controlled via the -x or --expansion command-line option (or HL_EXPANSION environment variable), which accepts four modes:

Expansion Modes

• never: All output is kept compact on a single line. Multi-line content is escaped using standard JSON escape sequences (\n, \t). Best for grep-friendly output or when you want maximum information density.

• inline: Multi-line content is preserved as-is, with actual line breaks in the output. Fields remain on the same conceptual line but may span multiple terminal lines. Useful when you want to see formatted content like JSON or stack traces in their natural form.

• auto (default): Intelligently expands fields and messages only when they contain multi-line content. Single-line logs stay compact, while multi-line content gets properly formatted with indentation. This provides the best of both worlds - compact output for simple logs and readable formatting for complex ones.

• always: Every field is expanded into multiple lines with clear indentation and visual structure. Provides maximum readability at the cost of vertical space.

Examples

Single-line log (all modes produce similar output)

2025-01-15 10:30:00.123 [INF] processing request › user=alice request-id=abc123

Multi-line message with auto mode (default)

2025-01-15 10:30:00.123 [ERR] request failed › user=alice request-id=abc123
                        [ ~ ]   > error=|=>
                        [ ~ ]         Connection timeout
                        [ ~ ]         Retry failed after 3 attempts
                        [ ~ ]         Server: api.example.com

Multi-line message with never mode

2025-01-15 10:30:00.123 [ERR] request failed › user=alice request-id=abc123 error="Connection timeout\nRetry failed after 3 attempts\nServer: api.example.com"

Multi-line message with always mode

2025-01-15 10:30:00.123 [INF] processing request
                        [ ~ ]   > user=alice
                        [ ~ ]   > request-id=abc123

Configuration

The default expansion mode can be configured in your configuration file:

[formatting.expansion]
mode = "auto"  # never, inline, auto, or always

Use Cases

• auto (recommended default): Best for general use, automatically adapting to content complexity
• never: When piping to grep, processing with text tools, or when horizontal space is limited
• inline: When you need to see formatted content (JSON, XML, stack traces) in their original form
• always: When maximum readability is needed, such as during debugging sessions or presentations

Breaking Changes

The default expansion mode has changed from inline to auto. This affects how multi-line content is displayed:

• Previous behavior (equivalent to inline mode): Multi-line content was always displayed with actual line breaks preserved in the output
• New default (auto mode): Multi-line content is now escaped and quoted by default, only expanding when it would improve readability

To preserve the exact previous behavior, set the expansion mode to inline:

• Command line: hl -x inline
• Environment: export HL_EXPANSION=inline
• Configuration file:

  [formatting.expansion]
  mode = "inline"

For most users, the new auto mode provides better output that adapts to content complexity while maintaining compatibility with text processing tools.

---

Closes #1170

[codecov]

Codecov Report

❌ Patch coverage is 99.15164% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.88%. Comparing base (76c296a) to head (bccb19b).
⚠️ Report is 7 commits behind head on master.

Files with missing lines	Patch %	Lines
src/datefmt.rs	66.66%	7 Missing ⚠️
src/formatting.rs	99.83%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1259      +/-   ##
==========================================
+ Coverage   87.19%   87.88%   +0.69%     
==========================================
  Files          66       67       +1     
  Lines       10873    11552     +679     
==========================================
+ Hits         9481    10153     +672     
- Misses       1392     1399       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.