| Subject: | error message formatting |
Seen in your documentation:
$sftp = Net::SFTP::Foreign->new($host, autodie => 1);
my $ls = $sftp->ls("/bar");
# dies as: "Couldn't open remote dir '/bar': No such file"
I recommend following the UNIX error message convention of $object: $message. So that would become:
/bar: couldn't open remote dir: No such file
So you start with the $object being operated on, follow by a high-level explanation of the operation that failed, and then append any error messages obtained from the OS or lower-level API calls.
Similarly:
$sftp->die_on_error("Something bad happened");
# is a shortcut for...
$sftp->error and die "Something bad happened: " . $sftp->error;
should be more like:
$sftp->die_on_error($object, "something bad happened");
# is a shortcut for...
$sftp->error
and die join(': ',$object, 'something bad happened', $sftp->error) . "\n";
Of course error message formatting is a matter of personal preference, but there is a long history of precedence for this format.