FormatBlock 0.4.1
Format blocks of characters for display, split by words, characters, or newlines.

Keywords: python module library 3 format block characters chars text

FmtBlock
========

Formats text into "blocks" that do not exceed the maximum length for
each line. This can be used as a command-line tool or imported for the
``FormatBlock`` class. There are various features like prepending,
appending, expanding space between words, splitting on characters or
spaces, and preserving newlines.

--------------

Command-line help:
------------------

::

    Usage:
        fmtblock -h | -v
        fmtblock [WORDS...] [-D] [-w num]
                 [-c | -f] [-e] ([-i num] | [-I num]) [-l] [-n]
                 ([-s] [-p txt | -P txt]) ([-S] [-a txt | -A txt])

    Options:
        WORDS                 : Words to format into a block.
                                File names can be passed to read from a file.
                                If not given, stdin is used instead.
        -a txt,--append txt   : Append this text before each line, after any
                                indents.
        -A txt,--APPEND txt   : Same as --append, except the appended text
                                is not included when calculating the width.
        -c,--chars            : Wrap on characters instead of spaces.
        -D,--debug            : Show some debugging info.
        -e,--enumerate        : Print line numbers before each line.
        -f,--fill             : Insert spaces between words so that each line
                                is the same width.
        -h,--help             : Show this help message.
        -i num,--indent num   : Indention level, where 4 spaces is 1 indent.
                                Maximum width includes any indention.
                                Default: 0
        -I num,--INDENT num   : Same as --indent, except the indention is not
                                included when calculating the width.
                                Default: 0
        -l,--lstrip           : Remove leading spaces for each line, before
                                indention.
        -n,--newlines         : Preserve newlines.
        -p txt,--prepend txt  : Prepend this text before each line, after any
                                indents.
        -P txt,--PREPEND txt  : Same as --prepend, except the prepended text
                                is not included when calculating the width.
        -s,--stripfirst       : Strip first --prepend.
        -S,--striplast        : Strip last --append.
        -v,--version          : Show version.
        -w num,--width num    : Maximum width for the block.
                                Default: 79

--------------

Dependencies:
-------------

-  **Python 3.3+** - This project uses ``yield from``. Porting to older
   python versions would be trivial, but I don't plan on doing it (just
   use ``for-loops`` and ``yield`` instead of ``yield from``).

Python Dependencies:
--------------------

These are installable with ``pip``.

-  **Colr** - Used for colorized output.
-  **Docopt** - Used to handle command-line argument parsing.

--------------

Installation:
-------------

Install the module with pip:

::

    # You may have to use pip3 here.
    pip install formatblock

Then you can run it like this:

::

    fmtblock --help

Or like this:

::

    python3 -m fmtblock --help

Imports
-------

All of the functionality for ``fmtblock`` is contained in a class called
``FormatBlock``, which is importable for use in your project.

.. code:: python

    from fmtblock import FormatBlock

    print(FormatBlock('This is a test okay.').format(width=5))

Output:

::

    This
    is a
    test
    okay.

--------------

Examples:
---------

Input:
~~~~~~

These three methods for sending input to ``fmtblock`` are the same:

.. code:: bash

    echo "Test String" | fmtblock -w 5
    fmtblock "Test String" -w 5
    fmtblock Test String -w 5

Space splitting:
~~~~~~~~~~~~~~~~

.. code:: bash

    fmtblock -w 30 "This is a fairly long string, though I've seen bigger."

Output:

::

    This is a fairly long string,
    though I've seen bigger.

Character splitting:
~~~~~~~~~~~~~~~~~~~~

.. code:: bash

    fmtblock -c -w 10 "This is a fairly long string, though I've seen bigger."

Output:

::

    This is a
    fairly lon
    g string,
    though I'v
    e seen big
    ger.

Newlines:
~~~~~~~~~

.. code:: bash

    echo "This is a string
    that contains newlines
    and they will be preserved." | fmtblock -w 20 -n

Output:

::

    This is a string
    that contains
    newlines
    and they will be
    preserved.

Enumeration:
~~~~~~~~~~~~

.. code:: bash

    echo {a..c} | fmtblock -e -w 1

Output:

::

    1: a
    2: b
    3: c

Indents:
~~~~~~~~

.. code:: bash

    # Preserving newlines with -n, instead of using -w.
    seq 1 3 | fmtblock -i 1 -n

Output:

::

        1
        2
        3

Prepended Text:
~~~~~~~~~~~~~~~

.. code:: bash

    # Preserving newlines with -n, instead of using -w.
    seq 1 3 | fmtblock -n -p "Test "

Output:

::

    Test 1
    Test 2
    Test 3

Also see ``-P``, to prepend text without it affecting width
calculations.

Appended Text:
~~~~~~~~~~~~~~

.. code:: bash

    seq 1 3 | fmtblock -n -a ") Test"

Output:

::

    1) Test
    2) Test
    3) Test

Also see ``-A``, to append text without it affecting width calculations.

Strip first/last:
~~~~~~~~~~~~~~~~~

When using ``-p`` or ``-P``, you can skip the first line with ``-s``.

When using ``-a`` or ``-A``, you can also skip the last line with
``-S``.

.. code:: bash

    seq 200000 200010 | fmtblock -w 30 -p "    " -s -a " \\" -S

Output:

::

    200000 200001 200002 \
        200003 200004 200005 \
        200006 200007 200008 \
        200009 200010

Fill:
~~~~~

.. code:: bash

    echo "this is a test of the word fill feature for fmtblock" | fmtblock -w 20 -f

Output:

::

    this  is  a  test of
    the     word    fill
    feature for fmtblock