doc/man: make default values of boolean init. params. clearer

[babeltrace.git] / doc / man / babeltrace2-sink.text.pretty.7.txt

= babeltrace2-sink.text.pretty(7)
:manpagetype: component class
:revdate: 1 September 2023


== NAME

babeltrace2-sink.text.pretty - Babeltrace 2's pretty-printing sink
component class


== DESCRIPTION

A Babeltrace~2 compcls:sink.text.pretty component pretty-prints the
events, discarded events, and discarded packets messages it consumes to
the standard output or to a file.

----
            +------------------+
            | sink.text.pretty |
            |                  +--> Pretty-printed messages to
Messages -->@ in               |    the standard output or a file and
            +------------------+    to the standard error
----

include::common-see-babeltrace2-intro.txt[]

By default, a compcls:sink.text.pretty component pretty-prints to the
standard output. You can use the param:path parameter to make the
component write to a file instead.

The component prints warnings on the standard error stream when it
consumes a discarded events or discarded packets message.

If you don't use the param:path parameter and the application's standard
output is connected to a color-capable terminal, the component emits
terminal color codes to enhance the text output. You can use the
param:color parameter to force the color support or to disable it.

This component class is equivalent to the `text` output format of
man:babeltrace(1) (Babeltrace~1 command-line tool).


== INITIALIZATION PARAMETERS

param:clock-cycles='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then print event times in clock cycles instead of
    hours, minutes, seconds, and nanoseconds.
+
Default: false.

param:clock-date='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then print event times _and_ dates.
+
Default: false.

param:clock-gmt='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then print event times in the GMT time zone
    instead of the local time zone.
+
Default: false.

param:clock-seconds='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then print event times in seconds instead of
    hours, minutes, seconds, and nanoseconds.
+
Default: false.

param:color=(`never` | `auto` | `always`) vtype:[optional string]::
    Force the terminal color support, one of:
+
--
`auto` (default)::
    Only emit terminal color codes when the standard output and error
    streams are connected to a color-capable terminal.

`never`::
    Never emit terminal color codes.

`always`::
    Always emit terminal color codes.
--
+
The `BABELTRACE_TERM_COLOR` environment variable overrides this
parameter.

param:field-default=(`show` | `hide`) vtype:[optional string]::
    By default, show or hide all the fields. This sets the default value
    of all the parameters which start with `field-`.

param:field-emf='VAL' vtype:[optional boolean]::
    Show or hide the event's Eclipse Modeling Framework URI field.
+
Default, depending on the param:field-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    False
--

param:field-loglevel='VAL' vtype:[optional boolean]::
    Show or hide the event's logging level field.
+
Default, depending on the param:field-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    False
--

param:field-trace='VAL' vtype:[optional boolean]::
    Show or hide the trace name field.
+
Default, depending on the param:field-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    False
--

param:field-trace:domain='VAL' vtype:[optional boolean]::
    Show or hide the tracing domain field.
+
Default, depending on the param:field-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    False
--

param:field-trace:hostname='VAL' vtype:[optional boolean]::
    Show or hide the hostname field.
+
Default, depending on the param:field-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    True
--

param:field-trace:procname='VAL' vtype:[optional boolean]::
    Show or hide the process name field.
+
Default, depending on the param:field-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    True
--

param:field-trace:vpid='VAL' vtype:[optional boolean]::
    Show or hide the virtual process ID field.
+
Default, depending on the param:field-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    True
--

param:name-default=(`show` | `hide`) vtype:[optional string]::
    By default, show or hide all the names. This sets the
    default value of all the parameters which start with `name-`.

param:name-header='VAL' vtype:[optional boolean]::
    Show or hide the field names in the header scopes.
+
Default, depending on the param:name-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    False
--

param:name-context='VAL' vtype:[optional boolean]::
    Show or hide the field names in the context scopes.
+
Default, depending on the param:name-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    True
--

param:name-payload='VAL' vtype:[optional boolean]::
    Show or hide the field names in the event payload scopes.
+
Default, depending on the param:name-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    True
--

param:name-scope='VAL' vtype:[optional boolean]::
    Show or hide the scope names.
+
Default, depending on the param:name-default parameter:
+
--
`show`::
    True

`hide`::
    False

Not set::
    False
--

param:no-delta='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then do not print the time delta between
    consecutive lines.
+
Default: false.

param:path='PATH' vtype:[optional string]::
    Print the text output to the file 'PATH' instead of the standard
    output.

param:verbose='VAL' vtype:[optional boolean]::
    If 'VAL' if true, then turn the verbose mode on.
+
Default: false.


== PORTS

----
+------------------+
| sink.text.pretty |
|                  |
@ in               |
+------------------+
----


=== Input

`in`::
    Single input port.


== ENVIRONMENT VARIABLES

include::common-common-env.txt[]


include::common-footer.txt[]


== SEE ALSO

man:babeltrace2-intro(7),
man:babeltrace2-plugin-text(7)