add more documentation

README.md

@@ -1,13 +1,69 @@
 # adif-pota2sig
 
-Convert POTA fields in adif files to SIG and SIG_INFO fields
+Process adif file for POTA uploads
 
-Parse adif file, if a record has one or more POTA_REF entries (delimited by a
+## SYNOPSIS
-comma), add SIG POTA and SIG_INFO with reference. Multiply record such, that
-every POTA_REF entry is a separate record with own SIG_INFO.
-Extended adif file will be printed to stdout.
 
-## Usage:
+adif-pota2sig.pl -i `in.adi` -o `out.adi`
-```sh
+
-adif-pota2sig.pl logfile.adi > extended-logfile.adi
+adif-pota2sig.pl < `in.adi` > `out.adi`
-```
+
+adif-pota2sig.pl -r K-TEST -t `out_REF.adi` -i `in.adi`
+
+adif-pota2sig.pl -r K-TEST -t `out_REF.adi` < `in.adi`
+
+adif-pota2sig.pl -h
+
+## DESCRIPTION
+
+**adif-pota2sig** will read an adif file, if a contact has one or more POTA\_REF
+entries (delimited by a comma), add SIG POTA and SIG\_INFO with reference.
+Multiply contact such, that every POTA\_REF entry is a separate contact with own
+SIG\_INFO. Extendet adif file will be printed to stdout or a file.
+
+If used with **-r** and **-t** options a number of files with contents described
+above will be created. One file for each POTA reference. For output filenames
+see **-t**.
+
+With **-r** you can also include the location in the format REFERENCE@LOCATION,
+which is handy for trails. E. g. -r DE-0622@DE-HH
+
+## OPTIONS
+
+- **-h|--help**
+
+    Print a brief help message and exits.
+
+- **-i `in.adi`|--input=`in.adi`**
+
+    Use `in.adi` as input (default: - for stdin).
+
+- **-o `out.adi`|--output=`out.adi`**
+
+    Use `out.adi` as output (default: - for stdout).
+
+- **-r MY\_POTA\_REF|--reference=MY\_POTA\_REF**
+
+    Use MY\_POTA\_REF as own POTA reference. If there are more than one (for a
+    n-fer) create a list with commas, e. g. **-r** K-TEST1,K-TEST2,K-TEST3.
+
+    Also set the entries MY\_SIG and MY\_SIG\_INFO matching the reference in the
+    output files. By default already existing entries with MY\_SIG and MY\_SIG\_INFO
+    won't be overwritten and the program will stop. Using **-f** will overwrite the
+    entries.
+
+    **-t** is mandatory for this option.
+
+- **-t `out_REF.adi`|--template=`out_REF.adi`**
+
+    Use `out_REF.adi` as output filename template for multiple references. REF
+    will be replaced by a POTA reference. Multiple filenames will be created.
+
+    **-o** is not allowed for this option.
+
+    **-r** is mandatory for this option.
+
+- **-f|--force**
+
+    By default filenames selected with **-o** and **-t** won't be overwritten and the
+    program will stop. Using **-f** will overwrite output files.

adif-pota2sig.pl

@@ -19,13 +19,13 @@ adif-pota2sig - Process adif file for POTA uploads
 
 =head1 SYNOPSIS
 
-adif-pota2sig.pl -i in.adi -o out.adi
+adif-pota2sig.pl -i F<in.adi> -o F<out.adi>
 
-adif-pota2sig.pl < in.adi > out.adi
+adif-pota2sig.pl < F<in.adi> > F<out.adi>
 
-adif-pota2sig.pl -r K-TEST -t out_REF.adi -i in.adi
+adif-pota2sig.pl -r K-TEST -t F<out_REF.adi> -i F<in.adi>
 
-adif-pota2sig.pl -r K-TEST -t out_REF.adi < in.adi
+adif-pota2sig.pl -r K-TEST -t F<out_REF.adi> < F<in.adi>
 
 adif-pota2sig.pl -h
 
@@ -39,21 +39,35 @@ use Pod::Usage;
 
 my $input_file = "";
 my $output_file = "";
-my $my_ref = "";
+my $my_refs = "";
 my $output_template = "";
 my $force_output = 0;
 
 GetOptions (
 	"i|input=s"	=> \$input_file,
 	"o|output=s"	=> \$output_file,
-	"r|reference=s"	=> \$my_ref,
+	"r|reference=s"	=> \$my_refs,
-	"f|force"	=> \$force_output,
 	"t|template=s"	=> \$output_template,
+	"f|force"	=> \$force_output,
 	"h|help"	=> sub {pod2usage(-verbose => 2)}
-) or die("Error in command line arguments\n");
+) or die("Error in command line arguments");
 
 =pod
 
+=head1 DESCRIPTION
+
+B<adif-pota2sig> will read an adif file, if a contact has one or more POTA_REF
+entries (delimited by a comma), add SIG POTA and SIG_INFO with reference.
+Multiply contact such, that every POTA_REF entry is a separate contact with own
+SIG_INFO. Extendet adif file will be printed to stdout or a file.
+
+If used with B<-r> and B<-t> options a number of files with contents described
+above will be created. One file for each POTA reference. For output filenames
+see B<-t>.
+
+With B<-r> you can also include the location in the format REFERENCE@LOCATION,
+which is handy for trails. E. g. -r DE-0622@DE-HH
+
 =head1 OPTIONS
 
 =over
@@ -73,14 +87,19 @@ Use F<out.adi> as output (default: - for stdout).
 =item B<-r MY_POTA_REF|--reference=MY_POTA_REF>
 
 Use MY_POTA_REF as own POTA reference. If there are more than one (for a
-n-fer) create a list with commas, e. g. S<B<-r> K-TEST1,K-TEST2,K-TEST3>
+n-fer) create a list with commas, e. g. S<B<-r> K-TEST1,K-TEST2,K-TEST3>.
+
+Also set the entries MY_SIG and MY_SIG_INFO matching the reference in the
+output files. By default already existing entries with MY_SIG and MY_SIG_INFO
+won't be overwritten and the program will stop. Using B<-f> will overwrite the
+entries.
 
 B<-t> is mandatory for this option.
 
 =item B<-t F<out_REF.adi>|--template=F<out_REF.adi>>
 
-Use out_REF.adi as output filename template for multiple references. REF will
+Use F<out_REF.adi> as output filename template for multiple references. REF
-be replaced by a POTA reference. Multiple filenames will be created.
+will be replaced by a POTA reference. Multiple filenames will be created.
 
 B<-o> is not allowed for this option.
 
@@ -95,11 +114,11 @@ program will stop. Using B<-f> will overwrite output files.
 
 =cut
 
-if (($my_ref ne "") && ($output_template eq "")) {
+if (($my_refs ne "") && ($output_template eq "")) {
 	die "-t is mandatory for -r";
 }
 
-if (($output_template ne "") && ($my_ref eq "")) {
+if (($output_template ne "") && ($my_refs eq "")) {
 	die "-r is mandatory for -t";
 }
 
@@ -118,17 +137,17 @@ if (($input_file eq "-") || ($input_file eq "")) {
 	open($FH_IN, '<', $input_file) or die "$input_file: $!";
 }
 
-my @output_filenames;
+my %filenames_ref = ();
 
-if ($my_ref ne "") {
+if ($my_refs ne "") {
-	foreach (split(/,/, $my_ref)) {
+	foreach (split(/,/, $my_refs)) {
-		push(@output_filenames, $output_template =~ s/REF/$_/r);
+		$filenames_ref{$output_template =~ s/REF/$_/r} = $_;
 	}
 } else {
-	push(@output_filenames, $output_file);
+	$filenames_ref{$output_file} = "";
 }
 
-foreach my $output_filename (@output_filenames) {
+foreach my $output_filename (keys %filenames_ref) {
 	seek $FH_IN, 0, 0;
 
 	my $FH_OUT;
@@ -158,21 +177,35 @@ foreach my $output_filename (@output_filenames) {
 		push @entry, $_;
 		if (m/<EOR>\s+$/i) {
 			# entry complete
+
+			# maybe add MY_SIG
+			my $my_ref = $filenames_ref{$output_filename};
+			if ($my_ref ne "") {
+				my $last = pop(@entry);
+				push(@entry, "<MY_SIG:4>POTA\r\n");
+				push(@entry, "<MY_SIG_INFO:" . length($my_ref) . ">" . $my_ref . "\r\n");
+				push(@entry, $last);
+			}
+
+			# print whole entry
 			if (scalar(@pota_refs) > 0) {
+				# maybe print entry multiple times
 				# add sig_info to each pota reference
 				foreach my $ref (@pota_refs) {
 					# print all except last
 					print @entry[0 .. $#entry - 1];
 					# insert POTA SIG
-					print "<SIG:4>POTA\n";
+					print "<SIG:4>POTA\r\n";
-					print "<SIG_INFO:" . length($ref) . ">" . $ref . "\n";
+					print "<SIG_INFO:" . length($ref) . ">" . $ref . "\r\n";
 					# print last
 					print $entry[-1];
 				}
 			} else {
 				# no park reference in this entry
+				# print entry only once
 				print @entry;
 			}
+
 			# clear entry and pota refs for next entry
 			@entry = ();
 			@pota_refs = ();
@@ -183,23 +216,15 @@ foreach my $output_filename (@output_filenames) {
 			# fill pota_refs with references
 			@pota_refs = split(/,/, $val);
 			chomp @pota_refs;
+		} elsif (m/^<MY_SIG(_INFO)?:/) {
+			if ($force_output) {
+				# remove MY_SIG and MY_SIG_INFO
+				pop(@entry);
+			} else {
+				die "MY_SIG exists. Overwrite with --force";
+			}
 		}
 	}
 	close($FH_OUT);
 }
 close($FH_IN);
-
-__END__
-
-=head1 DESCRIPTION
-
-B<adif-pota2sig> will read an adif file, if a contact has one or more POTA_REF
-entries (delimited by a comma), add SIG POTA and SIG_INFO with reference.
-Multiply contact such, that every POTA_REF entry is a separate contact with own
-SIG_INFO. Extendet adif file will be printed to stdout or a file.
-
-If used with B<-r> and B<-t> options a number of files with contents described
-above will be created. On file for each POTA reference. For output filenames
-see B<-t>.
-
-=cut