Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | Basename - parse file specifications |
4 | |
5 | fileparse - split a pathname into pieces |
6 | |
7 | basename - extract just the filename from a path |
8 | |
9 | dirname - extract just the directory from a path |
10 | |
11 | =head1 SYNOPSIS |
12 | |
13 | use File::Basename; |
14 | |
15 | ($name,$path,$suffix) = fileparse($fullname,@suffixlist) |
16 | fileparse_set_fstype($os_string); |
17 | $basename = basename($fullname,@suffixlist); |
18 | $dirname = dirname($fullname); |
19 | |
20 | ($name,$path,$suffix) = fileparse("lib/File/Basename.pm",".pm"); |
21 | fileparse_set_fstype("VMS"); |
22 | $basename = basename("lib/File/Basename.pm",".pm"); |
23 | $dirname = dirname("lib/File/Basename.pm"); |
24 | |
25 | =head1 DESCRIPTION |
26 | |
27 | These routines allow you to parse file specifications into useful |
748a9306 |
28 | pieces using the syntax of different operating systems. |
a0d0e21e |
29 | |
30 | =over 4 |
31 | |
32 | =item fileparse_set_fstype |
33 | |
34 | You select the syntax via the routine fileparse_set_fstype(). |
35 | If the argument passed to it contains one of the substrings |
36 | "VMS", "MSDOS", or "MacOS", the file specification syntax of that |
37 | operating system is used in future calls to fileparse(), |
38 | basename(), and dirname(). If it contains none of these |
39 | substrings, UNIX syntax is used. This pattern matching is |
40 | case-insensitive. If you've selected VMS syntax, and the file |
41 | specification you pass to one of these routines contains a "/", |
42 | they assume you are using UNIX emulation and apply the UNIX syntax |
43 | rules instead, for that function call only. |
44 | |
45 | If you haven't called fileparse_set_fstype(), the syntax is chosen |
46 | by examining the "osname" entry from the C<Config> package |
47 | according to these rules. |
48 | |
49 | =item fileparse |
50 | |
51 | The fileparse() routine divides a file specification into three |
52 | parts: a leading B<path>, a file B<name>, and a B<suffix>. The |
53 | B<path> contains everything up to and including the last directory |
54 | separator in the input file specification. The remainder of the input |
55 | file specification is then divided into B<name> and B<suffix> based on |
56 | the optional patterns you specify in C<@suffixlist>. Each element of |
57 | this list is interpreted as a regular expression, and is matched |
58 | against the end of B<name>. If this succeeds, the matching portion of |
59 | B<name> is removed and prepended to B<suffix>. By proper use of |
60 | C<@suffixlist>, you can remove file types or versions for examination. |
61 | |
62 | You are guaranteed that if you concatenate B<path>, B<name>, and |
63 | B<suffix> together in that order, the result will be identical to the |
64 | input file specification. |
65 | |
66 | =back |
67 | |
68 | =head1 EXAMPLES |
69 | |
70 | Using UNIX file syntax: |
71 | |
72 | ($base,$path,$type) = fileparse('/virgil/aeneid/draft.book7', |
73 | '\.book\d+'); |
74 | |
75 | would yield |
76 | |
77 | $base eq 'draft' |
78 | $path eq '/virgil/aeneid', |
79 | $tail eq '.book7' |
80 | |
81 | Similarly, using VMS syntax: |
82 | |
83 | ($name,$dir,$type) = fileparse('Doc_Root:[Help]Rhetoric.Rnh', |
84 | '\..*'); |
85 | |
86 | would yield |
87 | |
88 | $name eq 'Rhetoric' |
89 | $dir eq 'Doc_Root:[Help]' |
90 | $type eq '.Rnh' |
91 | |
92 | =item C<basename> |
93 | |
94 | The basename() routine returns the first element of the list produced |
95 | by calling fileparse() with the same arguments. It is provided for |
96 | compatibility with the UNIX shell command basename(1). |
97 | |
98 | =item C<dirname> |
99 | |
100 | The dirname() routine returns the directory portion of the input file |
101 | specification. When using VMS or MacOS syntax, this is identical to the |
102 | second element of the list produced by calling fileparse() with the same |
103 | input file specification. When using UNIX or MSDOS syntax, the return |
104 | value conforms to the behavior of the UNIX shell command dirname(1). This |
105 | is usually the same as the behavior of fileparse(), but differs in some |
106 | cases. For example, for the input file specification F<lib/>, fileparse() |
107 | considers the directory name to be F<lib/>, while dirname() considers the |
108 | directory name to be F<.>). |