######################
cmake_test/add_section
######################

.. module:: cmake_test/add_section


.. function:: ct_add_section(**kwargs)

   Adds a test section, should be called inside of a
   declared test function directly before declaring the section function.
   
   A variable named :code:`CMAKETEST_SECTION` will be set in the
   calling scope that holds the section function ID. Use this variable
   to define the CMake function holding the section code. Ex:
   
   .. code-block:: cmake
   
      #This is inside of a declared test function
      ct_add_section(NAME this_section)
      function(${CMAKETEST_SECTION})
          message(STATUS "This code will run in a test section")
      endfunction()
   
   
   Additionally, the NAME parameter will be populated as by set() with the
   generated section function name. This is for backwards-compatibility
   purposes. Ex:
   
   .. code-block:: cmake
   
      #This is inside of a declared test function
      ct_add_section(NAME this_section)
      function(${this_section})
          message(STATUS "This code will run in a test section")
      endfunction()
   
   This behavior is considered deprecated, use the first form
   for new sections.
   
   Print length of pass/fail lines can be adjusted with the `PRINT_LENGTH` option.
   
   Priority for print length is as follows (first most important):
    1. Current execution unit's PRINT_LENGTH option
    2. Parent's PRINT_LENGTH option
    3. Length set by ct_set_print_length()
    4. Built-in default of 80.
   
   If a section raises an exception when it is not expected to,
   it will be marked as a failing section and its subsections
   will not be executed, due to limitations in how CMake handles failures.
   However, sibling sections as well as other tests
   will continue to execute, and the failures will be aggregated
   and printed after all tests have been ran.
   
   **Keyword Arguments**
   
   :keyword NAME: Required argument specifying the name variable of the section. Will set a variable with
                  specified name containing the generated function ID to use.
   :type NAME: str*
   :keyword EXPECTFAIL: Option indicating whether the section is expected to fail or not, if
                        specified will cause test failure when no exceptions were caught and success
                        upon catching any exceptions.
   :type EXPECTFAIL: option
   :keyword PRINT_LENGTH: Optional argument specifying the desired
                          print length of pass/fail output lines.
   :type PRINT_LENGTH: int
   
   .. seealso:: :func:`~cmake_test/add_test.ct_add_test` for details on EXPECTFAIL.
   
   .. seealso:: :func:`~cmake_test/exec_tests.ct_exec_tests` for details on halting tests on exceptions.
   
   Implementation Details
   ----------------------
   
   Upon being executed, this function will check if the section should be executed.
   If it is not, this function will generate an ID for the section
   function and sets the variable pointed to by the NAME parameter to it.
   It will also construct a new :class:`~cmake_test/execution_unit.CTExecutionUnit`
   instance to represent the section.
   
   If the section is supposed to be executed, this function
   will call the :meth:`~cmake_test/execution_unit.CTExecutionUnit.execute`
   method of the unit representing this section.
   Exceptions will be tracked while the function is being executed.
   After completion of the test, the test status will be output
   using :meth:`~cmake_test/execution_unit.CTExecutionUnit.print_pass_or_fail`.
   The section's subsections will then be executed recursively, following
   this same flow until there are no more subsections.