README

NAME

    File::Basename::Extra - Extension to File::Basename, adds named access
    to file parts and handling of filename suffixes

VERSION

    version 0.004

SYNOPSIS

      # Note: by default no symbols get exported so make sure you export
      # the ones you need!
      use File::Basename::Extra qw(basename);
    
      # basename and friends
      my $file      = basename('/foo/bar/file.txt');          # "file.txt"
      my $fileext   = basename_suffix('/foo/bar/file.txt');   # ".txt"
      my $filenoext = basename_nosuffix('/foo/bar/file.txt'); # "file"
    
      # dirname
      my $dir       = dirname('/foo/bar/file.txt');           # "/foo/bar/"
    
      # fileparse
      my ($filename, $dirs, $suffix) = fileparse('/foo/bar/file.txt', qr/\.[^.]*/);
                                                              # ("file", "/foo/bar/", ".txt")
    
      # pathname
      my $path      = pathname('/foo/bar/file.txt');          # "/foo/bar/"
    
      # fullname and friends
      my $full      = fullname('/foo/bar/file.txt');          # "/foo/bar/file.txt"
      my $fullext   = fullname_suffix('/foo/bar/file.txt');   # ".txt"
      my $fullnoext = fullname_nosuffix('/foo/bar/file.txt'); # "/foo/bar/file"
    
      # getting/setting the default suffix patterns
      my @patterns = default_suffix_patterns(); # Returns the currently active patterns
    
      # setting the default suffix patterns
      my @previous = default_suffix_patterns(qr/[._]bar/, '\.baz');
                     # Now only .bar, _bar, and .baz are matched suffixes

DESCRIPTION

    This module provides functionalty for handling file name suffixes (aka
    file name extensions).

FUNCTIONS

 fileparse FILEPATH

 fileparse FILEPATH PATTERN_LIST

 basename FILEPATH

 basename FILEPATH PATTERN_LIST

 dirname FILEPATH

 fileparse_set_fstype FSTYPE

    These functions are exactly the same as the corresponding ones from
    File::Basename except that they aren't exported by default.

 basename_suffix FILEPATH

 basename_suffix FILEPATH PATTERN_LIST

    Returns the file name suffix part of the given filepath. The default
    suffix patterns are used if none are provided. Behaves the same as
    basename, i.e., it uses the last last level of a filepath as filename,
    even if the last level is clearly directory.

    Also, like basename, files that consist of only a matched suffix are
    treated as if they do not have a suffix. So, using the default suffix
    pattern, basename_suffix('/Users/home/.profile') would return an empty
    string.

    Note: Like the original basename function from File::Basename, suffix
    patterns are automatically escaped so pattern .bar only matches .bar
    and not e.g., _bar (this is not done for the default suffix patterns,
    nor for patterns provided to the non-basename family functions of this
    module!).

 basename_nosuffix FILEPATH

 basename_nosuffix FILEPATH PATTERN_LIST

    Acts basically the same as the original basename function, except that
    the default suffix patterns are used to strip the name of its suffixes
    when none are provided.

    Also, like basename, files that consist of only a matched suffix are
    treated as if they do not have a suffix. So, using the default suffix
    pattern, basename_nosuffix('/Users/home/.profile') would return
    .profile.

    Note: Like the original basename function from File::Basename, suffix
    patterns are automatically escaped so pattern .bar only matches .bar
    and not e.g., _bar (this is not done for the default suffix patterns,
    nor for patterns provided to the non-basename family of functions of
    this module!).

 filename FILEPATH

 filename FILEPATH PATTERN_LIST

    Returns just the filename of the filepath, optionally stripping the
    suffix when it matches a provided suffix patterns. Basically the same
    as calling fileparse in scalar context.

 filename_suffix FILEPATH

 filename_suffix FILEPATH PATTERN_LIST

    Returns the matched suffix of the filename. The default suffix patterns
    are used when none are provided.

 filename_nosuffix FILEPATH

 filename_nosuffix FILEPATH PATTERN_LIST

    Returns the filename with the the matched suffix stripped. The default
    suffix patterns are used when none are provided.

 pathname FILEPATH

    Returns the path part of the file. Contrary to dirname, a filepath that
    is clearly a directory, is treated as such (e.g., on Unix,
    pathname('/foo/bar/') returns /foo/bar/).

 fullname FILEPATH

 fullname FILEPATH PATTERN_LIST

    Returns the provided filepath, optionally stripping the filename of its
    matching suffix.

 fullname_suffix FILEPATH

 fullname_suffix FILEPATH PATTERN_LIST

    Synonym for filename_suffix.

 fullname_nosuffix FILEPATH

 fullname_nosuffix FILEPATH PATTERN_LIST

    Returns the full filepath with the the matched suffix stripped. The
    default suffix patterns are used when none are provided.

 default_suffix_patterns

 default_suffix_patterns NEW_PATTERN_LIST

    The default suffix pattern list (see the fileparse function in
    File::Basename for details) is qr/\.[^.]*/. Meaning that this defines
    the suffix as the part of the filename from (and including) the last
    dot. In other words, the part of a filename that is popularly known as
    the file extension.

    You can alter the suffix matching by proving this function with a
    different pattern list.

    This function returns the pattern list that was effective before
    optionally changing it.

BUGS

    Please report any bugs or feature requests on the bugtracker website
    <https://github.com/HayoBaan/File-Basename-Extra/issues>.

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

    File::Basename for the suffix matching and platform specific details.

AUTHOR

    Hayo Baan <info@hayobaan.com>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2015 by Hayo Baan.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.