=======
rtprint
=======

-----------------------
display data from ports
-----------------------

.. include:: ../common/docinfo_block.txt

Synopsis
========

rtprint [options] <path1>:<port1> [<path2>:<port2>...]

Description
===========

Print the data being sent by one or more output ports to stdout.

By default, only the first value received from one or more ports is
printed.  Options are available to print multiple values or print
regularly for a specified length of time. In any one loop of the port
checks, if only one port out of multiple has data available, that is
counted as a print for the purposes of printing a fixed number of times.

To print data which cannot be natively printed by Python, create a
formatting function to print that data. The function must receive one
argument: the data to print. For example::

  def rawpy(data):
      return data.__repr__()

A connection will be made to each port using the default connection
settings compatible with that port.


Options
=======

-m MODULES, --mod=MODULES
  Extra modules to import. If automatic module loading struggles with
  the constant's data types, try listing the modules here. The module
  and its ``__POA`` partner will be imported.

-n MAX, --number=MAX
  Specify the number of times to read from any ports.

-p PATHS, --path=PATHS
  Extra module search paths to add to the ``PYTHONPATH``.

-r RATE, --rate=RATE
  Specify the rate in Hertz at which to read and print.

-t TIMEOUT, --timeout=TIMEOUT
  Read data for this many seconds, then stop.  This option overrides
  ``--number``.

.. include:: ../common/common_opts.txt

.. include:: ../common/common_body.txt

Examples
========

::

  $ rtprint /localhost/ConsoleIn0.rtc:out

Print the first value sent by the ``ConsoleIn0.rtc`` component over its
``out`` port.

::

  $ rtprint /localhost/ConsoleIn0.rtc:out -n 5

Print the first five values sent by the ``ConsoleIn0.rtc`` component
over its ``out`` port.

::

  $ rtprint /localhost/ConsoleIn0.rtc:out -t 5

Print the values sent by the ``ConsoleIn0.rtc`` component over its
``out`` port for five seconds.

::

  $ rtprint /localhost/ConsoleIn0.rtc:out -t 5 -r 10

Print the values sent by the ``ConsoleIn0.rtc`` component over its
``out`` port up to ten times a second for for five seconds.

::

  $ rtprint /localhost/ConsoleIn0.rtc:out#rawpy

Print the first value sent by the ``ConsoleIn0.rtc`` component over its
``out`` port as a Python expression using the inbuilt ``rawpy``
formatter.

::

  $ rtprint /localhost/ConsoleIn0.rtc:out#printers.my_formatter

Print the first value sent by the ``ConsoleIn0.rtc`` component over its
``out`` port using the ``my_formatter`` formatting function from the
``printers`` module to print the data.

See rtinject(1) for examples using ``--mod`` and ``--path``.

See Also
========

  ``rtcat`` (1),
  ``rtinject`` (1),
  ``rtlog`` (1)

