Contents 
 Index 
 "Perl Program Reference" 
 < Previous 
 Next > 

sapi_check.pl

Go to the documentation of this file.
00001 // This file has been modified on-the-fly with an input filter
00002 // to change it from Perl syntax to C++ strictly for the purposes
00003 // of faking out Doxygen. Modifications include:
00004 
00005 // - changing local() definitions to C++ #define statements.
00006 // - commenting out undef statements.
00007 // - changing $globe'... variable names to $globe_...
00008 // - changing sub statements to look like C++ functions.
00009 // - changing # comments to C++ comments.
00010 // - ...
00011 
00012 // If you see other strangeness in the HTML version of the Perl file,
00013 // it comes from getting it to look more C++ like.
00014 
00015 
00016 // #!/usr/#define/bin/perl
00017 package scheck;
00018 //#############################################################################
00019 /** @file
00020  ** @brief Checks the generated SAPI files for completeness.
00021  ** 
00022  ** This uses the "sapi.pm" file that is generated by the "vproto.pl" tool.
00023  ** It can be named something else, but is the $scope_pm input variable
00024  ** to this program.
00025  ** 
00026  ** The "sapi.pm" file was intended for use with the xhelp tool for reducing noise.
00027  ** It has several data structures defined and then // undefined. They were defined
00028  ** because they could have been useful in locating the proper methods and
00029  ** doxygen comments in the code. (It turns out that the ingroup is more
00030  ** effective at that.)
00031  ** 
00032  ** Those data structures were // undefined (with "if (1)" enclosing an
00033  ** "// undef") so that they wouldn't result in unnecessary grep operations.
00034  ** 
00035  ** Those data structures, however, are useful for testing the integrity of
00036  ** the system in terms of missing commands.
00037  ** 
00038  ** This tool expects you to turn off ("if (0)") these // undefinition within the 
00039  ** the sapi.pm file. Run this tool and look at the output.
00040  **
00041  ** @ingroup tp_tools tp_xhelp
00042  **
00043  ** @author Glenn C. Maxey
00044  **/
00045 // #
00046 //#    $Id: sapi_check.pl,v 1.2 2002/11/20 01:49:13 gmaxe Exp $
00047 //#
00048 //# Copyright 2002 Created by Voyant Technologies, Inc., Westminster, Colorado, USA.
00049 //#
00050 //# Revision Information:
00051 //#
00052 //# $Log: sapi_check.pl,v $
00053 //# Revision 1.2  2002/11/20 01:49:13  gmaxe
00054 // //# Minor changes to exit codes.
00055 //#
00056 //# Revision 1.1  2002/04/12 22:52:25  gmaxe
00057 //# New tool to check on whether or not all SAPI commands are present.
00058 //# Uses the files generated by the vproto_gen.pl tool.
00059 //#
00060 //#
00061 //#############################################################################
00062 
00063 //#############################################################################
00064 /** @fn int BEGIN
00065  ** @brief Code to execute when first entered.
00066  **
00067  ** @param None. 
00068  **
00069  ** @return None.
00070  **
00071  ** @lim None
00072  ** @ingroup tp_xhelp
00073  **/
00074 // #############################################################################
00075 int BEGIN  ( ) {
00076 //    print "\n============  Starting sapi_check.pl ==================================\n";
00077    $_file_list = "_file_list";
00078    $in_file = "";
00079    $root_path = "./";
00080    $scope_pm = "";
00081    $no_scope_file = 0;
00082    $arg_cnt=0;
00083    
00084    push (@INC, `pwd`);
00085    push (@INC, '../perl');
00086    if (0){
00087 //       print (@INC, "\n");
00088    }
00089    
00090    //  Get scope files if there is one.
00091    if (@ARGV > $arg_cnt) {
00092       $scope_pm = @ARGV[$arg_cnt];
00093       
00094       unless (open ( IN_LIST, $scope_pm)) {
00095          push (@file_errors, "Cannot open file \"$scope_pm\"");
00096          $no_scope_file++;
00097       }
00098 //       close (IN_LIST);
00099       push (@INC, $scope_pm);
00100       
00101       if (!@file_errors) {
00102          // ####
00103          //  All global variables are defined in the following file
00104          // ####
00105          require $scope_pm;
00106    
00107          if (&xscope::declare_variables()) {
00108 //             print "Variables initialized from $scope_pm.\n";
00109          } else {
00110             push (@file_errors, "Could not initialize variables from $scope_pm.");
00111          }
00112       } //  if not @file_errors
00113    } else {
00114       push (@file_errors, "Need to provide a scope file as first argument.");
00115    } //  if 1 or more arguments
00116    $arg_cnt++;
00117 
00118   if (0) { //  not used
00119    //  Get path to code files 
00120    if (@ARGV > $arg_cnt) {
00121       $root_path = @ARGV[$arg_cnt];
00122       if ($root_path =~ /\/$/) {
00123 //          print "The path specified is $root_path\n";
00124       } else {
00125          push (@file_errors, "The input argument \"$root_path\" requires a forward slash (\/) at the end.\n");
00126       }
00127    } //  if 1 or more arguments
00128    $arg_cnt++;
00129   } //  not used
00130 
00131    if (@ARGV > $arg_cnt) {
00132       $gen_proto = @ARGV[$arg_cnt];
00133 //       print "The prototype input file is $gen_proto \n";
00134    } else {
00135       push (@file_errors, "Need to have the input prototype file.");
00136    } //  if 3 or more arguments
00137    $arg_cnt++;
00138 
00139 
00140    if (@ARGV > $arg_cnt) {
00141       $gen_class_dox = @ARGV[$arg_cnt];
00142 //       print "The class methods with doxygen comments is $gen_class_dox \n";
00143    } else {
00144       push (@file_errors, "Need to have the input class doxygen file.");
00145    } //  if 3 or more arguments
00146    $arg_cnt++;
00147 
00148    if (@ARGV > $arg_cnt) {
00149       $gen_error_out = @ARGV[$arg_cnt];
00150 //       print "The output file will be $gen_error_out \n";
00151    } else {
00152       push (@file_errors, "Need to have an output file for the results.");
00153    } //  if 3 or more arguments
00154    $arg_cnt++;
00155 
00156 
00157 } //  BEGIN
00158    
00159    
00160    
00161 
00162 //#############################################################################
00163 /** @fn int main
00164  ** @brief The main program.
00165  **
00166  ** @param file_errors If file errors are encountered before the main
00167 //  ** routine is hit, it prints them out and exits. 
00168  **
00169  ** @return None.
00170  **
00171  ** If the needed data structures in $scope_pm have not been enabled,
00172  ** this program errors out immediately.
00173  ** 
00174  ** Controls the program flow. It creates a temporary file with the
00175  ** error results.
00176  **
00177  ** @lim None
00178  ** @ingroup tp_xhelp
00179  **/
00180 // #############################################################################
00181 // sub main {
00182 {
00183    if (!@xscope::x_names) {
00184 //       print "\nThe \"$scope_pm\" file should have been generated with \"\@x_names\" completed.\n";
00185 //       print "Then \"\@x_names\" was probably turned off inside of an \"if (1) {\" statement\"\n";
00186       print "that \"// undef(\@x_names)\".\n\n";
00187 //       print "If this is the case, edit \"$scope_pm\" and change turn this off with\n";
00188 //       print "\"if (0) {\"\n";
00189       push (@file_errors, "Edit \"$scope_pm\" to enable \"\@x_names\".");
00190    }
00191    if (!@xscope::needed_in) {
00192 //       print "\nThe \"$scope_pm\" file should have been generated with \"\@needed_in\" completed.\n";
00193 //       print "Then \"\@needed_in\" was probably turned off inside of an \"if (1) {\" statement\"\n";
00194       print "that \"// undef(\@needed_in)\".\n";
00195 //       print "\nIf this is the case, edit \"$scope_pm\" and change turn this off with\n";
00196 //       print "\"if (0) {\"\n";
00197       push (@file_errors, "Edit \"$scope_pm\" to enable \"\@needed_in\".");
00198    }
00199    // #############################################################################
00200    // # Start of Main Program
00201    // #############################################################################
00202    if (@file_errors) {
00203       //  Makes no sense to go on if input parameters are off.
00204 //       print "\n============  Summary of errors ==================================\n";
00205       for ($i=0; $i<@file_errors; $i++){
00206 //          print "$i = $file_errors[$i]\n";
00207       }
00208       &scheck::using_scheck();
00209 //       exit(1);
00210    }
00211    
00212    if ((0) && (!(&read_and_check($gen_proto, "proto")))){
00213 //       print "$gen_proto failed some things.\n";
00214    } 
00215    if ((1) && (!(&read_and_check($gen_class_dox, "class")))){
00216 //       print "$gen_class_dox failed some things.\n";
00217    }
00218    
00219    if (1) {
00220       &write_output_list($gen_error_out);
00221    }
00222    
00223    // #############################################################################
00224    // # Spit out errors
00225    // #############################################################################
00226    if (@file_errors) {
00227 //       print "\n============  Summary of errors ==================================\n";
00228       for ($i=0; $i<@file_errors; $i++){
00229 //          print "$i = $file_errors[$i]\n";
00230       }
00231    }
00232 
00233    // #############################################################################
00234    // # End of most of work
00235    // #############################################################################
00236 //    exit(0);
00237 }
00238 
00239 //#############################################################################
00240 /** @brief Reads in the entire generated file and kicks off a routine to
00241  ** to the actual test.
00242  ** 
00243  ** @param src_file The file to open and read in.
00244  ** @param which_test Specifies which other test to run. Presently either
00245  ** "proto" or "class".
00246  ** 
00247  ** @lim When reading in the file and the later test is "proto", this doesn't
00248  ** bother to read in comment lines.
00249  **/
00250 // #############################################################################
00251 int read_and_check  ( ) {
00252    #define $src_file  $_[0]
00253    #define $which_test  $_[1]
00254    // undef ($globe::entire_file);
00255    unless (open ( IN_SRC, $src_file)) {
00256 //       print "Cannot open file \"$src_file\"\n";
00257       push (@file_errors, "Cannot open file \"$src_file\"\n");
00258       $ret_val = 0;
00259       return (0);
00260    }
00261    while (<IN_SRC>) {
00262       if ($which_test =~ /proto/){
00263          if (($_ !~ /\/\//) && ($_ !~ /\/\*/)){
00264             //  Only read in non-comment lines.
00265             $globe::entire_file .= $_;
00266          }
00267       } else {
00268          $globe::entire_file .= $_;
00269       }
00270    }
00271    if ($which_test =~ /proto/){
00272       $ret_val = &check_prototype($src_file);
00273    } elsif ($which_test =~ /class/){
00274       $ret_val = &check_class_dox($src_file);
00275    } else {
00276 //       print "The test specified, \"$which_test\" is invalid.\n";
00277       $ret_val = 0;
00278    }
00279 //    close (IN_SRC);
00280    if (0) {
00281 //       print $globe::entire_file;
00282 //       exit(1);
00283    }
00284    return ($ret_val);
00285 } //  read_and_check
00286 
00287 //#############################################################################
00288 /** @brief Checks the file that contains prototypes against the data structure
00289  ** created in an earlier process and part of the $scope_pm file.
00290  ** 
00291  ** @param in_file A notation of the file that the information was checked
00292  ** against.
00293  ** 
00294  ** This loops through the (enabled) data structure to make sure that those
00295  ** keywords appear somewhere in the file. It is assumed that their occurrence
00296  ** means that they have been defined.
00297  ** 
00298  ** If the keyword from the data structure does not appear in the file,
00299  ** this logs and error to @file_error for later output.
00300  ** Not all errors are true errors.
00301  **
00302  ** This checks for both the occurrence of the expected SAPI command (originally
00303  ** defined in vfuncs.inp).
00304  **/
00305 // #############################################################################
00306 int check_prototype  ( ) {
00307    #define $in_file  $_[0]
00308    push (@file_errors, "$in_file: Checking for prototypes in $in_file...");
00309 //    print "======\nChecking for prototypes in $in_file\n=====\n";
00310    foreach $item (@xscope::x_names){
00311       if ($globe::entire_file !~ /$item/){
00312          if (1) {
00313 //             print "$in_file: Missing prototype for \"$item\".\n";
00314          }
00315          push (@file_errors, "$in_file: Missing prototype for \"$item\".");
00316       }
00317       if (0) {
00318 //          print "$item\n";
00319       }
00320    }
00321 //    print "======\n\n";
00322    return (1);
00323 } //  check_prototype
00324 
00325 //#############################################################################
00326 /** @brief Checks the file that contains class definitions and doxygen
00327  ** comments and compares against the data structure
00328  ** created in an earlier process and part of the $scope_pm file.
00329  ** 
00330  ** @param in_file A notation of the file that the information was checked
00331  ** against.
00332  ** 
00333  ** This loops through the (enabled) data structure to make sure that those
00334  ** keywords appear somewhere in the file. It is assumed that their occurrence
00335  ** means that they have been defined.
00336  ** 
00337  ** If the keyword from the data structure does not appear in the file,
00338  ** this logs and error to @file_error for later output.
00339  ** Not all errors are true errors.
00340  **
00341  ** This checks for both the occurrence of the expected SAPI command (originally
00342  ** defined in vfuncs.inp) and the associated class method that implements
00343  ** the command.
00344  **/
00345 // #############################################################################
00346 int check_class_dox  ( ) {
00347    #define $in_file  $_[0]
00348    push (@file_errors, "\n\n>>>>> Checking for doxygen comment blocks in $in_file...");
00349 //    print "======\nChecking for doxygen comment blocks in $in_file\n=====\n";
00350    foreach $item (@xscope::x_names){
00351       if ($globe::entire_file !~ /$item/){
00352          if (1) {
00353 //             print "$in_file: Missing doxygen comment block for \"$item\".\n";
00354          }
00355          push (@file_errors, "$in_file: Missing doxygen comment block for \"$item\".");
00356       }
00357       if (0) {
00358 //          print "$item\n";
00359       }
00360    }
00361 //    print "======\n\n";
00362 
00363 
00364    push (@file_errors, "\n\n>>>>> Checking for C++ class definitions in $in_file...");
00365 //    print "======\nChecking for C++ class definitions in $in_file\n=====\n";
00366    foreach $item (@xscope::needed_in){
00367       if ($globe::entire_file !~ /$item/){
00368          if (1) {
00369 //             print "$in_file: Missing C++ class definitions for \"$item\".\n";
00370          }
00371          push (@file_errors, "$in_file: Missing C++ class definitions for \"$item\".");
00372       }
00373       if (0) {
00374 //          print "$item\n";
00375       }
00376    }
00377 //    print "======\n\n";
00378 
00379 
00380    return (1);
00381 } //  check_class_dox
00382 
00383 
00384 //#############################################################################
00385 /** @fn int write_output_list
00386  ** @brief Creates a file lists all of the potential errors discovered in
00387  ** the generated files.
00388  **
00389  ** @param file_out The name of the file to output.
00390  **
00391  ** @ingroup tp_xhelp
00392  **/
00393 // #############################################################################
00394 int write_output_list  ( ) {
00395    $file_out = $_[0];
00396 //    print "Writing the $file_out output file.\n";
00397    
00398    unless (open ( OUT_FILE, ">$file_out")) {
00399       push (@file_errors, "Cannot open file \"$file_out\"\n");
00400 //       print "Cannot open file \"$file_out\"\n";
00401    }
00402 //    print (OUT_FILE "This file contains a list of potential errors in the\n");
00403 //    print (OUT_FILE "SAPI generation process.\n\n");
00404 //    print (OUT_FILE "Not all of them are true errors, because it is known\n");
00405 //    print (OUT_FILE "that certain functions beginning with \":\" or \"__\"\n");
00406 //    print (OUT_FILE "are NOT really errors.\n\n");
00407 //    print (OUT_FILE "This list is just to serve as a starting point for\n");
00408 //    print (OUT_FILE "potentially missing items and maybe the class that\n");
00409 //    print (OUT_FILE "is supposed to define it.\n\n");
00410 //    print (OUT_FILE "==============================================================\n\n");
00411 
00412    for ($i=0; $i<@file_errors; $i++){
00413 //       print (OUT_FILE "$i = $file_errors[$i]\n");
00414    }
00415 //    close (OUT_FILE);
00416 } //  write_output_list
00417 
00418 
00419 //#############################################################################
00420 /** @fn int using_scheck
00421  ** @brief What to do when no arguments are given.
00422  ** @param None
00423  ** @return None
00424  ** 
00425  ** @lim None
00426  ** @ingroup tp_xhelp
00427  **/
00428 // #############################################################################
00429 int using_scheck  ( ) {
00430 //    print "============  Syntax  ==================================\n";
00431 //    print "sapi_check.pl <input scope package> <input prototype> <input class> <output file path \& name> \n\n";
00432 //    print "- <input scope package> is file path and name to a perl package that ";
00433 //    print "has lists of functions to be included and to be excluded.\n\n";
00434 //    print "- <input prototype> is file path and name the generated sapi prototype ";
00435 //    print "file that came from the vproto_gen.pl tool.\n\n";
00436 //    print "- <input prototype> is file path and name the generated sapi class ";
00437 //    print "file that came from the vproto_gen.pl tool; it has class member function ";
00438 //    print "definitions and their associated doxygen comments.\n\n";
00439 //    print "- <output file path \& name> is file path and name of error file ";
00440 //    print "of things that might be missing. \n\n";
00441 //    print "============  Terminate  ==================================\n";
00442 //    print "Terminating sapi_check.pl without doing anything.\n";
00443    return(1);
00444 }
00445 
00446 
00447 
00448 
00449 //#############################################################################
00450 /** @fn int END
00451  ** @brief Code to execute when terminated nicely.
00452  **
00453  ** @param None. 
00454  **
00455  ** @return None.
00456  **
00457  ** @lim None
00458  ** @ingroup tp_xhelp
00459  **/
00460 // #############################################################################
00461 int END  ( ) {
00462    // undef ($_file_list); //  "_file_list";
00463    // undef ($in_file ); //   "";
00464    // undef ($root_path ); //   "./";
00465    // undef (%file_hash);
00466 
00467    
00468    // #############################################################################
00469    // # Memory clean-up.
00470    // # Perform this if it was defined.
00471    // #############################################################################
00472    if ($no_scope_file > 0){
00473       &xscope::memory_clean_up();
00474    }
00475    
00476 //    print "\n============  Finished sapi_check.pl ==================================\n";
00477    
00478 } //  END
00479 


 "Perl Program Reference" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-perl-hcr-02