DoxyFilt.pl

Go to the documentation of this file.

#!/bin/perl

=head1 NAME

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

=head1 SYNOPSIS

In Doxygen configuration file:

    INPUT_FILTER = DoxyFilt

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

    set doxpath=%~p0
    perl %doxpath%DoxyFilt.pl %1

or (Linux shell script):

    #!/bin/sh
    perl DoxyFilt.pl $1

Any command line parameters necessary to DoxyFilt.pl will be invoked in
the batch file.

Note that in more complex situations, where a number of languages are
used, the batch file or shell script will need to choose the appropriate
filter (DoxyFilt.pl or another program) and invoke it.

=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<--alias I<filter>=I<existing>>

Specific a filter that will be handled by an existing filter.
Use this when it is necessary to specify multiple
filters that use the same filter module but have different
characteristics.
For example, C<Batch> and C<Shell> both link to the
C<Script> filter by default, but use different comment
patterns.

=item   C<--comment I<filter>=I<comment>>

Specify a comment pattern for a given filter.
Only one comment pattern may be defined for a given filter,
new ones with old filter names replace the old patterns.

=item   C<--check I<filter>=I<recognition>>

Specify a recognition pattern for a given filter.
This is used for files without suffixes.  Any such file is
tested with all registered patterns of this type and the
specified filter(s) are applied.

=item   C<--docs I<filter>=I<suffix>>

Specify a suffix to be handled by a specific filter.
Filters may be added by the user and specified in
this manner.
The default filters include C<Perl>, C<POD>, C<Batch>, and C<Shell>.
More than one filter may be applied to the same file.
Only one suffix pattern may be defined for a given filter,
new ones with old filter names replace the old patterns.

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

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

=item   C<--noinfo>

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

=item   C<--pass=I<suffix>>

Specify a suffix to be passed through unchanged.
This flag may be used multiple times.
Defaults to C<dox> or C<doxy> (Doxygen source files).
Flags are cumulative, and can't be removed,
but may be overridden by C<--docs>.

=item   C<--path=I<pathname>>

Alternative way to specify pathname of file to be processed.
Normally it is specified by the positional argument,
but it can be set this way instead.
This flag takes priority over the positional argument.

=item   C<--spawn I<filter>=I<command>>

Specify a command to be executed as a subprocess
to implement a given filter.
In this case there will be no matching Doxygen::Filter
subclass, just specify a C<--docs> setting to 'declare'
the filter name and its suffix and then use the
C<--spawn> parameter to set the command to be executed.
The pathname to be processed is appended after a space
to the end of the command line, or it will replace the
string C<'{}'> if these are present in the command.

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

=back

Where the above flags specify C<suffix> the argument
will be converted into a pattern.
If a simple string or pattern fragment it will be embedded
in the pattern C<qr(\.$string)i>.
If it matches C</^qr\((.*)\)$/> it will be converted
via C<qr($1)>.

Arbitrarily complex patterns should be possible when
appropriately quoted to get past the operating system's
command line interpreter.
The following appears to work on Linux:

    perl DoxyFilt.pl '--pass=qr(\.doxy?)i' --docs 'Batch=qr(\.bat)i' ...

In a similar fashion, where flags specify C<suffix>
the argument will be converted into a pattern.
In this case, if it is a simple string it is embedded
in the pattern C<qr(^\\s*$string(.*)$)m>.
If the string matches the C<qr()> format it will be
converted directly as with suffix patterns.
    
=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     Doxygen::Source;

our $VERSION = '0.75';

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

my  %flags = (
    info => 1,
    type => {
        alias => { },
        chck  => { },
        cmnt  => { },
        docs  => { },
        flag  => { },
        pass  => [ ],
        spawn => { }
    }
);
my  %pass  = ( );
my  $opts = GetOptions('alias=s'    =>  $flags{type}->{alias},
                       'check=s'    =>  $flags{type}->{chck},
                       'comment=s'  =>  $flags{type}->{cmnt},
                       'docs=s'     =>  $flags{type}->{docs},
                       'flag=s'     =>  $flags{type}->{flag},
                       'help'       => \$flags{help},
                       'info!'      => \$flags{info},
                       'pass=s'     =>  $flags{type}->{pass},
                       'path=s'     => \$flags{path},
                       'spawn=s'    =>  $flags{type}->{spawn},
                       'trace'      => \$flags{trace});

$flags{path} = shift
    unless $flags{path}
        || ! @ARGV;

die <<USAGE if $flags{help} || ! $opts || ! $flags{path};
usage:  $0 <flag>* [ <path> ]
        Process file specified by <path> (or via --path flag),
        generating faux C++ and Doxygen comments to standard output
    --alias     <docType>=<filter>
                    set an alias for a document type, so that
                    <docType> is handled by the <filter> filter
    --check     <docType>=<pattern>
                    set the file recognition pattern for
                    a document type
    --comment   <docType>=<pattern>
                    set the comment recognition pattern for
                    a document type
    --docs      <docType>=<suffix>
                    set the suffix pattern for a document type
    --flag      <[docType::]flag>=<value>
    --help          show this usage description
    --noinfo        deactivate informational logging ([I])
    --pass=<suffix> suffix to be passed through unchanged
    --path=<path>   specify file path (or use positional argument)
    --spawn     <docType>=<command>
                    set command to be spawned via system()
    --trace         activate trace logging ([T] and [H])
USAGE

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

my  $source = new Doxygen::Source(%flags);

if (isa($source, 'Doxygen::Source')) {
#   $source->log('T', 'Normal execution...')->pushLog;
    $source->massage;
    $source->generate;
#   $source->popLog->log('T', 'Output generated!');
} else {
    local   $/ = undef; # slurp entire file

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

    print <FILE>;
}

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

__END__

=head1 SEE ALSO

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

=head1 COPYRIGHT

Copyright (C) 2004-2010  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