.. _bag-cat:

=========
 bag-cat
=========

.. program:: bag-cat

Synopsis
========

:samp:`bag-cat {[OPTIONS]} {INPUT-FILE-OR--}`

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

Like UNIX :command:`cat`, the :program:`bag-cat` program makes a
stream of data available on its standard output stream. Unlike UNIX
:command:`cat`, the data is obtained by processing :term:`log files
<log file>`.

.. only:: html

   .. seealso::

      :ref:`rsb:common-options`
        The usual RSB-related commandline options are accepted.

      :ref:`rsb:idl-options`
        The usual IDL-related commandline options are accepted.

      :ref:`replay-related-options`
        The usual replay-related commandline options are accepted.

.. only:: man

   .. include:: common.rst
      :start-line: 7
      :end-line:   12

   .. include:: common.rst
      :start-line: 18

.. option:: --target-stream STREAM-NAME

   Stream to which produced output should be sent. Allowed values for
   :samp:`{STREAM-NAME}`: ``stdout``, ``standard-output``, ``stderr``,
   ``error-output``

Examples
========

* .. code-block:: sh

     $ bag-cat isr.tide | head
     <sr db_start="80" db_utt="80" />
     <sr db_start="45" db_utt="46" />
     <?xml version="1.0" encoding="UTF-8" standalone="no" ?><speech_hyp [...]
     <?xml version="1.0" encoding="UTF-8" standalone="no" ?><speech_hyp [...]
     <?xml version="1.0" encoding="UTF-8" standalone="no" ?><speech_hyp [...]
     <?xml version="1.0" encoding="UTF-8" standalone="no" ?><speech_hyp [...]
     <?xml version="1.0" encoding="UTF-8" standalone="no" ?><speech_hyp [...]
     <speech_hyp xmlns:bxml="http://www.sleepycat.com/2002/dbxml" [...]
     <TIMESTAMP>1290275288296</TIMESTAMP>

  The above examples demonstrates retrieving and printing the complete
  contents of the :term:`log file` :file:`isr.tide`. In this example,
  all :term:`payloads <payload>` are XML documents and therefore
  strings. All :term:`payload` strings are simply concatenated and
  printed. Note how this leads to individual :term:`events <event>`
  not being easily recognizable.
* .. code-block:: sh

     $ bag-cat -c 'hyp' -c 'param' /tmp/nao.tide

  The above example prints the contents of all :term:`channels
  <channel>` matching one of the regular expressions :regexp:`hyp` and
  :regexp:`param`.
* .. code-block:: sh

     $ bag-cat --style 'programmable/template :template "${create} ${data}\\n"' mydata.tide
     2011-12-13T17:03:25.533535+01:00 blup
     2011-12-13T17:03:25.534054+01:00 blup
     2011-12-13T17:03:25.534121+01:00 blup
     [...]

  This example uses the ``programmable/template`` formatting style to
  print each event of the :term:`log file` :file:`mydata.tide` on a
  single line. ``${create}`` expands to the ``create`` timestamp and
  ``${data}`` expands to the :term:`payload`. Note the final ``\\n``.

Caveats
=======

* Individual entries can no longer be distinguished (unless some
  in-band properties permit this) - see first example above.
* If multiple channels are printed, the channel from which a given
  part of the output originated is no longer apparent (unless some
  in-band properties allow determining this)
* Printing channels which contain binary content to a terminal may
  mess up the terminal and cause all sorts of mayhem