| Subject: | Example code not clear - gunzip() takes filenames! |
The pod documentation starts off with some examples similar to:
my $status = gunzip $input => $output
or die "gunzip failed: $GunzipError";
I spent a few hours trying to work out why this didn't work, even on
simple gzip input data, until I realized that here $input and $output
are not strings of data but *filenames*!
The problem was that because $GunzipError contains binary data it
corrupts the terminal so I never saw the error message 'input file ...
does not exist'.
Obviously I was a bit of an idiot here but there is scope for making
the documentation and error message more idiot-proof. I would suggest
changing the example code to something like
my $status = gunzip $input_filename_or_reference,
$output_filename_or_reference
or die "gunzip failed: $GunzipError";
just to make it extra clear what is expected.
Additionally, if the 'filename' passed in is binary gzip data, then
the error message should say that and crucially should not include
the filename as part of the error message - since if it is there it
will often corrupt the terminal and stop the rest of the message
being seen.