################################
cmakepp_lang/utilities/pack_list
################################

.. module:: cmakepp_lang/utilities/pack_list

   Defines functions for packing and unpacking a CMake list into a string that
   can be passed through function calls.
   


.. function:: cpp_pack_list(result list **kwargs)

   Transforms a CMake list into a string that can be passed down through
   function calls and then transformed back to the original CMake list that
   retains the original nesting structure of the list.
   
   This function will take a CMake list and replace list separator characters at
   various levels of nesting with "_CPP_{N}_CPP_" where N is the level of
   nesting. N will be 0 for the top level list, 1 for the next level down, and so
   on.
   
   For example, take a list declared with the command:
   set(my_list a;b\\\;c\\\\\;cc\\\;bb;aa)
   
   my_list serializes to the (much more easily read) form:
   [ "a", [ "b", [ "c", "cc" ], "bb" ], "aa" ]
   
   my_list will be transformed to the packed list string:
   a_CPP_0_CPP_b_CPP_1_CPP_c_CPP_2_CPP_cc_CPP_1_CPP_bb_CPP_0_CPP_aa
   
   :param result: The name for the variable which will hold the result.
   :type result: desc
   :param list: The list we want to pack into a string.
   :type result: list
   :returns: ``result`` will be set to the resulting packed list string.
   :rtype: desc
   
   :var CMAKEPP_LANG_DEBUG_MODE: Used to determine if CMakePP is being run in
                                 debug mode or not.
   :vartype CMAKEPP_LANG_DEBUG_MODE: bool
   
   Error Checking
   ==============
   
   If CMakePP is run in debug mode ``cpp_pack_list`` will assert that it has
   been called with two arguments and that those arguments are of the correct
   types.
   


.. function:: cpp_unpack_list(result packed_list **kwargs)

   Transforms a string generated from a list being passed to cpp_pack_list
      back into the original CMake list, retaining the nesting structure.
   
   This function will take a packed list string and replace the "_CPP_{N}_CPP_"
   list separator placeholders with actual CMake list seperators with the
   the appropriate number of escape characters with respect to the nesting level
   of the list separator placeholders (N).
   
   For example take a packed list string:
   a_CPP_0_CPP_b_CPP_1_CPP_c_CPP_2_CPP_cc_CPP_1_CPP_bb_CPP_0_CPP_aa
   
   This string will be transformed into a list that serializes to:
   [ "a", [ "b", [ "c", "cc" ], "bb" ], "aa" ]
   
   :param result: The name for the variable which will hold the result.
   :type result: desc
   :param packed_list: The string we want to transform to a CMake list.
   :type packed_list: desc
   :returns: ``result`` will be set to the resulting CMake list.
   :rtype: desc
   
   Error Checking
   ==============
   
   If CMakePP is run in debug mode ``cpp_unpack_list`` will assert that it has
   been called with two arguments and that those arguments are of the correct
   types.
   
   :var CMAKEPP_LANG_DEBUG_MODE: Used to determine if CMakePP is being run in
                                 debug mode or not.