package Autodoc::ParseComments;

###############################################################################
###############################################################################
##
##    Written by Adam Swift (c) 1995 by Friday Software and Consulting
##                           All rights reserved.
##
##	  This notice may not be removed from this source code.
##
##    This program is included in the MiscKit by permission from the author
##    and its use is governed by the MiscKit license, found in the file
##    "LICENSE.rtf" in the MiscKit distribution.  Please refer to that file
##    for a list of all applicable permissions and restrictions.
##
##    Because AutoDoc is licensed free of charge, there is no warranty 
##    for the program.  Copyright holder, Friday Software and Consulting, 
##    is providing this program "as is" and 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.
##
###############################################################################
###############################################################################

require 5.000;

##########################
# load required packages #
##########################
use Exporter;
use Autodoc::ScanFile;

@ISA      = qw(Exporter);
@EXPORT   = qw(parse_extractADComment
	       parse_extract_preADComment
	       parse_extract_postADComment
	       parse_containsADComment);

$module_version = '$Revision: 1.2 $';
$module_version =~ s!(\$\w+: | \$)!!g;
$module_id    = '$Id: ParseComments.pm,v 1.2 1995/10/20 22:16:28 aswift Exp $';
$module_id      =~ s!(\$\w+: | \$)!!g;
$module_name	= $module_id;
$module_name	=~ s!^([^\,]+).*$!$1!;

############################################################################
# 
# Purpose: Module that encapsulates parsing autodoc style comments out of 
#          source code
#
# HISTORY: START
# $Log: ParseComments.pm,v $
# Revision 1.2  1995/10/20  22:16:28  aswift
# Added DevMan style changes Log support
#
#
# HISTORY: END
############################################################################

#############################################################################
#
# NAME:       module_version
#
# ACTION:     returns the version number of this module
#
# RETURN:     the module version
#
#############################################################################
sub module_version
{
    return $module_version;
}

sub module_versionstamp
{
    return "$module_name (rev-$module_version)";
}

#############################################################################
#
# NAME:       parse_extractADComment
#
# ACTION:     Extracts the portion of the string argument which contains 
#             an autodoc comment and processes it to remove extra whitespace
#
# ARGUMENTS:  The string (possibly) containing an autodoc comment
#
# RETURN:     The processed portion of the string which contains an autodoc 
#             comment, or an empty string if no comment was found.
#
#############################################################################
sub parse_extractADComment
{
    local ($ADcomment, $in);

    use Autodoc::ScanFile;

    $ADcomment = "";
    $in = $_[0];

    return "" if (!($in =~ m!/\*+\"(.*)\"\*+/!));

    
    $ADcomment = scan_postprocess($1);
    
    # remove marked newlines from the beginning of the line
    $ADcomment =~ s/^\s*\\n\s*// 
	while ($ADcomment =~ m/^\\n/);
    
    # remove marked newlines from the end of the line also
    $ADcomment =~ s/\s*\\n\s*$// 
	while ($ADcomment =~ m/\\n$/);	
    
#    $ADcomment =~ s/\s*\\n\s*\\n\s*/ \\n/g
#	while ($ADcomment =~ m/\\n\s*\\n/);	
#				# Remove all repeater newlines
    return $ADcomment;
}


#############################################################################
#
# NAME:       parse_containsADComment
#
# ACTION:     Returns 1 if the string passed as the argument conforms to 
#             the format of an autodoc comment.
#
# ARGUMENTS:  The string which is being tested
#
# RETURN:     1 if the string passed contains an autodoc comment, 0 otherwise.
#
#############################################################################
sub parse_containsADComment
{
    local ($in);

    $in = $_[0];

    return 1 if ($in =~ m!/\*+\".*\"\*+/!);
    return 0;
}


#############################################################################
#
# NAME:       parse_extract_preADComment
#
# ACTION:     Returns the portion of the string that preceeds the autodoc 
#             comment (if any).
#
# ARGUMENTS:  The string which is being extracted
#
# RETURN:     The portion of the string that preceeds the autodoc comment, or
#             an empty string.
#
#############################################################################
sub parse_extract_preADComment
{
    local ($in);

    $in = $_[0];

    return $` if ($in =~ m!/\*+\".*\"\*+/!);

    return "";
}


#############################################################################
#
# NAME:       parse_extract_postADComment
#
# ACTION:     Returns the portion of the string that follows the autodoc 
#             comment (if any).
#
# ARGUMENTS:  The string which is being extracted
#
# RETURN:     The portion of the string that follows the autodoc comment, or
#             an empty string.
#
#############################################################################
sub parse_extract_postADComment
{
    local ($in);

    $in = $_[0];

    return $' if ($in =~ m!/\*+\".*\"\*+/!);

    return "";
}


1;
