mingw/html/lib/File/Spec.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::Spec - portably perform operations on file names</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::Spec - portably perform operations on file names</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="#methods">METHODS</a></li>
  26         <li><a href="#see_also">SEE ALSO</a></li>
  27         <li><a href="#author">AUTHOR</a></li>
  28         <li><a href="#copyright">COPYRIGHT</a></li>
  29 </ul>
  30 <!-- INDEX END -->
  31
  32 <hr />
  33 <p>
  34 </p>
  35 <h1><a name="name">NAME</a></h1>
  36 <p>File::Spec - portably perform operations on file names</p>
  37 <p>
  38 </p>
  39 <hr />
  40 <h1><a name="synopsis">SYNOPSIS</a></h1>
  41 <pre>
  42         use File::Spec;</pre>
  43 <pre>
  44         $x=File::Spec-&gt;catfile('a', 'b', 'c');</pre>
  45 <p>which returns 'a/b/c' under Unix. Or:</p>
  46 <pre>
  47         use File::Spec::Functions;</pre>
  48 <pre>
  49         $x = catfile('a', 'b', 'c');</pre>
  50 <p>
  51 </p>
  52 <hr />
  53 <h1><a name="description">DESCRIPTION</a></h1>
  54 <p>This module is designed to support operations commonly performed on file
  55 specifications (usually called ``file names'', but not to be confused with the
  56 contents of a file, or Perl's file handles), such as concatenating several
  57 directory and file names into a single path, or determining whether a path
  58 is rooted. It is based on code directly taken from MakeMaker 5.17, code
  59 written by Andreas K&ouml;nig, Andy Dougherty, Charles Bailey, Ilya
  60 Zakharevich, Paul Schinder, and others.</p>
  61 <p>Since these functions are different for most operating systems, each set of
  62 OS specific routines is available in a separate module, including:</p>
  63 <pre>
  64         File::Spec::Unix
  65         File::Spec::Mac
  66         File::Spec::OS2
  67         File::Spec::Win32
  68         File::Spec::VMS</pre>
  69 <p>The module appropriate for the current OS is automatically loaded by
  70 File::Spec. Since some modules (like VMS) make use of facilities available
  71 only under that OS, it may not be possible to load all modules under all
  72 operating systems.</p>
  73 <p>Since File::Spec is object oriented, subroutines should not be called directly,
  74 as in:</p>
  75 <pre>
  76         File::Spec::catfile('a','b');</pre>
  77 <p>but rather as class methods:</p>
  78 <pre>
  79         File::Spec-&gt;catfile('a','b');</pre>
  80 <p>For simple uses, <a href="file://C|\msysgit\mingw\html/lib/File/Spec/Functions.html">the File::Spec::Functions manpage</a> provides convenient functional
  81 forms of these methods.</p>
  82 <p>
  83 </p>
  84 <hr />
  85 <h1><a name="methods">METHODS</a></h1>
  86 <dl>
  87 <dt><strong><a name="item_canonpath">canonpath</a></strong>
  88
  89 <dd>
  90 <p>No physical check on the filesystem, but a logical cleanup of a
  91 path.</p>
  92 </dd>
  93 <dd>
  94 <pre>
  95     $cpath = File::Spec-&gt;canonpath( $path ) ;</pre>
  96 </dd>
  97 <dd>
  98 <p>Note that this does *not* collapse <em>x/../y</em> sections into <em>y</em>.  This
  99 is by design.  If <em>/foo</em> on your system is a symlink to <em>/bar/baz</em>,
 100 then <em>/foo/../quux</em> is actually <em>/bar/quux</em>, not <em>/quux</em> as a naive
 101 <em>../</em>-removal would give you.  If you want to do this kind of
 102 processing, you probably want <code>Cwd</code>'s <code>realpath()</code> function to
 103 actually traverse the filesystem cleaning up paths like this.</p>
 104 </dd>
 105 </li>
 106 <dt><strong><a name="item_catdir">catdir</a></strong>
 107
 108 <dd>
 109 <p>Concatenate two or more directory names to form a complete path ending
 110 with a directory. But remove the trailing slash from the resulting
 111 string, because it doesn't look good, isn't necessary and confuses
 112 OS/2. Of course, if this is the root directory, don't cut off the
 113 trailing slash :-)</p>
 114 </dd>
 115 <dd>
 116 <pre>
 117     $path = File::Spec-&gt;catdir( @directories );</pre>
 118 </dd>
 119 </li>
 120 <dt><strong><a name="item_catfile">catfile</a></strong>
 121
 122 <dd>
 123 <p>Concatenate one or more directory names and a filename to form a
 124 complete path ending with a filename</p>
 125 </dd>
 126 <dd>
 127 <pre>
 128     $path = File::Spec-&gt;catfile( @directories, $filename );</pre>
 129 </dd>
 130 </li>
 131 <dt><strong><a name="item_curdir">curdir</a></strong>
 132
 133 <dd>
 134 <p>Returns a string representation of the current directory.</p>
 135 </dd>
 136 <dd>
 137 <pre>
 138     $curdir = File::Spec-&gt;curdir();</pre>
 139 </dd>
 140 </li>
 141 <dt><strong><a name="item_devnull">devnull</a></strong>
 142
 143 <dd>
 144 <p>Returns a string representation of the null device.</p>
 145 </dd>
 146 <dd>
 147 <pre>
 148     $devnull = File::Spec-&gt;devnull();</pre>
 149 </dd>
 150 </li>
 151 <dt><strong><a name="item_rootdir">rootdir</a></strong>
 152
 153 <dd>
 154 <p>Returns a string representation of the root directory.</p>
 155 </dd>
 156 <dd>
 157 <pre>
 158     $rootdir = File::Spec-&gt;rootdir();</pre>
 159 </dd>
 160 </li>
 161 <dt><strong><a name="item_tmpdir">tmpdir</a></strong>
 162
 163 <dd>
 164 <p>Returns a string representation of the first writable directory from a
 165 list of possible temporary directories.  Returns the current directory
 166 if no writable temporary directories are found.  The list of directories
 167 checked depends on the platform; e.g. File::Spec::Unix checks <code>$ENV{TMPDIR}</code>
 168 (unless taint is on) and <em>/tmp</em>.</p>
 169 </dd>
 170 <dd>
 171 <pre>
 172     $tmpdir = File::Spec-&gt;tmpdir();</pre>
 173 </dd>
 174 </li>
 175 <dt><strong><a name="item_updir">updir</a></strong>
 176
 177 <dd>
 178 <p>Returns a string representation of the parent directory.</p>
 179 </dd>
 180 <dd>
 181 <pre>
 182     $updir = File::Spec-&gt;updir();</pre>
 183 </dd>
 184 </li>
 185 <dt><strong><a name="item_no_upwards">no_upwards</a></strong>
 186
 187 <dd>
 188 <p>Given a list of file names, strip out those that refer to a parent
 189 directory. (Does not strip symlinks, only '.', '..', and equivalents.)</p>
 190 </dd>
 191 <dd>
 192 <pre>
 193     @paths = File::Spec-&gt;no_upwards( @paths );</pre>
 194 </dd>
 195 </li>
 196 <dt><strong><a name="item_case_tolerant">case_tolerant</a></strong>
 197
 198 <dd>
 199 <p>Returns a true or false value indicating, respectively, that alphabetic
 200 case is not or is significant when comparing file specifications.</p>
 201 </dd>
 202 <dd>
 203 <pre>
 204     $is_case_tolerant = File::Spec-&gt;case_tolerant();</pre>
 205 </dd>
 206 </li>
 207 <dt><strong><a name="item_file_name_is_absolute">file_name_is_absolute</a></strong>
 208
 209 <dd>
 210 <p>Takes as its argument a path, and returns true if it is an absolute path.</p>
 211 </dd>
 212 <dd>
 213 <pre>
 214     $is_absolute = File::Spec-&gt;file_name_is_absolute( $path );</pre>
 215 </dd>
 216 <dd>
 217 <p>This does not consult the local filesystem on Unix, Win32, OS/2, or
 218 Mac OS (Classic).  It does consult the working environment for VMS
 219 (see <a href="file://C|\msysgit\mingw\html/lib/File/Spec/VMS.html#file_name_is_absolute">file_name_is_absolute in the File::Spec::VMS manpage</a>).</p>
 220 </dd>
 221 </li>
 222 <dt><strong><a name="item_path">path</a></strong>
 223
 224 <dd>
 225 <p>Takes no argument.  Returns the environment variable <code>PATH</code> (or the local
 226 platform's equivalent) as a list.</p>
 227 </dd>
 228 <dd>
 229 <pre>
 230     @PATH = File::Spec-&gt;path();</pre>
 231 </dd>
 232 </li>
 233 <dt><strong><a name="item_join">join</a></strong>
 234
 235 <dd>
 236 <p>join is the same as catfile.</p>
 237 </dd>
 238 </li>
 239 <dt><strong><a name="item_splitpath">splitpath</a></strong>
 240
 241 <dd>
 242 <p>Splits a path in to volume, directory, and filename portions. On systems
 243 with no concept of volume, returns '' for volume.</p>
 244 </dd>
 245 <dd>
 246 <pre>
 247     ($volume,$directories,$file) = File::Spec-&gt;splitpath( $path );
 248     ($volume,$directories,$file) = File::Spec-&gt;splitpath( $path, $no_file );</pre>
 249 </dd>
 250 <dd>
 251 <p>For systems with no syntax differentiating filenames from directories,
 252 assumes that the last file is a path unless <code>$no_file</code> is true or a
 253 trailing separator or <em>/.</em> or <em>/..</em> is present. On Unix, this means that <code>$no_file</code>
 254 true makes this return ( '', $path, '' ).</p>
 255 </dd>
 256 <dd>
 257 <p>The directory portion may or may not be returned with a trailing '/'.</p>
 258 </dd>
 259 <dd>
 260 <p>The results can be passed to <a href="#item_catpath">catpath()</a> to get back a path equivalent to
 261 (usually identical to) the original path.</p>
 262 </dd>
 263 </li>
 264 <dt><strong><a name="item_splitdir">splitdir</a></strong>
 265
 266 <dd>
 267 <p>The opposite of <a href="#item_catdir">catdir()</a>.</p>
 268 </dd>
 269 <dd>
 270 <pre>
 271     @dirs = File::Spec-&gt;splitdir( $directories );</pre>
 272 </dd>
 273 <dd>
 274 <p><code>$directories</code> must be only the directory portion of the path on systems
 275 that have the concept of a volume or that have path syntax that differentiates
 276 files from directories.</p>
 277 </dd>
 278 <dd>
 279 <p>Unlike just splitting the directories on the separator, empty
 280 directory names (<code>''</code>) can be returned, because these are significant
 281 on some OSes.</p>
 282 </dd>
 283 </li>
 284 <dt><strong><a name="item_catpath"><code>catpath()</code></a></strong>
 285
 286 <dd>
 287 <p>Takes volume, directory and file portions and returns an entire path. Under
 288 Unix, <code>$volume</code> is ignored, and directory and file are concatenated.  A '/' is
 289 inserted if need be.  On other OSes, <code>$volume</code> is significant.</p>
 290 </dd>
 291 <dd>
 292 <pre>
 293     $full_path = File::Spec-&gt;catpath( $volume, $directory, $file );</pre>
 294 </dd>
 295 </li>
 296 <dt><strong><a name="item_abs2rel">abs2rel</a></strong>
 297
 298 <dd>
 299 <p>Takes a destination path and an optional base path returns a relative path
 300 from the base path to the destination path:</p>
 301 </dd>
 302 <dd>
 303 <pre>
 304     $rel_path = File::Spec-&gt;abs2rel( $path ) ;
 305     $rel_path = File::Spec-&gt;abs2rel( $path, $base ) ;</pre>
 306 </dd>
 307 <dd>
 308 <p>If <code>$base</code> is not present or '', then <a href="file://C|\msysgit\mingw\html/lib/Cwd.html">cwd()</a> is used. If <code>$base</code> is
 309 relative, then it is converted to absolute form using
 310 <a href="#item_rel2abs">rel2abs()</a>. This means that it is taken to be relative to
 311 <a href="file://C|\msysgit\mingw\html/lib/Cwd.html">cwd()</a>.</p>
 312 </dd>
 313 <dd>
 314 <p>On systems with the concept of volume, if <code>$path</code> and <code>$base</code> appear to be
 315 on two different volumes, we will not attempt to resolve the two
 316 paths, and we will instead simply return <code>$path</code>.  Note that previous
 317 versions of this module ignored the volume of <code>$base</code>, which resulted in
 318 garbage results part of the time.</p>
 319 </dd>
 320 <dd>
 321 <p>On systems that have a grammar that indicates filenames, this ignores the
 322 <code>$base</code> filename as well. Otherwise all path components are assumed to be
 323 directories.</p>
 324 </dd>
 325 <dd>
 326 <p>If <code>$path</code> is relative, it is converted to absolute form using <a href="#item_rel2abs">rel2abs()</a>.
 327 This means that it is taken to be relative to <a href="file://C|\msysgit\mingw\html/lib/Cwd.html">cwd()</a>.</p>
 328 </dd>
 329 <dd>
 330 <p>No checks against the filesystem are made.  On VMS, there is
 331 interaction with the working environment, as logicals and
 332 macros are expanded.</p>
 333 </dd>
 334 <dd>
 335 <p>Based on code written by Shigio Yamaguchi.</p>
 336 </dd>
 337 </li>
 338 <dt><strong><a name="item_rel2abs"><code>rel2abs()</code></a></strong>
 339
 340 <dd>
 341 <p>Converts a relative path to an absolute path.</p>
 342 </dd>
 343 <dd>
 344 <pre>
 345     $abs_path = File::Spec-&gt;rel2abs( $path ) ;
 346     $abs_path = File::Spec-&gt;rel2abs( $path, $base ) ;</pre>
 347 </dd>
 348 <dd>
 349 <p>If <code>$base</code> is not present or '', then <a href="file://C|\msysgit\mingw\html/lib/Cwd.html">cwd()</a> is used. If <code>$base</code> is relative,
 350 then it is converted to absolute form using <a href="#item_rel2abs">rel2abs()</a>. This means that it
 351 is taken to be relative to <a href="file://C|\msysgit\mingw\html/lib/Cwd.html">cwd()</a>.</p>
 352 </dd>
 353 <dd>
 354 <p>On systems with the concept of volume, if <code>$path</code> and <code>$base</code> appear to be
 355 on two different volumes, we will not attempt to resolve the two
 356 paths, and we will instead simply return <code>$path</code>.  Note that previous
 357 versions of this module ignored the volume of <code>$base</code>, which resulted in
 358 garbage results part of the time.</p>
 359 </dd>
 360 <dd>
 361 <p>On systems that have a grammar that indicates filenames, this ignores the
 362 <code>$base</code> filename as well. Otherwise all path components are assumed to be
 363 directories.</p>
 364 </dd>
 365 <dd>
 366 <p>If <code>$path</code> is absolute, it is cleaned up and returned using <a href="#item_canonpath">canonpath()</a>.</p>
 367 </dd>
 368 <dd>
 369 <p>No checks against the filesystem are made.  On VMS, there is
 370 interaction with the working environment, as logicals and
 371 macros are expanded.</p>
 372 </dd>
 373 <dd>
 374 <p>Based on code written by Shigio Yamaguchi.</p>
 375 </dd>
 376 </li>
 377 </dl>
 378 <p>For further information, please see <a href="file://C|\msysgit\mingw\html/lib/File/Spec/Unix.html">the File::Spec::Unix manpage</a>,
 379 <a href="file://C|\msysgit\mingw\html/lib/File/Spec/Mac.html">the File::Spec::Mac manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/File/Spec/OS2.html">the File::Spec::OS2 manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/File/Spec/Win32.html">the File::Spec::Win32 manpage</a>, or
 380 <a href="file://C|\msysgit\mingw\html/lib/File/Spec/VMS.html">the File::Spec::VMS manpage</a>.</p>
 381 <p>
 382 </p>
 383 <hr />
 384 <h1><a name="see_also">SEE ALSO</a></h1>
 385 <p><a href="file://C|\msysgit\mingw\html/lib/File/Spec/Unix.html">the File::Spec::Unix manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/File/Spec/Mac.html">the File::Spec::Mac manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/File/Spec/OS2.html">the File::Spec::OS2 manpage</a>,
 386 <a href="file://C|\msysgit\mingw\html/lib/File/Spec/Win32.html">the File::Spec::Win32 manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/File/Spec/VMS.html">the File::Spec::VMS manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/File/Spec/Functions.html">the File::Spec::Functions manpage</a>,
 387 <a href="file://C|\msysgit\mingw\html/lib/ExtUtils/MakeMaker.html">the ExtUtils::MakeMaker manpage</a></p>
 388 <p>
 389 </p>
 390 <hr />
 391 <h1><a name="author">AUTHOR</a></h1>
 392 <p>Currently maintained by Ken Williams <code>&lt;KWILLIAMS@cpan.org&gt;</code>.</p>
 393 <p>The vast majority of the code was written by
 394 Kenneth Albanowski <code>&lt;kjahds@kjahds.com&gt;</code>,
 395 Andy Dougherty <code>&lt;doughera@lafayette.edu&gt;</code>,
 396 Andreas K&ouml;nig <code>&lt;A.Koenig@franz.ww.TU-Berlin.DE&gt;</code>,
 397 Tim Bunce <code>&lt;Tim.Bunce@ig.co.uk&gt;</code>.
 398 VMS support by Charles Bailey <code>&lt;bailey@newman.upenn.edu&gt;</code>.
 399 OS/2 support by Ilya Zakharevich <code>&lt;ilya@math.ohio-state.edu&gt;</code>.
 400 Mac support by Paul Schinder <code>&lt;schinder@pobox.com&gt;</code>, and
 401 Thomas Wegner <code>&lt;wegner_thomas@yahoo.com&gt;</code>.
 402 <a href="#item_abs2rel"><code>abs2rel()</code></a> and <a href="#item_rel2abs"><code>rel2abs()</code></a> written by Shigio Yamaguchi <code>&lt;shigio@tamacom.com&gt;</code>,
 403 modified by Barrie Slaymaker <code>&lt;barries@slaysys.com&gt;</code>.
 404 splitpath(), splitdir(), <a href="#item_catpath"><code>catpath()</code></a> and <a href="#item_catdir"><code>catdir()</code></a> by Barrie Slaymaker.</p>
 405 <p>
 406 </p>
 407 <hr />
 408 <h1><a name="copyright">COPYRIGHT</a></h1>
 409 <p>Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.</p>
 410 <p>This program is free software; you can redistribute it and/or modify
 411 it under the same terms as Perl itself.</p>
 412 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 413 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 414 <big><strong><span class="block">&nbsp;File::Spec - portably perform operations on file names</span></strong></big>
 415 </td></tr>
 416 </table>
 417
 418 </body>
 419
 420 </html>