Automatic documentation stubs for .pl source

Foggy Bottoms has asked for the wisdom of the Perl Monks concerning the following question:

Dear monks,

I've come to this point where it's high time I wrote some documentation for the couple of files I've written so far. I was thinking of using a tool very much like Javadoc so I set myself to writing one up, in a rather simple way where it'd take a .pl file, detect the subs, keep the sub names and add them to the HTML file...

I wanted to take a line, eg sub myFunction # this function does blablabla and solely retrieve the first part, from sub till #... I wrote the following expression which can probably be simplified :

      if ($content =~ /^(sub\s+\w+).+$/)
      {
         print "$1.\n"; # print sub name
         if ($content =~ /(#.+)$/)
         {
            print "$1\n"; # print sub comment
         }
      }
[download]

How can I reduce the 2 ifs to a one-liner ? Thanks for your insight...

But then again, I assume a perl2html parser already exists, so could someone please tell me if there's such a package somewhere ?

Thanks all

20030827 Edit by jeffa: Changed title from 'regular expression help '

Comment on Automatic documentation stubs for .pl source Download Code

Replies are listed 'Best First'.
Re: Automatic documentation stubs for .pl source by halley (Prior) on Aug 26, 2003 at 15:33 UTC
POD in 5 Minutes Why are you writing your own solution before searching for predictable tools already built? Get into the habit of using google.com, search.cpan.org, perlmonks.org super-search... before you start coding. There's also a common saying, *Nothing can parse Perl* except `perl`.** Trying to parse a few constrained varieties of Perl code with a few regular expressions will be an infinite task, chasing parse bugs and finding new valid syntax. -- `[ e d @ h a l l e y . c c ]`	[reply] [d/l]
Re: Automatic documentation stubs for .pl source by Abigail-II (Bishop) on Aug 26, 2003 at 15:32 UTC
Something like (untested): `if ($content =~ /^sub\s+(\w+)[^#](?:#(.))?$/) { print "Subname: $1\n"; print "Comment: $2\n" if defined $2; }` [download] Note that it will fail to catch subs with attributes, or subs with a fully qualified name. Abigail	[reply] [d/l]
Re: Automatic documentation stubs for .pl source by Fletch (Bishop) on Aug 26, 2003 at 15:25 UTC
Erm, perhaps `perldoc perlpod` or perltidy would be helpful?	[reply] [d/l]
Re: Automatic documentation stubs for .pl source by CombatSquirrel (Hermit) on Aug 26, 2003 at 15:38 UTC
The following should work: `if ($content =~ /^(sub\s+\w+)[^#](#.)?/) { print "$1\n"; print "$2\n" if ($2); }` [download] Hope this helped. CombatSquirrel. Entropy is the tendency of everything going to hell.	[reply] [d/l]
Re: Automatic documentation stubs for .pl source by davido (Cardinal) on Aug 26, 2003 at 17:00 UTC
The following is untested. I'll describe what it's doing. @parsed receives the captured matches. The captured matches will be the sub portion, followed by either the comment or nothing (using alternation, grouped by non-matching parens). `my @parsed; if ( @parsed = $content =~ /^\s*(sub\s+\w+).+?(?:(#.+)\|())$/ ) { local $, = "\n"; print @parsed; }` [download] Dave "If I had my life to do over again, I'd be a plumber." -- Albert Einstein	[reply] [d/l]
Re: Automatic documentation stubs for .pl source by BrowserUk (Patriarch) on Aug 26, 2003 at 23:53 UTC
Just for kicks here's my attempt at handling fully qualified names (including archaic forms), prototypes, and attributes. #! perl -slw use strict; use re 'eval'; my $re_sub = qr[ sub\s+ ( (?: (\w+)? (?: :: \| ' ) )* \w+ \s* ) (?{ $name = $^N }) ( (?: $ [&$@\\; ]+ $ )? \s* ) (?{ $prototype = $^N \|\| '' }) ( (?: : \s* \w+ (?: $ .+? $ )? \s* )* ) (?{ $attributes = $^N \|\| '' }) \{ ]x; BEGIN{ @ARGV = map{ glob } @ARGV if $^O eq 'MSWin32'; } our( $name, $prototype, $attributes ); local $/ = undef; while( <> ) { tr[\n][]; s[\s+][ ]g; printf "%-40s : Name: %-20s\tPrototype: %10s\n\tAttributes : %s\n" +, $ARGV, $name, $prototype, $attributes while m[$re_sub]g; } [download] It's quite interesting to run this against the files in your libpath. Of course this doesn't respect comments or pod boundaries. Examine what is said, not who speaks. "Efficiency is intelligent laziness." -David Dunham "When I'm working on a problem, I never think about beauty. I think only how to solve the problem. But when I have finished, if the solution is not beautiful, I know it is wrong." -Richard Buckminster Fuller If I understand your problem, I can solve it! Of course, the same can be said for you.	[reply] [d/l]


Welcome to the Monastery
	PerlMonks