---
name: text-formatter
group: api
category: formatter
update-time: 20260512
description: Create a configurable text formatter for console, callback, and file-oriented text logging output.
key-word:
    - formatter
    - text
    - color
    - public
---

## Text-formatter

Create a `TextFormatter` that controls timestamp, level, target, field rendering, template substitution, color behavior, and style markup behavior. This is the main API for readable text output in `BitLogger`.

### Interface

```moonbit
pub fn text_formatter(
  show_timestamp~ : Bool = true,
  show_level~ : Bool = true,
  show_target~ : Bool = true,
  show_fields~ : Bool = true,
  separator~ : String = " ",
  field_separator~ : String = " ",
  template~ : String = "",
  color_mode~ : ColorMode = ColorMode::Never,
  color_support~ : ColorSupport = ColorSupport::TrueColor,
  style_markup~ : StyleMarkupMode = StyleMarkupMode::Full,
  target_style_markup~ : StyleMarkupMode = StyleMarkupMode::Disabled,
  fields_style_markup~ : StyleMarkupMode = StyleMarkupMode::Disabled,
  style_tags~ : StyleTagRegistry? = None,
) -> TextFormatter {}
```

#### input

- `show_timestamp : Bool` - Whether timestamp text is rendered when the record carries a timestamp.
- `show_level : Bool` - Whether the level label is rendered.
- `show_target : Bool` - Whether the target is rendered.
- `show_fields : Bool` - Whether structured fields are rendered.
- `separator : String` - Separator between major rendered parts.
- `field_separator : String` - Separator used between field values in text output.
- `template : String` - Optional template using tokens such as `{level}`, `{target}`, `{message}`, `{timestamp}`, `{timestamp_ms}`, and `{fields}`.
- `color_mode : ColorMode` - `Never`, `Auto`, or `Always`.
- `color_support : ColorSupport` - `Basic` or `TrueColor`.
- `style_markup : StyleMarkupMode` - Controls whether message style tags are parsed.
- `target_style_markup : StyleMarkupMode` - Controls whether target style tags are parsed.
- `fields_style_markup : StyleMarkupMode` - Controls whether field-value style tags are parsed.
- `style_tags : StyleTagRegistry?` - Optional local tag registry.

#### output

- `TextFormatter` - A reusable text formatter instance for text sinks or direct formatting.

### Explanation

Detailed rules explaining key parameters and behaviors

- If `template` is empty, the formatter uses built-in part assembly.
- `color_mode=Auto` currently follows a conservative rule based on `NO_COLOR`.
- `style_markup`, `target_style_markup`, and `fields_style_markup` are independent scopes.
- Local `style_tags` override global tag registry lookup, which overrides builtin tags.

### How to Use

Here are some specific examples provided.

#### When Need Human-readable Console Output

When logs should stay readable in terminals:
```moonbit
let formatter = text_formatter(
  show_timestamp=false,
  template="[{level}] {target} {message} :: {fields}",
)
let logger = Logger::new(text_console_sink(formatter), target="demo")
```

In this example, the formatter produces predictable text output without timestamps.

And the same formatter can be reused by multiple sinks.

#### When Need Styled ANSI Output

When you want visible severity or semantic tags in terminal output:
```moonbit
let formatter = text_formatter(color_mode=ColorMode::Always)
  .with_style_tags(default_style_tag_registry().set_tag("accent", fg=Some("#4cc9f0"), bold=true))
```

In this example, message text can use inline tags such as `<accent>...</>`.

### Error Case

e.g.:
- If `template` contains unknown text, the formatter keeps it as plain text.

- If a style tag is unknown or invalid, current behavior falls back to plain text rather than raising an error.

### Notes

Notes are here.

1. Prefer `text_formatter(...)` when you want explicit control over readable text output.

2. `TextFormatter` is reusable and should usually be constructed once, then shared.

3. `fields_style_markup` currently affects field values only, not field keys.

4. Use `TextFormatterConfig` when the formatter must be driven by JSON config rather than code.