mingw/html/lib/File/Basename.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>File::Basename - Parse file paths into directory, filename and suffix.</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;File::Basename - Parse file paths into directory, filename and suffix.</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#see_also">SEE ALSO</a></li>
  26 </ul>
  27 <!-- INDEX END -->
  28
  29 <hr />
  30 <p>
  31 </p>
  32 <h1><a name="name">NAME</a></h1>
  33 <p>File::Basename - Parse file paths into directory, filename and suffix.</p>
  34 <p>
  35 </p>
  36 <hr />
  37 <h1><a name="synopsis">SYNOPSIS</a></h1>
  38 <pre>
  39     use File::Basename;</pre>
  40 <pre>
  41     ($name,$path,$suffix) = fileparse($fullname,@suffixlist);
  42     $name = fileparse($fullname,@suffixlist);</pre>
  43 <pre>
  44     $basename = basename($fullname,@suffixlist);
  45     $dirname  = dirname($fullname);</pre>
  46 <p>
  47 </p>
  48 <hr />
  49 <h1><a name="description">DESCRIPTION</a></h1>
  50 <p>These routines allow you to parse file paths into their directory, filename
  51 and suffix.</p>
  52 <p><strong>NOTE</strong>: <a href="#item_dirname"><code>dirname()</code></a> and <a href="#item_basename"><code>basename()</code></a> emulate the behaviours, and
  53 quirks, of the shell and C functions of the same name.  See each
  54 function's documentation for details.  If your concern is just parsing
  55 paths it is safer to use <a href="file://C|\msysgit\mingw\html/lib/File/Spec.html">the File::Spec manpage</a>'s <code>splitpath()</code> and
  56 <code>splitdir()</code> methods.</p>
  57 <p>It is guaranteed that</p>
  58 <pre>
  59     # Where $path_separator is / for Unix, \ for Windows, etc...
  60     dirname($path) . $path_separator . basename($path);</pre>
  61 <p>is equivalent to the original path for all systems but VMS.</p>
  62 <dl>
  63 <dt><strong><a name="item_fileparse"><code>fileparse</code></a></strong>
  64
  65 <dd>
  66 <pre>
  67     my($filename, $directories, $suffix) = fileparse($path);
  68     my($filename, $directories, $suffix) = fileparse($path, @suffixes);
  69     my $filename                         = fileparse($path, @suffixes);</pre>
  70 </dd>
  71 <dd>
  72 <p>The <a href="#item_fileparse"><code>fileparse()</code></a> routine divides a file path into its $directories, $filename
  73 and (optionally) the filename $suffix.</p>
  74 </dd>
  75 <dd>
  76 <p>$directories contains everything up to and including the last
  77 directory separator in the $path including the volume (if applicable).
  78 The remainder of the $path is the $filename.</p>
  79 </dd>
  80 <dd>
  81 <pre>
  82      # On Unix returns (&quot;baz&quot;, &quot;/foo/bar/&quot;, &quot;&quot;)
  83      fileparse(&quot;/foo/bar/baz&quot;);</pre>
  84 </dd>
  85 <dd>
  86 <pre>
  87      # On Windows returns (&quot;baz&quot;, &quot;C:\foo\bar\&quot;, &quot;&quot;)
  88      fileparse(&quot;C:\foo\bar\baz&quot;);</pre>
  89 </dd>
  90 <dd>
  91 <pre>
  92      # On Unix returns (&quot;&quot;, &quot;/foo/bar/baz/&quot;, &quot;&quot;)
  93      fileparse(&quot;/foo/bar/baz/&quot;);</pre>
  94 </dd>
  95 <dd>
  96 <p>If @suffixes are given each element is a pattern (either a string or a
  97 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_qr_"><code>qr//</code></a>) matched against the end of the $filename.  The matching
  98 portion is removed and becomes the $suffix.</p>
  99 </dd>
 100 <dd>
 101 <pre>
 102      # On Unix returns (&quot;baz&quot;, &quot;/foo/bar&quot;, &quot;.txt&quot;)
 103      fileparse(&quot;/foo/bar/baz&quot;, qr/\.[^.]*/);</pre>
 104 </dd>
 105 <dd>
 106 <p>If type is non-Unix (see <a href="#item_fileparse_set_fstype"><code>fileparse_set_fstype()</code></a>) then the pattern
 107 matching for suffix removal is performed case-insensitively, since
 108 those systems are not case-sensitive when opening existing files.</p>
 109 </dd>
 110 <dd>
 111 <p>You are guaranteed that <code>$directories . $filename . $suffix</code> will
 112 denote the same location as the original $path.</p>
 113 </dd>
 114 <dt><strong><a name="item_basename"><code>basename</code></a></strong>
 115
 116 <dd>
 117 <pre>
 118     my $filename = basename($path);
 119     my $filename = basename($path, @suffixes);</pre>
 120 </dd>
 121 <dd>
 122 <p>This function is provided for compatibility with the Unix shell command
 123 <a href="#item_basename"><code>basename(1)</code></a>.  It does <strong>NOT</strong> always return the file name portion of a
 124 path as you might expect.  To be safe, if you want the file name portion of
 125 a path use <a href="#item_fileparse"><code>fileparse()</code></a>.</p>
 126 </dd>
 127 <dd>
 128 <p><a href="#item_basename"><code>basename()</code></a> returns the last level of a filepath even if the last
 129 level is clearly directory.  In effect, it is acting like <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_pop"><code>pop()</code></a> for
 130 paths.  This differs from <a href="#item_fileparse"><code>fileparse()</code></a>'s behaviour.</p>
 131 </dd>
 132 <dd>
 133 <pre>
 134     # Both return &quot;bar&quot;
 135     basename(&quot;/foo/bar&quot;);
 136     basename(&quot;/foo/bar/&quot;);</pre>
 137 </dd>
 138 <dd>
 139 <p>@suffixes work as in <a href="#item_fileparse"><code>fileparse()</code></a> except all regex metacharacters are
 140 quoted.</p>
 141 </dd>
 142 <dd>
 143 <pre>
 144     # These two function calls are equivalent.
 145     my $filename = basename(&quot;/foo/bar/baz.txt&quot;,  &quot;.txt&quot;);
 146     my $filename = fileparse(&quot;/foo/bar/baz.txt&quot;, qr/\Q.txt\E/);</pre>
 147 </dd>
 148 <dd>
 149 <p>Also note that in order to be compatible with the shell command,
 150 <a href="#item_basename"><code>basename()</code></a> does not strip off a suffix if it is identical to the
 151 remaining characters in the filename.</p>
 152 </dd>
 153 <dt><strong><a name="item_dirname"><code>dirname</code></a></strong>
 154
 155 <dd>
 156 <p>This function is provided for compatibility with the Unix shell
 157 command <a href="#item_dirname"><code>dirname(1)</code></a> and has inherited some of its quirks.  In spite of
 158 its name it does <strong>NOT</strong> always return the directory name as you might
 159 expect.  To be safe, if you want the directory name of a path use
 160 <a href="#item_fileparse"><code>fileparse()</code></a>.</p>
 161 </dd>
 162 <dd>
 163 <p>Only on VMS (where there is no ambiguity between the file and directory
 164 portions of a path) and AmigaOS (possibly due to an implementation quirk in
 165 this module) does <a href="#item_dirname"><code>dirname()</code></a> work like <a href="#item_fileparse"><code>fileparse($path)</code></a>, returning just the
 166 $directories.</p>
 167 </dd>
 168 <dd>
 169 <pre>
 170     # On VMS and AmigaOS
 171     my $directories = dirname($path);</pre>
 172 </dd>
 173 <dd>
 174 <p>When using Unix or MSDOS syntax this emulates the <a href="#item_dirname"><code>dirname(1)</code></a> shell function
 175 which is subtly different from how <a href="#item_fileparse"><code>fileparse()</code></a> works.  It returns all but
 176 the last level of a file path even if the last level is clearly a directory.
 177 In effect, it is not returning the directory portion but simply the path one
 178 level up acting like <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_chop"><code>chop()</code></a> for file paths.</p>
 179 </dd>
 180 <dd>
 181 <p>Also unlike <a href="#item_fileparse"><code>fileparse()</code></a>, <a href="#item_dirname"><code>dirname()</code></a> does not include a trailing slash on
 182 its returned path.</p>
 183 </dd>
 184 <dd>
 185 <pre>
 186     # returns /foo/bar.  fileparse() would return /foo/bar/
 187     dirname(&quot;/foo/bar/baz&quot;);</pre>
 188 </dd>
 189 <dd>
 190 <pre>
 191     # also returns /foo/bar despite the fact that baz is clearly a
 192     # directory.  fileparse() would return /foo/bar/baz/
 193     dirname(&quot;/foo/bar/baz/&quot;);</pre>
 194 </dd>
 195 <dd>
 196 <pre>
 197     # returns '.'.  fileparse() would return 'foo/'
 198     dirname(&quot;foo/&quot;);</pre>
 199 </dd>
 200 <dd>
 201 <p>Under VMS, if there is no directory information in the $path, then the
 202 current default device and directory is used.</p>
 203 </dd>
 204 </li>
 205 <dt><strong><a name="item_fileparse_set_fstype"><code>fileparse_set_fstype</code></a></strong>
 206
 207 <dd>
 208 <pre>
 209   my $type = fileparse_set_fstype();
 210   my $previous_type = fileparse_set_fstype($type);</pre>
 211 </dd>
 212 <dd>
 213 <p>Normally File::Basename will assume a file path type native to your current
 214 operating system (ie. /foo/bar style on Unix, \foo\bar on Windows, etc...).
 215 With this function you can override that assumption.</p>
 216 </dd>
 217 <dd>
 218 <p>Valid $types are ``MacOS'', ``VMS'', ``AmigaOS'', ``OS2'', ``RISCOS'',
 219 ``MSWin32'', ``DOS'' (also ``MSDOS'' for backwards bug compatibility),
 220 ``Epoc'' and ``Unix'' (all case-insensitive).  If an unrecognized $type is
 221 given ``Unix'' will be assumed.</p>
 222 </dd>
 223 <dd>
 224 <p>If you've selected VMS syntax, and the file specification you pass to
 225 one of these routines contains a ``/'', they assume you are using Unix
 226 emulation and apply the Unix syntax rules instead, for that function
 227 call only.</p>
 228 </dd>
 229 </dl>
 230 <p>
 231 </p>
 232 <hr />
 233 <h1><a name="see_also">SEE ALSO</a></h1>
 234 <p><a href="#item_dirname">dirname(1)</a>, <a href="#item_basename">basename(1)</a>, <a href="file://C|\msysgit\mingw\html/lib/File/Spec.html">the File::Spec manpage</a></p>
 235 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 236 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 237 <big><strong><span class="block">&nbsp;File::Basename - Parse file paths into directory, filename and suffix.</span></strong></big>
 238 </td></tr>
 239 </table>
 240
 241 </body>
 242
 243 </html>