txt: ## open.md
  open
  
  Combined from primary sources listed below.
  
  # [In IO::Handle](#___top "go to top of document")[§](#(IO::Handle)_method_open "direct link")
  
  See primary documentation
  [in context](/type/IO/Handle#method_open)
  for **method open**.
  
  ```raku
  method open(IO::Handle:D:
        :$r, :$w, :$x, :$a, :$update,
        :$rw, :$rx, :$ra,
        :$mode is copy,
        :$create is copy,
        :$append is copy,
        :$truncate is copy,
        :$exclusive is copy,
        :$bin,
        :$enc is copy,
        :$chomp = $!chomp,
        :$nl-in is copy = $!nl-in,
        Str:D :$nl-out is copy = $!nl-out,
        :$out-buffer is copy,
      )
  
  ```
  
  Opens the handle in one of the modes. [Fails](/routine/fail) with appropriate exception if the open fails.
  
  See description of individual methods for the accepted values and behavior of [`:$chomp`](/type/IO/Handle#method_chomp), [`:$nl-in`](/type/IO/Handle#method_nl-in), [`:$nl-out`](/type/IO/Handle#method_nl-out), and [`:$enc`](/type/IO/Handle#method_encoding). 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:
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  :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
  
  
  ```
  
  
  ```
  
  Argument `:r` along with `:w`, `:a`, `:x` are exactly the same as the combination of both letters, shown in the three last rows in the table above. 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:
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  :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, the use of 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`](/type/Nil). See method [out-buffer](/routine/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.
  
  # [In IO::CatHandle](#___top "go to top of document")[§](#(IO::CatHandle)_method_open "direct link")
  
  See primary documentation
  [in context](/type/IO/CatHandle#method_open)
  for **method open**.
  
  ```raku
  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`](/type/IO/Handle). You never have to call this method intentionally.
  
  # [In IO::Path](#___top "go to top of document")[§](#(IO::Path)_method_open "direct link")
  
  See primary documentation
  [in context](/type/IO/Path#method_open)
  for **method open**.
  
  ```raku
  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](/routine/open) function accepts.
  
  # [In Independent routines](#___top "go to top of document")[§](#(Independent_routines)_sub_open "direct link")
  
  See primary documentation
  [in context](/type/independent-routines#sub_open)
  for **sub open**.
  
  ```raku
  multi open(IO() $path, |args --> IO::Handle:D)
  ```
  
  Creates [a handle](/type/IO/Handle) with the given `$path`, and calls [`IO::Handle.open`](/type/IO/Handle#method_open), passing any of the remaining arguments to it. Note that [`IO::Path`](/type/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/IO/Handle) type directly.
  
  ```raku
  my $fh = open :w, '/tmp/some-file.txt';
  $fh.say: 'I ♥ writing Raku 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 ♥ Raku␤»
  
  ```
  