translator.pl

doxygen(一个自动从源代码生成文档的工具)的源代码

#! /usr/bin/perl -w
# -*- mode: perl; mode: fold -*-

# This is a Perl script for Doxygen developers.  
# Its main purpose is to extract the information from sources
# related to internationalization (the translator classes).
# It uses the information to generate documentation (language.doc,
# translator_report.txt) from templates (language.tpl, maintainers.txt).
#
#                              Petr Prikryl ([e-mail])
# History:
# --------
# 2001/04/27
#  - First version of the script.
#
# 2001/05/02
#  - Update to accept updateNeededMessage() in the Translator class.
#  - First version that generates doc/language.doc.
#
# 2001/05/07
#  - Environment variable $doxygenrootdir now points to the
#    Doxygen's root directory.
#
# 2001/05/11
#  - Updated to reflect using TranslatorAdapterCVS as the base
#    class for "almost up-to-date" translators.
#  - $doxygenrootdir and other global variables for storing 
#    directories determined from DOXYGEN_DOCDIR environment 
#    variable. The change was done because the DOXYGEN_DOCDIR
#    was already used before.
#  - $version mark can be used in the language.tpl template.
#
# 2001/05/18
#  - Character entity ø recognized in maintainers.txt.
#
# 2001/06/06
#  - Implementation of the methods recognized even when the
#    argument list does not contain argument identifiers 
#    (i.e., when it contains type information only).
#
# 2001/06/11
#  - Character entity č recognized in maintainers.txt.
#
# 2001/07/17
#  - Perl version checking is less confusing now. The script stops
#    immediately after the first command below when your perl
#    is older that required.
#  - The information below the table of languages is not produced
#    with the table. Another symbol replacement is done, so language.tpl
#    can be updated so that the generated language.doc does not contain
#    the link to the translator_report.txt.
#
# 2001/08/20
#  - StripArgIdentifiers() enhanced to be more robust in producing
#    equal prototypes from the base class and from the derived
#    classes (if they should be considered equal).
#
# 2001/08/28
#  - "see details" added to the up-to-date translator list 
#    (in translator report) to translators for which some details
#    are listed below in the report.  This is usually the case
#    when the up-to-date translator still implements a obsolete
#    method that will never be called (i.e. the code should be removed).
#
# 2001/09/10
#  - The script now always exits with 0.  If the sources are not
#    found, translator report is not generated.  If the $flangdoc
#    is not also found and no sources are available, the simplified
#    result with remarks inside is generated from the template.
#    The consequences, translator.pl should never break the "make",
#    and the language.doc should always be present after running
#    this script -- no problem should occur when generating doxygen
#    documentation.
#
# 2001/09/11
#  - Minor (say cosmetic) enhancement.  The code for generating
#    the simplified language.doc from the template was moved to 
#    the separate function CopyTemplateToLanguageDoc().
#
# 2001/10/17
#  - Minor update of GetInfoFrom() to ignore spaces between the
#    method identifier and the opening parenthesis to match better
#    the method prototype with the one in the translator.h.
#
# 2001/11/06
#  - TranslatorAdapterCVS is not used any more.  There is nothing
#    like "almost up-to-date" any more.  The script was simplified
#    to reflect the changes.  
#
################################################################

use 5.005;
use strict;
use Carp;

# Global variables
#
my $doxygenrootdir = 'directory set at the beginning of the body';
my $srcdir =         'directory set at the beginning of the body';
my $docdir =         'directory set at the beginning of the body';

my $doxversion =     'set at the beginning of the body';

# Names of the output files.
#
my $ftranslatortxt = "translator_report.txt";
my $flangdoc = "language.doc";

# Names of the template files and other intput files.
#
my $flangtpl = "language.tpl";         # template for language.doc
my $fmaintainers = "maintainers.txt";  # database of local lang. maintainers


################################################################
# GetPureVirtual returns the list of pure virtual method prototypes
# as separate strings (one prototype, one line, one list item).
# The input argument is the full name of the source file.
#
sub GetPureVirtualFrom  ##{{{
{
    my $fin = shift;  # Get the file name.
    
    # Let's open the file and read it into a single string.
    #
    open(FIN, "< $fin") or die "\nError when open < $fin: $!";
    my @content = <FIN>;
    close FIN;
    my $cont = join("", @content);
    
    # Remove comments and empty lines.
    #
    $cont =~ s{\s*//.*$}{}mg; # remove one-line comments
    while ($cont =~ s{/\*.+?\*/}{}sg ) {}   # remove C comments
    $cont =~ s{\n\s*\n}{\n}sg;  # remove empty lines    

    # Remove the beginning up to the first virtual method.
    # Remove also the text behind the class.
    #
    $cont =~ s/^.*?virtual/virtual/s;
    $cont =~ s/\n\};.*$//s;

    # Erase anything between "=0;" and "virtual". Only the pure 
    # virtual methods will remain.  Remove also the text behind 
    # the last "= 0;"
    #
    $cont =~ s{(=\s*0\s*;).*?(virtual)}{$1 $2}sg;
    $cont =~ s{^(.+=\s*0\s*;).*?$}{$1}s;
    
    # Remove the empty implementation of the updateNeededMessage() 
    # method which is to be implemented by adapters only, not by 
    # translators.
    #
    $cont =~ s{\s*virtual
               \s+QCString
               \s+updateNeededMessage\(\)
               \s+\{\s*return\s+"";\s*\}
              }
              {}xs;
    
    # Replace all consequent white spaces (including \n) by a single 
    # space. Trim also the leading and the trailing space.
    #
    $cont =~ s{\s+}{ }sg;
    $cont =~ s{^\s+}{}s;
    $cont =~ s{\s+$}{}s;
    
    # Split the result to the lines again.  Remove the "= 0;".
    #
    $cont =~ s{\s*=\s*0\s*;\s*}{\n}sg;
    
    # Remove the keyword "virtual" because the derived classes 
    # may not use it.
    #
    $cont =~ s{^virtual\s+}{}mg;
    
    # Split the string into array of lines and return it as
    # the output list.
    #
    return split(/\n/, $cont);
}
##}}}


################################################################
# StripArgIdentifiers takes a method prototype (one line string),
# removes the argument identifiers, and returns only the necessary
# form of the prototype.
#
sub StripArgIdentifiers  ##{{{
{
    my $prototype = shift;  # Get the prototype string.
    
    # Extract the list of arguments from the prototype.
    #
    $prototype =~ s{^(.+\()(.*)(\).*)$}{$1#ARGS#$3};
    my $a = (defined $2) ? $2 : '';
    
    # Split the list of arguments.
    #
    my @a = split(/,/, $a);
    
    # Strip each of the arguments.
    #
    my @stripped = ();
    
    foreach my $arg (@a) {
        
        # Only the type of the identifier is important...
        #
        $arg =~ s{^(\s*             # there can be spaces behind comma,
                    (const\s+)?     # possibly const at the beginning
                    [A-Za-z0-9_:]+  # type identifier can be qualified
                    (\s*[*&])?      # could be reference or pointer
                   )                # ... the above is important,
                  .*$               # the rest contains the identifier 
                 }
                 {$1}x;             # remember only the important things
        
        # People may differ in opinion whether a space should
        # or should not be written between a type identifier and 
        # the '*' or '&' (when the argument is a pointer or a reference).
        #
        $arg =~ s{\s*([*&])}{ $1};
        
        # Whitespaces are not only spaces. Moreover, the difference
        # may be in number of them in a sequence or in the type 
        # of a whitespace. This is the reason to replace each sequence
        # of whitespace by a single, real space.
        #
        $arg =~ s{\s+}{ }g;
        
        # Remember the stripped form of the arguments
        push(@stripped, $arg); 
    }
    
    # Join the stripped arguments into one line again, and 
    # insert it back.
    #
    $a = join(',', @stripped);
    $prototype =~ s{#ARGS#}{$a};
    
    # Finally, return the stripped prototype.
    # 
    return $prototype;
}
##}}}


################################################################
# GetInfoFrom returns the list of information related to the
# parsed source file.  The input argument is the name of the 
# translator_xx.h file including path. 
#
# The output list contains the following items:
#  - class identifier
#  - base class identifier
#  - method prototypes (each in a separate item)
#
sub GetInfoFrom  ##{{{
{
    # Get the file name.
    #
    my $fin = shift;

    # Let's open the file and read it into a single string.
    #
    open(FIN, "< $fin") or die "\nError when open < $fin: $!";
    my @content = <FIN>;
    close FIN;
    my $cont = join("", @content);
    
    # Remove comments and empty lines.
    #
    $cont =~ s{\s*//.*$}{}mg;    # remove one-line comments
    $cont =~ s{/\*.+?\*/}{}sg;   # remove C comments
    $cont =~ s{\n\s*\n}{\n}sg;   # remove empty lines    

    # Extract the class and base class identifiers.  Remove the 
    # opening curly brace.  Remove also the first "public:"
    # Put the class and the base class into the output list.
    #
    $cont =~ s{^.*class\s+(Translator\w+)[^:]*:
                \s*public\s+(\w+)\b.*?\{\s*
                (public\s*:\s+)?
              }
              {}sx;
    
    @content = ($1, $2);
    
    # Cut the things after the class.
    #
    $cont =~ s{\}\s*;\s*#endif\s*$}{}s;
    
    # Remove the "virtual" keyword, because some the derived class
    # is not forced to use it.
    #
    $cont =~ s{^\s*virtual\s+}{}mg;

    # Remove all strings from lines.
    #
    $cont =~ s{".*?"}{}mg;
    
    # Remove all bodies of methods;
    #
    while ($cont =~ s/{[^{}]+?}//sg) {}
    
    # Remove all private methods, i.e. from "private:" to "public:"
    # included.  Later, remove also all from "private:" to the end.
    #
    $cont =~ s{private\s*:.*?public\s*:}{}sg;
    $cont =~ s{private\s*:.*$}{}s;

    # Some of the translators use conditional compilation where 
    # the branches define the body of the method twice.  Remove
    # the ifdef/endif block content.
    # 
    $cont =~ s{#ifdef.*?#endif}{}sg;
    
    # Now the string should containt only method prototypes.
    # Let's unify their format by removing all spaces that 
    # are not necessary.  Then let's put all of them on separate
    # lines (one protototype -- one line; no empty lines).
    #
    $cont =~ s{\s+}{ }sg;
    $cont =~ s{^\s+}{}s;
    $cont =~ s{\s+$}{}s;
    
    $cont =~ s{\s+\(}{(}g;
    $cont =~ s{\)\s*}{)\n}g;
    
    # Split the string and add it to the ouptut list.
    #
    @content = (@content, split(/\n/, $cont));
    return @content;
}
##}}}


################################################################
# GenerateLanguageDoc takes document templates and code sources
# generates the content as expected in the $flangdoc file (the
# part of the Doxygen documentation), and returns the result as a
# string.
#
sub GenerateLanguageDoc ##{{{
{
    # Get the references to the hash of class/base class.
    #
    my $rcb = shift;
    
    # Define templates for HTML table parts of the documentation. #{{{
    #
    my $htmlTableHead = <<'xxxTABLE_HEADxxx';
\htmlonly
<TABLE ALIGN=center CELLSPACING=0 CELLPADDING=0 BORDER=0>
<TR BGCOLOR="#000000">
<TD>
  <TABLE CELLSPACING=1 CELLPADDING=2 BORDER=0>
  <TR BGCOLOR="#4040c0">
  <TD ><b><font size=+1 color="#ffffff"> Language </font></b></TD>
  <TD ><b><font size=+1 color="#ffffff"> Maintainer </font></b></TD>