PrePAN

Sign in to PrePAN

Fancy::Open Fancy::Open opens a file and creates an array with several options.

Good

Synopsis

use Fancy::Open qw(fancy_open);

my @plain_array   = fancy_open('file_path');

my @prefix_array  = fancy_open('file_path', { 'prefix' => 'solid' });

my @suffix_array  = fancy_open('file_path', { 'suffix' => 'bead' });

my @both_array    = fancy_open('file_path', { 'prefix' => 'solid', 'suffix' => 'bead' });

my @joiner_array  = fancy_open('file_path', { 'prefix' => 'solid', 'suffix' => 'bead', 'joiner' => ' ' });

my @empty_line    = fancy_open('file_path', { 'empty' => 'fill' });

my @encoded_array = fancy_open('file_path', { 'encoding' => 'ascii' });

Description

(The module has been renamed, url updated.)

NAME

Fancy::Open opens a file and creates an array with an optional prefix string, suffix string, or both to the lines in the file. You can also add an optional string to join the prefix, line, and suffix. You can specify how to handle empty lines. The array is returned in your preferred encoding.

VERSION

This document describes Fancy::Open version 1.0.

DESCRIPTION

fancy_open can be exported and returns a list of values. These values can be modified if the optional parameters prefix, suffix, or both are used. You can also add a joiner string to join the prefix, line, and suffix. If your file could have empty lines, the empty option can be used to specify how to handle them. There is the additional option to choose your encoding, the default is utf-8.

If the open fails, fancy_open will die.

perl my @fancy_array = fancy_open( 'file_path', { 'prefix' => 'prefix_string', 'suffix' => 'suffix_string', 'joiner' => 'joiner_string', 'empty' => 'empty_option', # fill, blank, or undefined 'encoding' => 'encoding_option' # any valid encoding } );

The file is also closed by fancy_open.

Fancy::Open requires Perl version 5.6 or better.

Parameters

fancy_open has two parameters.

Note: all sample returned arrays are the results from Data::Dump.

Sample file contents.

red orange yellow spring green teal cyan azure blue violet magenta pink white black gray

file

perl my @plain_array = fancy_open('file_path');

The first parameter is the file to be opened. If this is the only parameter specified, the file will be opened, encoded to utf-8, and returned as a list.

Options

The second parameter are the options: prefix, suffix, joiner, empty, and encoding.

prefix

perl my @prefix_array = fancy_open('file_path', { 'prefix' => 'solid' });

The prefix option is the string you want prepended to each item in the list. Using the example, all items on the list will be returned with solid prepended to them.

perl ( "solidred", "solidorange", "solidyellow", "solidspring", "solidgreen", "solidteal", "solidcyan", "solidazure", "solidblue", "solidviolet", "solidmagenta", "solidpink", "solidwhite", "solidblack", "solidgray", )

suffix

perl my @suffix_array = fancy_open('file_path', { 'suffix' => 'bead; });

The suffix option is the string you want to appear appended to each item in the list. Using the example, all items on the list will be returned with bead appended to them.

perl ( "redbead", "orangebead", "yellowbead", "springbead", "greenbead", "tealbead", "cyanbead", "azurebead", "bluebead", "violetbead", "magentabead", "pinkbead", "whitebead", "blackbead", "graybead", )

prefix and suffix

perl my @both_array = fancy_open('file_path', { 'prefix' => 'solid', 'suffix' => 'bead' });

Using both the prefix and suffix options together will prepend and append the associated strings to the items in the list.

perl ( "solidredbead", "solidorangebead", "solidyellowbead", "solidspringbead", "solidgreenbead", "solidtealbead", "solidcyanbead", "solidazurebead", "solidbluebead", "solidvioletbead", "solidmagentabead", "solidpinkbead", "solidwhitebead", "solidblackbead", "solidgraybead", )

joiner

perl my @joiner_array = fancy_open('file_path', { 'prefix' => 'solid', 'suffix' => 'bead', 'joiner' => ' ' });

The joiner option will add a string between the prefix, the line from the file, and the suffix. In this case, a single space.

perl ( "solid red bead", "solid orange bead", "solid yellow bead", "solid spring bead", "solid green bead", "solid teal bead", "solid cyan bead", "solid azure bead", "solid blue bead", "solid violet bead", "solid magenta bead", "solid pink bead", "solid white bead", "solid black bead", "solid gray bead", )

empty

perl my @empty_line = fancy_open('file_path', { 'empty' => 'fill' });

The empty option has three possible values for what to do with empty lines in the file: fill, blank, or undefined. If empty is not used or is any value than the three listed, the empty line will be ignored.

Sample file contents with an empty line.

``` red orange yellow spring green teal cyan azure

blue violet magenta pink white black gray ```

  • fill will prefix and suffix the value as it does with all other lines.

    perl my @empty_line = fancy_open('file_path', { 'prefix' => 'solid', 'empty' => 'fill' });

    The array returned will be:

    perl ( "solidred", "solidorange", "solidyellow", "solidspring", "solidgreen", "solidteal", "solidcyan", "solidazure", "solid", "solidblue", "solidviolet", "solidmagenta", "solidpink", "solidwhite", "solidblack", "solidgray", )

  • blank will return a zero length but defined value.

    perl my @empty_line = fancy_open('file_path', { 'prefix' => 'solid', 'empty' => 'blank' }); The array returned will be:

    perl ( "solidred", "solidorange", "solidyellow", "solidspring", "solidgreen", "solidteal", "solidcyan", "solidazure", "", "solidblue", "solidviolet", "solidmagenta", "solidpink", "solidwhite", "solidblack", "solidgray", )

  • undefined will return an undefined value.

    perl @empty_line = fancy_open('file_path', { 'prefix' => 'solid', 'empty' => 'undefined' });

    The array returned will be:

    perl ( "solidred", "solidorange", "solidyellow", "solidspring", "solidgreen", "solidteal", "solidcyan", "solidazure", undef, "solidblue", "solidviolet", "solidmagenta", "solidpink", "solidwhite", "solidblack", "solidgray", )

encoding

perl my @encoded_array = fancy_open('file_path', { 'encoding' => 'ascii' });

The encoding option is the encoding you want to use to open the file. The above file will be opened ascii encoded.

Comments

The interface looks just fine. The naming needs improvement though. “Open” is a hint, but not a strong one, that the module has to do with files, and “fancy” conveys nothing specific, so the name gives very little indication of what the module does. And the function doesn’t return a file handle, as “open” would suggest, but the contents of the file.

The general term in use for “I give a function a filename and it gives me back the contents of the file” is “slurping a file”, so that is what I’d go with for the module:

https://metacpan.org/search?q=slurp
https://metacpan.org/search?q=slurper

And the more general term for “prefix” and “suffix” is “affix”.

So I’d suggest File::Slurp::Affix as the name of the module.

The most conventional name for the function is read_file, which seems just fine for this one too.
Totally agree with ap.
I'd suggest specifying a fourth possible value for the `empty` option of `discard` or `drop` in your documentation (which you would state is the default). It won't require any changes to your code, but it'll leave you room to maneuver in the future (if you do need add a new value later you can be sure you won't pick one that someone might have already used).

Also the name the `joiner` option sounds like it's going to join all the lines in the file together. I'd find `separator` or `delimiter` would be a bit more intuitive (but that might just be me).
I am updating things as your suggestions come in.

Please sign up to post a review.