Notebook Catenation
===================

``cat`` catenates the cells of multiple notebooks into a single notebook.
The resulting notebook takes its notebook-level properties from the first notebook.

This tool can be used to prepend and append cells to a notebook
(also see the ``append-cell`` option of the ``run`` tool).
Prepended cells can provide (re)definitions,
and appended cells can show further output.


Educational Use
---------------

In an educational setting,
it can be useful to redefine the built-in function ``input()``
to either be blocked:

.. code-block:: python

    def input(*args, **kwargs):
        import sys
        print('input() is forbidden in notebooks', file=sys.stderr)
        sys.exit(1)

Or to deliver strings read from a file:

.. code-block:: python

    def __yield_from_file(file_name):
        with open(file_name) as f:
            yield from f.readlines()

    def input(prompt=None, __gen=__yield_from_file('input.txt')):
        if prompt:
            print(prompt, end='')
        line = next(__gen)
        # suppress terminating end-of-line
        if line and line[-1] == '\n':
            return line[:-1]
        return line

By putting this code in a notebook, it can be prepended to every student notebook,
via ``cat``.


Result File Name
----------------

The result of catenating notebooks ``nb.ipynb ...`` is written to ``nb-cat.ipynb``
(that is, the name of the first notebook argument is used),
unless the option ``--inplace`` is applied,
in which case the result is written to ``nb.ipynb``.

The result name addition can be adjusted in the configuration file
by setting ``cat_result_name``;
see :doc:`configuration`.


Options
-------

``cat`` does not have any tool-specific options.


JSON Output
-----------

See :ref:`output-json` for general information about JSON output.

``cat`` produces the following members in the JSON output:

  +------------------+-------------------------------------------------------+
  | Name             | Value                                                 |
  +==================+=======================================================+
  | ``"cell_types"`` | object with counts per cell type (see :doc:`nbstats`) |
  +------------------+-------------------------------------------------------+

Note that members are absent when count is zero.