doc/doxygen/DoxyFilt.pl

#!/bin/perl

=head1 NAME

C<DoxyFilt.pl> Script for preparing non-C/C++ input documents for Doxygen.

=head1 SYNOPSIS

usage:  $0 <flag>* <path>
        Process file specified by <path> (or via --path flag),
        generating faux C++ and Doxygen comments to standard output
    --filter    <filter>*
                    set filter to be applied to <path>
    --flag      <flag>=<value>
                    set a specified flag for all filters
    --flag      <<filter>::flag>=<value>
                    set a flag for the specified filter filter
    
    --noinfo        deactivate informational logging ([I])
    --trace         activate trace logging ([T] and [H])

In Doxygen configuration file (using Perl as source filter example):

    INPUT_FILTER = DoxyPerl

or:

    FILTER_PATTERNS = *.p?=DoxyPerl
    
The C<DoxyPerl> entry will be a batch file or shell script that in turn
invokes DoxyFilt.pl.  For example (DOS/Windows batch file):

    perl DoxyFilt.pl --filter=Perl --filter=POD %1

or (Linux shell script):

    #!/bin/sh
    perl DoxyFilt.pl --filter=Perl --filter=POD $1

Any command line parameters necessary to DoxyFilt.pl will be invoked in
the batch file.  The batch/shell scripts  (one per language) should be
either local to the execution directory or on the C<PATH>.  If the
DoxyFilt.pl script is not on the C<PATH> the batch/shell scripts
will need to be modified appropriately.

=head1 ABSTRACT

Provides an input filter for the Doxygen documentation generation tool
to convert Perl/POD (and/or other source formats) into C/C++ with
Doxygen-enabled comments.

=head1 DESCRIPTION

The Doxygen documentation processor collects information from source code
files in C and C++ and generates nicely formatted source code documentation.
This can be an important component of any fully documented software project.

Unfortunately, Doxygen doesn't know anything about any other languages.
It does, however, have an input filter setting that allows source files in
other languages to be converted to something that Doxygen I<can> recognize.
This means parsing the source files and converting them into a combination
of C/C++ and Doxygen-enabled comments.

=head1  Command-Line Arguments

The following flags can be specified to affect the
operation of <tt>DoxyFilt.pl</tt>:

=over

=item   C<--flag I<[filter::]name>=I<value>>

Specify a named flag.
Flags can be specified as global or per document filter.
More specific flags (per document filter) override global flags
for the specified document filter and are invisible to other
document filters.

=item   C<--noinfo>

Deactivates informational messages such as those that specify what file is
being processed.
These are the C<[I]> messages.

=item   C<--trace>

Activates tracing and 'hacking' messages.
The former are lower-level debugging messages.
The latter are specific conditions that have been bypassed
in possibly strange ways (if any).
These are the C<[T]> and C<[H]> messages, respectively.

=item   C<--filter>

Specify a filter filter to be applied to the source file.
There may be one or more such filters.  They will be applied
in the specified order.  After all parsing is done, a massage
step will be invoked to merge disparate results in cases where
there are multiple filters.

=back

=cut

#=| \ingroup    scripts

###########################################################################
###########################################################################

use     5.005;  # just to pick something, but not really tested
use     strict;
use     warnings;
use     UNIVERSAL   qw(isa);

use     Getopt::Long;
use     Pod::Usage;

use     Doxygen::Context;

# The last version from which this was taken was 0.23.
#   The current directory is a new branch of changes.
#   This could almost be though of as moving to V4,
#   but realistically it would be V3.5 or something,
#   as we keep the same general architecture but try
#   to make it easier to use by taking advantage of
#   new doxygen 1.4.3 features and playing with the
#   instantiation and startup flags.

our $VERSION = '0.83';

###########################################################################
# Command-line arguments:

my  %flags = (
    info   => 1,
    filter => [ ],
    flag   => [ ],
    trace  => 0
);
my  $help = undef;

pod2usage(2)
    unless GetOptions(
            'flag=s'     =>  $flags{flag},
            'info!'      => \$flags{info},
            'trace'      => \$flags{trace},
            'filter=s'   =>  $flags{filter},
            'help'       => \$help
           );

pod2usage('No file filter specified')
    unless @{$flags{filter}};

pod2usage(1)
    if $help;

my  $path = shift @ARGV;

pod2usage('No path specified')
    unless $path;

pod2usage('Input file does not exist')
    unless -f $path;

pod2usage('Input file not readable')
    unless -r $path;

###########################################################################
###########################################################################
#
# Main Program:
#

my  %fixed = ( );

for (@{$flags{flag}}) {
    my ($flag, $value);
    
    if (/^\s*(.*?)\s*=\s*(.*?)\s*$/) {
        ($flag, $value) = ($1, $2);
    } else {
        ($flag, $value) = ($_, 1);
    }
    
    if (isa($fixed{$flag}, 'ARRAY')) {
        push @{$fixed{$flag}}, $value;
    } elsif ($fixed{$flag}) {
        $fixed{$flag} = [ $fixed{$flag}, $value ];
    } else {
        $fixed{$flag} = $value;
    }
}

$flags{flag} = %fixed ? \%fixed : undef;

if (my $context = new Doxygen::Context(%flags)) {
#   $context->log('T', 'Process ', $path)->pushLog;
    $context->parse($path);
    $context->massage;
    $context->generate;
#   $context->log('T', 'Output generated!')->popLog;
} else {
    local   $/ = undef; # slurp entire file

    die "Unable to read (slurp) from file:\n    $path\n  $!\n"
        unless open FILE, '<', $path;

    print <FILE>;
}

###########################################################################
###########################################################################

__END__

=head1 SEE ALSO

Doxygen::Filter, http://www.doxygen.org

=head1 COPYRIGHT

Copyright (C) 2004  Marc M. Adkins

This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=head1 AUTHOR

Marc M. Adkins  L<mailto:Perl@Doorways.org>

=cut
Revision:	1.1
Committed:	Fri Aug 5 16:39:16 2005 UTC (19 years, 9 months ago) by sashby
Content type:	application/x-perl
Branch:	MAIN
CVS Tags:	V1_1_7, V1_1_6, V1_1_5, V1_1_4, V1_1_3, V1_1_2, V1_1_0_reltag8, V1_1_0_reltag7, V1_1_0_reltag6, V1_1_1, V1_1_0_reltag5, V1_1_0_reltag4, V1_1_0_reltag3, V1_1_0_reltag2, V1_1_0_reltag1, V1_1_0_reltag, V1_0_3-p4, V1_1_0_cand3, V1_1_0_cand2, V1_1_0_cand1, HEAD_SM_071214, forV1_1_0, v103_xml_071106, V1_0_3-p3, V1_0_3-p2, V1_1_0, v110p1, V110p6, V110p5, V110p4, V110p3, V110p2, V110p1, V1_0_4p1, V1_0_3-p1, V1_0_3, V1_0_2, V1_0_2_p1
Branch point for:	HEAD_BRANCH_SM_071214, v200branch, v103_with_xml, v103_branch
Log Message:	First attempt at doxygenising SCRAM documentation.
#	User	Rev	Content
1	sashby	1.1	#!/bin/perl
2
3			=head1 NAME
4
5			C<DoxyFilt.pl> Script for preparing non-C/C++ input documents for Doxygen.
6
7			=head1 SYNOPSIS
8
9			usage: $0 <flag>* <path>
10			Process file specified by <path> (or via --path flag),
11			generating faux C++ and Doxygen comments to standard output
12			--filter <filter>*
13			set filter to be applied to <path>
14			--flag <flag>=<value>
15			set a specified flag for all filters
16			--flag <<filter>::flag>=<value>
17			set a flag for the specified filter filter
18
19			--noinfo deactivate informational logging ([I])
20			--trace activate trace logging ([T] and [H])
21
22			In Doxygen configuration file (using Perl as source filter example):
23
24			INPUT_FILTER = DoxyPerl
25
26			or:
27
28			FILTER_PATTERNS = *.p?=DoxyPerl
29
30			The C<DoxyPerl> entry will be a batch file or shell script that in turn
31			invokes DoxyFilt.pl. For example (DOS/Windows batch file):
32
33			perl DoxyFilt.pl --filter=Perl --filter=POD %1
34
35			or (Linux shell script):
36
37			#!/bin/sh
38			perl DoxyFilt.pl --filter=Perl --filter=POD $1
39
40			Any command line parameters necessary to DoxyFilt.pl will be invoked in
41			the batch file. The batch/shell scripts (one per language) should be
42			either local to the execution directory or on the C<PATH>. If the
43			DoxyFilt.pl script is not on the C<PATH> the batch/shell scripts
44			will need to be modified appropriately.
45
46			=head1 ABSTRACT
47
48			Provides an input filter for the Doxygen documentation generation tool
49			to convert Perl/POD (and/or other source formats) into C/C++ with
50			Doxygen-enabled comments.
51
52			=head1 DESCRIPTION
53
54			The Doxygen documentation processor collects information from source code
55			files in C and C++ and generates nicely formatted source code documentation.
56			This can be an important component of any fully documented software project.
57
58			Unfortunately, Doxygen doesn't know anything about any other languages.
59			It does, however, have an input filter setting that allows source files in
60			other languages to be converted to something that Doxygen I<can> recognize.
61			This means parsing the source files and converting them into a combination
62			of C/C++ and Doxygen-enabled comments.
63
64			=head1 Command-Line Arguments
65
66			The following flags can be specified to affect the
67			operation of <tt>DoxyFilt.pl</tt>:
68
69			=over
70
71			=item C<--flag I<[filter::]name>=I<value>>
72
73			Specify a named flag.
74			Flags can be specified as global or per document filter.
75			More specific flags (per document filter) override global flags
76			for the specified document filter and are invisible to other
77			document filters.
78
79			=item C<--noinfo>
80
81			Deactivates informational messages such as those that specify what file is
82			being processed.
83			These are the C<[I]> messages.
84
85			=item C<--trace>
86
87			Activates tracing and 'hacking' messages.
88			The former are lower-level debugging messages.
89			The latter are specific conditions that have been bypassed
90			in possibly strange ways (if any).
91			These are the C<[T]> and C<[H]> messages, respectively.
92
93			=item C<--filter>
94
95			Specify a filter filter to be applied to the source file.
96			There may be one or more such filters. They will be applied
97			in the specified order. After all parsing is done, a massage
98			step will be invoked to merge disparate results in cases where
99			there are multiple filters.
100
101			=back
102
103			=cut
104
105			#=\| \ingroup scripts
106
107			###########################################################################
108			###########################################################################
109
110			use 5.005; # just to pick something, but not really tested
111			use strict;
112			use warnings;
113			use UNIVERSAL qw(isa);
114
115			use Getopt::Long;
116			use Pod::Usage;
117
118			use Doxygen::Context;
119
120			# The last version from which this was taken was 0.23.
121			# The current directory is a new branch of changes.
122			# This could almost be though of as moving to V4,
123			# but realistically it would be V3.5 or something,
124			# as we keep the same general architecture but try
125			# to make it easier to use by taking advantage of
126			# new doxygen 1.4.3 features and playing with the
127			# instantiation and startup flags.
128
129			our $VERSION = '0.83';
130
131			###########################################################################
132			# Command-line arguments:
133
134			my %flags = (
135			info => 1,
136			filter => [ ],
137			flag => [ ],
138			trace => 0
139			);
140			my $help = undef;
141
142			pod2usage(2)
143			unless GetOptions(
144			'flag=s' => $flags{flag},
145			'info!' => \$flags{info},
146			'trace' => \$flags{trace},
147			'filter=s' => $flags{filter},
148			'help' => \$help
149			);
150
151			pod2usage('No file filter specified')
152			unless @{$flags{filter}};
153
154			pod2usage(1)
155			if $help;
156
157			my $path = shift @ARGV;
158
159			pod2usage('No path specified')
160			unless $path;
161
162			pod2usage('Input file does not exist')
163			unless -f $path;
164
165			pod2usage('Input file not readable')
166			unless -r $path;
167
168			###########################################################################
169			###########################################################################
170			#
171			# Main Program:
172			#
173
174			my %fixed = ( );
175
176			for (@{$flags{flag}}) {
177			my ($flag, $value);
178
179			if (/^\s(.?)\s=\s(.?)\s$/) {
180			($flag, $value) = ($1, $2);
181			} else {
182			($flag, $value) = ($_, 1);
183			}
184
185			if (isa($fixed{$flag}, 'ARRAY')) {
186			push @{$fixed{$flag}}, $value;
187			} elsif ($fixed{$flag}) {
188			$fixed{$flag} = [ $fixed{$flag}, $value ];
189			} else {
190			$fixed{$flag} = $value;
191			}
192			}
193
194			$flags{flag} = %fixed ? \%fixed : undef;
195
196			if (my $context = new Doxygen::Context(%flags)) {
197			# $context->log('T', 'Process ', $path)->pushLog;
198			$context->parse($path);
199			$context->massage;
200			$context->generate;
201			# $context->log('T', 'Output generated!')->popLog;
202			} else {
203			local $/ = undef; # slurp entire file
204
205			die "Unable to read (slurp) from file:\n $path\n $!\n"
206			unless open FILE, '<', $path;
207
208			print <FILE>;
209			}
210
211			###########################################################################
212			###########################################################################
213
214			__END__
215
216			=head1 SEE ALSO
217
218			Doxygen::Filter, http://www.doxygen.org
219
220			=head1 COPYRIGHT
221
222			Copyright (C) 2004 Marc M. Adkins
223
224			This library is free software; you can redistribute it and/or
225			modify it under the same terms as Perl itself.
226
227			This program is distributed in the hope that it will be useful, but
228			without any warranty; without even the implied warranty of
229			merchantability or fitness for a particular purpose.
230
231			=head1 AUTHOR
232
233			Marc M. Adkins L<mailto:Perl@Doorways.org>
234
235			=cut