|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.