From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/mageia-cauldron/man3pm/File::Basename.3pm | 241 +++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 upstream/mageia-cauldron/man3pm/File::Basename.3pm (limited to 'upstream/mageia-cauldron/man3pm/File::Basename.3pm') diff --git a/upstream/mageia-cauldron/man3pm/File::Basename.3pm b/upstream/mageia-cauldron/man3pm/File::Basename.3pm new file mode 100644 index 00000000..e1222c35 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/File::Basename.3pm @@ -0,0 +1,241 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "File::Basename 3pm" +.TH File::Basename 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +File::Basename \- Parse file paths into directory, filename and suffix. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use File::Basename; +\& +\& my ($name, $path, $suffix) = fileparse($fullname, @suffixlist); +\& my $name = fileparse($fullname, @suffixlist); +\& +\& my $basename = basename($fullname, @suffixlist); +\& my $dirname = dirname($fullname); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These routines allow you to parse file paths into their directory, filename +and suffix. +.PP +\&\fBNOTE\fR: \f(CWdirname()\fR and \f(CWbasename()\fR emulate the behaviours, and +quirks, of the shell and C functions of the same name. See each +function's documentation for details. If your concern is just parsing +paths it is safer to use File::Spec's \f(CWsplitpath()\fR and +\&\f(CWsplitdir()\fR methods. +.PP +It is guaranteed that +.PP +.Vb 2 +\& # Where $path_separator is / for Unix, \e for Windows, etc... +\& dirname($path) . $path_separator . basename($path); +.Ve +.PP +is equivalent to the original path for all systems but VMS. +.ie n .IP """fileparse""" 4 +.el .IP \f(CWfileparse\fR 4 +.IX Xref "fileparse" +.IX Item "fileparse" +.Vb 3 +\& my($filename, $dirs, $suffix) = fileparse($path); +\& my($filename, $dirs, $suffix) = fileparse($path, @suffixes); +\& my $filename = fileparse($path, @suffixes); +.Ve +.Sp +The \f(CWfileparse()\fR routine divides a file path into its \f(CW$dirs\fR, \f(CW$filename\fR +and (optionally) the filename \f(CW$suffix\fR. +.Sp +\&\f(CW$dirs\fR contains everything up to and including the last +directory separator in the \f(CW$path\fR including the volume (if applicable). +The remainder of the \f(CW$path\fR is the \f(CW$filename\fR. +.Sp +.Vb 2 +\& # On Unix returns ("baz", "/foo/bar/", "") +\& fileparse("/foo/bar/baz"); +\& +\& # On Windows returns ("baz", \*(AqC:\efoo\ebar\e\*(Aq, "") +\& fileparse(\*(AqC:\efoo\ebar\ebaz\*(Aq); +\& +\& # On Unix returns ("", "/foo/bar/baz/", "") +\& fileparse("/foo/bar/baz/"); +.Ve +.Sp +If \f(CW@suffixes\fR are given each element is a pattern (either a string or a +\&\f(CW\*(C`qr//\*(C'\fR) matched against the end of the \f(CW$filename\fR. The matching +portion is removed and becomes the \f(CW$suffix\fR. +.Sp +.Vb 2 +\& # On Unix returns ("baz", "/foo/bar/", ".txt") +\& fileparse("/foo/bar/baz.txt", qr/\e.[^.]*/); +.Ve +.Sp +If type is non-Unix (see "fileparse_set_fstype") then the pattern +matching for suffix removal is performed case-insensitively, since +those systems are not case-sensitive when opening existing files. +.Sp +You are guaranteed that \f(CW\*(C`$dirs . $filename . $suffix\*(C'\fR will +denote the same location as the original \f(CW$path\fR. +.ie n .IP """basename""" 4 +.el .IP \f(CWbasename\fR 4 +.IX Xref "basename filename" +.IX Item "basename" +.Vb 2 +\& my $filename = basename($path); +\& my $filename = basename($path, @suffixes); +.Ve +.Sp +This function is provided for compatibility with the Unix shell command +\&\f(CWbasename(1)\fR. It does \fBNOT\fR always return the file name portion of a +path as you might expect. To be safe, if you want the file name portion of +a path use \f(CWfileparse()\fR. +.Sp +\&\f(CWbasename()\fR returns the last level of a filepath even if the last +level is clearly directory. In effect, it is acting like \f(CWpop()\fR for +paths. This differs from \f(CWfileparse()\fR's behaviour. +.Sp +.Vb 3 +\& # Both return "bar" +\& basename("/foo/bar"); +\& basename("/foo/bar/"); +.Ve +.Sp +\&\f(CW@suffixes\fR work as in \f(CWfileparse()\fR except all regex metacharacters are +quoted. +.Sp +.Vb 3 +\& # These two function calls are equivalent. +\& my $filename = basename("/foo/bar/baz.txt", ".txt"); +\& my $filename = fileparse("/foo/bar/baz.txt", qr/\eQ.txt\eE/); +.Ve +.Sp +Also note that in order to be compatible with the shell command, +\&\f(CWbasename()\fR does not strip off a suffix if it is identical to the +remaining characters in the filename. +.ie n .IP """dirname""" 4 +.el .IP \f(CWdirname\fR 4 +.IX Xref "dirname" +.IX Item "dirname" +This function is provided for compatibility with the Unix shell +command \f(CWdirname(1)\fR and has inherited some of its quirks. In spite of +its name it does \fBNOT\fR always return the directory name as you might +expect. To be safe, if you want the directory name of a path use +\&\f(CWfileparse()\fR. +.Sp +Only on VMS (where there is no ambiguity between the file and directory +portions of a path) and AmigaOS (possibly due to an implementation quirk in +this module) does \f(CWdirname()\fR work like \f(CWfileparse($path)\fR, returning just the +\&\f(CW$dirs\fR. +.Sp +.Vb 2 +\& # On VMS and AmigaOS +\& my $dirs = dirname($path); +.Ve +.Sp +When using Unix or MSDOS syntax this emulates the \f(CWdirname(1)\fR shell function +which is subtly different from how \f(CWfileparse()\fR works. It returns all but +the last level of a file path even if the last level is clearly a directory. +In effect, it is not returning the directory portion but simply the path one +level up acting like \f(CWchop()\fR for file paths. +.Sp +Also unlike \f(CWfileparse()\fR, \f(CWdirname()\fR does not include a trailing slash on +its returned path. +.Sp +.Vb 2 +\& # returns /foo/bar. fileparse() would return /foo/bar/ +\& dirname("/foo/bar/baz"); +\& +\& # also returns /foo/bar despite the fact that baz is clearly a +\& # directory. fileparse() would return /foo/bar/baz/ +\& dirname("/foo/bar/baz/"); +\& +\& # returns \*(Aq.\*(Aq. fileparse() would return \*(Aqfoo/\*(Aq +\& dirname("foo/"); +.Ve +.Sp +Under VMS, if there is no directory information in the \f(CW$path\fR, then the +current default device and directory is used. +.ie n .IP """fileparse_set_fstype""" 4 +.el .IP \f(CWfileparse_set_fstype\fR 4 +.IX Xref "filesystem" +.IX Item "fileparse_set_fstype" +.Vb 2 +\& my $type = fileparse_set_fstype(); +\& my $previous_type = fileparse_set_fstype($type); +.Ve +.Sp +Normally File::Basename will assume a file path type native to your current +operating system (ie. /foo/bar style on Unix, \efoo\ebar on Windows, etc...). +With this function you can override that assumption. +.Sp +Valid \f(CW$types\fR are "MacOS", "VMS", "AmigaOS", "OS2", "RISCOS", +"MSWin32", "DOS" (also "MSDOS" for backwards bug compatibility), +"Epoc" and "Unix" (all case-insensitive). If an unrecognized \f(CW$type\fR is +given "Unix" will be assumed. +.Sp +If you've selected VMS syntax, and the file specification you pass to +one of these routines contains a "/", they assume you are using Unix +emulation and apply the Unix syntax rules instead, for that function +call only. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBdirname\fR\|(1), \fBbasename\fR\|(1), File::Spec -- cgit v1.2.3