#!/usr/local/bin/perl -w

=head1 NAME

fo_comment_spec.pl - form-out trigger that inserts comments read from a file into a spec form presented to the user. 

=head1 SYNOPSYS

B<e.g.:> trigger installation entry for protection table:

record_comments form-out protect "/<path-to>/perl /<path-to>/fo_comment_spec.pl %formfile% /<path_to>/<protect_comments_file>"

=head1 DESCRIPTION

This trigger script together with its matching form-in partner
allows the commenting of spec forms such as the protection table,
transparently for the user (i.e. without having to invoke I<p4 protect>
from a wrapper script).

Comment lines start with the B<#> char, which can be preceeded by
blank spaces.
Comments will be recorded even if Perforce returns that
the spec was not changed.

=head1 LIMITATIONS

This works on the principle that each line in a spec is unique, which
is often (but not necessarily always) the case. If identical lines
are found, they will all get the same comment.

Only one comment per line is permitted for now.

=head1 AUTHOR

Guillaume Barthelemy <F<gb.perforce@gmail.com>>, June 2008.

=cut

use strict;

my $form = shift;
my $comments_path = shift;

# we need a comment file otherwise exit
exit 0 unless (-e $comments_path);

# slurp protection table form
open FORM, "<", $form or die ("Trigger couldn't read from temporary file $form.\n$!");
my @lines = <FORM>;
close FORM;

# read the comments
my %comments = %{ do $comments_path };

# rewrite form to be presented to user
open FORM, ">", $form or die ("Trigger couldn't write temporary file $form.\n$!");
foreach my $line (@lines) {
	chomp $line;
	print FORM $comments{$line}, "\n" if exists ($comments{$line});
	print FORM $line, "\n";
}
close FORM;
exit 0;