From type/IO/CatHandle

See Original text in context

method next-handle(IO::CatHandle:D: --> IO::Handle:D)

Switches the active source handle to the next handle in the source handle queue, which is the sources given in @handles attribute to .new. The return value is the currently active source handle or Nil if the source handle queue has been exhausted.

Coerces Cool source "handles" to IO::Path; opens IO::Path and unopened IO::Handle source handles for reading using the invocant's $.nl-in attribute, $.chomp attribute, and :$encoding attributes; those same attributes of already-opened IO::Handle objects will be changed to the values of the invocant's attributes.

This method is called automatically whenever CatHandle's methods require a switch to the next source handle, triggers .on-switch method Callable to be called, and is called once during .new call. The .on-switch will continue to be triggered each time this method is called, even after the source handle queue has been exhausted. Note that generally reaching the EOF of the currently active source handle does not trigger the .next-handle call, but rather further read operations that need more data do.

(my $f1 = 'foo'.IO).spurt: "a\nb";
(my $f2 = 'bar'.IO).spurt: "c\nd";
with IO::CatHandle.new: :on-switch{ say '▸ Switching' }, $f1, $f2 {
    say 'one';
    .next-handle.^name.say;
    say 'two';
    .next-handle.^name.say;
    say 'three';
    .next-handle.^name.say;
    # OUTPUT: 
    # ▸ Switching 
    # one 
    # ▸ Switching 
    # IO::Handle 
    # two 
    # ▸ Switching 
    # Nil 
    # three 
    # ▸ Switching 
    # Nil 
}