.. _excel:

################
Excel generation
################

.. testsetup::

   >>> esl_path = (datadir / "esl" / "pump_example.esl")
   >>> excel_path = "./pump.xlsx"
   >>> drive_mechanism_excel = "./pump-drive-mechanism.xlsx"
   >>> import os
   >>> cwd = os.getcwd()
   >>> os.chdir(outdir)


RaESL enables you to convert an ESL specification into an Excel workbook.From a Python
script, you can call the conversion using the following snippet:

.. doctest::

   >>> import raesl.excel
   >>> raesl.excel.convert(esl_path, output=excel_path)  # e.g. "pump.esl" and "pump.xlsx"
   <openpyxl.workbook.workbook.Workbook object at 0x...>


Which results in :download:`this Excel </_static/generated/pump.xlsx>`. You can supply
any number of (positional) ESL file and directory paths just like you can with the ESL
compiler.


**********************************
Customizing the generated workbook
**********************************


There are several ways to further customize the Excel workbook. Lets review a fully
fledged example:

.. doctest::

   >>> import raesl.excel
   >>> raesl.excel.convert(
   ...     esl_path,                             # e.g. "pump.esl"
   ...     output=drive_mechanism_excel,         # e.g. "pump-drive-mechanism.xlsx"
   ...     scopes={"world.drive-mechanism": 1},
   ... )
   <openpyxl.workbook.workbook.Workbook object at 0x...>


which results in :download:`this </_static/generated/pump-drive-mechanism.xlsx>` Excel
file.


Providing scopes
================

Note that in this case, we *scoped* the output document to the ``drive-mechanism``
instead of the complete component tree. This means that in this case, only the
``drive-mechanism`` and components with a relative depth of 1 with respect to the
drive-mechanism are included in the generated output (e.g. its direct children).

You can supply any number of (overlapping) scopes and receive an Excel workbook for
those scopes specifically. Supplying a scope with :obj:`None` as the depth value results
in the inclusion of the complete sub-tree starting at that component instance.


.. testcleanup::

   >>> os.chdir(cwd)


**********************
Command-Line Interface
**********************

RaESL Excel generation is also available under the Command-Line Interface (CLI) as
``raesl excel``. Type ``raesl excel --help`` in your terminal to see the available
arguments and usage. Most notable change with respect to usage from a Python script is
that you have to supply a value of ``-1`` instead of :obj:`None` when specifying
output scopes.