#!/usr/bin/perl -w

# Fixes up some mistakes in the javadoc comments of the comp2100.oops source.
# Use at your own risk! Backing up your files manually is recommended.
# by Jan Vaughan

# Note: It expects the declaration of the first class to start on a new line,
# and that there are no open braces in the file before that starting the
# first class. (If this isn't the case, it should just fail to match and
# not do anything evil, but I make no guarantee on that.)

# What it actually does is moves class comments that were at the start of
# the file to just before the class, so the javadoc tool recognises them as
# being associated with that class. It then also gets rid of any whitespace
# that is before anything else in the file, as if the comment was the first
# thing in the file and there were some newlines after the comment, there
# will be extra whitespace at the top of the file once the comment is moved.
# It moves the comment through one big regex substitution. The regex breaks
# the file into six pieces:
# 1: Everything up to the first javadoc comment
# 2: The first javadoc comment, including /** and */
# 3: Whitespace and a newline immediately after the comment (optional)
# 4: Everthing between there and the first class
# 5: The declaration of the first class, up to and including the first brace
# Everything else, which is ignored and left where it is.
# It then rearranges these parts into the order 1-4-3-2-5

# backup files emacs style
$^I = '~';
# read whole files at a time
$/ = undef;

while(<>) {
    s%
	^((?:(?:.(?!/\*\*))*.)?)      # anything up to a javadoc comment
	(/\*\*(?:(?:.(?!\*/))*.)?\*/) # javadoc comment
        (?:(?!\n)\s)*(\n?)            # newline after non-newline space
	([^\{]*\s*)                   # anything before the first class's body
        (\n                           # class declaration starting on a newline
          (?:(?!\n)\s)*               # whitespace that isn't a newline
          (?:                         # stuff between newline and class name
	     (?:                      # abstract class...
	        public\s+abstract
	     |
	        abstract\s+public
	     |
	        abstract
             )\s+class
	  |                            # ... or an
	     (public\s+)?(class|interface) # interface or concrete class
	  )
	  (?:<\w+>)?                  # possible generic
	  \s+[\w\s<>,\{]+             # anything sensible between here and body
	  \{                          # start of the body
	)                             # close of the last capture group at last
    %$1$4$3$2$5%xs
        or warn "No class comment and class declaration found in $ARGV\n";
    
    s/^\s+//;
    print;
}