class IO::Handle | Raku Documentation

<!DOCTYPE html> <html lang="en" class="fontawesome-i2svg-active fontawesome-i2svg-complete" style="scroll-padding-top:60px"> <head> <title>class IO::Handle | Raku Documentation</title> <meta charset="UTF-8" /> <link href="/assets/images/Camelia.ico" rel="icon" type="image/x-icon"/> <link rel="stylesheet" href="/assets/css/Website.css"/> <link rel="stylesheet" href="/assets/css/typegraph-styling.css"/> <link rel="stylesheet" href="/assets/css/typegraph-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/typegraph-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/filtered-toc-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/filtered-toc-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/announce-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/announce-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/all.min.css"/> <link rel="stylesheet" href="/assets/css/listf-styling-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/listf-styling-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/options-search-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/options-search-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/page-styling-main.css"/> <link rel="stylesheet" href="/assets/css/css/page-styling-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/page-styling-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/chyronToggle-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/chyronToggle-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/centreToggle-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/centreToggle-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/tm-styling.css"/> <link rel="stylesheet" href="/assets/css/tm-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/tm-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/rainbow-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/rainbow-light.css" title="light"/> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/css/autoComplete.min.css" /> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-light.min.css" title="light" /> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css" title="dark" /> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script> <script src="/assets/scripts/all.min.js"></script><script src="/assets/scripts/filter-script.js"></script><script src="/assets/scripts/tableManager.js"></script><script src="https://cdn.jsdelivr.net/npm/fuzzysort@2.0.4/fuzzysort.min.js"></script><script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/autoComplete.min.js"></script><script src="/assets/scripts/filtered-toc.js"></script><script src="/assets/scripts/options-search.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/haskell.min.js"></script><script src="/assets/scripts/page-styling.js"></script><script src="/assets/scripts/announcements.js"></script><script src="/assets/scripts/rainbow.js"></script> </head> <body class="has-navbar-fixed-top"> <div id="class_IO::Handle" class="top-of-page"></div> <nav class="navbar is-fixed-top is-flex-touch" role="navigation" aria-label="main navigation"> <div class="navbar-item" style="margin-left: auto;"> <div class="left-bar-toggle" title="Toggle Table of Contents & Index"> <label class="chyronToggle left"> <input id="navbar-left-toggle" type="checkbox"> <span class="text">Contents</span> </label> </div> </div> <div class="container is-justify-content-space-around"> <div class="navbar-brand"> <div class="navbar-logo"> <a class="navbar-item" href="/"> <img src="/assets/images/camelia-recoloured.png" alt="Raku" width="52.83" height="38"> </a> <span class="navbar-logo-tm">tm</span> </div> <a role="button" class="navbar-burger burger" aria-label="menu" aria-expanded="false" data-target="navMenu"> <span aria-hidden="true"></span> <span aria-hidden="true"></span> <span aria-hidden="true"></span> </a> </div> <div id="navMenu" class="navbar-menu"> <div class="navbar-start"> <a class="navbar-item" href="/introduction" title="Getting started, Tutorials, Migration guides"> Introduction </a> <a class="navbar-item" href="/reference" title="Fundamentals, General reference"> Reference </a> <a class="navbar-item" href="/miscellaneous" title="Programs, Experimental"> Miscellaneous </a> <a class="navbar-item" href="/types" title="The core types (classes) available"> Types </a> <a class="navbar-item" href="/routines" title="Searchable table of routines"> Routines </a> <a class="navbar-item" href="https://raku.org" title="Home page for community"> Raku<sup>®</sup> </a> <a class="navbar-item" href="https://web.libera.chat/#raku" title="IRC live chat"> Chat </a> <div class="navbar-item has-dropdown is-hoverable"> <a class="navbar-link"> More </a> <div class="navbar-dropdown is-right is-rounded"> <hr class="navbar-divider"> <a class="navbar-item js-modal-trigger" data-target="download-ebook"> Download E-Book (epub) </a> <hr class="navbar-divider"> <a class="navbar-item" href="/about"> About </a> <hr class="navbar-divider"> <a class="navbar-item has-text-red" href="https://github.com/raku/doc-website/issues"> Report an issue with this site </a> <hr class="navbar-divider"> <a class="navbar-item" href="https://github.com/raku/doc/issues"> Report an issue with the documentation content </a> <hr class="navbar-divider"> <label class="navbar-item centreToggle" title="Enable/Disable Announcements" style="--switch-width: 18"> <input id="cancelAnnouncements" type="checkbox"> <span class="text">Announcements</span> <span class="on">suppressed</span> <span class="off">allowed</span> </label> </div> </div> </div> <div class="navbar-end navbar-search-wrapper"> <div class="navbar-item"> <div class="field has-addons"> <div class="autoComplete_options"> <input class="control input" id="autoComplete" type="search" dir="ltr" spellcheck=false autocorrect="off" autocomplete="off" autocapitalize="off" placeholder="🔍 Type f to search for ..."> </div> <div class="control" title="Search options"> <a class="button is-primary js-modal-trigger" data-target="options-search-info"> <span class="icon"> <i class="fas fa-cogs"></i> </span> </a> </div> </div> </div> </div> <div id="options-search-info" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <p>The last search was: <span id="selected-candidate" class="ss-selected"></span></p> <div class="control is-grouped is-grouped-centered options-search-controls"> <label class="centreToggle" title="Include extra information (Alt-E)" style="--switch-width: 10.5"> <input id="options-search-extra" type="checkbox"> <span class="text">Extra info</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>The search response can be shortened by excluding the extra information line (Alt-E)</p> <label class="centreToggle" title="Search engine type Strict/Loose (Alt-L)" style="--switch-width: 10.5"> <input id="options-search-loose" type="checkbox"> <span class="text">Search type</span> <span class="on">loose</span> <span class="off">strict</span> </label> <p> The search engine can perform a strict search (only the characters in the search box) or a loose search (Alt-L)</p> <label class="centreToggle" title="Search in headings (Alt-H)" style="--switch-width: 10.5"> <input id="options-search-headings" type="checkbox"> <span class="text">Headings</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through headings in all web-pages (Alt-H)</p> <label class="centreToggle" title="Search indexed items (Alt-I)" style="--switch-width: 10.5"> <input id="options-search-indexed" type="checkbox"> <span class="text">Indexed</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through all indexed items (Alt-I)</p> <label class="centreToggle" title="Search composite pages (Alt-C)" style="--switch-width: 10.5"> <input id="options-search-composite" type="checkbox"> <span class="text">Composite</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search in the names of composite pages, which combine similar information from the main web pages (Alt-C)</p> <label class="centreToggle" title="Search primary sources (Alt-P)" style="--switch-width: 10.5"> <input id="options-search-primary" type="checkbox"> <span class="text">Primary</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through the names of the main web pages (Alt-P)</p> <label class="centreToggle" title="Open in new tab (Alt-Q)" style="--switch-width: 10.5"> <input id="options-search-newtab" type="checkbox"> <span class="text">New tab</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Once a search candidate has been chosen, it can be opened in a new tab or in the current tab (Alt-Q)</p> <p>If all else fails, an item is added to use the Google search engine on the whole site</p> <button class="button is-warning" id="options-search-reset-defaults">Clear options, reset to defaults</button> <p>Exit this page by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> </div> <div id="download-ebook" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <p><a href="/RakuDocumentation.epub" download>RakuDocumentation.epub</a> is a work in progress e-book. It targets the <a href="https://www.w3.org/publishing/epub3/">EPUB v3 specification</a>. It needs testing on a variety of ereaders (some of which may still implicitly expect compliance with EPUB v2). The CSS definitely needs enhancing (especially for code snippets). The Ebook opens in a Calibre reader, which is available on all operating systems.</p> <p>Suggestions are welcome and should be addressed by opening an issue on the Raku/doc-website repository</p> <p>Exit this popup by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> <div id="announcement-modal" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <div id="raku-doc-announcement"></div> <p>For more see <a href="/announcements">Announcements page</a>.</p> <p>Exit this popup by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> </div> </nav> <div class="tile is-ancestor section"> <div class="page-edit"> <a class="button page-edit-button" href="https://github.com/Raku/doc/edit/main/doc/Type/IO/Handle.rakudoc" title="Edit this page.Commit: a89742bdf 2024-07-14"> <span class="icon is-right"> <i class="fas fa-pen-alt is-medium"></i> </span> </a> </div> <div id="left-column" class="tile is-parent is-2 is-hidden"> <div id="left-col-inner"> <div class="tabs" id="tabs"> <ul> <li class="is-active" id="toc-tab"> <a>Table of Contents</a> </li> <li id="index-tab"> <a>Index</a> </li> </ul> </div> <div class="field"> <div class="control has-icons-right"> <input id="toc-filter" class="input" type="text" placeholder="Filter"> <span class="icon is-right has-text-grey"> <i class="fas fa-search is-medium"></i> </span> </div> </div> <div class="raku-sidebar"> <aside id="toc-menu" class="menu"> <ul class="menu-list"> <li><a href="#Methods">Methods</a></li> <ul> <li><a href="#method_open">method open</a></li> <li><a href="#method_comb">method comb</a></li> <li><a href="#method_chomp">method chomp</a></li> <li><a href="#routine_get">routine get</a></li> <li><a href="#routine_getc">routine getc</a></li> <ul> <li><a href="#Buffering_terminals">Buffering terminals</a></li> <li><a href="#Waiting_for_potential_combiners">Waiting for potential combiners</a></li> </ul> <li><a href="#submethod_DESTROY">submethod DESTROY</a></li> <li><a href="#method_gist">method gist</a></li> <li><a href="#method_eof">method eof</a></li> <li><a href="#method_encoding">method encoding</a></li> <ul> <li><a href="#utf16,_utf16le_and_utf16be">utf16, utf16le and utf16be</a></li> <li><a href="#Examples">Examples</a></li> </ul> <li><a href="#routine_lines">routine lines</a></li> <li><a href="#method_lock">method lock</a></li> <li><a href="#method_unlock">method unlock</a></li> <li><a href="#routine_words">routine words</a></li> <li><a href="#method_split">method split</a></li> <li><a href="#method_spurt">method spurt</a></li> <li><a href="#method_print">method print</a></li> <li><a href="#method_print-nl">method print-nl</a></li> <li><a href="#method_printf">method printf</a></li> <li><a href="#method_out-buffer">method out-buffer</a></li> <li><a href="#method_put">method put</a></li> <li><a href="#method_say">method say</a></li> <li><a href="#method_read">method read</a></li> <li><a href="#method_readchars">method readchars</a></li> <li><a href="#method_write">method write</a></li> <li><a href="#method_seek">method seek</a></li> <li><a href="#method_tell">method tell</a></li> <li><a href="#method_slurp-rest">method slurp-rest</a></li> <li><a href="#method_slurp">method slurp</a></li> <li><a href="#method_Supply">method Supply</a></li> <li><a href="#method_path">method path</a></li> <li><a href="#method_IO">method IO</a></li> <li><a href="#method_Str">method Str</a></li> <li><a href="#routine_close">routine close</a></li> <li><a href="#method_flush">method flush</a></li> <li><a href="#method_native-descriptor">method native-descriptor</a></li> <li><a href="#method_nl-in">method nl-in</a></li> <li><a href="#method_nl-out">method nl-out</a></li> <li><a href="#method_opened">method opened</a></li> <li><a href="#method_t">method t</a></li> </ul> <li><a href="#Creating_Custom_Handles">Creating Custom Handles</a></li> <ul> <li><a href="#method_WRITE">method WRITE</a></li> <li><a href="#method_READ">method READ</a></li> <li><a href="#method_EOF">method EOF</a></li> </ul> <li><a href="#Related_roles_and_classes">Related roles and classes</a></li> </ul> </aside> <aside id="index-menu" class="menu is-hidden"> <ul class="menu-list"> <li>Reference<ul> <li><a href="#index-entry-File_locking">File locking</a></li> <li><a href="#index-entry-SeekFromBeginning">SeekFromBeginning</a></li> <li><a href="#index-entry-SeekFromCurrent">SeekFromCurrent</a></li> <li><a href="#index-entry-SeekFromEnd">SeekFromEnd</a></li> <li><a href="#index-entry-ShiftJIS-ShiftJIS">ShiftJIS</a></li> <li><a href="#index-entry-ascii">ascii</a></li> <li><a href="#index-entry-iso-8859-1">iso-8859-1</a></li> <li><a href="#index-entry-utf-16">utf-16</a></li> <li><a href="#index-entry-utf16">utf16</a></li> <li><a href="#index-entry-utf16-be">utf16-be</a></li> <li><a href="#index-entry-utf16-le">utf16-le</a></li> <li><a href="#index-entry-utf16be-utf16be">utf16be</a></li> <li><a href="#index-entry-utf16le-utf16le">utf16le</a></li> <li><a href="#index-entry-windows-1251">windows-1251</a></li> <li><a href="#index-entry-windows-1252">windows-1252</a></li> <li><a href="#index-entry-windows-932">windows-932</a></li> </ul></li> </ul> </aside> </div> </div> </div> <div id="main-column" class="tile is-parent" style="overflow-x: hidden;"> <div id="main-col-inner"> <section class="raku page-header"> <div class="container px-4"> <div class="raku page-title has-text-centered"> class IO::Handle </div> <div class="raku page-subtitle has-text-centered"> <p>Opened file or stream</p> </div> </div> </section> <section class="raku page-content"><div class="container px-4"><div class="columns one-col"> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">class</span> <span class="highlite-TYPE">IO::Handle</span> { }</pre> </div> </div> <p>Instances of <code>IO::Handle</code> encapsulate a <em>handle</em> to manipulate input/output resources. Usually there is no need to create directly an <code>IO::Handle</code> instance, since it will be done by other roles and methods. For instance, an <a href="/type/IO/Path"><code>IO::Path</code></a> object provides an <a href="/routine/open">open</a> method that returns an <code>IO::Handle</code>:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">/tmp/log.txt</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$fh</span>.^<span class="highlite-ROUTINE">name</span>; <span class="highlite-COMMENT"># OUTPUT: IO::Handle</span></pre> </div> </div> <p>The first line is pretty much equivalent to the following piece of code:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">IO::Handle</span>.<span class="highlite-ROUTINE">new</span>( :path( <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">/tmp/log.txt</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">path</span> ) ).<span class="highlite-ROUTINE">open</span>;</pre> </div> </div> <h1 id="Methods" class="raku-h1"><a href="#class_IO::Handle" title="go to top of document">Methods<a class="raku-anchor" title="direct link" href="#Methods">§</a></a></h1> <h2 id="method_open" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method open<a class="raku-anchor" title="direct link" href="#method_open">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">open</span>(IO::Handle:D: <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$r</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$w</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$x</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$a</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$update</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$rw</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$rx</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$ra</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$mode</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$create</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$append</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$truncate</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$exclusive</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$bin</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$enc</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$chomp</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$!chomp</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$nl-in</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$!nl-in</span><span class="highlite-OPERATOR">,</span> Str:D <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$nl-out</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$!nl-out</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$out-buffer</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-ROUTINE">copy</span><span class="highlite-OPERATOR">,</span> ) </pre> </div> </div> <p>Opens the handle in one of the modes. <a href="/routine/fail">Fails</a> with appropriate exception if the open fails.</p><p>See description of individual methods for the accepted values and behavior of <a href="/type/IO/Handle#method_chomp"><code>:$chomp</code></a>, <a href="/type/IO/Handle#method_nl-in"><code>:$nl-in</code></a>, <a href="/type/IO/Handle#method_nl-out"><code>:$nl-out</code></a>, and <a href="/type/IO/Handle#method_encoding"><code>:$enc</code></a>. 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 <code>:$bin</code> set to <code>True</code> instead of <code>:$enc</code> to indicate the handle should be opened in binary mode. Specifying undefined value as <code>:$enc</code> is equivalent to not specifying <code>:$enc</code> at all. Specifying both a defined encoding as <code>:$enc</code> and <code>:$bin</code> set to true will cause <code>X::IO::BinaryAndEncoding</code> exception to be thrown.</p><p>The open mode defaults to non-exclusive, read only (same as specifying <code>:r</code>) and can be controlled by a mix of the following arguments:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>｢text｣ without highlighting</label> <div> <pre class="nohighlights"><pre class="nohighlights"> :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 </pre> </pre> </div> </div> <p>Argument <code>:r</code> along with <code>:w</code>, <code>:a</code>, <code>:x</code> 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 <em>other</em> than what is listed above is implementation-dependent and should be assumed unsupported. That is, specifying, for example, <code>.open(:r :create)</code> or <code>.open(:mode<wo> :append :truncate)</code> 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.</p><p>The mode details are:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>｢text｣ without highlighting</label> <div> <pre class="nohighlights"><pre class="nohighlights"> :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 </pre> </pre> </div> </div> <p>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.</p><p>In <strong>6.c</strong> language, it's possible to open path <code>'-'</code>, which will cause <code>open</code> to open (if <code>closed</code>) the <code>$*IN</code> handle if opening in read-only mode or to open the <code>$*OUT</code> handle if opening in write-only mode. All other modes in this case will result in exception being thrown.</p><p>As of <strong>6.d</strong> language version, the use of path <code>'-'</code> is deprecated and it will be removed in future language versions entirely.</p><p>The <code>:out-buffer</code> controls output buffering and by default behaves as if it were <a href="/type/Nil"><code>Nil</code></a>. See method <a href="/routine/out-buffer">out-buffer</a> for details.</p><p><strong>Note (Rakudo versions before 2017.09): Filehandles are NOT flushed or closed when they go out of scope</strong>. While they <em>will</em> get closed when garbage collected, garbage collection isn't guaranteed to get run. This means <em>you should</em> use an explicit <code>close</code> on handles opened for writing, to avoid data loss, and an explicit <code>close</code> is <em>recommended</em> 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 <code>open</code> calls.</p><p><strong>Note (Rakudo versions 2017.09 and after):</strong> Open filehandles are automatically closed on program exit, but it is still highly recommended that you <code>close</code> opened handles explicitly.</p> <h2 id="method_comb" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method comb<a class="raku-anchor" title="direct link" href="#method_comb">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">comb</span>(IO::Handle:D: <span class="highlite-TYPE">Bool</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span><span class="highlite-OPERATOR">,</span> |<span class="highlite-ROUTINE">args</span> <span class="highlite-KEYWORD">--></span> Seq:D)</pre> </div> </div> <p>Read the handle and processes its contents the same way <a href="/type/Str#routine_comb"><code>Str.comb</code></a> does, taking the same arguments, closing the handle when done if <code>$close</code> is set to a true value. Implementations may slurp the file in its entirety when this method is called.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">path/to/file</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">The file has </span><span class="highlite-ESCAPE">{</span><span class="highlite-OPERATOR">+</span><span class="highlite-NAME_SCALAR">$fh</span>.comb: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">♥</span><span class="highlite-STRING_DELIMITER">'</span><span class="highlite-OPERATOR">,</span> :close<span class="highlite-ESCAPE">}</span><span class="highlite-STRING"> ♥s in it</span><span class="highlite-STRING_DELIMITER">"</span>; </pre> </div> </div> <h2 id="method_chomp" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method chomp<a class="raku-anchor" title="direct link" href="#method_chomp">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">has</span> <span class="highlite-NAME_SCALAR">$.chomp</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">rw</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">True</span></pre> </div> </div> <p>One of the attributes that can be set via <code>.new</code> or <a href="/routine/open">open</a>. Defaults to <code>True</code>. Takes a <a href="/type/Bool"><code>Bool</code></a> specifying whether the line separators (as defined by <a href="/type/IO/Handle#method_nl-in"><code>.nl-in</code></a>) should be removed from content when using <a href="/type/IO/Handle#routine_get"><code>.get</code></a> or <a href="/type/IO/Handle#routine_lines"><code>.lines</code></a> methods.</p> <h2 id="routine_get" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">routine get<a class="raku-anchor" title="direct link" href="#routine_get">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">get</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Str:D) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">get</span> (<span class="highlite-TYPE">IO::Handle</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$*ARGFILES</span> <span class="highlite-KEYWORD">--></span> Str:D)</pre> </div> </div> <p>Reads a single line of input from the handle, removing the trailing newline characters (as set by <a href="/routine/nl-in"><code>.nl-in</code></a>) if the handle's <code>.chomp</code> attribute is set to <code>True</code>. Returns <a href="/type/Nil"><code>Nil</code></a>, if no more input is available. The subroutine form defaults to <a href="/language/variables#index-entry-%24%2AARGFILES"><code>$*ARGFILES</code></a> if no handle is given.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-NAME_SCALAR">$*IN</span>.<span class="highlite-ROUTINE">get</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># Read one line from the standard input </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">open</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">filename</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">get</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># Read one line from a file </span><span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">close</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-ROUTINE">get</span>; <span class="highlite-COMMENT"># Read one line from $*ARGFILES </span></pre> </div> </div> <h2 id="routine_getc" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">routine getc<a class="raku-anchor" title="direct link" href="#routine_getc">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">getc</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Str:D) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">getc</span> (<span class="highlite-TYPE">IO::Handle</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$*ARGFILES</span> <span class="highlite-KEYWORD">--></span> Str:D)</pre> </div> </div> <p>Reads a single character from the input stream. Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown. The subroutine form defaults to <a href="/language/variables#index-entry-%24%2AARGFILES"><code>$*ARGFILES</code></a> if no handle is given. Returns <a href="/type/Nil"><code>Nil</code></a>, if no more input is available, otherwise operation will block, waiting for at least one character to be available; these caveats apply:</p> <h3 id="Buffering_terminals" class="raku-h3"><a href="#class_IO::Handle" title="go to top of document">Buffering terminals<a class="raku-anchor" title="direct link" href="#Buffering_terminals">§</a></a></h3> <p>Using getc to get a single keypress from a terminal will only work properly if you've set the terminal to "unbuffered". Otherwise the terminal will wait for the return key to be struck or the buffer to be filled up before the compiler gets even a single byte of data.</p> <h3 id="Waiting_for_potential_combiners" class="raku-h3"><a href="#class_IO::Handle" title="go to top of document">Waiting for potential combiners<a class="raku-anchor" title="direct link" href="#Waiting_for_potential_combiners">§</a></a></h3> <p>If your handle's encoding allows combining characters to be read, raku will wait for more data to be available before it provides a character. This means that inputting an "e" followed by a combining acute will give you an e with an acute rather than giving an "e" and letting the next reading function give you a dangling combiner. However, it also means that when the user inputs just an "e" and has no intention to also input a combining acute, your program will be waiting for another keypress before the initial "e" is returned.</p> <h2 id="submethod_DESTROY" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">submethod DESTROY<a class="raku-anchor" title="direct link" href="#submethod_DESTROY">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">submethod</span> <span class="highlite-ROUTINE">DESTROY</span>(IO::Handle:D:)</pre> </div> </div> <p>Closes the filehandle, unless its <a href="/routine/native-descriptor">native-descriptor</a> is <code>2</code> or lower. This ensures the standard filehandles do not get inadvertently closed.</p><p>Note that garbage collection is not guaranteed to happen, so you must NOT rely on <code>DESTROY</code> for closing the handles you <em>write to</em> and instead close them yourself. Programs that open a lot of files should close the handles explicitly as well, regardless of whether they were open for writing, since too many files might get opened before garbage collection happens and the no longer used handles get closed.</p> <h2 id="method_gist" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method gist<a class="raku-anchor" title="direct link" href="#method_gist">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">gist</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Str:D)</pre> </div> </div> <p>Returns a string containing information which <a href="/type/IO/Handle#method_path"><code>.path</code></a>, if any, the handle is created for and whether it is <a href="/type/IO/Handle#method_opened"><code>.opened</code></a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-TYPE">IO::Handle</span>.<span class="highlite-ROUTINE">new</span>; <span class="highlite-COMMENT"># IO::Handle<(Any)>(closed) </span><span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>; <span class="highlite-COMMENT"># IO::Handle<"foo".IO>(opened) </span></pre> </div> </div> <h2 id="method_eof" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method eof<a class="raku-anchor" title="direct link" href="#method_eof">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">eof</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Bool:D)</pre> </div> </div> <p>Non-blocking. Returns <code>True</code> if the read operations have exhausted the contents of the handle. For <a href="/routine/seek">seekable</a> handles, this means current position is at or beyond the end of file and <a href="/routine/seek">seeking</a> an exhausted handle back into the file's contents will result in <a href="/routine/eof">eof</a> returning <code>False</code> again.</p><p>On <a href="/routine/seek">non-seekable</a> handles and handles opened to zero-size files (including special files in <code>/proc/</code>), EOF won't be set until a read operation fails to read any bytes. For example, in this code, the first <code>read</code> consumes all of the data, but it's only until the second <code>read</code> that reads nothing would the EOF on a TTY handle be set:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Shell highlighting by highlight-js</label> <div> <pre class="nohighlights"><pre class="browser-hl"> <code class="language-shell">$ echo "x" | raku -e 'with $*IN { .read: 10000; .eof.say; .read: 10; .eof.say }' False True </code></pre> </pre> </div> </div> <h2 id="method_encoding" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method encoding<a class="raku-anchor" title="direct link" href="#method_encoding">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">encoding</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Str:D) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">encoding</span>(IO::Handle:D: <span class="highlite-NAME_SCALAR">$enc</span> <span class="highlite-KEYWORD">--></span> Str:D)</pre> </div> </div> <p>Returns a <a href="/type/Str"><code>Str</code></a> representing the encoding currently used by the handle, defaulting to <code>"utf8"</code>. <a href="/type/Nil"><code>Nil</code></a> indicates the filehandle is currently in binary mode. Specifying an optional positional <code>$enc</code> argument switches the encoding used by the handle; specify <a href="/type/Nil"><code>Nil</code></a> as encoding to put the handle into binary mode.</p><p>The accepted values for encoding are case-insensitive. The available encodings vary by implementation and backend. On Rakudo MoarVM the following are supported:</p><p><a name="index-entry-windows-1252" class="index-entry"></a><a name="index-entry-windows-1251" class="index-entry"></a><a name="index-entry-windows-932" class="index-entry"></a><a name="index-entry-iso-8859-1" class="index-entry"></a><a name="index-entry-ascii" class="index-entry"></a></p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>｢text｣ without highlighting</label> <div> <pre class="nohighlights"><pre class="nohighlights"> utf8 utf16 utf16le utf16be utf8-c8 iso-8859-1 windows-1251 windows-1252 windows-932 ascii </pre> </pre> </div> </div> <p>The default encoding is utf8, which undergoes normalization into Unicode <a href="/type/NFC"><code>NFC</code></a> (normalization form canonical). In some cases you may want to ensure no normalization is done; for this you can use <code>utf8-c8</code>. Before using <code>utf8-c8</code> please read <a href="/language/unicode#Filehandles_and_I/O">Unicode: Filehandles and I/O</a> for more information on <code>utf8-c8</code> and <a href="/type/NFC"><code>NFC</code></a>.</p><p>As of Rakudo 2018.04 <a href="https://en.wikipedia.org/wiki/Code_page_932_(Microsoft_Windows)">windows-932</a> is also supported which is a variant of <a name="index-entry-ShiftJIS-ShiftJIS" class="index-entry"><span class="glossary-entry" data-index-text="⦃〚Reference〛〚ShiftJIS〛⦄">ShiftJIS</span></a>.</p><p>Implementation may choose to also provide support for aliases, e.g. Rakudo allows aliases <code>latin-1</code> for <code>iso-8859-1</code> encoding and dashed utf versions: <code>utf-8</code> and <code>utf-16</code>.</p> <h3 id="utf16,_utf16le_and_utf16be" class="raku-h3"><a href="#class_IO::Handle" title="go to top of document">utf16, utf16le and utf16be<a class="raku-anchor" title="direct link" href="#utf16,_utf16le_and_utf16be">§</a></a></h3> <p><a name="index-entry-utf16-le" class="index-entry"></a><a name="index-entry-utf16-be" class="index-entry"></a><a name="index-entry-utf16" class="index-entry"></a><a name="index-entry-utf-16" class="index-entry"></a></p><p>Unlike utf8, utf16 has an endianness — either big endian or little endian. This relates to the ordering of bytes. Computer CPUs also have an endianness. Raku's <code>utf16</code> format specifier will use the endianness of host system when encoding. When decoding it will look for a byte order mark and if it is there use that to set the endianness. If there is no byte order mark it will assume the file uses the same endianness as the host system. A byte order mark is the codepoint U+FEFF which is ZERO WIDTH NO-BREAK SPACE. On <code>utf16</code> encoded files the standard states if it exists at the start of a file it shall be interpreted as a byte order mark, not a U+FEFF codepoint.</p><p>While writing will cause a different file to be written on different endian systems, at the release of 2018.10 the byte order mark will be written out when writing a file and files created with the utf16 encoding will be able to be read on either big or little endian systems.</p><p>When using utf16be or utf16le encodings a byte order mark is <strong>not</strong> used. The endianness used is not affected by the host cpu type and is either big endian for utf16be or little endian for utf16le.</p><p>In keeping with the standard, a 0xFEFF byte at the start of a file is interpreted as a ZERO WIDTH NO-BREAK SPACE and not as a byte order mark. No byte order mark is written to files that use the utf16be or utf16le encodings.</p><p>As of Rakudo 2018.09 on MoarVM, utf16, <a name="index-entry-utf16le-utf16le" class="index-entry"><span class="glossary-entry" data-index-text="⦃〚Reference〛〚utf16le〛⦄">utf16le</span></a> and <a name="index-entry-utf16be-utf16be" class="index-entry"><span class="glossary-entry" data-index-text="⦃〚Reference〛〚utf16be〛⦄">utf16be</span></a> are supported. In 2018.10, writing to a file with utf16 will properly add a byte order mark (BOM).</p> <h3 id="Examples" class="raku-h3"><a href="#class_IO::Handle" title="go to top of document">Examples<a class="raku-anchor" title="direct link" href="#Examples">§</a></a></h3> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">with</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span> { .spurt: <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">First line is text, then:</span><span class="highlite-ESCAPE">\n</span><span class="highlite-STRING">Binary</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> will leave {.<span class="highlite-ROUTINE">close</span>} <span class="highlite-OPERATOR">=</span> .<span class="highlite-ROUTINE">open</span>; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">get</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «First line is text, then:␤» </span> <span class="highlite-NAME_SCALAR">$fh</span>.encoding: <span class="highlite-TYPE">Nil</span>; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">slurp</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «Buf[uint8]:0x<42 69 6e 61 72 79>␤» </span>} </pre> </div> </div> <h2 id="routine_lines" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">routine lines<a class="raku-anchor" title="direct link" href="#routine_lines">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> <span class="highlite-ROUTINE">lines</span>( <span class="highlite-NAME_SCALAR">$what</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$*ARGFILES</span><span class="highlite-OPERATOR">,</span> |c) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">lines</span>( IO::Handle:D: <span class="highlite-NAME_SCALAR">$limit</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span> ) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">lines</span>( IO::Handle:D: <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span> )</pre> </div> </div> <p>The sub form, which takes <code>$*ARGFILES</code> by default, will apply the <code>lines</code> method to the object that's the first argument, and pass it the rest of the arguments.</p><p>The method will return a <a href="/type/Seq"><code>Seq</code></a> each element of which is a line from the handle (that is chunks delineated by <a href="/type/IO/Handle#method_nl-in"><code>.nl-in</code></a>). If the handle's <a href="/type/IO/Handle#method_chomp"><code>.chomp</code></a> attribute is set to <code>True</code>, then characters specified by <a href="/type/IO/Handle#method_nl-in"><code>.nl-in</code></a> will be stripped from each line.</p><p>Reads up to <code>$limit</code> lines, where <code>$limit</code> can be a non-negative <a href="/type/Int"><code>Int</code></a>, <code>Inf</code>, or <a href="/type/Whatever"><code>Whatever</code></a> (which is interpreted to mean <code>Inf</code>). If <code>:$close</code> is set to <code>True</code>, will close the handle when the file ends or <code>$limit</code> is reached. Subroutine form defaults to <a href="/language/variables#index-entry-%24%2AARGFILES"><code>$*ARGFILES</code></a>, if no handle is provided.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p><p><strong>NOTE:</strong> the lines are read lazily, so ensure the returned <a href="/type/Seq"><code>Seq</code></a> is either <a href="/language/glossary#Reify">fully reified</a> or is no longer needed when you close the handle or attempt to use any other method that changes the file position.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">The file contains </span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">50GB-file</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>.<span class="highlite-ROUTINE">lines</span>.<span class="highlite-ROUTINE">grep</span>(<span class="highlite-OPERATOR">*</span>.contains: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Raku</span><span class="highlite-STRING_DELIMITER">'</span>).<span class="highlite-ROUTINE">elems</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING"> lines that mention Raku</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-COMMENT"># OUTPUT: «The file contains 72 lines that mention Raku␤» </span></pre> </div> </div> <p>You can use <code>lines</code> in <code>/proc/*</code> files (from the 6.d version):</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-ROUTINE">lines</span>( <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">/proc/</span><span class="highlite-NAME_SCALAR">$*PID</span><span class="highlite-STRING">/statm</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span> ); <span class="highlite-COMMENT"># OUTPUT: «(58455 31863 8304 2 0 29705 0)␤» </span></pre> </div> </div> <p><a name="index-entry-File_locking" class="index-entry"></a></p> <h2 id="method_lock" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method lock<a class="raku-anchor" title="direct link" href="#method_lock">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">lock</span>(IO::Handle:D: Bool:D <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$non-blocking</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">False</span><span class="highlite-OPERATOR">,</span> Bool:D <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$shared</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">False</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>) </pre> </div> </div> <p>Places an advisory lock on the file the filehandle if open for. If <code>:$non-blocking</code> is <code>True</code> will <a href="/routine/fail"><code>fail</code></a> with <a href="/type/X/IO/Lock"><code>X::IO::Lock</code></a> if lock could not be obtained, otherwise will block until the lock can be placed. If <code>:$shared</code> is <code>True</code> will place a shared (read) lock, otherwise will place an exclusive (write) lock. On success, returns <code>True</code>; <a href="/routine/fail">fails</a> with <a href="/type/X/IO/Lock"><code>X::IO::Lock</code></a> if lock cannot be placed (e.g. when trying to place a shared lock on a filehandle opened in write mode or trying to place an exclusive lock on a filehandle opened in read mode).</p><p>You can use <code>.lock</code> again to replace an existing lock with another one. To remove a lock, <a href="/routine/close"><code>close</code></a> the filehandle or use <a href="/routine/unlock"><code>unlock</code></a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-COMMENT"># One program writes, the other reads, and thanks to locks either </span><span class="highlite-COMMENT"># will wait for the other to finish before proceeding to read/write </span> <span class="highlite-COMMENT"># Writer </span><span class="highlite-KEYWORD">given</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>(:w) { .<span class="highlite-ROUTINE">lock</span>; .spurt: <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">I ♥ Raku!</span><span class="highlite-STRING_DELIMITER">"</span>; .<span class="highlite-ROUTINE">close</span>; <span class="highlite-COMMENT"># closing the handle unlocks it; we could also use `unlock` for that </span>} <span class="highlite-COMMENT"># Reader </span><span class="highlite-KEYWORD">given</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span> { .lock: :shared; .<span class="highlite-ROUTINE">slurp</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «I ♥ Raku!␤» </span> .<span class="highlite-ROUTINE">close</span>; } </pre> </div> </div> <h2 id="method_unlock" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method unlock<a class="raku-anchor" title="direct link" href="#method_unlock">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">unlock</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>Removes a <a href="/routine/lock"><code>lock</code></a> from the filehandle. It will return <code>True</code> or fail with an exception if it's not possible.</p> <h2 id="routine_words" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">routine words<a class="raku-anchor" title="direct link" href="#routine_words">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">words</span>(IO::Handle:D <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$*ARGFILES</span><span class="highlite-OPERATOR">,</span> <span class="highlite-NAME_SCALAR">$limit</span> <span class="highlite-OPERATOR">=</span> Inf<span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span> <span class="highlite-KEYWORD">--></span> Seq:D) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">words</span>(IO::Handle:D: <span class="highlite-NAME_SCALAR">$limit</span> <span class="highlite-OPERATOR">=</span> Inf<span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span> <span class="highlite-KEYWORD">--></span> Seq:D)</pre> </div> </div> <p>Similar to <a href="/type/Str#routine_words"><code>Str.words</code></a>, separates the handle's stream on contiguous chunks of whitespace (as defined by Unicode) and returns a <a href="/type/Seq"><code>Seq</code></a> of the resultant "words." Takes an optional <code>$limit</code> argument that can be a non-negative <a href="/type/Int"><code>Int</code></a>, <code>Inf</code>, or <a href="/type/Whatever"><code>Whatever</code></a> (which is interpreted to mean <code>Inf</code>), to indicate only up-to <code>$limit</code> words must be returned. If <a href="/type/Bool"><code>Bool</code></a> <code>:$close</code> named argument is set to <code>True</code>, will automatically close the handle when the returned <a href="/type/Seq"><code>Seq</code></a> is exhausted. Subroutine form defaults to <a href="/language/variables#index-entry-%24%2AARGFILES"><code>$*ARGFILES</code></a>, if no handle is provided.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%dict</span> <span class="highlite-OPERATOR">:=</span> <span class="highlite-ROUTINE">bag</span> <span class="highlite-NAME_SCALAR">$*IN</span>.<span class="highlite-ROUTINE">words</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Most common words: </span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> <span class="highlite-NAME_HASH">%dict</span>.<span class="highlite-ROUTINE">sort</span>(<span class="highlite-OPERATOR">-</span>*.<span class="highlite-ROUTINE">value</span>).head: 5; </pre> </div> </div> <p><strong>NOTE:</strong> implementations may read <em>more</em> data than necessary when a call to <code>.words</code> is made. That is, <code>$handle.words(2)</code> may read more data than two "words" worth of data and subsequent calls to read methods might not read from the place right after the two fetched words. After a call to <code>.words</code>, the file position should be treated as undefined.</p> <h2 id="method_split" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method split<a class="raku-anchor" title="direct link" href="#method_split">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">split</span>(IO::Handle:D: <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span><span class="highlite-OPERATOR">,</span> |c)</pre> </div> </div> <p><a href="/routine/slurp">Slurps</a> the handle's content and calls <a href="/type/Str#routine_split"><code>Str.split</code></a> on it, forwarding any of the given arguments. If <code>:$close</code> named parameter is set to <code>True</code>, will <a href="/routine/close">close</a> the invocant after slurping.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">path/to/file</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>; <span class="highlite-NAME_SCALAR">$fh</span>.split: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">♥</span><span class="highlite-STRING_DELIMITER">'</span><span class="highlite-OPERATOR">,</span> :close; <span class="highlite-COMMENT"># Returns file content split on ♥ </span></pre> </div> </div> <h2 id="method_spurt" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method spurt<a class="raku-anchor" title="direct link" href="#method_spurt">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">spurt</span>(IO::Handle:D: <span class="highlite-TYPE">Blob</span> <span class="highlite-NAME_SCALAR">$data</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">False</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">spurt</span>(IO::Handle:D: <span class="highlite-TYPE">Cool</span> <span class="highlite-NAME_SCALAR">$data</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">False</span>)</pre> </div> </div> <p>Writes all of the <code>$data</code> into the filehandle, closing it when finished, if <code>$close</code> is <code>True</code>. For <a href="/type/Cool"><code>Cool</code></a> <code>$data</code>, will use the encoding the handle is set to use (<a href="/routine/open"><code>IO::Handle.open</code></a> or <a href="/routine/encoding"><code>IO::Handle.encoding</code></a>).</p><p>Behavior for spurting a <a href="/type/Cool"><code>Cool</code></a> when the handle is in binary mode or spurting a <a href="/type/Blob"><code>Blob</code></a> when the handle is NOT in binary mode is undefined.</p> <h2 id="method_print" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method print<a class="raku-anchor" title="direct link" href="#method_print">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">print</span>(<span class="highlite-OPERATOR">**</span><span class="highlite-NAME_ARRAY">@text</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">print</span>(Junction:D <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>Writes the given <code>@text</code> to the handle, coercing any non-<a href="/type/Str"><code>Str</code></a> objects to <a href="/type/Str"><code>Str</code></a> by calling <a href="/routine/Str"><code>.Str</code></a> method on them. <a href="/type/Junction"><code>Junction</code></a> arguments <a href="/language/glossary#Autothreading">autothread</a> and the order of printed strings is not guaranteed. See <a href="/routine/write">write</a> to write bytes.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">path/to/file</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.open: :w; <span class="highlite-NAME_SCALAR">$fh</span>.print: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">some text</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">close</span>; </pre> </div> </div> <h2 id="method_print-nl" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method print-nl<a class="raku-anchor" title="direct link" href="#method_print-nl">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">print-nl</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>Writes the value of <code>$.nl-out</code> attribute into the handle. This attribute, by default, is <code>␤</code>, but see the <a href="/language/newline">page on newline</a> for the rules it follows in different platforms and environments.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">path/to/file</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.open: :w<span class="highlite-OPERATOR">,</span> :nl-out(<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-ESCAPE">\r</span><span class="highlite-ESCAPE">\n</span><span class="highlite-STRING_DELIMITER">"</span>); <span class="highlite-NAME_SCALAR">$fh</span>.print: <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">some text</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">print-nl</span>; <span class="highlite-COMMENT"># prints \r\n </span><span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">close</span>; </pre> </div> </div> <h2 id="method_printf" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method printf<a class="raku-anchor" title="direct link" href="#method_printf">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">printf</span>(IO::Handle:D: <span class="highlite-TYPE">Cool</span> <span class="highlite-NAME_SCALAR">$format</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">*</span><span class="highlite-NAME_ARRAY">@args</span>)</pre> </div> </div> <p>Formats a string based on the given format and arguments and <code>.print</code>s the result into the filehandle. See <a href="/routine/sprintf">sprintf</a> for details on acceptable format directives.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">open</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">path/to/file</span><span class="highlite-STRING_DELIMITER">'</span><span class="highlite-OPERATOR">,</span> :w; <span class="highlite-NAME_SCALAR">$fh</span>.printf: <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">The value is </span><span class="highlite-NAME_HASH">%d</span><span class="highlite-ESCAPE">\n</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> 32; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">close</span>; </pre> </div> </div> <h2 id="method_out-buffer" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method out-buffer<a class="raku-anchor" title="direct link" href="#method_out-buffer">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">out-buffer</span>(<span class="highlite-KEYWORD">--></span> Int:D) <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">rw</span></pre> </div> </div> <p>Controls output buffering and can be set via an argument to <a href="/routine/open">open</a>. Takes an <code>int</code> as the size of the buffer to use (zero is acceptable). Can take a <a href="/type/Bool"><code>Bool</code></a>: <code>True</code> means to use default, implementation-defined buffer size; <code>False</code> means to disable buffering (equivalent to using <code>0</code> as buffer size).</p><p>Lastly, can take a <a href="/type/Nil"><code>Nil</code></a> to enable TTY-based buffering control: if the handle <a href="/routine/t">is a TTY</a>, the buffering is disabled, otherwise, default, implementation-defined buffer size is used.</p><p>See <a href="/routine/flush">flush</a> to write out data currently in the buffer. Changing buffer size flushes the filehandle.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">given</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.open: :w<span class="highlite-OPERATOR">,</span> :1000out-buffer { .say: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Hello world!</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># buffered </span> .<span class="highlite-ROUTINE">out-buffer</span> <span class="highlite-OPERATOR">=</span> 42; <span class="highlite-COMMENT"># buffer resized; previous print flushed </span> .say: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">And goodbye</span><span class="highlite-STRING_DELIMITER">'</span>; .<span class="highlite-ROUTINE">close</span>; <span class="highlite-COMMENT"># closing the handle flushes the buffer </span>} </pre> </div> </div> <h2 id="method_put" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method put<a class="raku-anchor" title="direct link" href="#method_put">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">put</span>(<span class="highlite-OPERATOR">**</span><span class="highlite-NAME_ARRAY">@text</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">put</span>(Junction:D <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>Writes the given <code>@text</code> to the handle, coercing any non-<a href="/type/Str"><code>Str</code></a> objects to <a href="/type/Str"><code>Str</code></a> by calling <a href="/routine/Str"><code>.Str</code></a> method on them, and appending the value of <a href="/type/IO/Handle#method_nl-out"><code>.nl-out</code></a> at the end. <a href="/type/Junction"><code>Junction</code></a> arguments <a href="/language/glossary#Autothreading">autothread</a> and the order of printed strings is not guaranteed.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">path/to/file</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.open: :w; <span class="highlite-NAME_SCALAR">$fh</span>.put: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">some text</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">close</span>; </pre> </div> </div> <h2 id="method_say" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method say<a class="raku-anchor" title="direct link" href="#method_say">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">say</span>(IO::Handle:D: <span class="highlite-OPERATOR">**</span><span class="highlite-NAME_ARRAY">@text</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>This method is identical to <a href="/type/IO/Handle#method_put">put</a> except that it stringifies its arguments by calling <a href="/routine/gist"><code>.gist</code></a> instead of <a href="/routine/Str"><code>.Str</code></a>.</p><p>Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">open</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">path/to/file</span><span class="highlite-STRING_DELIMITER">'</span><span class="highlite-OPERATOR">,</span> :w; <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">say</span>(<span class="highlite-TYPE">Complex</span>.<span class="highlite-ROUTINE">new</span>(3<span class="highlite-OPERATOR">,</span> 4)); <span class="highlite-COMMENT"># OUTPUT: «3+4i␤» </span><span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">close</span>; </pre> </div> </div> <h2 id="method_read" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method read<a class="raku-anchor" title="direct link" href="#method_read">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">read</span>(IO::Handle:D: <span class="highlite-TYPE">Int</span>(Cool:D) <span class="highlite-NAME_SCALAR">$bytes</span> <span class="highlite-OPERATOR">=</span> 65536 <span class="highlite-KEYWORD">--></span> Buf:D)</pre> </div> </div> <p>Binary reading; reads and returns up to <code>$bytes</code> bytes from the filehandle. <code>$bytes</code> defaults to an implementation-specific value (in Rakudo, the value of <code>$*DEFAULT-READ-ELEMS</code>, which by default is set to <code>65536</code>). This method can be called even when the handle is not <a href="/type/IO/Handle#method_encoding">in binary mode</a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights">(<span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$file</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>).spurt: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">I ♥ Raku</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-KEYWORD">given</span> <span class="highlite-NAME_SCALAR">$file</span>.<span class="highlite-ROUTINE">open</span> { <span class="highlite-ROUTINE">say</span> .read: 6; <span class="highlite-COMMENT"># OUTPUT: «Buf[uint8]:0x<49 20 e2 99 a5 20>␤» </span> .<span class="highlite-ROUTINE">close</span>; } </pre> </div> </div> <h2 id="method_readchars" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method readchars<a class="raku-anchor" title="direct link" href="#method_readchars">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">readchars</span>(IO::Handle:D: <span class="highlite-TYPE">Int</span>(Cool:D) <span class="highlite-NAME_SCALAR">$chars</span> <span class="highlite-OPERATOR">=</span> 65536 <span class="highlite-KEYWORD">--></span> Str:D)</pre> </div> </div> <p>Reading chars; reads and returns up to <code>$chars</code> chars (graphemes) from the filehandle. <code>$chars</code> defaults to an implementation-specific value (in Rakudo, the value of <code>$*DEFAULT-READ-ELEMS</code>, which by default is set to <code>65536</code>). Attempting to call this method when the handle is <a href="/type/IO/Handle#method_encoding">in binary mode</a> will result in <a href="/type/X/IO/BinaryMode"><code>X::IO::BinaryMode</code></a> exception being thrown.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights">(<span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$file</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>).spurt: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">I ♥ Raku</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-KEYWORD">given</span> <span class="highlite-NAME_SCALAR">$file</span>.<span class="highlite-ROUTINE">open</span> { <span class="highlite-ROUTINE">say</span> .readchars: 5; <span class="highlite-COMMENT"># OUTPUT: «I ♥ R␤» </span> .<span class="highlite-ROUTINE">close</span>; } </pre> </div> </div> <h2 id="method_write" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method write<a class="raku-anchor" title="direct link" href="#method_write">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">write</span>(IO::Handle:D: Blob:D <span class="highlite-NAME_SCALAR">$buf</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>Writes <code>$buf</code> to the filehandle. This method can be called even when the handle is not <a href="/type/IO/Handle#method_encoding">in binary mode</a>.</p><p><a name="index-entry-SeekFromBeginning" class="index-entry"></a> <a name="index-entry-SeekFromCurrent" class="index-entry"></a> <a name="index-entry-SeekFromEnd" class="index-entry"></a></p> <h2 id="method_seek" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method seek<a class="raku-anchor" title="direct link" href="#method_seek">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">seek</span>(IO::Handle:D: Int:D <span class="highlite-NAME_SCALAR">$offset</span><span class="highlite-OPERATOR">,</span> SeekType:D <span class="highlite-NAME_SCALAR">$whence</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>Move the file pointer (that is, the position at which any subsequent read or write operations will begin) to the byte position specified by <code>$offset</code> relative to the location specified by <code>$whence</code> which may be one of:</p> <ul class="rakudoc-item"> <li><p><code>SeekFromBeginning</code>: The beginning of the file.</p></li> <li><p><code>SeekFromCurrent</code>: The current position in the file.</p></li> <li><p><code>SeekFromEnd</code>: The end of the file. Please note that you need to specify a negative offset if you want to position before the end of the file.</p></li> </ul> <h2 id="method_tell" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method tell<a class="raku-anchor" title="direct link" href="#method_tell">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">tell</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Int:D)</pre> </div> </div> <p>Return the current position of the file pointer in bytes.</p> <h2 id="method_slurp-rest" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method slurp-rest<a class="raku-anchor" title="direct link" href="#method_slurp-rest">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">slurp-rest</span>(IO::Handle:D: <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$bin</span>! <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Buf</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">slurp-rest</span>(IO::Handle:D: <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$enc</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Str</span>)</pre> </div> </div> <p><strong>DEPRECATION NOTICE:</strong> this method is deprecated in the <code>6.d</code> version. Do not use it for new code, use <a href="/routine/slurp"><code>.slurp</code> method</a> instead.</p><p>Returns the remaining content of the file from the current file position (which may have been set by previous reads or by <code>seek</code>.) If the adverb <code>:bin</code> is provided a <a href="/type/Buf"><code>Buf</code></a> will be returned; otherwise the return will be a <a href="/type/Str"><code>Str</code></a> with the optional encoding <code>:enc</code>.</p> <h2 id="method_slurp" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method slurp<a class="raku-anchor" title="direct link" href="#method_slurp">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">slurp</span>(IO::Handle:D: <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$close</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$bin</span>)</pre> </div> </div> <p>Returns all the content from the current file pointer to the end. If the invocant is in binary mode or if <code>$bin</code> is set to <code>True</code>, will return a <a href="/type/Buf"><code>Buf</code></a>, otherwise will decode the content using invocant's current <a href="/routine/encoding"><code>.encoding</code></a> and return a <a href="/type/Str"><code>Str</code></a>.</p><p>If <code>:$close</code> is set to <code>True</code>, will close the handle when finished reading.</p><p><strong>Note:</strong> On <a href="/language/glossary#Rakudo">Rakudo</a> this method was introduced with release 2017.04; <code>$bin</code> arg was added in 2017.10.</p> <h2 id="method_Supply" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method Supply<a class="raku-anchor" title="direct link" href="#method_Supply">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-TYPE">Supply</span>(IO::Handle:D: <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$size</span> <span class="highlite-OPERATOR">=</span> 65536)</pre> </div> </div> <p>Returns a <a href="/type/Supply"><code>Supply</code></a> that will emit the contents of the handle in chunks. The chunks will be <a href="/type/Buf"><code>Buf</code></a> if the handle is in binary mode or, if it isn't, <a href="/type/Str"><code>Str</code></a> decoded using same encoding as <a href="/routine/encoding"><code>IO::Handle.encoding</code></a>.</p><p>The size of the chunks is determined by the optional <code>:size</code> named parameter and <code>65536</code> bytes in binary mode or <code>65536</code> characters in non-binary mode.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>(:bin).<span class="highlite-TYPE">Supply</span>(:size<10>).tap: <span class="highlite-OPERATOR">*</span>.<span class="highlite-ROUTINE">raku</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: </span><span class="highlite-COMMENT"># Buf[uint8].new(73,32,226,153,165,32,80,101,114,108) </span><span class="highlite-COMMENT"># Buf[uint8].new(32,54,33,10) </span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>.<span class="highlite-TYPE">Supply</span>(:size<10>).tap: <span class="highlite-OPERATOR">*</span>.<span class="highlite-ROUTINE">raku</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: </span><span class="highlite-COMMENT"># "I ♥ Perl" </span><span class="highlite-COMMENT"># " 6!\n" </span></pre> </div> </div> <h2 id="method_path" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method path<a class="raku-anchor" title="direct link" href="#method_path">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">path</span>(IO::Handle:D:)</pre> </div> </div> <p>For a handle opened on a file this returns the <a href="/type/IO/Path"><code>IO::Path</code></a> that represents the file. For the standard I/O handles <a href="/language/variables#index-entry-%24%2AIN"><code>$*IN</code></a>, <a href="/language/variables#index-entry-%24%2AOUT"><code>$*OUT</code></a>, and <a href="/language/variables#index-entry-%24%2AERR"><code>$*ERR</code></a> it returns an <a href="/type/IO/Special"><code>IO::Special</code></a> object.</p> <h2 id="method_IO" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method IO<a class="raku-anchor" title="direct link" href="#method_IO">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-TYPE">IO</span>(IO::Handle:D:)</pre> </div> </div> <p>Alias for <a href="/type/IO/Handle#method_path"><code>.path</code></a></p> <h2 id="method_Str" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method Str<a class="raku-anchor" title="direct link" href="#method_Str">§</a></a></h2>  <p>Returns the value of <a href="/type/IO/Handle#method_path"><code>.path</code></a>, coerced to <a href="/type/Str"><code>Str</code></a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>.<span class="highlite-TYPE">Str</span>; <span class="highlite-COMMENT"># OUTPUT: «foo␤» </span></pre> </div> </div> <h2 id="routine_close" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">routine close<a class="raku-anchor" title="direct link" href="#routine_close">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">close</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Bool:D) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">close</span>(<span class="highlite-TYPE">IO::Handle</span> <span class="highlite-NAME_SCALAR">$fh</span>)</pre> </div> </div> <p>Closes an open filehandle, returning <code>True</code> on success. No error is thrown if the filehandle is already closed, although if you close one of the standard filehandles (by default: <code>$*IN</code>, <code>$*OUT</code>, or <code>$*ERR</code>: any handle with <a href="/routine/native-descriptor">native-descriptor</a> <code>2</code> or lower), you won't be able to re-open them.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">given</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo/bar</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">open</span>(:w) { .spurt: <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">I ♥ Raku!</span><span class="highlite-STRING_DELIMITER">"</span>; .<span class="highlite-ROUTINE">close</span>; } </pre> </div> </div> <p>It's a common idiom to use <a href="/language/phasers#LEAVE"><code>LEAVE</code> phaser</a> for closing the handles, which ensures the handle is closed regardless of how the block is left.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">do</span> { <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">open</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">path-to-file</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-KEYWORD">LEAVE</span> <span class="highlite-ROUTINE">close</span> <span class="highlite-NAME_SCALAR">$fh</span>; <span class="highlite-COMMENT"># ... do stuff with the file </span>} <span class="highlite-KEYWORD">sub</span> do-stuff-with-the-file (<span class="highlite-TYPE">IO</span> <span class="highlite-NAME_SCALAR">$path-to-file</span>) { <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$path-to-file</span>.<span class="highlite-ROUTINE">open</span>; <span class="highlite-COMMENT"># stick a `try` on it, since this will get run even when the sub is </span> <span class="highlite-COMMENT"># called with wrong arguments, in which case the `$fh` will be an `Any` </span> <span class="highlite-KEYWORD">LEAVE</span> <span class="highlite-KEYWORD">try</span> <span class="highlite-ROUTINE">close</span> <span class="highlite-NAME_SCALAR">$fh</span>; <span class="highlite-COMMENT"># ... do stuff with the file </span>} </pre> </div> </div> <p><strong>Note:</strong> unlike some other languages, Raku does not use reference counting, and so <strong>the filehandles are NOT closed when they go out of scope</strong>. While they <em>will</em> get closed when garbage collected, garbage collection isn't guaranteed to get run. This means <strong>you must</strong> use an explicit <code>close</code> on handles opened for writing, to avoid data loss, and an explicit <code>close</code> is <em>recommended</em> 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 <code>open</code> calls.</p><p>Note several methods allow for providing <code>:close</code> argument, to close the handle after the operation invoked by the method completes. As a simpler alternative, the <a href="/type/IO/Path"><code>IO::Path</code></a> type provides many reading and writing methods that let you work with files without dealing with filehandles directly.</p> <h2 id="method_flush" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method flush<a class="raku-anchor" title="direct link" href="#method_flush">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">flush</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>)</pre> </div> </div> <p>Will flush the handle, writing any of the buffered data. Returns <code>True</code> on success; otherwise, <a href="/routine/fail">fails</a> with <a href="/type/X/IO/Flush"><code>X::IO::Flush</code></a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">given</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-TYPE">IO</span>.open: :w { <span class="highlite-KEYWORD">LEAVE</span> .<span class="highlite-ROUTINE">close</span>; .print: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">something</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">slurp</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># (if the data got buffered) OUTPUT: «␤» </span> .<span class="highlite-ROUTINE">flush</span>; <span class="highlite-COMMENT"># flush the handle </span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">slurp</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «something␤» </span>} </pre> </div> </div> <h2 id="method_native-descriptor" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method native-descriptor<a class="raku-anchor" title="direct link" href="#method_native-descriptor">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">native-descriptor</span>(IO::Handle:D:)</pre> </div> </div> <p>This returns a value that the operating system would understand as a "file descriptor" and is suitable for passing to a native function that requires a file descriptor as an argument such as <code>fcntl</code> or <code>ioctl</code>.</p> <h2 id="method_nl-in" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method nl-in<a class="raku-anchor" title="direct link" href="#method_nl-in">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">nl-in</span>(<span class="highlite-KEYWORD">--></span> Str:D) <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">rw</span></pre> </div> </div> <p>One of the attributes that can be set via <code>.new</code> or <a href="/routine/open">open</a>. Defaults to <code>["\x0A", "\r\n"]</code>. Takes either a <a href="/type/Str"><code>Str</code></a> or <a href="/type/Array"><code>Array</code></a> of <a href="/type/Str"><code>Str</code></a> specifying input line ending(s) for this handle. If <code>.chomp</code> attribute is set to <code>True</code>, will strip these endings in routines that <code>chomp</code>, such as <a href="/routine/get"><code>get</code></a> and <a href="/routine/lines"><code>lines</code></a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">with</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">test</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span> { .spurt: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">1foo2bar3foo</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># write some data into our test file </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> will leave {.<span class="highlite-ROUTINE">close</span>} <span class="highlite-OPERATOR">=</span> .<span class="highlite-ROUTINE">open</span>; <span class="highlite-COMMENT"># can also set .nl-in via .open arg </span> <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">nl-in</span> <span class="highlite-OPERATOR">=</span> [<foo bar>]; <span class="highlite-COMMENT"># set two possible line endings to use; </span> <span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">lines</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: ("1", "2", "3").Seq </span>} </pre> </div> </div> <h2 id="method_nl-out" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method nl-out<a class="raku-anchor" title="direct link" href="#method_nl-out">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">has</span> Str:D <span class="highlite-NAME_SCALAR">$.nl-out</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">rw</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-ESCAPE">\n</span><span class="highlite-STRING_DELIMITER">"</span>;</pre> </div> </div> <p>One of the attributes that can be set via <code>.new</code> or <a href="/routine/open">open</a>. Defaults to <code>"\n"</code>. Takes a <a href="/type/Str"><code>Str</code></a> specifying output line ending for this handle, to be used by methods <a href="/type/IO/Handle#method_put"><code>.put</code></a> and <a href="/type/IO/Handle#method_say"><code>.say</code></a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">with</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">test</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">IO</span> { <span class="highlite-KEYWORD">given</span> .open: :w { .put: 42; .<span class="highlite-ROUTINE">nl-out</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>; .put: 42; .<span class="highlite-ROUTINE">close</span>; } .<span class="highlite-ROUTINE">slurp</span>.<span class="highlite-ROUTINE">raku</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «"42\n42foo"␤» </span>} </pre> </div> </div> <h2 id="method_opened" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method opened<a class="raku-anchor" title="direct link" href="#method_opened">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">opened</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Bool:D)</pre> </div> </div> <p>Returns <code>True</code> if the handle is open, <code>False</code> otherwise.</p> <h2 id="method_t" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method t <a name="index-entry-tty" data-indexedheader="Reference;tty"></a><span class="glossary-entry-heading"></span><a class="raku-anchor" title="direct link" href="#method_t">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">t</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Bool:D)</pre> </div> </div> <p>Returns <code>True</code> if the handle is opened to a <a href="https://en.wikipedia.org/wiki/Terminal_emulator">TTY</a>, <code>False</code> otherwise.</p> <h1 id="Creating_Custom_Handles" class="raku-h1"><a href="#class_IO::Handle" title="go to top of document">Creating Custom Handles<a class="raku-anchor" title="direct link" href="#Creating_Custom_Handles">§</a></a></h1> <p>As of 6.d language (early implementation available in Rakudo compiler version 2018.08), a few helper methods are available to simplify creation of custom <code>IO::Handle</code> objects. In your subclass you simply need to implement those methods to affect all of the related features. If your handle wants to work with textual read/write methods and doesn't use the standard <code>.open</code> method, be sure to call <code>.encoding</code> method in your custom handle to get decoder/encoder properly set up:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">class</span> IO::URL <span class="highlite-KEYWORD">is</span> <span class="highlite-TYPE">IO::Handle</span> { <span class="highlite-KEYWORD">has</span> <span class="highlite-NAME_SCALAR">$.URL</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">required</span>; <span class="highlite-KEYWORD">has</span> <span class="highlite-TYPE">Buf</span> <span class="highlite-NAME_SCALAR">$!content</span>; <span class="highlite-KEYWORD">submethod</span> <span class="highlite-ROUTINE">TWEAK</span> { <span class="highlite-KEYWORD">use</span> WWW; <span class="highlite-COMMENT"># ecosystem module that will let us `get` a web page </span> <span class="highlite-KEYWORD">use</span> DOM::Tiny; <span class="highlite-COMMENT"># ecosystem module that will parse out all text from HTML </span> <span class="highlite-NAME_SCALAR">$!content</span> <span class="highlite-OPERATOR">:=</span> <span class="highlite-TYPE">Buf</span>.new: DOM::Tiny.<span class="highlite-ROUTINE">parse</span>(<span class="highlite-ROUTINE">get</span> <span class="highlite-NAME_SCALAR">$!URL</span>).all-text(:trim).<span class="highlite-ROUTINE">encode</span>; <span class="highlite-ROUTINE">self</span>.encoding: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">utf8</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># set up encoder/decoder </span> } <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">open</span>(<span class="highlite-OPERATOR">|</span>) { <span class="highlite-ROUTINE">self</span> } <span class="highlite-COMMENT"># block out some IO::Handle methods </span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">close</span>(<span class="highlite-OPERATOR">|</span>) { <span class="highlite-ROUTINE">self</span> } <span class="highlite-COMMENT"># that work with normal low-level file </span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">opened</span> { <span class="highlite-OPERATOR">!</span> <span class="highlite-ROUTINE">self</span>.<span class="highlite-ROUTINE">EOF</span> } <span class="highlite-COMMENT"># handles, since we don't. This isn't </span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">lock</span>(<span class="highlite-OPERATOR">|</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>) { } <span class="highlite-COMMENT"># necessary, but will make our handle </span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">unlock</span>( <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">True</span>) { } <span class="highlite-COMMENT"># be more well-behaved if someone </span> <span class="highlite-COMMENT"># actually calls one of these methods. There are more of these you </span> <span class="highlite-COMMENT"># can handle, such as .tell, .seek, .flush, .native-descriptor, etc. </span> <span class="highlite-KEYWORD">method</span> WRITE(<span class="highlite-OPERATOR">|</span>) { <span class="highlite-COMMENT"># For this handle we'll just die on write. If yours can handle writes. </span> <span class="highlite-COMMENT"># The data to write will be given as a Blob positional argument. </span> <span class="highlite-ROUTINE">die</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Cannot write into IO::URL</span><span class="highlite-STRING_DELIMITER">"</span>; } <span class="highlite-KEYWORD">method</span> READ(\<span class="highlite-ROUTINE">bytes</span>) { <span class="highlite-COMMENT"># We splice off the requested number of bytes from the head of </span> <span class="highlite-COMMENT"># our content Buf. The handle's decoder will handle decoding them </span> <span class="highlite-COMMENT"># automatically, if textual read methods were called on the handle. </span> <span class="highlite-NAME_SCALAR">$!content</span>.splice: 0<span class="highlite-OPERATOR">,</span> <span class="highlite-ROUTINE">bytes</span> } <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">EOF</span> { <span class="highlite-COMMENT"># For "end of file", we'll simply report whether we still have </span> <span class="highlite-COMMENT"># any bytes of the website we fetched on creation. </span> <span class="highlite-OPERATOR">not</span> <span class="highlite-NAME_SCALAR">$!content</span> } } <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$fh</span> <span class="highlite-OPERATOR">:=</span> IO::URL.new: :URL<<span class="highlite-ROUTINE">raku</span>.org>; <span class="highlite-COMMENT"># .slurp and print all the content from the website. We can use all other </span><span class="highlite-COMMENT"># read methods, such as .lines, or .get, or .readchars. All of them work </span><span class="highlite-COMMENT"># correctly, even though we only defined .READ and .EOF </span><span class="highlite-NAME_SCALAR">$fh</span>.<span class="highlite-ROUTINE">slurp</span>.<span class="highlite-ROUTINE">say</span>; </pre> </div> </div> <h2 id="method_WRITE" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method WRITE<a class="raku-anchor" title="direct link" href="#method_WRITE">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> WRITE(IO::Handle:D: Blob:D \data <span class="highlite-KEYWORD">--></span> Bool:D)</pre> </div> </div> <p>Called whenever a write operation is performed on the handle. Always receives the data as a <a href="/type/Blob"><code>Blob</code></a>, even if a textual writing method has been called.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">class</span> IO::Store <span class="highlite-KEYWORD">is</span> <span class="highlite-TYPE">IO::Handle</span> { <span class="highlite-KEYWORD">has</span> <span class="highlite-NAME_ARRAY">@.lines</span> <span class="highlite-OPERATOR">=</span> []; <span class="highlite-KEYWORD">submethod</span> <span class="highlite-ROUTINE">TWEAK</span> { <span class="highlite-ROUTINE">self</span>.encoding: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">utf8</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># set up encoder/decoder </span> } <span class="highlite-KEYWORD">method</span> WRITE(IO::Handle:D: Blob:D \data <span class="highlite-KEYWORD">--></span> Bool:D) { <span class="highlite-NAME_ARRAY">@!lines</span>.push: data.<span class="highlite-ROUTINE">decode</span>(); <span class="highlite-TYPE">True</span>; } <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">gist</span>() { <span class="highlite-KEYWORD">return</span> <span class="highlite-NAME_ARRAY">@!lines</span>.<span class="highlite-ROUTINE">join</span>(<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-ESCAPE">\n</span><span class="highlite-STRING_DELIMITER">"</span> ); } } <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$store</span> <span class="highlite-OPERATOR">=</span> IO::Store.<span class="highlite-ROUTINE">new</span>(); <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$output</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$PROCESS::OUT</span>; <span class="highlite-NAME_SCALAR">$PROCESS::OUT</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$store</span>; .<span class="highlite-ROUTINE">say</span> <span class="highlite-KEYWORD">for</span> <<span class="highlite-ROUTINE">one</span> two three>; <span class="highlite-NAME_SCALAR">$PROCESS::OUT</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$output</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$store</span>.<span class="highlite-ROUTINE">lines</span>(); <span class="highlite-COMMENT"># OUTPUT: «[one␤ two␤ three␤]» </span></pre> </div> </div> <p>In this example we are creating a simple <code>WRITE</code> redirection which stores anything written to the filehandle to an array. Se need to save the standard output first, which we do in <code>$output</code>, and then everything that is <code>print</code>ed or said (through <code>say</code>) gets stored in the defined <code>IO::Store</code> class. Two things should be taken into account in this class. By default, <code>IO::Handle</code>s are in binary mode, so we need to <code>TWEAK</code> the objects if we want them to work with text. Second, a <code>WRITE</code> operation should return <code>True</code> if successful. It will fail if it does not.</p> <h2 id="method_READ" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method READ<a class="raku-anchor" title="direct link" href="#method_READ">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> READ(IO::Handle:D: Int:D \<span class="highlite-ROUTINE">bytes</span> <span class="highlite-KEYWORD">--></span> Buf:D)</pre> </div> </div> <p>Called whenever a read operation is performed on the handle. Receives the number of bytes requested to read. Returns a <a href="/type/Buf"><code>Buf</code></a> with those bytes which can be used to either fill the decoder buffer or returned from reading methods directly. The result is allowed to have fewer than the requested number of bytes, including no bytes at all.</p><p>If you provide your own <code>.READ</code>, you very likely need to provide your own <a href="/routine/EOF"><code>.EOF</code></a> as well, for all the features to behave correctly.</p><p>The compiler may call <a href="/routine/EOF"><code>.EOF</code></a> method any number of times during a read operation to ascertain whether a call to <code>.READ</code> should be made. More bytes than necessary to satisfy a read operation may be requested from <code>.READ</code>, in which case the extra data may be buffered by the <code>IO::Handle</code> or the decoder it's using, to fulfill any subsequent reading operations, without necessarily having to make another <code>.READ</code> call.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">class</span> IO::Store <span class="highlite-KEYWORD">is</span> <span class="highlite-TYPE">IO::Handle</span> { <span class="highlite-KEYWORD">has</span> <span class="highlite-NAME_ARRAY">@.lines</span> <span class="highlite-OPERATOR">=</span> []; <span class="highlite-KEYWORD">submethod</span> <span class="highlite-ROUTINE">TWEAK</span> { <span class="highlite-ROUTINE">self</span>.encoding: <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">utf8</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># set up encoder/decoder </span> } <span class="highlite-KEYWORD">method</span> WRITE(IO::Handle:D: Blob:D \data <span class="highlite-KEYWORD">--></span> Bool:D) { <span class="highlite-NAME_ARRAY">@!lines</span>.push: data; <span class="highlite-TYPE">True</span>; } <span class="highlite-KEYWORD">method</span> whole() { <span class="highlite-KEYWORD">my</span> <span class="highlite-TYPE">Buf</span> <span class="highlite-NAME_SCALAR">$everything</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">Buf</span>.<span class="highlite-ROUTINE">new</span>(); <span class="highlite-KEYWORD">for</span> <span class="highlite-NAME_ARRAY">@!lines</span> <span class="highlite-KEYWORD">-></span> <span class="highlite-NAME_SCALAR">$b</span> { <span class="highlite-NAME_SCALAR">$everything</span> <span class="highlite-OPERATOR">~</span><span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$b</span>; } <span class="highlite-KEYWORD">return</span> <span class="highlite-NAME_SCALAR">$everything</span>; } <span class="highlite-KEYWORD">method</span> READ(IO::Handle:D: Int:D \<span class="highlite-ROUTINE">bytes</span> <span class="highlite-KEYWORD">--></span> Buf:D) { <span class="highlite-KEYWORD">my</span> <span class="highlite-TYPE">Buf</span> <span class="highlite-NAME_SCALAR">$everything</span> <span class="highlite-OPERATOR">:=</span> <span class="highlite-ROUTINE">self</span>.whole(); <span class="highlite-KEYWORD">return</span> <span class="highlite-NAME_SCALAR">$everything</span>; } <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">EOF</span> { <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$everything</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">self</span>.whole(); <span class="highlite-OPERATOR">!</span><span class="highlite-NAME_SCALAR">$everything</span>; } } <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$store</span> <span class="highlite-OPERATOR">:=</span> IO::Store.<span class="highlite-ROUTINE">new</span>(); <span class="highlite-NAME_SCALAR">$store</span>.<span class="highlite-ROUTINE">print</span>( <span class="highlite-NAME_SCALAR">$_</span> ) <span class="highlite-KEYWORD">for</span> <<span class="highlite-ROUTINE">one</span> two three>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$store</span>.<span class="highlite-ROUTINE">read</span>(3).<span class="highlite-ROUTINE">decode</span>; <span class="highlite-COMMENT"># OUTPUT: «one␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$store</span>.<span class="highlite-ROUTINE">read</span>(3).<span class="highlite-ROUTINE">decode</span>; <span class="highlite-COMMENT"># OUTPUT: «two␤» </span></pre> </div> </div> <p>In this case, we have programmed the two <code>READ</code> and <code>EOF</code> methods, as well as <code>WRITE</code>, which stores every line in an element in an array. The <code>read</code> method actually calls <code>READ</code>, returning 3 bytes, which correspond to the three characters in the first two elements. Please note that it's the <code>IO::Handle</code> base class the one that is taking care of cursor, since <code>READ</code> just provides a handle into the whole content of the object; the base class will <code>READ</code> 1024 * 1024 bytes at a time. If your object is planned to hold an amount of bytes bigger than that, you will have to handle an internal cursor yourself. That is why in this example we don't actually use the <code>bytes</code> argument.</p> <h2 id="method_EOF" class="raku-h2"><a href="#class_IO::Handle" title="go to top of document">method EOF<a class="raku-anchor" title="direct link" href="#method_EOF">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">EOF</span>(IO::Handle:D: <span class="highlite-KEYWORD">--></span> Bool:D)</pre> </div> </div> <p>Indicates whether "end of file" has been reached for the <strong>data source</strong> of the handle; i.e. no more data can be obtained by calling <a href="/routine/READ"><code>.READ</code></a> method. Note that this is <strong>not</strong> the same as <a href="/routine/eof">eof</a> method, which will return <code>True</code> only if <code>.EOF</code> returns <code>True</code> <strong>and all the decoder buffers</strong>, if any were used by the handle, are also empty. See <a href="/routine/READ"><code>.READ</code></a> for an example implementation.</p> <h1 id="Related_roles_and_classes" class="raku-h1"><a href="#class_IO::Handle" title="go to top of document">Related roles and classes<a class="raku-anchor" title="direct link" href="#Related_roles_and_classes">§</a></a></h1> <p>See also the related role <a href="/type/IO"><code>IO</code></a> and the related class <a href="/type/IO/Path"><code>IO::Path</code></a>.</p> </div></div></section> </div> </div> </div> <footer class="footer main-footer"> <div class="container px-4"> <nav class="level"> <div class="level-left"> <div class="level-item"> <a href="/about">About</a> </div> <div class="level-item"> <a id="toggle-theme">Toggle theme</a> </div> <div class="level-item" title="a89742bdf 2024-07-14"> <a>Commit</a> </div> </div> <div class="level-right"> <div class="level-item"> <a href="/license">License</a> </div> </div> </nav> </div> </footer> </body> </html>

CINXE.COM

class IO::Handle | Raku Documentation