TITLE

SUBTITLE

This official documentation covers a variety of presentation styles.
See the main L</introduction> and L</reference> pages for a list of documents in
the following styles.


item

root

A basic introductory example of a Raku program


Raku by example 101


How to contribute to Raku and to the documents, how to generate the docs locally


About the docs


The extensions recommended for files with Raku content.


Filename extensions


Using Raku official documentation


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

Brief introduction


head

The vast majority of common IO work is done by the L<C<IO::Path>|/type/IO::Path>
type. If you want to read from or write to a file in some form or shape, this
is the class you want. It abstracts away the details of filehandles
(or "file descriptors") and so you mostly don't even have to think about them.


Behind the scenes, L<C<IO::Path>|/type/IO::Path> works with
L<C<IO::Handle>|/type/IO::Handle>, a class which you can use directly if you
need a bit more control than what L<C<IO::Path>|/type/IO::Path> provides. When
working with other processes, e.g. via L<C<Proc>|/type/Proc> or
L<C<Proc::Async>|/type/Proc::Async> types, you'll also be dealing with a
I<subclass> of L<C<IO::Handle>|/type/IO::Handle>: the L<C<IO::Pipe>|/type/IO::Pipe>.


Lastly, you have the L<C<IO::CatHandle>|/type/IO::CatHandle>, as well as
L<C<IO::Spec>|/type/IO::Spec> and its subclasses, that you'll rarely, if ever,
use directly. These classes give you advanced features, such as operating on
multiple files as one handle, or low-level path manipulations.


Along with all these classes, Raku provides several subroutines that
let you indirectly work with these classes. These come in handy if you like
functional programming style or in Raku one liners.


While L<C<IO::Socket>|/type/IO::Socket> and its subclasses also have to do with
Input and Output, this guide does not cover them.


To represent paths as either files or directories, use
L<C<IO::Path>|/type/IO::Path> type. The simplest way to obtain an object of that
type is to coerce a L<C<Str>|/type/Str> by calling the L«C<.IO>|/routine/IO» method
on it:


say 'my-file.txt'.IO; # OUTPUT: «"my-file.txt".IO␤»


It may seem like something is missing here—there is no volume or absolute
path involved—but that information is actually present in the object. You can
see it by using L«C<.raku>|/routine/raku» method:


say 'my-file.txt'.IO.raku;
# OUTPUT: «IO::Path.new("my-file.txt", :SPEC(IO::Spec::Unix), :CWD("/home/camelia"))␤»


The two extra attributes—C<SPEC> and C<CWD>—specify what type of operating
system semantics the path should use as well as the "current working directory"
for the path, i.e. if it's a relative path, then it's relative to that
directory.


This means that regardless of how you made one, an L<C<IO::Path>|/type/IO::Path>
object technically always refers to an absolute path. This is why its
L«C<.absolute>|/routine/absolute» and L«C<.relative>|/routine/relative»
methods return L<C<Str>|/type/Str> objects and they are the correct way to
stringify a path.


However, don't be in a rush to stringify anything. Pass paths around as
L<C<IO::Path>|/type/IO::Path> objects. All the routines that operate on paths
can handle them, so there's no need to convert them.


Given a local file name, it's very easy to get its components.
For example, we have a file, "financial.data", in some
directory, "/usr/local/data". Use Raku to analyze its path:


code

=begin code
my $fname = "financial.data";
# Stringify the full path name
my $f = $fname.IO.absolute;
say $f;
#   OUTPUT: «/usr/local/data/financial.data␤»
# Stringify the path's parts:
say $f.IO.dirname;                       # OUTPUT: «/usr/local/data␤»
say $f.IO.basename;                      # OUTPUT: «financial.data␤»
# And the basename's parts:
# Use a method for the extension:
say $f.IO.extension;                     # OUTPUT: «data␤»
# Remove the extension by redefining it:
say ($f.IO.extension("")).IO.basename;   # OUTPUT: «financial␤»
=end code


Let's make some files and write and read data from them! The
L«C<spurt>|/routine/spurt» and L«C<slurp>|/routine/slurp» routines write and
read the data in one chunk respectively. Unless you're working with very large
files that are difficult to store entirely in memory all at the same time,
these two routines are for you.


The code above creates a file named C<my-file.txt> in the current directory
and then writes text C<I ♥ Raku!> into it. If Raku is your first language,
celebrate your accomplishment! Try to open the file you created with a
text editor to verify what you wrote with your program. If you already know
some other language, you may be wondering if this guide missed anything like
handling encoding or error conditions.


However, that is all the code you need. The string will be encoded in C<utf-8>
encoding by default and the errors are handled via the L<C<Failure>|/type/Failure>
mechanism: these are exceptions you can handle using regular conditionals. In
this case, we're letting all potential L<C<Failure>|/type/Failure>s get sunk
after the call and so any L<C<Exceptions>|/type/Exception> they contain will be
thrown.


If you wanted to add more content to the file we created in the previous
section, you could note the L«C<spurt> documentation|/routine/spurt» mentions
C<:append> as one of its argument options. However, for finer control, let's
get ourselves an L<C<IO::Handle>|/type/IO::Handle> to work with:


The L«C<.open>|/routine/open» method call opens our L<C<IO::Path>|/type/IO::Path>
and returns an L<C<IO::Handle>|/type/IO::Handle>. We passed C<:a> as argument, to
indicate we want to open the file for writing in append mode.


In the next two lines of code, we use the usual L«C<.print>|/routine/print»
method on that L<C<IO::Handle>|/type/IO::Handle> to print a line with 11 pieces
of text (the C<'I count: '> string and 10 numbers). Note that, once again,
L<C<Failure>|/type/Failure> mechanism takes care of all the error checking for us.
If the L«C<.open>|/routine/open» fails, it returns a L<C<Failure>|/type/Failure>,
which will throw when we attempt to call method the L«C<.print>|/routine/print»
on it.


Finally, we close the L<C<IO::Handle>|/type/IO::Handle> by calling the
L«C<.close>|/routine/close» method on it. It is
I<important that you do it>, especially in large programs or ones that deal
with a lot of files, as many systems have limits to how many files a program
can have open at the same time. If you don't close your handles, eventually
you'll reach that limit and the L«C<.open>|/routine/open» call will fail.
Note that unlike some other languages, Raku does not use reference counting,
so the filehandles B<are NOT closed> when the scope they're defined in is left.
They will be closed only when they're garbage collected and failing to close
the handles may cause your program to reach the file limit I<before> the open
handles get a chance to get garbage collected.


We've seen in previous sections that writing stuff to files is a single-line
of code in Raku. Reading from them, is similarly easy:


The L«C<.slurp>|/routine/slurp» method reads entire contents of the file
and returns them as a single L<C<Str>|/type/Str> object, or as a L<C<Buf>|/type/Buf>
object, if binary mode was requested, by specifying C<:bin> named argument.


Since L«slurping|/routine/slurp» loads the entire file into memory, it's not
ideal for working with huge files.


The L<C<IO::Path>|/type/IO::Path> type offers two other handy methods:
L«C<.words>|/type/IO::Path#method_words» and
L«C<.lines>|/type/IO::Path#method_lines» that lazily read the file in smaller
chunks and return L<C<Seq>|/type/Seq> objects that (by default) don't keep
already-consumed values around.


Here's an example that finds lines in a text file that mention Raku and prints
them out. Despite the file itself being too large to fit into available
L<RAM|https://en.wikipedia.org/wiki/Random-access_memory>, the program will
not have any issues running, as the contents are processed in small chunks:


Here's another example that prints the first 100 words from a file, without
loading it entirely:


Note that we did this by passing a limit argument to
L«C<.words>|/type/IO::Path#method_words» instead of, say, using
L<a list indexing operation|/language/operators#index-entry-array_indexing_operator-array_subscript_operator-array_indexing_operator>.
The reason for that is there's still a filehandle in use under the hood, and
until you fully consume the returned L<C<Seq>|/type/Seq>, the handle will remain open.
If nothing references the L<C<Seq>|/type/Seq>, eventually the handle will get closed, during
a garbage collection run, but in large programs that work with a lot of files,
it's best to ensure all the handles get closed right away. So, you should
always ensure the L<C<Seq>|/type/Seq> from L<C<IO::Path>|/type/IO::Path>'s
L«C<.words>|/type/IO::Path#method_words» and
L«C<.lines>|/type/IO::Path#method_lines» methods is
L<fully reified|/language/glossary#Reify>; and the limit argument
is there to help you with that.


You can read from files using the L<C<IO::Handle>|/type/IO::Handle>
type; this gives you a finer control over the process.


=begin code
given 'some-file.txt'.IO.open {
    say .readchars: 8;  # OUTPUT: «I ♥ Raku␤»
    .seek: 1, SeekFromCurrent;
    say .readchars: 15;  # OUTPUT: «I ♥ Programming␤»
    .close
}
=end code


The L<C<IO::Handle>|/type/IO::Handle> gives you
L«.read|/type/IO::Handle#method_read»,
L«.readchars|/type/IO::Handle#method_readchars»,
L«.get|/type/IO::Handle#routine_get»,
L«.getc|/type/IO::Handle#routine_getc»,
L«.words|/type/IO::Handle#routine_words»,
L«.lines|/type/IO::Handle#routine_lines»,
L«.slurp|/type/IO::Handle#method_slurp»,
L«.comb|/type/IO::Handle#method_comb»,
L«.split|/type/IO::Handle#method_split»,
and L«.Supply|/type/IO::Handle#method_Supply»
methods to read data from it. Plenty of
options; and the catch is you need to close the handle when you're done with it.


Unlike some languages, the handle won't get automatically closed when the
scope it's defined in is left. Instead, it'll remain open until it's garbage
collected. To make the closing business easier, some of the methods let you
specify a C<:close> argument, you can also use the
L«C<will leave> trait|/language/phasers#index-entry-will_trait», or the
C<does auto-close> trait provided by the
L«C<Trait::IO>|https://raku.land/zef:raku-community-modules/Trait::IO» module.


A low-level explanation of Raku containers


Containers


What are contexts and how to switch into them


Contexts and contextualizers


Statements used to control the flow of execution


Control flow


An example using the enum type


Enumeration


Using exceptions in Raku


Exceptions


Functions and functional programming in Raku


Functions


Parsing and interpreting text


Grammars


Working with associative arrays/dictionaries/hashes


Hashes and maps


Positional data constructs


Lists, sequences, and arrays


Introspection and the Raku object system


Metaobject protocol (MOP)


Call into dynamic libraries that follow the C calling convention


Native calling interface


Using the types the compiler and hardware make available to you


Raku native types


How the different newline characters are handled, and how to change the behavior


Newline handling in Raku


Numeric types available in Raku


Numerics


Object orientation in Raku


Object orientation


Common Raku infixes, prefixes, postfixes, and more!


Operators


Organizing and referencing namespaced program elements


Packages


Measuring and improving runtime or compile-time performance


Performance


Program execution phases and corresponding phaser blocks


Phasers


Special modules that define certain aspects of the behavior of the code


Pragmas


Writing strings and word lists, in Raku


Quoting constructs


Pattern matching against strings


Regexes


Unordered collections of unique and weighted objects in Raku


Sets, bags, and mixes


A guide to signatures in Raku


Signature literals


Prefixes that alter the behavior of a statement or a set of them


Statement prefixes


How Raku deals with data structures and what we can expect from them


Data structures


Accessing data structure elements by index or key


Subscripts


General rules of Raku syntax


Syntax


Working with the underlying operating system and running applications


System interaction


Processing date and time in Raku


Date and time functions


Compile-time specification of behavior made easy


Traits


Unicode symbols and their ASCII equivalents


Unicode versus ASCII symbols


Unicode support in Raku


Unicode


Variables in Raku


Variables


Routines not defined within any class or role.


Independent routines


Correctly use Raku IO


Input/Output the definitive guide


Learning Raku from Haskell, in a nutshell


Haskell and Raku are I<very> different languages. This is obvious.
However, that does not mean there are not similarities or shared ideas!
This page attempts to get a Haskell user up and running with Raku. The
Haskell user may find that they need not abandon all of their Haskelly
thoughts while scripting in Raku.


Note that this should not be mistaken for a beginner tutorial or overview of
Raku; it is intended as a technical reference for Raku learners with a
strong Haskell background.


In Haskell, you have type level programming and then value level programming.


    =begin code :lang<haskell>
    plusTwo :: Integer -> Integer   -- Types
    plusTwo x = x + 2               -- Values
    =end code


You do not mix types and values in Haskell like the below


    =begin code :lang<haskell>
    plusTwo 2          -- This is valid
    plusTwo Integer    -- This is not valid
    =end code


In Raku, types (AKA type objects) live on the same level as values


    =begin code
    sub plus-two(Int $x --> Int) { $x + 2 }

    plus-two(2);    # This is valid
    plus-two(Int);  # This is valid
    =end code


I will illustrate this unique aspect of Raku with one more example:


    =begin code
    multi is-string(Str $ --> True) {}
    multi is-string(Any $ --> False) {}

    is-string('hello');    #True
    is-string(4);          #False
    =end code


In Haskell, you have a Maybe type that allows you to forgo the worry of null types.
Let's say you have a hypothetical function that parses a String to an Integer:


    =begin code :lang<haskell>
    parseInt :: String -> Maybe Integer

    case parseInt myString of
      Just x  -> x
      Nothing -> 0
    =end code


In Raku, since type objects coexist with regular objects, we have the concept
of Defined and Undefined objects. Plain type objects are undefined while
instantiated objects are defined.


    =begin code
    sub parse-int(Str $s --> Int) { ... }

    my $string = {...};
    given parse-int($string) {
      when Int:D { $_ }
      when Int:U { 0 }
    }
    =end code


So in Raku we have type constraints that indicate the definedness of a type. These are


    =begin code
    Int:D; # This is a defined Int.
    Int:U; # This is an undefined Int, AKA a type object
    Int:_; # This is either defined or undefined.
    =end code


If we wanted to be explicit in the above example (probably a good idea), we could add
the C<:_> constraint on the return type. This would let the user know that they should account
for both defined and undefined return values. We could also use other methods and constructs
that specifically test for definedness.


    =begin code
    sub parse-int(Str $s --> Int:_) { ... }

    # One way to do it
    my $string = {...};
    given parse-int($string) {
      when Int:D { $_ }
      when Int:U { 0 }
    }

    # Another way to do it
    my Int $number = parse-int($string);
    if $number.defined { $number } else { 0 }


    # A better way
    with parse-int($string) { $_ } else { 0 }

    # With the defined-or operator
    parse-int($string) // 0
    =end code


The C<with> operator that you see above is like C<if>, except it explicitly tests for definedness and then
passes the result to the following block. Similarly, C<without> tests that the object is undefined and also
passes the result to the following block.


For more natural control flow with undefined and defined types, Raku introduces C<andthen> and C<orelse>.


    =begin code
    sub parse-int(Str $s --> Int:_) { ... }

    my $string = {...};
    my $result = parse-int($string) orelse 0;

    sub hello() { say 'hi' }
    hello() andthen say 'bye';
    =end code


comment

=begin comment
TODO: include a better example for andthen that makes sense. Maybe using promise objects?
=end comment


So in practice, Raku does not have the concept of a null type, but rather of
defined or undefined types.


Raku is fundamentally an object oriented language. However, it also gives you
the freedom to write in virtually any paradigm you wish. If you only want to
pure functions that take an object and return a new object, you can certainly do
so.


    =begin code :lang<haskell>
    data Point = Point x y

    moveUp :: Point -> Point
    moveUp (Point x y) = Point x (y + 1)
    =end code


    =begin code
    class Point { has $.x; has $.y; }

    sub move-up(Point $p --> Point) {
      Point.new(x => $p.x, y => $p.y + 1)
    }
    =end code


The code illustrated above is an example of a
L<Product Type|https://wiki.haskell.org/Algebraic_data_type>. If instead you'd like to
write a Sum Type, there is not an exact equivalent in Raku. The closest thing
would be an L<Enum|/language/typesystem#enum>.


    =begin code :lang<haskell>
    data Animal = Dog | Cat | Bird | Horse

    testAnimal :: Animal -> String
    testAnimal Dog   = "Woof"
    testAnimal Horse = "Neigh"
    =end code


Although it does not fit the same exact use cases, it can be used in putting
constraints on types.


    =begin code
    enum Animal < Dog Cat Bird Horse >;

    proto test-animal( Animal        ) {*}
    multi test-animal( Dog           ) { 'Woof' }
    multi test-animal( Animal::Horse ) { 'Neigh'  }   # more explicit

    say test-animal Animal::Dog;                          # more explicit
    say test-animal Horse;
    =end code


In Haskell, you can alias an existing type to simply increase clarity of intent
and re-use existing types.


    =begin code :lang<haskell>
    type Name = String

    fullName :: Name -> Name -> Name
    fullName first last = first ++ last
    =end code


The equivalent in Raku is the following.


    =begin code
    my constant Name = Str;

    sub full-name ( Name \first, Name \last --> Name ) { first ~ last }
    =end code


It should be noted that in Raku, one can also create a subset of an existing type.


    =begin code
    subset Name of Str where *.chars < 20;

    sub full-name(Name $first, Name $last) {
      $first ~ $last
    }

    full-name("12345678901234567890111", "Smith") # This does not compile, as the first parameter
                                                  # doesn't fit the Name type
    =end code


=begin comment
explain how Raku roles compare to Haskell typeclasses
=end comment


How do I do what I used to do? (Raku in a nutshell)


Perl to Raku guide - in a nutshell


How do I do what I used to do?


Perl to Raku guide - overview


Builtin functions in Perl to Raku


Perl to Raku guide - functions


Operators in Perl to Raku: equivalencies and variations


Perl to Raku guide - operators


Syntactic differences between Perl and Raku


Perl to Raku guide - syntax


A comparison of special variables in Perl and Raku


Perl to Raku guide - special variables


Learning Raku from Node.js, in a nutshell


JavaScript (Node.js) to Raku - nutshell


Learning Raku from Python, in a nutshell


Python to Raku - nutshell


Learning Raku from Ruby, in a nutshell: what do I already know?


Ruby to Raku - nutshell


Haskell to Raku - nutshell


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


See Also