apidoc.pl

mini http server,可以集成嵌入到程序中,实现简单的web功能

#!/usr/bin/perl

#*____________________________________________________________________________*\
#*
#
# Copyright (c) 1997-2003 John Roy, Holger Zimmermann. All rights reserved.
# These sources, libraries and applications are
# FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
# as long as the following conditions are adhered to.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
# 1. Redistributions of source code must retain the above copyright
#    notice, this list of conditions and the following disclaimer. 
#
# 2. Redistributions in binary form must reproduce the above copyright
#    notice, this list of conditions and the following disclaimer in
#    the documentation and/or other materials provided with the
#    distribution.
#
# 3. The name of the author may not be used to endorse or promote products
#    derived from this software without specific prior written permission. 
#
# THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
# WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
# IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
# GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
# OF THE POSSIBILITY OF SUCH DAMAGE.
#
#*____________________________________________________________________________*|
#*
#* $Source: /cvsroot/pi3web/Pi3Web_200/Source/Scripts/apidoc.pl,v $
#* $Date: 2003/05/13 18:42:17 $
#*
# Description:
#	Create HTML API documentation given comments in header files.
#
# Parameters
#	ARGV[0] - name of HTML file to create. Full path or relative from
#				current directory.
#	ARGV[1] - name of the index datafile to create. Full path or relative from
#				current directory.
#	ARGV[2..n] - Header files (relative from current directory, or full path )
#				to look in
#
# Note:
#	This script could order elements a number of ways, the variable $entry
#	exists to maintain the order of paragraphs for a function in the
#	original order encountered in the source file. The same could be
#	done for the functions themselves, but is not, functions are inserted
#	into the hash table and sorted before print, so functions are listed
#	untimately in alphabetical order regardless of there original order
#	in the source files
#
#*____________________________________________________________________________*/

#/*___________________________________________________________________________*\
# Global declarations:
#\*___________________________________________________________________________*/
%Hoh;
$entry = 0;
$canonical_name = "";

&do_main( @ARGV );

#/*___________________________________________________________________________*\
# *
# Function:
# Synopsis:
# Description:
#\*___________________________________________________________________________*/
sub do_main
	{
	local( $index_file ) = shift;
	local( $data_file ) = shift;
	print "#\n# apidoc.pl, generating files '$index_file' and '$data_file' \n#\n";
	if ( $^O =~ /MSWin32/ )
		{
		local( @args );
		foreach( @_ ) { push @args, glob; };
		@_=@args;
		};
	foreach( @_ )
		{
		print "apidoc.pl: Scanning $_...\n";
		open( INP, '<'.$_ ) || die "Cannot open file $_: $!\n";
		&process_file();
		close( INP );
		};
	open( OUT, '>'.$index_file ) ||
		die "Cannot open file $index_file: $!\n";
	print OUT '<!--
/*____________________________________________________________________________*\
 *
	*** AUTOMATICALLY GENERATED FILE: DO NOT MODIFY ***
\*____________________________________________________________________________*/
/* $SourceTop:$ */

-->

';
	# print index
	print OUT "<HR><DIR COMPACT>\n";
	print OUT "<A NAME=\"___index\"\n";
	local( $tmp );
	foreach $tmp ( sort keys( %Hoh ) )
		{
		local( $can_name ) = split( /:\s*/, $tmp, 2 );
		local ( $name, $para ) = split( /:\s*/, $Hoh{$tmp}, 2 );
		$_ = $name;
		if ( /Name/ )
			{
			print OUT "<A HREF=\"#$can_name\">$can_name</A><BR>\n";
			};
		};
	print OUT "</DIR>\n";
	print OUT "<P>\n";
	
	# print data
	foreach $tmp ( sort( keys( %Hoh ) ) )
		{
		local( $can_name, $entry ) = split( /:\s*/, $tmp, 2 );
		local ( $name, $para ) = split( /:\s*/, $Hoh{$tmp}, 2 );
		&PrintParagraph( $name, $para );
		};
	print OUT "\n";
	close( OUT );

	# 
	# generate the datafile for indexing
	#
	open( OUT, '>>'.$data_file ) ||
		die "Cannot open file $data_file: $!\n";
	$_ = $index_file;
	s/\.\.\/\.\.\/Pi3Docs\//\/pidocs\//;
	$index_file = $_;
	foreach $tmp ( sort( keys( %Hoh ) ) )
		{
		local( $can_name, $entry ) = split( /:\s*/, $tmp, 2 );
		if ( $entry =~ "A" ) 
			{
			print OUT "$can_name: ".&GetURLPath($index_file)."#$can_name\n";
			};
		};
	close( OUT );
	};

#/*___________________________________________________________________________*\
# *
# Function:
# Synopsis:
# Description:
#	Recognise sections of header comments by moving the scanner through the
#	following states.
#\*___________________________________________________________________________*/
sub process_file
	{
	local( $state, $para );
	$state = 1;
	while( <INP> )
		{
		if ( $state == 1 )
			{
			if ( /\/\*____________________________________________________________________________\*\\.*/ )
				{ $state = 2; $para = ""; next; };
			}
		elsif ( $state == 2 )
			{
			if ( /(\w)*Name:(.)*/ )
				{ $state = 3; $para = ""; next; };
			}
		elsif ( $state == 3 )
			{
			if ( /(\w)*Synopsis:(.)*/ )
				{ &emit("Name", $para); $state = 4; $para = ""; next; };
			}
		elsif ( $state == 4 )
			{
			if ( /(\w)*Description:(.)*/ )
				{ &emit("Synopsis", $para); $state = 5; $para = ""; next; };
			}
		elsif ( $state == 5 )
			{
			if ( /(\w)*Notes:(.)*/ )
				{ &emit("Description",$para), $state = 6; $para = ""; next; };
			}
		elsif ( $state == 6 )
			{
			if ( /(\w)*Return Values:(.)*/ )
				{ &emit("Notes",$para); $state = 7; $para = ""; next; };
			}
		elsif ( $state == 7 )
			{
			if ( /(\w)*Errors:(.)*/ )
				{ &emit("Return Values",$para); $state = 8; $para = ""; next; };
			}
		elsif ( $state == 8 )
			{
			if ( /(\w)*See Also:(.)*/ )
				{ &emit("Errors",$para); $state = 9; $para = ""; next; };
			}
		elsif ( $state == 9 )
			{
			if ( /\\\*____________________________________________________________________________\*\/.*/ )
				{ &emit("See Also",$para); $state = 1; $para = ""; next; };
			};
		$para = $para.$_;
		};
	};

#/*___________________________________________________________________________*\
# *
# Function:
# Synopsis:
# Description:
#\*___________________________________________________________________________*/
sub emit
	{
	local( $name, $para ) = @_;

	$_=$name;
	if ( /Name/ )
		{
		$entry = 64;
		$canonical_name = &GetCanonicalName($para);
		};
	$entry = $entry+1;

	$Hoh{$canonical_name.": ".pack("c", $entry)} = $name.": ".$para;
	}

#/*___________________________________________________________________________*\
# *
# Function:
# Synopsis:
# Description:
#\*___________________________________________________________________________*/
sub PrintParagraph
	{
	( $name, $para ) = @_;

	$_ = $name;
	if ( /Name/ )
		{
		print OUT "<HR><A NAME=\"".&GetCanonicalName($para)."\">";
		};
	print OUT "<P><B>".$name.":</B><BR>";

	$_ = $name;
	if ( /See Also/ )
		{
		#
		# strip space characters and make each reference to a link;
		#
		$_ = $para;
		s/\s+/ /g; s/[,|.]//g; s/\(\)//g;
		foreach ( split( / / ) )
			{
			local( $name ) = &GetCanonicalName($_);
			print OUT "<A HREF=\"#$name\">$name</A> ";
			};
		print OUT "<P><A HREF=\"#___index\">Return to index</A>\n";
		}
	else
		{
		print OUT $para;
		};
	}

#/*___________________________________________________________________________*\
# *
# Function:
# Synopsis:
# Description:
#\*___________________________________________________________________________*/
sub GetCanonicalName
	{
	$_ = shift;
	s/^(\s*)(.*)(\s*)$/$2/g;
	return $_;
	};

#/*___________________________________________________________________________*\
# *
# Function:
# Synopsis:
# Description:
#\*___________________________________________________________________________*/
sub GetURLPath
	{
	( $_ ) = shift;
	s/\\\\/\//g;
	s/.*\/+Pi3Docs\/+/\/pidocs\//;
	return $_;
	};