txt: ## next-handle.md
  next-handle
  
  Combined from primary sources listed below.
  
  # [In IO::CatHandle](#___top "go to top of document")[§](#(IO::CatHandle)_method_next-handle "direct link")
  
  See primary documentation
  [in context](/type/IO/CatHandle#method_next-handle)
  for **method next-handle**.
  
  ```raku
  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`](/type/IO/CatHandle#method_new). The return value is the currently active source handle or [`Nil`](/type/Nil) if the source handle queue has been exhausted.
  
  Coerces [`Cool`](/type/Cool) source "handles" to [`IO::Path`](/type/IO/Path); opens [`IO::Path`](/type/IO/Path) and unopened [`IO::Handle`](/type/IO/Handle) source handles for reading using the invocant's [`$.nl-in`](/type/IO/CatHandle#method_nl-in), [`$.chomp`](/type/IO/CatHandle#method_chomp), and [`$.encoding`](/type/IO/CatHandle#method_encoding) attributes; those same attributes of already-opened [`IO::Handle`](/type/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`](/type/IO/CatHandle#method_on-switch) [`Callable`](/type/Callable) to be called, and is called once during [.new](/type/IO/CatHandle#method_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.
  
  ```raku
  (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
  }
  
  ```
  