Documentation for routine open

Documentation for routine open, assembled from the following types:

role IO

From IO

(IO) sub open

my $fh = open(IO::Path() $path:$r:$w:$a:$rw,
              :$bin:$enc:$nl-in:$nl-out:$chomp)

Opens the $path (by default in text mode) with the given options, returning an IO::Handle object. In order to close the IO::Handle one needs to call close explicitly or use a LEAVE phaser.

File mode options

Open the file as read only, e.g.:

my $fh = open("path/to/file":r);

This is the default mode for open.

Write-related methods on the returned IO::Handle object will fail in this mode:

my $fh = open("test");   # the file "test" already exists 
$fh.print("new text\n"); # fails 
CATCH { default { put .^name''.Str } };
# OUTPUT: «X::AdHoc: Failed to write bytes to filehandle: bad file descriptor␤» 

Open the file for writing, creating it if it doesn't exist or overwriting the file if it does exist, e.g.:

my $fh = open("path-to-file":w);

Read-related methods will fail in this mode:

my $fh = open("test":w);
$fh.print("stuff\n");
$fh.print("more stuff\n");
$fh.seek(0);      # return to the start of the file 
$fh.get();        # fails 
CATCH { default { put .^name''.Str } };
# OUTPUT: «Reading from filehandle failed: bad file descriptor␤» 

Open the file for reading and writing, creating the file if it doesn't exist or overwriting the file if it already exists.

my $fh = open("path-to-file":rw);

Open the file for appending. If the file does not exist, create it. If the file already exists, append data to it.

my $fh = open("path-to-file":a);

Encoding options

Open the file in binary mode (byte mode):

my $fh = open("path-to-file":bin);

A file opened with :bin may still be processed line-by-line, but IO will be in terms of Buf rather than Str types. Default is False, implying text semantics.

The encoding to use if opened in text mode.

my $fh1 = open 'path-to-file';                # default, utf-8 
my $fh2 = open 'path-to-file':enc<latin-1># explicit, latin-1 

Defaults to utf8. Attempting to set the encoding while :bin is true will cause X::IO::BinaryAndEncoding exception to be thrown. Note that specifying Str type object or Nil as encoding is the same as not specifying the argument at all; use :bin argument if you want to enable binary mode.

The values are case-insensitive. The available encodings vary by implementation and backend. On Rakudo MoarVM the following are supported:

  utf8
  utf16
  utf8-c8
  iso-8859-1
  windows-1252
  ascii

Implementation may choose to also provide support for aliases, e.g. Rakudo allows aliases latin-1 for iso-8859-1 encoding and dashed utf versions: utf-8 and utf-16.

Newline options

nl-in is the marker used to indicate the end of a line of text. Only used in text mode. Defaults to ["\n", "\r\n"] and does not include "\r". nl-out defaults to "\n".

# explicitly use CR-LF as EOL character 
my $fh = open("path-to-file"nl-in => "\r\n");

Whether or not to remove newline characters from text obtained with .lines and .get. Defaults to True.

# don't remove newline characters from input 
my $fh = open("path-to-file"chomp => False);
say $fh.get();     # returns line including newline char 

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.