[plug] Another perl question...

[Anthony J. Breeds-Taurima]

On Thu, 21 Nov 2002, David Buddrige wrote:

> Hi all, 
> 
> I am writing a program which will re-arrange a doc++ comment. 
> 
> A doc++ comment is a C/C++ comment that starts with an extra "*".  An 
> example of a doc++ comment is this: 
> 
> /**
>  @doc Some general info about a function.
>  @precondition Any precondition that the function has
>  @postcondition Any postcondition that the function has.
> */ 
> 
>  
> 
> I want to have all of my doc++ comments formatted so that the start comment 
> "/**" is on a line by itself, and each @entry is on a line by itself. 
> 
> At the moment, I have some doc++ comments that are like this: 
> 
> /** @doc 
> 
> This is some general info about a function 
> 
> @precondition 
> 
> This is info about a precondition.
> */ 
> 
> I would like to re-arrange this comment so that it looks like this: 
> 
> /**
>  @doc This is some general info about a function
>  @precondition This is info about a precondition.
> */ 
> 
> To do this, I have written the following function: 
> 
> # This subroutine takes as input a single array reference, and
> # rearranges any doc++ commands that are split over multiple lines so
> # that each doc++ command is on a line of its own, including the /** and
> # */ delimiters which indicate the start and end of a doc++ comment. 
> 
> sub format_docpp_comment
> {
>    my $doc_comment_array;
>    my $comment_line;
>    my $single_comment_line; 
> 
>    $doc_comment_array = $_[0]; # give a friendly name to the array 
> 
>    foreach $comment_line ( @$doc_comment_array )
>    {
>    #chomp $comment_line;
>    my $temp_string;
>    $temp_string = $comment_line;
>    chomp $temp_string;
>    $single_comment_line .= $temp_string;
>    } 
> 
>    # At this point we have a single string that contains our entire
>    # doc++ comment. We can now use simple pattern matching to parse
>    # it. 
> 
>    $single_comment_line =~ m"(\/\*\*)(([\t\n 
> ]*)(\@)(doc|invariant|return|precondition|postcondition)([\t\n\w\.\ ]+))+";
>    print "2: $2\n";
> } 

Trying to stick to you're code fairly closely I'd do something like.

sub format_docpp_comment(@)                     # Use a prototype
{
   my @doc_comment_array;                       # Its an array make use it.
   my $comment_line;
   my $single_comment_line;
   my $indent = '';                             # set iff needed.

   @doc_comment_array = @_; # give a friendly name to the array

   # join every thing except the blank lines.
   $single_comment_line = join ('', grep {!/^$/} @doc_comment_array);

   # make life easier, trim the comments,
   $single_comment_line =~ s,^\s*/\*\*,,;
   $single_comment_line =~ s,\*/\s*$,,;


   # At this point we have a single string that contains our entire
   # doc++ comment. We can now use simple pattern matching to parse
   # it.

   $single_comment_line =~ s/\s*(@\w+)\s*/\n$indent$1 /gs;

   return "/**$single_comment_line*/";
}

#include <http://thor.cantech.net.au/~tony/stddisclaimer.h>

Yours Tony

   Jan 22-25 2003           Linux.Conf.AU            http://linux.conf.au/
		  The Australian Linux Technical Conference!