Documentation for routine open assembled from the following types:

language documentation Independent routines

From Independent routines

(Independent routines) sub open

multi sub open(IO() $path, |args --> IO::Handle:D)

Creates a handle with the given $path, and calls IO::Handle.open, passing any of the remaining arguments to it. Note that IO::Path type provides numerous methods for reading and writing from files, so in many common cases you do not need to open files or deal with IO::Handle type directly.

my $fh = open :w, '/tmp/some-file.txt';
$fh.say: 'I ♥ writing Perl code';
$fh.close;
 
$fh = open '/tmp/some-file.txt';
print $fh.readchars: 4;
$fh.seek: 7, SeekFromCurrent;
say $fh.readchars: 4;
$fh.close;
 
# OUTPUT: «I ♥ Perl␤» 

class IO::CatHandle

From IO::CatHandle

(IO::CatHandle) method open

Defined as:

method open(IO::CatHandle:D: --> IO::CatHandle:D)

Returns the invocant. The intent of this method is to merely make CatHandle workable with things that open IO::Handle. You never have to call this method intentionally.

class IO::Path

From IO::Path

(IO::Path) method open

Defined as:

method open(IO::Path:D: *%opts)

Opens the path as a file; the named options control the mode, and are the same as the open function accepts.

class IO::Handle

From IO::Handle

(IO::Handle) method open

Defined as:

method open(IO::Handle:D:
    :$bin, :$enc, :$chomp, :$nl-in, Str:D :$nl-out,
    Str :$mode,
    :$r, :$w, :$a, :$x, :$update, :$rw, :$rx, :$ra,
    :$create, :$append, :$truncate, :$exclusive,
    :$out-buffer,
    --> IO::Handle:D
)

Opens the handle in one of the modes. Fails with appropriate exception if the open fails.

See description of individual methods for the accepted values and behavior of :$chomp, :$nl-in, :$nl-out, and :$enc. The values for parameters default to the invocant's attributes and if any of them are provided, the attributes will be updated to the new values. Specify :$bin set to True instead of :$enc to indicate the handle should be opened in binary mode. Specifying undefined value as :$enc is equivalent to not specifying :$enc at all. Specifying both a defined encoding as :$enc and :$bin set to true will cause X::IO::BinaryAndEncoding exception to be thrown.

The open mode defaults to non-exclusive, read only (same as specifying :r) and can be controlled by a mix of the following arguments:

:r      same as specifying   :mode<ro>  same as specifying nothing
 
:w      same as specifying   :mode<wo>, :create, :truncate
:a      same as specifying   :mode<wo>, :create, :append
:x      same as specifying   :mode<wo>, :create, :exclusive
 
:update same as specifying   :mode<rw>
:rw     same as specifying   :mode<rw>, :create
:ra     same as specifying   :mode<rw>, :create, :append
:rx     same as specifying   :mode<rw>, :create, :exclusive

Support for combinations of modes other than what is listed above is implementation-dependent and should be assumed unsupported. That is, specifying, for example, .open(:r :create) or .open(:mode<wo> :append :truncate) might work or might cause the Universe to implode, depending on a particular implementation. This applies to reads/writes to a handle opened in such unsupported modes as well.

The mode details are:

:mode<ro>  means "read only"
:mode<wo>  means "write only"
:mode<rw>  means "read and write"
 
:create    means the file will be created, if it does not exist
:truncate  means the file will be emptied, if it exists
:exclusive means .open will fail if the file already exists
:append    means writes will be done at the end of file's current contents

Attempts to open a directory, write to a handle opened in read-only mode or read from a handle opened in write-only mode, or using text-reading methods on a handle opened in binary mode will fail or throw.

In 6.c language, it's possible to open path '-', which will cause open to open (if closed) the $*IN handle if opening in read-only mode or to open the $*OUT handle if opening in write-only mode. All other modes in this case will result in exception being thrown.

As of 6.d language version, use path '-' is deprecated and it will be removed in future language versions entirely.

The :out-buffer controls output buffering and by default behaves as if it were Nil. See method out-buffer for details.

Note (Rakudo versions before 2017.09): Filehandles are NOT flushed or closed when they go out of scope. While they will get closed when garbage collected, garbage collection isn't guaranteed to get run. This means you should use an explicit close on handles opened for writing, to avoid data loss, and an explicit close is recommended on handles opened for reading as well, so that your program does not open too many files at the same time, triggering exceptions on further open calls.

Note (Rakudo versions 2017.09 and after): Open filehandles are automatically closed on program exit, but it is still highly recommended that you close opened handles explicitly.