Add a bunch of simple examples to the doc

Author: iMichka

docs/examples.rst

@@ -0,0 +1,13 @@
+========
+Examples
+========
+
+First examples
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   examples/first/example.rst
+   examples/variables/example.rst
+   examples/caching/example.rst

docs/examples/caching/example.cpp

@@ -0,0 +1,7 @@
+// Copyright 2014-2015 Insight Software Consortium.
+// Distributed under the Boost Software License, Version 1.0.
+// See http://www.boost.org/LICENSE_1_0.txt
+
+namespace ns{
+    int a = 1;
+}

docs/examples/caching/example.py

@@ -0,0 +1,32 @@
+# Copyright 2014-2015 Insight Software Consortium.
+# 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
+
+# Find out the c++ parser
+generator_path, generator_name = utils.find_cpp_parser()
+
+# Configure the xml generator
+xml_generator_config = parser.xml_generator_configuration_t(
+    xml_generator_path=generator_path,
+    xml_generator=generator_name)
+
+# The c++ file we want to parse
+filename = "example.hpp"
+
+file_config = parser.file_configuration_t(
+    data=filename,
+    content_type=parser.CONTENT_TYPE.CACHED_SOURCE_FILE)
+
+project_reader = parser.project_reader_t(xml_generator_config)
+decls = project_reader.read_files(
+    [file_config],
+    compilation_mode=parser.COMPILATION_MODE.FILE_BY_FILE)
+
+global_namespace = declarations.get_global_namespace(decls)
+
+value = global_namespace.namespace("ns")
+print("My name is: " + value.name)

docs/examples/caching/example.rst

@@ -0,0 +1,32 @@
+=======
+Caching
+=======
+
+This example shows how to use caching. This can be useful
+for big projects where you don't want the c++ to be parsed
+again and again.
+
+Let's consider the following c++ file:
+
+.. literalinclude:: example.hpp
+   :language: c++
+
+To enable caching, you can use the following code:
+
+.. literalinclude:: example.py
+   :language: python
+
+The first time you run this example, the c++ file will be read and a xml
+file will be generated:
+
+INFO Creating xml file "example.hpp.xml" from source file "example.hpp" ...
+INFO Parsing xml file "example.hpp.xml" ...
+My name is: ns
+
+The second time you run the example the xml file will not be regenerated:
+
+INFO Parsing xml file "example.hpp.xml" ...
+My name is: ns
+
+Of course the performance gain will be small for this example,
+but can be intersting for bigger projects.

docs/examples/parsing/example.cpp

@@ -0,0 +1,7 @@
+// Copyright 2014-2015 Insight Software Consortium.
+// Distributed under the Boost Software License, Version 1.0.
+// See http://www.boost.org/LICENSE_1_0.txt
+
+namespace ns{
+    int a = 1;
+}

docs/examples/parsing/example.py

@@ -0,0 +1,27 @@
+# Copyright 2014-2015 Insight Software Consortium.
+# 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
+
+# Find the location of the xml generator (castxml or gccxml)
+generator_path, generator_name = utils.find_cpp_parser()
+
+# Configure the xml generator
+xml_generator_config = parser.xml_generator_configuration_t(
+    xml_generator_path=generator_path,
+    xml_generator=generator_name)
+
+# The c++ file we want to parse
+filename = "example.hpp"
+
+# Parse the c++ file
+decls = parser.parse([filename], xml_generator_config)
+
+# Get access to the global namespace
+global_namespace = declarations.get_global_namespace(decls)
+
+# Get access to the 'ns' namespace
+ns = global_namespace.namespace("ns")

docs/examples/parsing/example.rst

@@ -0,0 +1,18 @@
+==================
+Parsing a c++ file
+==================
+
+This example shows how to setup pygccxml to parse a c++ file, and how
+to access the declaration tree.
+
+Let's consider the following c++ file (example.cpp):
+
+.. literalinclude:: example.hpp
+   :language: c++
+
+The following code will show you how to create a configuration for
+the xml generator (an external tool, either castxml or gccxml),
+and how to parse the c++ file:
+
+.. literalinclude:: example.py
+   :language: python

docs/examples/variables/example.cpp

@@ -0,0 +1,9 @@
+// Copyright 2014-2015 Insight Software Consortium.
+// Distributed under the Boost Software License, Version 1.0.
+// See http://www.boost.org/LICENSE_1_0.txt
+
+namespace ns{
+    int a = 1;
+    int b = 2;
+    double c = 3.0;
+}

docs/examples/variables/example.py

@@ -0,0 +1,45 @@
+# Copyright 2014-2015 Insight Software Consortium.
+# 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
+
+# Find out the c++ parser
+generator_path, generator_name = utils.find_cpp_parser()
+
+# Configure the xml generator
+xml_generator_config = parser.xml_generator_configuration_t(
+    xml_generator_path=generator_path,
+    xml_generator=generator_name)
+
+# The c++ file we want to parse
+filename = "variables.hpp"
+
+decls = parser.parse([filename], xml_generator_config)
+global_namespace = declarations.get_global_namespace(decls)
+ns = global_namespace.namespace("ns")
+
+# The variables() method will return a list of variables.
+# We know that he c variable is the third one in the list:
+c = ns.variables()[2]
+print("My name is: " + c.name)
+print("My type is: " + str(c.type))
+print("My value is: " + c.value)
+
+# Of course you can also loop over the list and look for the right name
+for var in ns.variables():
+    if var.name == "c":
+        print("My name is: " + var.name)
+        print("My type is: " + str(var.type))
+        print("My value is: " + var.value)
+
+# One way to get a variable is to use the variable() method and
+# a lambda function. This is the most flexible way as you can implement
+# your own lambda function to filter out variables following your
+# specific criteria.
+c = ns.variable(lambda v: v.name == "c")
+print("My name is: " + c.name)
+print("My type is: " + str(c.type))
+print("My value is: " + c.value)

docs/examples/variables/example.rst

@@ -0,0 +1,16 @@
+=========
+Variables
+=========
+
+This example shows how to find variables and find information about them.
+
+Let's consider the following c++ file:
+
+.. literalinclude:: example.hpp
+   :language: c++
+
+The following code can be use to find the variable named "c" using different
+strategies, and to print information about it:
+
+.. literalinclude:: example.py
+   :language: python