12.1 Sample Function-Oriented Interface: File::Basename

To understand what happens with use, look at one of the many modules included with a normal Perl distribution: File::Basename. This module parses file specifications into useful pieces in a mostly portable manner. The default usage:

use File::Basename;

introduces three subroutines, fileparse, basename, and dirname,^[1] into the current package: typically, main in the main part of your program. From this point forward, within this package, you can say: ^[2]

^[1] As well as a utility routine, fileparse_set_fstype.

^[2] The new symbols are available for all code compiled in the current package from this point on, whether it's in this same file or not. However, these symbols won't be available in a different package.

my $basename = basename($some_full_path);
my $dirname = dirname($some_full_path);

as if you had written the basename and dirname subroutines yourself, or (nearly) as if they were built-in Perl functions.^[3]

^[3] These routines pick out the filename and the directory parts of a pathname. For example, if $some_full_path were D:\Projects\Island Rescue\plan 7.rtf (presumably, the program is running on a Windows machine), the basename would be plan 7.rtf and the dirname would be D:\Projects\Island Rescue.

However, suppose you already had a dirname subroutine? You've now overwritten it with the definition provided by File::Basename! If you had turned on warnings, you'd see a message stating that, but otherwise, Perl really doesn't care.