| 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
|
