Add elaborated type specifier example

Author: iMichka

docs/examples.rst

@@ -33,6 +33,8 @@ Advanced examples
 .. toctree::
    :maxdepth: 1
 
+   examples/elaborated/example.rst
    examples/function-pointer/example.rst
    examples/caching/example.rst
    examples/print-example/example.rst
+

docs/examples/elaborated/example.hpp

@@ -0,0 +1,11 @@
+// Copyright 2014-2017 Insight Software Consortium.
+// Copyright 2004-2009 Roman Yakovenko.
+// Distributed under the Boost Software License, Version 1.0.
+// See http://www.boost.org/LICENSE_1_0.txt
+
+class A {};
+
+A a1;
+class A a2;
+
+void function(A arg1, class A arg2);

docs/examples/elaborated/example.py

@@ -0,0 +1,56 @@
+# Copyright 2014-2017 Insight Software Consortium.
+# Copyright 2004-2009 Roman Yakovenko.
+# Distributed under the Boost Software License, Version 1.0.
+# See http://www.boost.org/LICENSE_1_0.txt
+
+from pygccxml import utils
+from pygccxml import declarations
+from pygccxml import parser
+
+import os
+import sys
+import warnings
+warnings.simplefilter("error", Warning)
+# Find out the file location within the sources tree
+this_module_dir_path = os.path.abspath(
+    os.path.dirname(sys.modules[__name__].__file__))
+
+# Find out the c++ parser
+generator_path, generator_name = utils.find_xml_generator()
+
+# Configure the xml generator
+xml_generator_config = parser.xml_generator_configuration_t(
+    xml_generator_path=generator_path,
+    xml_generator=generator_name,
+    castxml_epic_version=1)
+
+# The c++ file we want to parse
+filename = "example.hpp"
+filename = this_module_dir_path + "/" + filename
+
+decls = parser.parse([filename], xml_generator_config)
+global_namespace = declarations.get_global_namespace(decls)
+
+a1 = global_namespace.variable("a1")
+print(str(a1.decl_type), type(a1.decl_type))
+# > 'A', <class 'pygccxml.declarations.cpptypes.declarated_t'>
+
+print(declarations.is_elaborated(a1.decl_type))
+# > False
+
+a2 = global_namespace.variable("a2")
+print(str(a2.decl_type), type(a2.decl_type))
+# > 'class ::A', <class 'pygccxml.declarations.cpptypes.elaborated_t'>
+
+print(declarations.is_elaborated(a2.decl_type))
+# > True
+
+base = declarations.remove_elaborated(a2.decl_type)
+print(str(base), type(base))
+# > 'A', <class 'pygccxml.declarations.cpptypes.declarated_t'>
+
+# The same can be done with function arguments:
+fun = global_namespace.free_function("function")
+print(type(fun.arguments[0].decl_type), type(fun.arguments[1].decl_type))
+# > <class 'pygccxml.declarations.cpptypes.declarated_t'>,
+#   <class 'pygccxml.declarations.cpptypes.elaborated_t'>

docs/examples/elaborated/example.rst

@@ -0,0 +1,24 @@
+==========================
+Elaborated type specifiers
+==========================
+
+Elaborated type specifiers are one of these four possibilities: *class*, *struct*, *union* or *enum*.
+
+In C++ they can often be skipped (but may be useful; see `this interesting topic`_ for example).
+In C code they are mandatory.
+
+Let's consider the following c++ file:
+
+.. literalinclude:: example.hpp
+   :language: c++
+   :lines: 5-
+
+The following code will show how the elaborated type specifiers are treated in pygccxml.
+Please note that this feature is only available since recent versions of *CastXML* (Mar 1, 2017),
+and a special flag needs to be passed to pygccxml to make this work (castxml_epic_version=1).
+
+.. literalinclude:: example.py
+   :language: python
+   :lines: 6,7,8,17-27,29-
+
+.. _`this interesting topic`: http://stackoverflow.com/questions/1675351/typedef-struct-vs-struct-definitions/1675446#1675446

unittests/example_tester.py

@@ -8,8 +8,10 @@
 import unittest
 import subprocess
 
+from . import parser_test_case
 
-class Test(unittest.TestCase):
+
+class Test(parser_test_case.parser_test_case_t):
 
     def test_example(self):
         """Runs the example in the docs directory"""
@@ -30,6 +32,14 @@ def test_example(self):
                 file_paths.append(os.path.join(root, file_path))
 
         for file_path in file_paths:
+
+            if "elaborated" in file_path and\
+                    self.config.castxml_epic_version != 1:
+                # Don't run this test if the castxml_epic_version was not
+                # set to 1, because the test needs to be able to run with
+                # that version
+                continue
+
             return_code = subprocess.call(
                 ["python", path + "/example_tester_wrap.py", file_path],
                 env=env)