1Glib::ParseXSDoc(3)   User Contributed Perl Documentation  Glib::ParseXSDoc(3)
2
3
4

NAME

6       Glib::ParseXSDoc - Parse POD and XSub declarations from XS files.
7

DESCRIPTION

9       This is the heart of an automatic API reference documentation system
10       for XS-based Perl modules.  FIXME more info here!!
11
12       FIXME document recognized POD directives and the output data structures
13

FUNCTIONS

15       xsdocparse (@filenames)
16           Parse xs files for xsub signatures and pod.  Writes to standard
17           output a data structure suitable for eval'ing in another Perl
18           script, describing all the stuff found.  The output contains three
19           variables:
20
21           $xspods = ARRAYREF
22               array of pods found in the verbatim C portion of the XS file,
23               listed in the order found.  These are assumed to pertain to the
24               XS/C api, not the Perl api.  Any "=for apidoc" paragraphs
25               following an "=object" paragraphs in the verbatim sections are
26               stripped (as are the "=object" paragraphs), and will appear
27               instead in "$data->{$package}{pods}".
28
29           $data = HASHREF
30               big hash keyed by package name (as found in the MODULE line),
31               containing under each key a hash with all the xsubs and pods in
32               that package, in the order found.  Packages are consolidated
33               across multiple files.
34
35           FYI, this creates a new parser and calls "parse_file" on it for
36           each input filename; then calls "swizzle_pods" to ensure that any
37           "=for apidoc name" pods are matched up with their target xsubs; and
38           finally calls Data::Dumper to write the data to stdout.  So, if you
39           want to get finer control over how the output is created, or keep
40           all the data in-process, now you know how.  :-)
41

METHODS

43       $Glib::ParseXSDoc::verbose
44           If true, this causes the parser to be verbose.
45
46       $parser = Glib::ParseXSDoc->new
47           Create a new xsub parser.
48
49       string = $parser->package
50           Get the current package name.  Falls back to the module name.  Will
51           be undef if the parser hasn't reached the first MODULE line.
52
53       HASHREF = $parser->pkgdata
54           The data hash corresponding to the current package, honoring the
55           most recently encountered "=for object" directive.  Ensures that it
56           exists.  Returns a reference to the member of the main data
57           structure, so modifications are permanent and useful.
58
59       $parser->parse_file (filename)
60           Parse one xs file.  Stores all the collected data in $parser's
61           internal data structures.
62
63       $parser->swizzle_pods
64           Match "=for apidoc" pods to xsubs.
65
66       $parser->preprocess_pods
67           Honor the "__hide__" and "__function__" directives in "=for apidoc"
68           lines.
69
70           We look for the strings anywhere, but you'll typically have it at
71           the end of the line, e.g.:
72
73             =for apidoc symname __hide__        for detached blocks
74             =for apidoc __hide__                for attached blocks
75
76             =for apidoc symname __function__    for functions rather than methods
77             =for apidoc __function__            for functions rather than methods
78
79       bool = $parser->is_module_line ($line)
80           Analyze $line to see if it contains an XS MODULE directive.  If so,
81           returns true after setting the $parser's module, package, and
82           prefix accordingly.
83
84       $pod = $parser->slurp_pod_paragraph ($firstline,
85       $term_regex=/^=cut\s*/)
86           Slurp up POD lines from $filehandle from here to the next
87           $term_regex or EOF.  Since you probably already read a line to
88           determine that we needed to start a pod, you can pass that first
89           line to be included.
90
91       $xsub = $parser->parse_xsub (\@lines)
92       $xsub = $parser->parse_xsub (@lines)
93           Parse an xsub header, in the form of a list of lines, into a data
94           structure describing the xsub.  That includes pulling out the
95           argument types, aliases, and code type.
96
97           Without artificial intelligence, we cannot reliably determine
98           anything about the types or number of parameters returned from
99           xsubs with PPCODE bodies.
100
101           OUTLIST parameters are pulled from the args list and put into an
102           "outlist" key.  IN_OUTLIST parameters are put into both.
103
104           Data type names are not mangled at all.
105
106           Note that the method can take either a list of lines or a reference
107           to a list of lines.  The flat list form is provided for
108           compatibility; the reference form is preferred, to avoid
109           duplicating a potentially large list of strings.
110
111       $parser->clean_out_empty_pods
112           Looks through the data member of the parser and removes any keys
113           (and associated values) when no pod, enums, and xsubs exist for the
114           package.
115

AUTHOR

117       muppet <scott at asofyet dot org>
118
120       Copyright (C) 2003, 2004 by muppet
121
122       This library is free software; you can redistribute it and/or modify it
123       under the terms of the GNU Library General Public License as published
124       by the Free Software Foundation; either version 2.1 of the License, or
125       (at your option) any later version.
126
127       This library is distributed in the hope that it will be useful, but
128       WITHOUT ANY WARRANTY; without even the implied warranty of
129       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
130       Library General Public License for more details.
131
132       You should have received a copy of the GNU Library General Public
133       License along with this library; if not, write to the Free Software
134       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
135       02110-1301 USA.
136
137
138
139perl v5.38.0                      2023-08-01               Glib::ParseXSDoc(3)
Impressum