Rules / Types, classes & roles / domain-specific

IO::Spec::Unix Reference

Platform specific operations on file and directory paths for POSIX

What it is #

Position in the hierarchy #


Inherits from	—
Does	—
Inherited by	`IO::Spec::Win32`, `IO::Spec::Cygwin`, `IO::Spec::QNX`

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method `abs2rel` #

method abs2rel(IO::Path:D $path, IO::Path:D $base = $*CWD --> Str:D)

Returns Str:D.

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` #

method basename(Str:D $path --> Str:D)

Returns Str:D.

Takes a path as a string and returns a possibly-empty portion after the last slash:

method `canonpath` #

method canonpath(Str() $path, :$parent --> Str:D)

Returns Str:D.

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.

method `catdir` #

method catdir (*@parts --> Str:D)

Returns Str:D.

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.

method `catfile` #

Alias for catdir.

method `catpath` #

method catpath ($, Str:D $part1, Str:D $part2 --> Str:D)

Returns Str:D.

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 types for systems that have volumes).

method `curdir` #

method curdir()

Returns a string representing the current directory:

method `curupdir` #

method curupdir()

Returns a Block taking an argument. This block returns True if its argument is neither the string representing the current directory nor the string representing the directory one up from the current one. It returns False otherwise. This block is intended to be used with smartmatching. Neither foo nor bar are equal to the representation of the current

method `devnull` #

method devnull(--> Str:D)

Returns Str:D.

Returns the string "/dev/null" representing the "Null device":

method `dir-sep` #

method dir-sep(--> Str:D)

Returns Str:D.

Returns the string "/" representing canonical directory separator character.

method `extension` #

method extension(Str:D $path --> Str:D)

Returns Str:D.

NOTE: Most users would want to use the higher-level routine IO::Path.extension instead of this lower-level version. 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.

method `is-absolute` #

method is-absolute(Str:D $path --> Bool:D)

Returns Bool:D.

Returns True if the $path starts with a slash ("/"), even if it has combining character on it:

method `join` #

method join ($, Str:D $dir, Str:D $file --> Str:D)

Returns Str:D.

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).

method `path` #

method path(--> Seq:D)

Returns Seq:D.

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.

method `rel2abs` #

method rel2abs(Str() $path, $base = $*CWD --> Str:D)

Returns Str:D.

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.

method `rootdir` #

method rootdir(--> Str:D)

Returns Str:D.

Returns string '/', representing root directory.

method `split` #

method split(IO::Spec::Unix: Cool:D $path)

Creates an IO::Path::Parts for $path, with an empty string as its volume attribute's value. Note: Before Rakudo release 2020.06 this method split the given $path into "volume", "dirname", and "basename" and returned the result as a List of three Pairs, in that order.

method `splitdir` #

method splitdir(Cool:D $path --> List:D)

Returns List:D.

Splits the given $path on slashes.

method `splitpath` #

method splitpath(Cool:D $path, :$nofile --> List:D)

Returns List:D.

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.

method `tmpdir` #

method tmpdir(--> IO::Path:D)

Returns IO::Path:D.

Attempts to locate a system's temporary directory by checking several typical directories and environment variables. Uses current directory if no suitable directories are found.

method `updir` #

method updir()

Returns a string representing the directory one up from current:

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

1 all-differ · 1 doc-drift · 2 no-output · 16 ok

class IO::Spec::Unix is IO::Spec  { }

Not executed: the documentation states no expected output for this example.

IO::Spec::Unix.basename("foo/bar/") .raku.say; # OUTPUT: «""␤»
IO::Spec::Unix.basename("foo/bar/.").raku.say; # OUTPUT: «"."␤»
IO::Spec::Unix.basename("foo/bar")  .raku.say; # OUTPUT: «"bar"␤»

Output

""
"."
"bar"

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix.canonpath("foo//../bar/../ber").say;
# OUTPUT: «foo/../bar/../ber␤»

Output

foo/../bar/../ber

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix.canonpath("foo///./../bar/../ber").say;
# OUTPUT: «foo/../bar/../ber␤»

Output

foo/../bar/../ber

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix.canonpath("foo///./../bar/../ber", :parent).say;
# OUTPUT: «ber␤»

Output

ber

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix.catdir(<foo/bar ber raku>).say; # OUTPUT: «foo/bar/ber/raku␤»

Output

foo/bar/ber/raku

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix.catpath($, 'some/dir', 'and/more').say;
# OUTPUT: «some/dir/and/more␤»

Output

some/dir/and/more

Documentation, Rakudo and Raku++ all agree.

say '.' eq $*SPEC.curdir; # OUTPUT: «True␤»

Output

True

Documentation, Rakudo and Raku++ all agree.

say $*SPEC.curupdir;
# OUTPUT: «-> str $dir { #`(Block|65335808) ... }␤»

my @dirs = <. foo .. bar>;
say @dirs.grep: { $_ ~~ $*SPEC.curupdir };
# OUTPUT: «(foo bar)␤»

Documentation

-> str $dir { #`(Block|65335808) ... }
(foo bar)

Rakudo

-> str $dir { #`(Block|3795532471680) ... }
(foo bar)

Raku++

(__curupdir)
()

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

$*SPEC.devnull.IO.spurt: "foo bar baz";

Not executed: the documentation states no expected output for this example.

IO::Spec::Unix.dir-sep.say; # OUTPUT: «/␤»

Output

Documentation, Rakudo and Raku++ all agree.

$*SPEC.extension('foo.'      ).raku.say;  # OUTPUT: «""␤»
$*SPEC.extension('foo.txt'   ).raku.say;  # OUTPUT: «"txt"␤»
$*SPEC.extension('foo.tar.gz').raku.say;  # OUTPUT: «"gz"␤»
$*SPEC.extension('foo'       ).raku.say;  # OUTPUT: «""␤»
$*SPEC.extension('bar.foo/foo').raku.say; # OUTPUT: «"foo/foo"␤»

Output

""
"txt"
"gz"
""
"foo/foo"

Documentation, Rakudo and Raku++ all agree.

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␤»

Output

True
True
False

Documentation, Rakudo and Raku++ all agree.

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 $*SPEC.join(True,".","/foo");         # OUTPUT: «/foo␤»

Output

foo/bar
/
foo
/foo

Documentation, Rakudo and Raku++ all agree.

%*ENV<PATH> = 'foo:bar/ber::foo:';
IO::Spec::Unix.path.raku.say;
# OUTPUT: «("foo", "bar/ber", ".", "foo", ".").Seq␤»

Output

("foo", "bar/ber", ".", "foo", ".").Seq

Documentation, Rakudo and Raku++ all agree.

say $*CWD;                                  # 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/../..␤»

Documentation

"/home/camelia".IO
/home/camelia/foo
/home/camelia
/home/camelia/foo/../..
/foo
/home/camelia/bar/foo
/bar
/foo
/home/camelia/bar/foo/../..

Rakudo

"/private/tmp/typerun-sandbox".IO
/private/tmp/typerun-sandbox/foo
/private/tmp/typerun-sandbox
/private/tmp/typerun-sandbox/foo/../..
/foo
/private/tmp/typerun-sandbox/bar/foo
/bar
/foo
/private/tmp/typerun-sandbox/bar/foo/../..

Raku++

"/private/tmp/typerun-sandbox".IO
/private/tmp/typerun-sandbox/foo
/private/tmp/typerun-sandbox
/private/tmp/typerun-sandbox/foo/../..
/foo
/private/tmp/typerun-sandbox/bar/foo
/bar
/foo
/private/tmp/typerun-sandbox/bar/foo/../..

Both engines agree; the documentation states something else. Trust the engines.

IO::Spec::Unix.split('C:/foo/bar.txt').raku.say;
# OUTPUT: «IO::Path::Parts.new("","C:/foo","bar.txt")␤»

IO::Spec::Unix.split('/foo/').raku.say;
# OUTPUT: «IO::Path::Parts.new("","/","foo")␤»

IO::Spec::Unix.split('///').raku.say;
# OUTPUT: «IO::Path::Parts.new("","/","/")␤»

IO::Spec::Unix.split('./').raku.say;
# OUTPUT: «IO::Path::Parts.new("",".",".")␤»

IO::Spec::Unix.split('.').raku.say;
# OUTPUT: «IO::Path::Parts.new("",".",".")␤»

IO::Spec::Unix.split('').raku.say;
# OUTPUT: «IO::Path::Parts.new("","","")␤»

Output

IO::Path::Parts.new("","C:/foo","bar.txt")
IO::Path::Parts.new("","/","foo")
IO::Path::Parts.new("","/","/")
IO::Path::Parts.new("",".",".")
IO::Path::Parts.new("",".",".")
IO::Path::Parts.new("","","")

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix.splitdir('C:\foo/bar.txt').raku.say;
# OUTPUT: «("C:\\foo", "bar.txt")␤»

IO::Spec::Unix.splitdir('/foo/').raku.say;
# OUTPUT: «("", "foo", "")␤»

IO::Spec::Unix.splitdir('///').raku.say;
# OUTPUT: «("", "", "", "")␤»

IO::Spec::Unix.splitdir('./').raku.say;
# OUTPUT: «(".", "")␤»

IO::Spec::Unix.splitdir('.').raku.say;
# OUTPUT: «(".",)␤»

IO::Spec::Unix.splitdir('').raku.say;
# OUTPUT: «("",)␤»

Output

("C:\\foo", "bar.txt")
("", "foo", "")
("", "", "", "")
(".", "")
(".",)
("",)

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix.splitpath('C:\foo/bar.txt').raku.say;
# OUTPUT: «("", "C:\\foo/", "bar.txt")␤»

IO::Spec::Unix.splitpath('C:\foo/bar.txt', :nofile).raku.say;
# OUTPUT: «("", "C:\\foo/bar.txt", "")␤»

IO::Spec::Unix.splitpath('/foo/').raku.say;
# OUTPUT: «("", "/foo/", "")␤»

IO::Spec::Unix.splitpath('/foo/', :nofile).raku.say;
# OUTPUT: «("", "/foo/", "")␤»

IO::Spec::Unix.splitpath('///').raku.say;
# OUTPUT: «("", "///", "")␤»

IO::Spec::Unix.splitpath('./').raku.say;
# OUTPUT: «("", "./", "")␤»

IO::Spec::Unix.splitpath('.').raku.say;
# OUTPUT: «("", "", ".")␤»

IO::Spec::Unix.splitpath('').raku.say;
# OUTPUT: «("", "", "")␤»

Output

("", "C:\\foo/", "bar.txt")
("", "C:\\foo/bar.txt", "")
("", "/foo/", "")
("", "/foo/", "")
("", "///", "")
("", "./", "")
("", "", ".")
("", "", "")

Documentation, Rakudo and Raku++ all agree.

say '..' eq $*SPEC.updir; # OUTPUT: «True␤»

Output

True

Documentation, Rakudo and Raku++ all agree.

IO::Spec::Unix Reference

What it is #

Position in the hierarchy #

Routines #

method abs2rel #

method basename #

method canonpath #

method catdir #

method catfile #

method catpath #

method curdir #

method curupdir #

method devnull #

method dir-sep #

method extension #

method is-absolute #

method join #

method path #

method rel2abs #

method rootdir #

method split #

method splitdir #

method splitpath #

method tmpdir #

method updir #

Examples, run three ways #

method `abs2rel` #

method `basename` #

method `canonpath` #

method `catdir` #

method `catfile` #

method `catpath` #

method `curdir` #

method `curupdir` #

method `devnull` #

method `dir-sep` #

method `extension` #

method `is-absolute` #

method `join` #

method `path` #

method `rel2abs` #

method `rootdir` #

method `split` #

method `splitdir` #

method `splitpath` #

method `tmpdir` #

method `updir` #