Sectionizer sorts declarations into sections.
The default behaviour is to put each declaration from a header file into
a section formed by this header file. This corresponds to gtk-doc's
initial sectionization and --rebuild-sections behaviour. People
with sane header files will rarely need anything else.
Customization of sectioning is done using a set of rules that say where a declaration should be placed based on its name and the file it was encountered in.
The rules employ regular expression and their general form is:
file_regexp : symbol_regexp -> section
Any part can be empty, defaults (described below) are then substituted.
Spaces around : and -> are mandatory, except on
the side of a missing part.
Left hand side file_regexp and
symbol_regexp are python regular expressions, the
default for both is .* which makes absent parts to match
anything.
Right hand side section is a template where
substrings of the form
<file:group> <symbol:group>
are replaced with the corresponding matched groups from file name and symbol
regular expressions. To use the complete file name (or symbol, silly) as the
section name, group can be specified as
0, omitted, or even omitted including the :.
The default value is <file>.
The implicit rule
:->
or more verbosely
.* : .* -> <file:>
thus specifies that each symbol goes into a section named identically to
the header name (without .h which is removed before
matching).
A special form of symbol_regexp is
class<prefix,body,mixed>
generating a set of rules for GObject class following the standard naming conventions. For instance
: class<GWY,GRAPH,GwyGraph> -> gwygraph
is expanded to the following set of rules
.* : GWY_TYPE_GRAPH -> gwygraph .* : GWY_IS_GRAPH(?:_[A-Z0-9_]+)? -> gwygraph .* : GWY_GRAPH(?:_[A-Z0-9_]+)? -> gwygraph .* : GwyGraph(?:[A-Z][A-Za-z0-9_]*)? -> gwygraph .* : gwy_graph_[a-z0-9_]+ -> gwygraph
No spaces are allowed inside class. The case of
prefix and body does not
matter, they are converted to uppercase for the macro-like rules and to
lowercase for the function-like rule.
Examples:
garray : g_array_.* -> garray garray : GArray -> garray garray : g_ptr_array_.* -> gptrarray garray : GPtrArray -> gptrarray garray : g_byte_array_.* -> gbytearray garray : GByteArray -> gbytearray
sorts the declarations from garray.h to the individual
sections. Since the standard naming is employed we could also misuse the
class expansion mechanism:
garray : class<G,ARRAY,GArray> -> garray garray : class<G,PTR_ARRAY,GPtrArray> -> gptrarray garray : class<G,BYTE_ARRAY,GByteArray> -> gbytearray
although it would expand to much more rules than actually necessary.