Add test cases for the chomp option, fix for undef $/, improve some docs

lib/File/Slurp.pm

@@ -772,7 +772,7 @@ reference is followed by a comma.
 
 The next argument is the filename.
 
-The next argument(s) is either a hash reference or a flattened hash,
+The next argument is an optional hash reference of
 C<< key => value >> pairs. The options are passed through to the
 L<File::Slurp/"write_file"> function. All options are described there.
 Only the C<binmode> and C<err_mode> options are supported. The call to
@@ -799,7 +799,7 @@ code reference is followed by a comma.
 
 The next argument is the filename.
 
-The next argument(s) is either a hash reference or a flattened hash,
+The next argument is an optional hash reference of
 C<< key => value >> pairs. The options are passed through to the
 L<File::Slurp/"write_file"> function. All options are described there.
 Only the C<binmode> and C<err_mode> options are supported. The call to
@@ -859,7 +859,7 @@ C<write_file> with the new data and the existing file data.
 
 The first argument to C<prepend_file> is the filename.
 
-The next argument(s) is either a hash reference or a flattened hash,
+The next argument is an optional hash reference of
 C<< key => value >> pairs. The options are passed through to the
 L<File::Slurp/"write_file"> function. All options are described there.
 
@@ -937,11 +937,15 @@ ensure the proper directory separator is used for your OS. See L<File::Spec>.
 	# or we can get a scalar reference
 	my $text_ref = read_file('/path/file', scalar_ref => 1);
 
-This function reads in an entire file and returns its contents to the
-caller. In scalar context it returns the entire file as a single
-scalar. In list context it will return a list of lines (using the
-current value of C<$/> as the separator, including support for paragraph
-mode when it is set to C<''>).
+This function reads in an entire file and returns its contents to the caller.
+In list context, or in scalar context with the C<array_ref> option set, it
+splits the contents using the current value of C<$/> as the separator.
+Paragraph mode, when C<$/> is set to C<''>, is supported.  Note: Any value for
+C<$/> different from the default newline C<"\n"> and the empty string C<''>
+should not be used.
+
+In scalar context with the C<array_ref> option set to false, it returns the
+contents of the entire file as a scalar value.
 
 The first argument is the path to the file to be slurped in.
 
@@ -1073,7 +1077,7 @@ an error. You can change how errors are handled with the C<err_mode> option.
 
 The first argument to C<write_file> is the filename.
 
-The next argument(s) is either a hash reference or a flattened hash,
+The next argument is an optional hash reference of
 C<< key => value >> pairs. The following options are available:
 
 =over

t/option_chomp.t

@@ -0,0 +1,71 @@
+# Purpose: Test the chomp option while reading files
+use strict;
+use warnings;
+
+use File::Basename ();
+use File::Spec ();
+use lib File::Spec->catdir(File::Spec->rel2abs(File::Basename::dirname(__FILE__)), 'lib');
+use FileSlurpTest qw(temp_file_path);
+
+use File::Slurp qw(read_file write_file);
+use Test::More;
+plan tests => 7;
+
+# -------- Prelude: Set up expected data and write a data file
+my $expected = <<TEXT;
+PREFACE
+
+All in the golden afternoon
+    Full leisurely we glide;
+For both our oars, with little skill,
+    By little arms are plied,
+While little hands make vain pretence
+    Our wanderings to guide.
+
+-- Lewis Carroll, Alice in Wonderland
+TEXT
+
+my @expected_lines = $expected =~ /(.*\n)/mg;
+chomp (my @expected_chomped = @expected_lines);
+
+my ($array_ref,$scalar_ref);
+
+my $file = temp_file_path();
+{
+    open my $fh, ">", $file or die "Couldn't open $file for write: $!";
+    $fh->print($expected);
+}
+
+# -------- Run the tests
+{
+    local $/ = 'a';
+    my $got = read_file($file, {chomp => 1});
+    is($got,$expected,"scalar context, no chomping");
+}
+
+{
+    my @got = read_file($file);
+    is_deeply(\@got,\@expected_lines, "list context, chomp not provided");
+}
+
+{
+    my @got = read_file($file, { chomp => 0 });
+    is_deeply(\@got,\@expected_lines, "list context, chomp => 0");
+}
+
+{
+    my @got = read_file($file, chomp => 1);
+    is_deeply(\@expected_chomped,\@got, "list context, chomp => 1, option as flat hash");
+}
+
+{
+    my @got = read_file($file, {chomp => 1});
+    is_deeply(\@expected_chomped,\@got, "list context, chomp => 1, option as hashref");
+}
+
+{
+    local $/ = '';
+    my @got = read_file($file, {chomp => 1});
+    is(scalar @got,3,"paragraph mode splits into three paragraphs");
+    isnt(substr($got[2],-1,1),"\n","paragraph mode chomps trailing line feed");
+}