/**
@page GRAS_tut_tour_pointers Lesson 13: Defining structure containing pointers (TODO)
+This lesson is a bit different from the other ones. It aims at explaining
+several features of the automatic datadesc parsing. Since it would be a bit
+long otherwise, the lesson is organized as a FAQ, with little examples of
+how to do things.
+
\section GRAS_tut_tour_pointers_toc Table of Contents
- - \ref GRAS_tut_tour_pointers_intro
- - \ref GRAS_tut_tour_pointers_use
- - \ref GRAS_tut_tour_pointers_recap
+ - \ref GRAS_tut_tour_pointers_cste
<hr>
-\section GRAS_tut_tour_pointers_intro Introduction
+\section GRAS_tut_tour_pointers_cste How to have constants in parsed structures?
-\section GRAS_tut_tour_pointers_use Defining structure containing pointers
+You can use gras_datadesc_set_const() to explain GRAS about the value of
+your \#define'd constants.
+\verbatim
+#define SIZE 12
+GRAS_DEFINE_TYPE(array,struct array {
+ int data[SIZE];
+};);
-\section GRAS_tut_tour_pointers_recap Recapping everything together
+void declare_ddt() {
+ gras_datadesc_type_t ddt;
+
+ gras_datadesc_set_const("SIZE",SIZE); /* Set it before */
+ gras_datadesc_by_symbol(array);
+}
+\endverbatim
-The program now reads:
-include 12-pointers.c
-Which produces the expected output:
-include 12-pointers.output
+*/
+
+ and the this example do use structures as payload,
+ so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing
+ the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this
+ declaration into an hidden string variable, which can be automatically parsed at
+ run time. Of course, the declaration is also copied unmodified by this macro, so that it
+ gets parsed by the compiler also.
+
+ There is some semantic that GRAS cannot guess alone and you need to <i>annotate</i>
+ your declaration to add some. For example, the ctn pointer can be a reference to an
+ object or a whole array (in which case you also has to specify its size). This is done
+ with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps
+ GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an
+ array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols
+ being the other fields of the structure).
+
+ Please note that this annotation mechanism is not as robust and cool as this example seems to
+ imply. If you want to use it yourself, you'd better use the exact right syntax, which is
+ detailed in the \ref GRAS_dd section.
+
+ \skip GRAS_DEFINE_TYPE
+ \until matrix_t
-*/
#define COLS 16
#define MAX_ROUTESET 10
