NAME

SYNOPSIS

    # using Badger::Filesytem constructor subroutine
    use Badger::Filesystem 'File';
    
    # use native OS-specific paths:
    $file = File('/path/to/file');
    
    # or generic OS-independent paths
    $file = File('path', 'to', 'file');

    # manual object construction
    use Badger::Filesystem::File;
    
    # positional arguments
    $file = Badger::Filesystem::File->new('/path/to/file');
    $file = Badger::Filesystem::File->new(['path', 'to', 'file']);
    
    # named parameters
    $file = Badger::Filesystem::File->new(
        path => '/path/to/file'             # native
    );
    $file = Badger::Filesystem::File->new(
        path => ['path', 'to', 'file']      # portable
    );
    
    # path inspection methods
    $file->path;                    # full path
    $file->name;                    # file name
    $file->directory;               # parent directory
    $file->dir;                     # alias to directory()
    $file->base;                    # same thing as directory()
    $file->volume;                  # path volume (e.g. C:)
    $file->is_absolute;             # path is absolute
    $file->is_relative;             # path is relative
    $file->exists;                  # returns true/false
    $file->must_exist;              # throws error if not
    @stats = $file->stat;           # returns list
    $stats = $file->stat;           # returns list ref

    # path translation methods
    $file->relative;                # relative to cwd
    $file->relative($base);         # relative to $base
    $file->absolute;                # relative to filesystem root
    $file->definitive;              # physical file location
    $file->collapse;                # resolve '.' and '..' in $file path
    
    # path comparison methods
    $file->above($another_path);    # $file is ancestor of $another_path
    $file->below($another_path);    # $file is descendant of $another_path
    
    # file manipulation methods
    $file->create;                  # create file
    $file->touch;                   # create file or update timestamp
    $file->delete;                  # delete file
    $fh = $file->open($mode);       # open file (for read by default)
    $fh = $file->write;             # open for write
    $fh = $file->append;            # open for append;
    
    # all-in-one read/write methods
    @data = $file->read;            # return list of lines
    $data = $file->read;            # slurp whole content
    $text = $file->text;            # same as read();
    $file->write(@content);         # write @content to file
    $file->append(@content);        # append @content to file

DESCRIPTION

You can create a file object "File" constructor function in Badger::Filesystem.

    use Badger::Filesystem 'File';

File paths can be specified as a single string using your native filesystem format or as a list or reference to a list of items in the path for platform-independent paths.

    my $file = File('/path/to/file');

If you're concerned about portability to other operating systems and/or file systems, then you can specify the file path as a list or reference to a list of component names.

    my $file = File('path', 'to', 'file');
    my $file = File(['path', 'to', 'file']);

You can specify a reference to a hash array of additional configuration items as the final argument. At present, there is are two configuration options. The first, "encoding", can be use to specify the encoding of the file. This is applied through Perl's IO layer encodings. See "perldoc binmode" for further information.

    my $file = File('path' , 'to', 'file', { encoding => 'utf8' });

The other option is "codec". This allows you to define the name of a Badger::Codec which will be used to serialise data to and from the file via the data() method.

    my $file = File('path' , 'to', 'file', { codec => 'storable' });
    
    # save some data, automatically serialised via Storable (freeze)
    $file->data({
        message => 'Hello World',
        numbers => [1.618, 2.718, 3.142],
    });
    
    # later... load data again and automatically de-serialise (thaw)
    $data = $file->data;
    print $data->{ message }, "\n";             # Hello World
    print join(', ', @{ $data->{ numbers } });  # 1.618, 2.718, 3.142

METHODS

    my $file = File('/path/to/file');
    print $file->dir;                   # /path/to
    print $file->dir('subdir');         # /path/to/subdir

    my $file = File('/path/to/file1');
    print $file->file;                   # /path/to/file1
    print $file->file('file2');          # /path/to/file2

    my $fh = $file->open;       # read
    my $fh = $file->open('w');  # write

    my $text  = $file->read;
    my @lines = $file->read;

    my $fh = $file->write;
    $fh->print("Hello World!\n");
    $fh->close;

    $file->write("Hello World!\n");

    $file->copy('/some/where/else');

    $file->copy(
        '/some/where/else' => {
            mkdir     => 1,         # create intermediate directories
            dir_mode  => 0775,      # permissions for created directories
            file_mode => 0664,      # permissions for created file
        }
    );

    $target_file->copy_from( $source_file );

    $file->move('/some/where/else');

    $target_file->move_from( $source_file );

    $file->print("hello");      
    $file->print(@stuff);       # works OK if @stuff is empty

    # manual open, append, close
    my $fh = $file->append;
    $fh->print("Hello World!\n");
    $fh->close;
    
    # all-in-one
    $file->append("Hello World\n");

    $file->encoding(':utf8');

    $file->utf8;

    # same
    $file->encoding(':utf8');

    $file->utf8->must_exist.

    $file->codec('storable');
    
    # first save the data to file
    $file->data($some_data_to_save);
    
    # later... load the data back out
    my $data = $file->data;

    $file->code('storable+base64');

    $file->data({               # either: HASH reference
        e   => 2.718,
        pi  => 3.142,
        phi => 1.618,
    });
    
    $file->data([               # or: ARRAY reference
        2.718,
        3.142,
        1.618
    ]);

    $file->data(                # same as ARRAY reference above
        2.718,
        3.142,
        1.618
    );

    my $data = $file->data;     # HASH or ARRAY reference

AUTHOR

COPYRIGHT

ACKNOWLEDGEMENTS

Please see the ACKNOWLEDGEMENTS in Badger::Filesystem for further information.

SEE ALSO