class IO::Spec::Unix
Platform specific operations on file and directory paths for POSIX
is IO::Spec
On object of this type is available via the variable $*SPEC
if the Perl 6 interpreter is running on a Unix-like platform.
The IO::Spec::*
classes provide low-level path operations. Unless you're creating your own high-level path manipulation routines, you don't need to use IO::Spec::*
. Use IO::Path
instead.
Beware that no special validation is done by these classes (e.g. check whether path contains a null character). It is the job of higher-level classes, like IO::Path
, to do that.
Methods
method abs2rel
Defined as:
method abs2rel(IO::Path , IO::Path = --> Str)
Returns a string that represents $path
, but relative to $base
path. Both $path
and $base
may be relative paths. $base
defaults to $*CWD
.
method basename
Defined as:
method basename(Str --> Str)
Takes a path as a string and returns a possibly-empty portion after the last slash:
IO::Spec::Unix.basename("foo/bar/") .perl.say; # OUTPUT: «""»IO::Spec::Unix.basename("foo/bar/.").perl.say; # OUTPUT: «"."»IO::Spec::Unix.basename("foo/bar") .perl.say; # OUTPUT: «"bar"»
method canonpath
Defined as:
method canonpath(Str() , : --> Str)
Returns a string that is a canonical representation of $path
. If :$parent
is set to true, will also clean up references to parent directories. NOTE: the routine does not access the filesystem, so no symlinks are followed.
IO::Spec::Unix.canonpath("foo//../bar/../ber").say;# OUTPUT: «foo/../bar/../ber»IO::Spec::Unix.canonpath("foo///./../bar/../ber").say;# OUTPUT: «foo/../bar/../ber»IO::Spec::Unix.canonpath("foo///./../bar/../ber", :parent).say;# OUTPUT: «ber»
method catdir
Defined as:
method catdir (* --> Str)
Concatenates multiple path fragments and returns the canonical representation of the resultant path as a string. The @parts
are Str
objects and are allowed to contain path separators.
IO::Spec::Unix.catdir(<foo/bar ber perl>).say; # OUTPUT: «foo/bar/ber/perl»
method catfile
Alias for catdir
.
method catpath
Defined as:
method catpath ($, Str , Str --> Str)
Takes two path fragments and concatenates them, adding or removing a path separator, if necessary. The first argument is ignored (it exists to maintain consistent interface with other IO::Spec|/type/IO::Spec
types for systems that have volumes).
IO::Spec::Unix.catpath($, 'some/dir', 'and/more').say;# OUTPUT: «some/dir/and/more»
method curdir
Defined as:
method curdir()
Returns a string representing the current directory:
say '.' eq .curdir; # OUTPUT: «True»
method curupdir
Defined as:
method curupdir()
Returns a none
Junction of strings representing the current directory and the "one directory up":
say .curupdir; # OUTPUT: «none(., ..)»my = <. foo .. bar>;say .grep(* eq .curupdir); # OUTPUT: «(foo bar)»
Neither foo
nor bar
are equal to the representation of the current or parent directory, that is why they are returned by grep
.
method devnull
Defined as:
method devnull(--> Str)
Returns the string "/dev/null"
representing the "Null device":
.devnull.IO.spurt: "foo bar baz";
method dir-sep
Defined as:
method dir-sep(--> Str)
Returns the string "/"
representing canonical directory separator character.
IO::Spec::Unix.dir-sep.say; # OUTPUT: «/»
method extension
NOTE: Most users would want to use the higher-level routine IO::Path.extension
instead of this lower-level version.
Defined as:
method extension(Str --> Str)
Takes a string representing a base name and returns the characters after the last dot ("."
), or empty string if no dots are present. The routine makes no attempt to detect path separators and will return everything after the last dot.
.extension('foo.' ).perl.say; # OUTPUT: «""».extension('foo.txt' ).perl.say; # OUTPUT: «"txt"».extension('foo.tar.gz').perl.say; # OUTPUT: «"gz"».extension('foo' ).perl.say; # OUTPUT: «""».extension('bar.foo/foo').perl.say; # OUTPUT: «"foo/foo"»
method is-absolute
Defined as:
method is-absolute(Str --> Bool)
Returns True
if the $path
starts with a slash ("/"
), even if it has combining character on it:
say IO::Spec::Unix.is-absolute: "/foo"; # OUTPUT: «True»say IO::Spec::Unix.is-absolute: "/\x[308]foo"; # OUTPUT: «True»say IO::Spec::Unix.is-absolute: "bar"; # OUTPUT: «False»
method join
Defined as:
method join ($, Str , Str --> Str)
Similar to catpath
, takes two path fragments and concatenates them, adding or removing a path separator, if necessary, except it will return just $file
if both $dir
and $file
are string '/'
or if $dir
is the string '.'
. The first argument is ignored (it exists to maintain consistent interface with other IO::Spec
types for systems that have volumes).
IO::Spec::Unix.join($, 'foo', 'bar').say; # OUTPUT: «foo/bar»IO::Spec::Unix.join($, '/', '/').say; # OUTPUT: «/»IO::Spec::Unix.join($, '.', 'foo').say; # OUTPUT: «foo»say .join(True,".","/foo"); # OUTPUT: «/foo»
method path
Defined as:
method path(--> Seq)
Splits the value of %*ENV<PATH>
on colons (":"
), replaces empty parts with "."
, and returns a Seq with each of the resultant parts. Returns an empty Seq if %*ENV<PATH>
is not set or is an empty string.
<PATH> = 'foo:bar/ber::foo:';IO::Spec::Unix.path.perl.say;# OUTPUT: «("foo", "bar/ber", ".", "foo", ".").Seq»
method rel2abs
Defined as:
method rel2abs(Str() , = --> Str)
Returns a string representing $path
converted to absolute path, based at $base
, which defaults to $*CWD
. If $base
is not an absolute path, it will be made absolute relative to $*CWD
, unless $*CWD
and $base
are the same.
say ; # OUTPUT: «"/home/camelia".IO»say IO::Spec::Unix.rel2abs: 'foo'; # OUTPUT: «/home/camelia/foo»say IO::Spec::Unix.rel2abs: './'; # OUTPUT: «/home/camelia»say IO::Spec::Unix.rel2abs: 'foo/../../'; # OUTPUT: «/home/camelia/foo/../..»say IO::Spec::Unix.rel2abs: '/foo/'; # OUTPUT: «/foo»say IO::Spec::Unix.rel2abs: 'foo', 'bar'; # OUTPUT: «/home/camelia/bar/foo»say IO::Spec::Unix.rel2abs: './', '/bar'; # OUTPUT: «/bar»say IO::Spec::Unix.rel2abs: '/foo/', 'bar'; # OUTPUT: «/foo»say IO::Spec::Unix.rel2abs: 'foo/../../', 'bar';# OUTPUT: «/home/camelia/bar/foo/../..»
method rootdir
Defined as:
method rootdir(--> Str)
Returns string '/'
, representing root directory.
method split
Defined as:
method split(Cool --> List)
Splits the given $path
into "volume", "dirname", and "basename" and returns the result as a List of three Pairs, in that order. The "volume" is always an empty string and exists for consistency with other IO::Spec classes.
IO::Spec::Unix.split('C:/foo/bar.txt').perl.say;# OUTPUT: «(:volume(""), :dirname("C:/foo"), :basename("bar.txt"))»IO::Spec::Unix.split('/foo/').perl.say;# OUTPUT: «(:volume(""), :dirname("/"), :basename("foo"))»IO::Spec::Unix.split('///').perl.say;# OUTPUT: «(:volume(""), :dirname("/"), :basename("/"))»IO::Spec::Unix.split('./').perl.say;# OUTPUT: «(:volume(""), :dirname("."), :basename("."))»IO::Spec::Unix.split('.').perl.say;# OUTPUT: «(:volume(""), :dirname("."), :basename("."))»IO::Spec::Unix.split('').perl.say;# OUTPUT: «(:volume(""), :dirname(""), :basename(""))»
method splitdir
Defined as:
method splitdir(Cool --> List)
Splits the given $path
on slashes.
IO::Spec::Unix.splitdir('C:\foo/bar.txt').perl.say;# OUTPUT: «("C:\\foo", "bar.txt")»IO::Spec::Unix.splitdir('/foo/').perl.say;# OUTPUT: «("", "foo", "")»IO::Spec::Unix.splitdir('///').perl.say;# OUTPUT: «("", "", "", "")»IO::Spec::Unix.splitdir('./').perl.say;# OUTPUT: «(".", "")»IO::Spec::Unix.splitdir('.').perl.say;# OUTPUT: «(".",)»IO::Spec::Unix.splitdir('').perl.say;# OUTPUT: «("",)»
method splitpath
Defined as:
method splitpath(Cool , : --> List)
Splits the given $path
into a list of 3 strings: volume, dirname, and file. The volume is always an empty string, returned for API compatibility with other IO::Spec types. If :$nofile
named argument is set to True
, the content of the file string is undefined and should be ignored; this is a means to get a performance boost, as implementations may use faster code path when file is not needed.
IO::Spec::Unix.splitpath('C:\foo/bar.txt').perl.say;# OUTPUT: «("", "C:\\foo/", "bar.txt")»IO::Spec::Unix.splitpath('C:\foo/bar.txt', :nofile).perl.say;# OUTPUT: «("", "C:\\foo/bar.txt", "")»IO::Spec::Unix.splitpath('/foo/').perl.say;# OUTPUT: «("", "/foo/", "")»IO::Spec::Unix.splitpath('/foo/', :nofile).perl.say;# OUTPUT: «("", "/foo/", "")»IO::Spec::Unix.splitpath('///').perl.say;# OUTPUT: «("", "///", "")»IO::Spec::Unix.splitpath('./').perl.say;# OUTPUT: «("", "./", "")»IO::Spec::Unix.splitpath('.').perl.say;# OUTPUT: «("", "", ".")»IO::Spec::Unix.splitpath('').perl.say;# OUTPUT: «("", "", "")»
method tmpdir
Defined as:
method tmpdir(--> IO::Path)
Attempts to locate a system's temporary directory by checking several typical directories and environmental variables. Uses current directory if no suitable directories are found.
method updir
Defined as:
method updir()
Returns a string representing the directory one up from current:
say '..' eq .updir; # OUTPUT: «True»