Usage guide
===========

Concepts
--------

A TERSE file is a container holding a small header (describing the source
data set's record format and length) and a 12-bit-code compressed payload
produced by one of two dictionary codecs:

===========  =========  ============================================
Method       Algorithm  Notes
===========  =========  ============================================
``SPACK``    LZMW       Default; better compression. Header ``0x05``.
``PACK``     LZW        Slightly faster, larger output. Header ``0x02``.
===========  =========  ============================================

Host files always store **EBCDIC** internally.  Whether output is
rendered as *text* (EBCDIC translated to ASCII, records as LF-terminated
lines) or *binary* (the exact stored bytes) is chosen at decompression
time — it is not recorded in the file.

Compressing
-----------

.. code-block:: console

   $ terse report.txt                # text mode: lines -> EBCDIC VB records
   $ terse -b image.png              # binary mode: lossless FB LRECL-1
   $ terse -m pack --recfm f -l 80 src.txt
   $ terse --native payload.bin      # native SPACK container (4-byte header)
   $ terse -c cp1047 unix.txt        # translate with a specific code page

Text mode splits the input into lines (CRLF is normalised to LF),
translates ASCII to EBCDIC and stores one logical record per line —
exactly what FTP in text mode would have uploaded to a data set.  Binary
mode stores the bytes untouched.

Decompressing
-------------

.. code-block:: console

   $ unterse DATA.TRS                # auto-detect text/binary content
   $ unterse -b DATA.TRS             # exact bytes; VB records get RDWs
   $ unterse -b --no-rdw DATA.TRS    # exact bytes, RDWs stripped
   $ unterse -t -c cp037 DATA.TRS    # force text via code page cp037
   $ unterse -i DATA.TRS             # header info only

In auto mode the decompressor decodes the payload, checks whether the
record contents look like EBCDIC text, and renders text if so.  Binary
output written without an explicit output name gets a file extension
chosen by content sniffing (libmagic), e.g. ``KENNEDY.TRS`` →
``KENNEDY.xls``.

Interoperability notes
----------------------

* Transfer ``.trs`` files to/from z/OS in **binary** mode.  Host TERSE
  files are always a multiple of 1024 bytes; ``RECFM=FB LRECL=1024``
  data sets suit them well.
* For byte-exact round trips use binary mode: EBCDIC↔ASCII translation
  is lossy for some byte values, and text mode normalises line endings.
* Variable-format binary output is RDW-framed, matching z/OS FTP with
  ``SITE RDW``; text output matches FTP with ``SITE TRAILINGBLANKS``.
* AMATERSE's own SPACK encoder writes an *empty* payload when the whole
  input fits in a single dictionary match (e.g. a one-byte file) — such
  files are unrecoverable everywhere, including on z/OS.  TerseLib
  encodes these correctly.

Logging
-------

The library is silent by default.  Enable diagnostics with:

.. code-block:: python

   import terselib
   terselib.enable_verbose_logging()   # or configure logger "terselib"

On the command line, pass ``-v`` (progress) or ``-vv`` (debug).