class IO::Handle { }

my $fh = '/tmp/log.txt'.IO.open;
say $fh.^name; # OUTPUT: IO::Handle

my $fh = IO::Handle.new( :path( '/tmp/log.txt'.IO.path ) ).open;

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

: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

: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

method comb(IO::Handle:D: Bool :$close, |args --> Seq:D)

my $fh = 'path/to/file'.IO.open;
say "The file has {+$fh.comb: '♥', :close} ♥s in it";

has $.chomp is rw = True

method get(IO::Handle:D: --> Str:D)
multi  get (IO::Handle $fh = $*ARGFILES --> Str:D)

$*IN.get.say;              # Read one line from the standard input 
 
my $fh = open 'filename';
$fh.get.say;               # Read one line from a file 
$fh.close;
 
say get;                   # Read one line from $*ARGFILES 

method getc(IO::Handle:D: --> Str:D)
multi  getc (IO::Handle $fh = $*ARGFILES --> Str:D)

submethod DESTROY(IO::Handle:D:)

method gist(IO::Handle:D: --> Str:D)

say IO::Handle.new; # IO::Handle<(Any)>(closed) 
say "foo".IO.open;  # IO::Handle<"foo".IO>(opened) 

method eof(IO::Handle:D: --> Bool:D)

$ echo "x" | raku -e 'with $*IN { .read: 10000; .eof.say; .read: 10; .eof.say }'
False
True

multi method encoding(IO::Handle:D: --> Str:D)
multi method encoding(IO::Handle:D: $enc --> Str:D)

utf8
utf16
utf16le
utf16be
utf8-c8
iso-8859-1
windows-1251
windows-1252
windows-932
ascii

with 'foo'.IO {
    .spurt: "First line is text, then:\nBinary";
    my $fh will leave {.close} = .open;
    $fh.get.say;         # OUTPUT: «First line is text, then:␤» 
    $fh.encoding: Nil;
    $fh.slurp.say;       # OUTPUT: «Buf[uint8]:0x<42 69 6e 61 72 79>␤» 
}

sub          lines( $what = $*ARGFILES, |c)
multi method lines( IO::Handle:D: $limit, :$close )
multi method lines( IO::Handle:D:         :$close )

say "The file contains ",
  '50GB-file'.IO.open.lines.grep(*.contains: 'Raku').elems,
  " lines that mention Raku";
# OUTPUT: «The file contains 72 lines that mention Raku␤» 

say lines( "/proc/$*PID/statm".IO ); # OUTPUT: «(58455 31863 8304 2 0 29705 0)␤» 

method lock(IO::Handle:D:
            Bool:D :$non-blocking = False, Bool:D :$shared = False
            --> True)

# One program writes, the other reads, and thanks to locks either 
# will wait for the other to finish before proceeding to read/write 
 
# Writer 
given "foo".IO.open(:w) {
    .lock;
    .spurt: "I ♥ Raku!";
    .close; # closing the handle unlocks it; we could also use `unlock` for that 
}
 
# Reader 
given "foo".IO.open {
    .lock: :shared;
    .slurp.say; # OUTPUT: «I ♥ Raku!␤» 
    .close;
}

method unlock(IO::Handle:D: --> True)

multi        words(IO::Handle:D $fh = $*ARGFILES, $limit = Inf, :$close --> Seq:D)
multi method words(IO::Handle:D: $limit = Inf, :$close --> Seq:D)

my %dict := bag $*IN.words;
say "Most common words: ", %dict.sort(-*.value).head: 5;

method split(IO::Handle:D: :$close, |c)

my $fh = 'path/to/file'.IO.open;
$fh.split: '♥', :close; # Returns file content split on ♥ 

multi method spurt(IO::Handle:D: Blob $data, :$close = False)
multi method spurt(IO::Handle:D: Cool $data, :$close = False)

multi method print(**@text --> True)
multi method print(Junction:D --> True)

my $fh = 'path/to/file'.IO.open: :w;
$fh.print: 'some text';
$fh.close;

method print-nl(IO::Handle:D: --> True)

my $fh = 'path/to/file'.IO.open: :w, :nl-out("\r\n");
$fh.print: "some text";
$fh.print-nl; # prints \r\n 
$fh.close;

multi method printf(IO::Handle:D: Cool $format, *@args)

my $fh = open 'path/to/file', :w;
$fh.printf: "The value is %d\n", 32;
$fh.close;

method out-buffer(--> Int:D) is rw

given 'foo'.IO.open: :w, :1000out-buffer {
    .say: 'Hello world!'; # buffered 
    .out-buffer = 42;       # buffer resized; previous print flushed 
    .say: 'And goodbye';
    .close; # closing the handle flushes the buffer 
}

multi method put(**@text --> True)
multi method put(Junction:D --> True)

my $fh = 'path/to/file'.IO.open: :w;
$fh.put: 'some text';
$fh.close;

multi method say(IO::Handle:D: **@text --> True)

my $fh = open 'path/to/file', :w;
$fh.say(Complex.new(3, 4));        # OUTPUT: «3+4i␤» 
$fh.close;

method read(IO::Handle:D: Int(Cool:D) $bytes = 65536 --> Buf:D)

(my $file = 'foo'.IO).spurt: 'I ♥ Raku';
given $file.open {
    say .read: 6; # OUTPUT: «Buf[uint8]:0x<49 20 e2 99 a5 20>␤» 
    .close;
}

method readchars(IO::Handle:D: Int(Cool:D) $chars = 65536 --> Str:D)

(my $file = 'foo'.IO).spurt: 'I ♥ Raku';
given $file.open {
    say .readchars: 5; # OUTPUT: «I ♥ R␤» 
    .close;
}

method write(IO::Handle:D: Blob:D $buf --> True)

method seek(IO::Handle:D: Int:D $offset, SeekType:D $whence --> True)

method tell(IO::Handle:D: --> Int:D)

multi method slurp-rest(IO::Handle:D: :$bin! --> Buf)
multi method slurp-rest(IO::Handle:D: :$enc --> Str)

method slurp(IO::Handle:D: :$close, :$bin)

multi method Supply(IO::Handle:D: :$size = 65536)

"foo".IO.open(:bin).Supply(:size<10>).tap: *.raku.say;
# OUTPUT: 
# Buf[uint8].new(73,32,226,153,165,32,80,101,114,108) 
# Buf[uint8].new(32,54,33,10) 
 
"foo".IO.open.Supply(:size<10>).tap: *.raku.say;
# OUTPUT: 
# "I ♥ Perl" 
# " 6!\n" 

method path(IO::Handle:D:)

method IO(IO::Handle:D:)

say "foo".IO.open.Str; # OUTPUT: «foo␤» 

method close(IO::Handle:D: --> Bool:D)
multi  close(IO::Handle $fh)

given "foo/bar".IO.open(:w) {
    .spurt: "I ♥ Raku!";
    .close;
}

do {
    my $fh = open "path-to-file";
    LEAVE close $fh;
    # ... do stuff with the file 
}
 
sub do-stuff-with-the-file (IO $path-to-file) {
  my $fh = $path-to-file.open;
 
  # stick a `try` on it, since this will get run even when the sub is 
  # called with wrong arguments, in which case the `$fh` will be an `Any` 
  LEAVE try close $fh;
 
  # ... do stuff with the file 
}

method flush(IO::Handle:D: --> True)

given "foo".IO.open: :w {
    LEAVE .close;
    .print: 'something';
    'foo'.IO.slurp.say; # (if the data got buffered) OUTPUT: «␤» 
    .flush;             # flush the handle 
    'foo'.IO.slurp.say; # OUTPUT: «something␤» 
}

method native-descriptor(IO::Handle:D:)

method nl-in(--> Str:D) is rw

with 'test'.IO {
    .spurt: '1foo2bar3foo'; # write some data into our test file 
    my $fh will leave {.close} = .open; # can also set .nl-in via .open arg 
    $fh.nl-in = [<foo bar>]; # set two possible line endings to use; 
    $fh.lines.say; # OUTPUT: ("1", "2", "3").Seq 
}

has Str:D $.nl-out is rw = "\n";

with 'test'.IO {
    given .open: :w {
        .put: 42;
        .nl-out = 'foo';
        .put: 42;
        .close;
    }
    .slurp.raku.say; # OUTPUT: «"42\n42foo"␤» 
}

method opened(IO::Handle:D: --> Bool:D)

method t(IO::Handle:D: --> Bool:D)

class IO::URL is IO::Handle {
    has $.URL is required;
    has Buf $!content;
    submethod TWEAK {
        use WWW; # ecosystem module that will let us `get` a web page 
        use DOM::Tiny; # ecosystem module that will parse out all text from HTML 
        $!content := Buf.new: DOM::Tiny.parse(get $!URL).all-text(:trim).encode;
        self.encoding: 'utf8'; # set up encoder/decoder 
    }
 
    method open(|)  { self }       # block out some IO::Handle methods 
    method close(|) { self }       # that work with normal low-level file 
    method opened   { ! self.EOF } # handles, since we don't. This isn't 
    method lock(| --> True) { }    # necessary, but will make our handle 
    method unlock( --> True) { }   # be more well-behaved if someone 
    # actually calls one of these methods. There are more of these you 
    # can handle, such as .tell, .seek, .flush, .native-descriptor, etc. 
 
    method WRITE(|) {
        # For this handle we'll just die on write. If yours can handle writes. 
        # The data to write will be given as a Blob positional argument. 
        die "Cannot write into IO::URL";
    }
    method READ(\bytes) {
        # We splice off the requested number of bytes from the head of 
        # our content Buf. The handle's decoder will handle decoding them 
        # automatically, if textual read methods were called on the handle. 
        $!content.splice: 0, bytes
    }
    method EOF {
        # For "end of file", we'll simply report whether we still have 
        # any bytes of the website we fetched on creation. 
        not $!content
    }
}
 
my $fh := IO::URL.new: :URL<raku.org>;
 
# .slurp and print all the content from the website. We can use all other 
# read methods, such as .lines, or .get, or .readchars. All of them work 
# correctly, even though we only defined .READ and .EOF 
$fh.slurp.say;

method WRITE(IO::Handle:D: Blob:D \data --> Bool:D)

class IO::Store is IO::Handle {
    has @.lines = [];
 
    submethod TWEAK {
        self.encoding: 'utf8'; # set up encoder/decoder 
    }
 
    method WRITE(IO::Handle:D: Blob:D \data --> Bool:D) {
        @!lines.push: data.decode();
        True;
    }
 
    method gist() {
        return @!lines.join("\n" );
    }
}
my $store = IO::Store.new();
my $output = $PROCESS::OUT;
$PROCESS::OUT = $store;
.say for <one two three>;
$PROCESS::OUT = $output;
say $store.lines(); # OUTPUT: «[one␤ two␤ three␤]» 

method READ(IO::Handle:D: Int:D \bytes --> Buf:D)

class IO::Store is IO::Handle {
    has @.lines = [];
 
    submethod TWEAK {
      self.encoding: 'utf8'; # set up encoder/decoder 
    }
 
    method WRITE(IO::Handle:D: Blob:D \data --> Bool:D) {
      @!lines.push: data;
      True;
    }
 
    method whole() {
      my Buf $everything = Buf.new();
      for @!lines -> $b {
        $everything ~= $b;
      }
      return $everything;
    }
 
    method READ(IO::Handle:D: Int:D \bytes --> Buf:D) {
      my Buf $everything := self.whole();
      return $everything;
    }
 
    method EOF {
      my $everything = self.whole();
      !$everything;
    }
}
 
my $store := IO::Store.new();
 
$store.print( $_ ) for <one two three>;
say $store.read(3).decode; # OUTPUT: «one␤» 
say $store.read(3).decode; # OUTPUT: «two␤» 

method EOF(IO::Handle:D: --> Bool:D)