#############################
cmakepp_lang/utilities/global
#############################

.. module:: cmakepp_lang/utilities/global

   Defines functions used to manipulate CMakePPLang global variables.
   


.. function:: cpp_append_global(key value)

   Appends a value to a global list.
   
   When we are manipulating a global state, which is actually a list, we often
   want to append to it and not "set" it (set in this context referring to
   overwriting the value with a new value). This function will append to the
   specified global variable the provided value. If the variable does not exist,
   the variable will be created and initialized to the provided value.
   
   :param key: The name of the global variable to append to. ``key`` is
               case-insensitive.
   :type key: desc
   :param value: The value to append to ``key``'s current value.
   :type value: str
   
   Error Checking
   ==============
   
   ``cpp_append_global`` will assert that it is called with only two arguments.
   


.. function:: cpp_set_global(key value)

   Sets a global variable to the provided value.
   
   This function will set a global variable to the value provided. If the global
   variable already exists it will overwrite its current value.
   
   :param key: The name of the global variable to set. ``key`` is
                   case-insensitive.
   :type key: desc
   :param value: The value to set ``key`` to.
   :type value: str
   
   Error Checking
   ==============
   
   ``cpp_set_global`` will assert that it is called with only two arguments.
   


.. function:: cpp_get_global(result key)

   Retrieves the value of the requested global variable.
   
   This function will get the value of the specified global variable. If the
   variable does not exist the empty string will be returned. It is thus not
   possible to discern between an uninitialized global variable and one set to
   the empty string. In practice this is not a problem because global variables
   are not typically set to the empty string.
   
   :param result: Identifier for the variable which after this call will hold
                      the value stored in global variable ``key``.
   :type value: desc
   :param key: The name of the global variable whose value has been
                   requested. ``key`` is case-insensitive.
   :type key: desc
   :returns: ``result`` will be set to the value stored in global variable
             ``key``. If ``key`` has not been set ``result`` will be
             set to the empty string.
   :rtype: str
   
   Error Checking
   ==============
   
   ``cpp_get_global`` will assert that it is called with only two arguments.