Blackbird for C++ overview
==========================

The Blackbird C++ library provides a Blackbird parser class for parsing Blackbird code, as
well as a utility function for automating this procedure given a Blackbird filename.


Main components
---------------

* :cpp:class:`Visitor`: the Blackbird visitor,
  which parses the abstract syntax tree using ANTLR4, evaluating expressions,
  extracting variables, and storing quantum program information.

  While derived classes can be defined in order to modify the actions
  performed while parsing the tree, in general this is not needed. In most cases,
  it is sufficient to simply iterate through the returned information contained
  in the :cpp:class:`Program` class.

* :cpp:func:`parse_blackbird`: a utility function that automates
  the parsing of the Blackbird abstract syntax tree. Use this function
  to parse arbitrary Blackbird code, and return the :cpp:class:`Program` class.


Source code overview
--------------------

The Blackbird C++ library source code, contained in the folder ``blackbird_cpp``, contains the
following files:

* ``Blackbird.h``: the public Blackbird library header. Contains the :cpp:class:`Visitor`
  declarations, as well as the utility function :cpp:func:`parse_blackbird`, which automates
  the process of parsing a Blackbird script given a file stream, and return the Blackbird program.

* ``Visitor.cpp``: contains the source code for the :cpp:class:`Visitor`. The :cpp:class:`Visitor`
  is a derived class of :cpp:class:`blackbirdBaseVisitor`, and provides ANTLR4 with actions to perform
  (e.g., evaluating expressions, storing variables, queuing quantum operations) as the abstract syntax
  tree is traversed.

  If a new quantum operation or quantum device needs to be added, its initialization will need to be
  defined here in the corresponding node of the AST.

* ``BlackbirdProgram.h``: contains the declarations for :cpp:class:`Program`, :cpp:class:`Operation`,
  and all derived classes.

  * Known devices and gates are recorded in the ``enum``'s :cpp:enum:`blackbird::Device` and
    :cpp:enum:`blackbird::Gate`. These have the same value as their Blackbird command name.

  * Each gate and measurement class is declared, including constructors, number of modes,
    number of parameters, and input/mode validation.

  * Each device class is declared, including constructors, the member function :cpp:member:`print_device_info`,
    and any required member variables, for instance :math:`\hbar` or cutoff dimension, if applicable.

  If a new quantum operation or quantum device needs to be added, its class declaration will need to be
  made here.

* ``BlackbirdVariables.h``: contains templates for setting and getting assigned Blackbird variables
  from a ``std::unordered_map``, with their name (``std::string``) as the key. Also includes some
  basic automatic casting operations, and casting exceptions.

* Autogenerated ANTLR4 headers and source.

  - ``blackbirdBaseVisitor.cpp``
  - ``blackbirdBaseVisitor.h``
  - ``blackbirdLexer.cpp``
  - ``blackbirdLexer.h``
  - ``blackbirdParser.cpp``
  - ``blackbirdParser.h``

  .. warning::

  	These are generated automatically by compiling the
 	ANTLR4 grammar ``src/blackbird.g4`` (see :ref:`compiling_grammar`), and **should not be
  	modified in any case**. If they are modified, your changes will be overwritten once the grammar
  	is re-compiled!