home *** CD-ROM | disk | FTP | other *** search
/ Nebula 2 / Nebula Two.iso / SourceCode / MiscKit1.7.1 / MiscKit / Examples / AutoDoc / lib / perl5 / Autodoc / ScanFile.pm < prev   
Encoding:
Perl POD Document  |  1995-11-02  |  11.2 KB  |  393 lines
  1. package Autodoc::ScanFile;
  2.  
  3. ###############################################################################
  4. ###############################################################################
  5. ##
  6. ##    Written by Adam Swift (c) 1995 by Friday Software and Consulting
  7. ##                           All rights reserved.
  8. ##
  9. ##      This notice may not be removed from this source code.
  10. ##
  11. ##    This program is included in the MiscKit by permission from the author
  12. ##    and its use is governed by the MiscKit license, found in the file
  13. ##    "LICENSE.rtf" in the MiscKit distribution.  Please refer to that file
  14. ##    for a list of all applicable permissions and restrictions.
  15. ##
  16. ##    Because AutoDoc is licensed free of charge, there is no warranty 
  17. ##    for the program.  Copyright holder, Friday Software and Consulting, 
  18. ##    is providing this program "as is" and this program is distributed in 
  19. ##    the hope that it will be useful, but WITHOUT ANY WARRANTY; without 
  20. ##    even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
  21. ##    PARTICULAR PURPOSE.
  22. ##
  23. ###############################################################################
  24. ###############################################################################
  25.  
  26. require 5.000;
  27.  
  28. ##########################
  29. # load required packages #
  30. ##########################
  31. use Exporter;
  32. use Autodoc::LogDebug;
  33.  
  34. @ISA      = qw(Exporter);
  35. @EXPORT   = qw(scan_line
  36.                scan_rescanline
  37.                scan_eoffound
  38.                scan_closefile
  39.                scan_openfile
  40.                scan_skipCStyleComments
  41.                scan_keepADCNewlines
  42.                scan_postprocess);
  43.  
  44. $module_version = '$Revision: 1.2 $';
  45. $module_version =~ s!(\$\w+: | \$)!!g;
  46. $module_id        = '$Id: ScanFile.pm,v 1.2 1995/10/20 22:16:29 aswift Exp $';
  47. $module_id      =~ s!(\$\w+: | \$)!!g;
  48. $module_name    = $module_id;
  49. $module_name    =~ s!^([^\,]+).*$!$1!;
  50.  
  51. ############################################################################
  52. # 
  53. # Purpose: Module that encapsulates scanning text out of files, specifically
  54. #          designed to scan entire autodoc style comments that span multiple
  55. #          lines.
  56. #
  57. # HISTORY: START
  58. # $Log: ScanFile.pm,v $
  59. # Revision 1.2  1995/10/20  22:16:29  aswift
  60. # Added DevMan style changes Log support
  61. #
  62. #
  63. # HISTORY: END
  64. ############################################################################
  65.  
  66. #############################################################################
  67. #
  68. # NAME:       module_version
  69. #
  70. # ACTION:     returns the version number of this module
  71. #
  72. # RETURN:     the module version
  73. #
  74. #############################################################################
  75. sub module_version
  76. {
  77.     return $module_version;
  78. }
  79.  
  80. sub module_versionstamp
  81. {
  82.     return "$module_name (rev-$module_version)";
  83. }
  84.  
  85. #############################################################################
  86. #
  87. # NAME:       scan_rescanline
  88. #
  89. # ACTION:     Sets a global variable so that scan_line will return the last
  90. #             line it returned - if no argument is passed, the current value
  91. #             will be returned
  92. #
  93. # GLOBALS:    $scan_repeatlast
  94. #
  95. # ARGUMENTS:  An argument may be passed to set $scan_skipCStyleComments
  96. #
  97. # RETURN:     1 if the next call to scan_line will return the previous line
  98. #             scanned, 0 if the next call will 
  99. #
  100. #############################################################################
  101. sub scan_rescanline
  102. {
  103.     $scan_repeatlast = 0 if (!defined($scan_repeatlast));
  104.     $scan_repeatlast = $_[0] if (scalar(@_) > 0);
  105.     return $scan_repeatlast;
  106. }
  107.  
  108.  
  109. #############################################################################
  110. #
  111. # NAME:       scan_eoffound
  112. #
  113. # ACTION:     Returns 1 if there is a file open and the end of file has
  114. #             been encountered, 0 otherwise
  115. #
  116. # GLOBALS:    $scan_eoffound - YES if the end of file has been detected
  117. #             $scan_fileopen - YES if there is a file open
  118. #
  119. # ARGUMENTS:  none
  120. #
  121. #############################################################################
  122. sub scan_eoffound
  123. {
  124.     if (defined($scan_fileopen) && ($scan_fileopen == 1)) {
  125.     $scan_eoffound = eof(SCANFILE);
  126.     return $scan_eoffound;
  127.     } else {
  128.     return 0;
  129.     }
  130. }
  131.  
  132.  
  133. #############################################################################
  134. #
  135. # NAME:       scan_closefile
  136. #
  137. # ACTION:     Closes the file currently open - if any.
  138. #
  139. # GLOBALS:    $scan_eoffound - YES if the end of file has been detected
  140. #             $scan_fileopen - YES if there is a file open
  141. #
  142. # ARGUMENTS:  none
  143. #
  144. #############################################################################
  145. sub scan_closefile
  146. {
  147.     if (defined ($scan_fileopen) && ($scan_fileopen == 1)) {
  148.     close (SCANFILE);
  149.     }
  150.     $scan_fileopen = 0;
  151.     $scan_eoffound = 0;
  152. }
  153.  
  154.  
  155. #############################################################################
  156. #
  157. # NAME:       scan_openfile
  158. #
  159. # ACTION:     Opens the file passed as the argument and sets the relevent 
  160. #             globals appropriatly
  161. #
  162. # GLOBALS:    $scan_eoffound - YES if the end of file has been detected
  163. #             $scan_fileopen - YES if there is a file open
  164. #
  165. # ARGUMENTS:  The path of the file to be opened
  166. #
  167. # RETURN:     Returns 0 if it fails, 1 if it succeeds
  168. #
  169. #############################################################################
  170. sub scan_openfile
  171. {
  172.     local ($filename);
  173.  
  174.     $filename = $_[0];
  175.     scan_closefile();
  176.  
  177.     if (!(open (SCANFILE, $filename))) {
  178.     warn ("Unable to open file: $filename\n");
  179.     return 0;
  180.     } else {
  181.     $scan_fileopen = 1;
  182.     dblog (1, "Scanning from file:\t$filename");
  183.     return 1;
  184.     }
  185. }
  186.  
  187.  
  188. #############################################################################
  189. #
  190. # NAME:       scan_skipCStyleComments
  191. #
  192. # ACTION:     Sets a global variable so that scan_line will keep or discard 
  193. #             c-style comments in its return - if no argument is passed, 
  194. #             the current value will be returned
  195. #
  196. # GLOBALS:    $scan_skipCStyleComments
  197. #
  198. # ARGUMENTS:  An argument may be passed to set $scan_skipCStyleComments
  199. #
  200. # RETURN:     1 if it is skipping c-style comments, 0 otherwise
  201. #
  202. #############################################################################
  203. sub scan_skipCStyleComments
  204. {
  205.     $scan_skipCStyleComments = 0 if (!defined($scan_skipCStyleComments));
  206.     $scan_skipCStyleComments = $_[0] if (scalar(@_) > 0);
  207.     return $scan_skipCStyleComments;
  208. }
  209.  
  210.  
  211. #############################################################################
  212. #
  213. # NAME:       scan_keepADCNewlines
  214. #
  215. # ACTION:     Sets a global variable so that scan_line will keep or discard
  216. #             newlines from autodoc comments - if no argument is passed, 
  217. #             the current value will be returned
  218. #
  219. # GLOBALS:    $scan_keepADCNewlines
  220. #
  221. # ARGUMENTS:  An argument may be passed to set $scan_keepADCNewlines
  222. #
  223. # RETURN:     1 if it is keeping newlines, 0 otherwise
  224. #
  225. #############################################################################
  226. sub scan_keepADCNewlines
  227. {
  228.     $scan_keepADCNewlines = 1 if (!defined($scan_keepADCNewlines));
  229.     $scan_keepADCNewlines = $_[0] if (scalar(@_) > 0);
  230.     return $scan_keepADCNewlines;
  231. }
  232.  
  233.  
  234. #############################################################################
  235. #
  236. # NAME:       scan_line
  237. #
  238. # ACTION:     Read and return a line from the passed file handle.  
  239. #             Ignore blank lines.  Always scan up to the AutoDoc comment 
  240. #             end if we encounter an AutoDoc comment start on a line.  
  241. #             If the $scan_keepADCnewlines is true, encode the newlines into 
  242. #             the string, since they affect paragraph formatting
  243. #             in the documentation.
  244. #
  245. #             If $scan_repeatlast is TRUE return the last line scanned in.  
  246. #             $scan_ok records whether the eof has been enountered
  247. #
  248. # GLOBALS     $scan_repeatlast - YES if the previous line should be returned
  249. #             $scan_lastline - the last line that was scanned by scan line
  250. #             $scan_fileopen - 1 if a scan file is open (SCANFILE is valid)
  251. #
  252. # ARGUMENTS:  none
  253. #
  254. # RETURN:     A string containing the last line scanned from the file
  255. #
  256. #############################################################################
  257. sub scan_line
  258. {
  259.     local ($in, $inputline, $findADCend, $findCSCend, $rescan);
  260.  
  261.     use Autodoc::LogDebug;
  262.  
  263.     # return the last line scanned if $scan_lastline is 1
  264.     if (scan_rescanline()) {
  265.     scan_rescanline(0);
  266.     if (defined($scan_lastline)) {
  267.         dblog (4, "Repeating last scan_line: [$scan_lastline]");
  268.         return $scan_lastline;    # return last line scanned
  269.     } else {
  270.         dblog (4, "Repeating last scan_line: --no last scan_line--");
  271.         return "";
  272.     }
  273.     }
  274.     $in          = "";
  275.     $inputline   = "";
  276.     $findADCend  = 0;
  277.     $rescan      = 0;
  278.  
  279.   SCANLINE:            
  280.     while (1) {
  281.  
  282.     if ($rescan == 0) {
  283.         # scan in the next line for processing
  284.         if ((!defined ($scan_fileopen)) || ($scan_fileopen == 0)) {
  285.         dblog (1, "No scan file open, scan_line failed.\n");
  286.         return "";        # return FALSE
  287.         }
  288.         if (scan_eoffound()) {
  289.         dblog (1, "EOF reached, scan_line couldn\'t read line.");
  290.         return "";        # return FALSE
  291.         }
  292.         $in = <SCANFILE>;
  293.         chop ($in) if ($in =~ m!\n$!);
  294.     } else {
  295.         # process whatever is in $in again
  296.         $rescan = 0;
  297.     }
  298.  
  299.     if (scan_skipCStyleComments()) {
  300.         if ($findCSCend) {
  301.         if ($in =~ m!\*+/!) {
  302.             $findCSCend = 0;
  303.             $in = $';    # continue processing with the remaining text
  304.         } else {
  305.             next SCANLINE; # scan a new line and look for the CSC end
  306.         }
  307.         }
  308.  
  309.         # ignore anything after a '//' found on a line
  310.         $in = $` if ($in =~ m!//!);
  311.  
  312.         if (($in =~ m!/\*!) && !($in =~ m!/\*+\"!)) {
  313.         # check for a single line comment
  314.         if ($in =~ m!/\*+[^\"].*\*+/!) {
  315.             $in = "$`$'";
  316.             $rescan = 1;
  317.             next SCANLINE; # make sure there aren't more comments
  318.         } else {
  319.             $inputline .= $`;
  320.             $findCSCend = 1;
  321.             next SCANLINE;
  322.         }
  323.         }
  324.     }
  325.  
  326.     # scan the whole AutoDoc style comment into the $inputline
  327.     if ($findADCend) {
  328.  
  329.         # kill any '*'s that appear on the beginning of the line 
  330.         $in = $' if ($in =~ m!^\s*\*+!);
  331.  
  332.         if (scan_keepADCNewlines() && !($in =~ m/\S+/)) {
  333.         $inputline .= "\\n"; # blank lines make newlines in docs
  334.         } else {
  335.         $inputline .= " ";
  336.         }
  337.         if (!($in =~ m!\*+/!)) {
  338.  
  339.         $inputline .= $in;
  340.         next SCANLINE;    # Keep looking...
  341.         } else {        # Found the ADC end
  342.         $findADCend = 0;
  343.         }
  344.     } else {
  345.         # read to end of autodoc comment if we are inside one
  346.         if (($in =~ m!/\*+\"!) && !($in =~ m!\*+/!)) {
  347.         $inputline .= $in;
  348.         $findADCend = 1;
  349.         next SCANLINE;
  350.         }
  351.     }
  352.  
  353.     $inputline .= $in;
  354.     if ($inputline =~ m/\S+/) {
  355.         last SCANLINE;    # found data on a line, so return it
  356.     }             
  357.     }
  358.     
  359.     $scan_lastline = &scan_postprocess($inputline);
  360.  
  361.     dblog (4, "scanned[$scan_lastline]");
  362.     return $scan_lastline;        # return new $scan_lastline
  363. }
  364.  
  365.  
  366. #############################################################################
  367. #
  368. # NAME:       scan_postprocess
  369. #
  370. # ACTION:     Removes whitespace from the beginning and end of the string, 
  371. #             and compresses all whitespace runs into a single space
  372. #
  373. # ARGUMENTS:  The string to be processed
  374. #
  375. # RETURN:     Returns the processed version of the line
  376. #
  377. #############################################################################
  378. sub scan_postprocess
  379. {
  380.     local ($line);
  381.  
  382.     $line = $_[0];
  383.  
  384.     $line =~ s!\s*$!!;        # remove whitespace from the end of the line
  385.     $line =~ s!^\s*!!;            # and the beginning of the line
  386.     $line =~ s/\s+/ /g;        # turn all whitespace into a single space
  387.  
  388.     return $line
  389. }
  390.  
  391. 1;
  392.     
  393.