TITLE

SUBTITLE

head

The C<REPL> is an interactive Raku prompt. Each line of code you enter in the C<REPL>
is executed, and if no output was generated, the value returned
by the expression is output.


B<Note>: Running code in the C<REPL> is not equivalent to saving the code in a file and
running that. Each line introduces a new scope which can confuse code that has multiple
lines. See C<sub repl()> below for a way to target a REPL inside a larger script.


If invoked from the command line with  C<raku --repl-mode=non-interactive>, no history or prompts
are printed, and the code is not executed until you close input (on Linux, for example, you can pipe
the code to it or press C<Control-d>.


code

This routine allows you to embed a REPL inside a larger script and have access to all
the variables in context.


See L<sub repl()|/type/independent-routines#sub_repl> in Independent Routines for more
information.


See L<ENVIRONMENT Variables|/programs/03-environment-variables#Environment_variables_used_by_the_raku_command_line>.


In a fresh install, there is no command history. Running the C<REPL> in this mode will
prompt you to install one of the various modules that provide this support. If enabled,
you can use the arrow keys to scroll through previous commands and use standard terminal
shortcuts for editing. There are currently four options:


item

This requires an installation of the C<Readline> development library.


An alternative for UNIX-like systems is to install C<rlwrap>. This can
be done on Debian-ish systems by running:


root

A tutorial about creating and using classes in Raku


Classes and objects


How and when Raku modules are compiled, where they are stored, and how to access them in compiled form.


CompUnits and where to find them


Concurrency and asynchronous programming


Concurrency


Creating your own CLI in Raku


Command line interface


An introduction to grammars


Grammar tutorial


File-related operations


Input/Output


Programs running other programs and communicating with them


Inter-process communication


Functionalities available for visiting all items in a complex data structure


Iterating


Different mathematical paradigms and how they are implemented in this language


Doing math with Raku


Creating module packages for code reuse


Module packages


Core modules that may be useful to module authors


Core modules


What can help you write/test/improve your module(s)


Module development utilities


How to create, use, and distribute Raku modules


Modules


A short tutorial on how to declare operators and create new ones.


Creating operators


Some tips on regexes and grammars


Regexes: best practices and gotchas


Input methods for unicode characters in terminals, the shell, and editors


Entering unicode characters


Read-eval-print loop


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

REPL


Unordered collections of unique and weighted objects in Raku


In a nutshell, these classes hold, in general, unordered collections of
objects, much like an L<object hash|/type/Hash>.
The L<C<QuantHash>|/type/QuantHash> role is the role that is implemented by all
of these classes: therefore they are also referenced as L<C<QuantHash>|/type/QuantHash>es.


Sets only consider if objects in the collection are present or not, bags can
hold several objects of the same kind, and mixes also allow fractional (and
negative) weights. The regular versions are immutable, the I<-Hash> versions
are mutable.


Let's elaborate on that. If you want to collect objects in a container but
you do not care about the order of these objects, Raku provides these
I<unordered> collection types.  Being unordered, these containers can be more
efficient than L<C<List>|/type/List>s or L<C<Array>|/type/Array>s for looking up
elements or dealing with repeated items.


On the other hand, if you want to get the contained objects (elements)
B<without duplicates> and you only care I<whether> an element is in the
collection or not, you can use a L<C<Set>|/type/Set> or L<C<SetHash>|/type/SetHash>.


If you want to get rid of duplicates but still preserve order, take a look
at the L<unique|/routine/unique> routine for L<C<List>|/type/List>.


comment

=begin comment
=defn  Set or SetHash
Collection of distinct objects
=end comment


If you want to keep track of the B<number of times each object appeared>,
you can use a L<C<Bag>|/type/Bag> or L<C<BagHash>|/type/BagHash>. In these
L<C<Baggy>|/type/Baggy> containers each element has a weight (an unsigned integer)
indicating the number of times the same object has been included in the
collection.


The types L<C<Mix>|/type/Mix> and L<C<MixHash>|/type/MixHash> are similar
to L<C<Bag>|/type/Bag> and L<C<BagHash>|/type/BagHash>, but they also
allow B<fractional and negative weights>.


For one thing, as far as they are concerned, identical objects refer to the
same element – where identity is determined using the L<WHICH|/routine/WHICH>
method (i.e. the same way that the L<===|/routine/===> operator checks identity). For value
types like L<C<Str>|/type/Str>, this means having the same value; for reference types
like L<C<Array>|/type/Array>, it means referring to the same object instance.


Secondly, they provide a Hash-like interface where the actual elements of
the collection (which can be objects of any type) are the 'keys', and the
associated weights are the 'values':


table_head

    -------------     ----------------------      ---------------------


table_row

table

There are several infix operators devoted to performing common operations
using L<C<QuantHash>|/type/QuantHash> semantics.  Since that is a mouthful, these operators
are usually referred to as "set operators".


This does B<not> mean that the parameters of these operators must always be
L<C<Set>|/type/Set>, or even a more generic L<C<QuantHash>|/type/QuantHash>.  It just means that the logic
that is applied to the operators is the logic of
L<Set Theory|https://en.wikipedia.org/wiki/Set_theory>.


These infixes can be written using the Unicode character that represents the
function (like C<∈> or C<∪>), or with an equivalent ASCII version (like
C<(elem)> or C<(|)>).


So explicitly using L<C<Set>|/type/Set> (or L<C<Bag>|/type/Bag> or L<C<Mix>|/type/Mix>) objects with these infixes is
unnecessary.  All set operators work with all possible arguments, including
(since 6.d) those that are not explicitly set-like.  If necessary, a coercion
will take place internally: but in many cases that is not actually needed.


However, if a L<C<Bag>|/type/Bag> or L<C<Mix>|/type/Mix> is one of the parameters to these set operators,
then the semantics will be upgraded to that type (where L<C<Mix>|/type/Mix> supersedes
L<C<Bag>|/type/Bag> if both types happen to be used).


Set operators that return L<C<Bool>|/type/Bool>


Returns C<True> if C<$a> is an B<element> of C<$b>, else C<False>.
L<More information|/language/operators#infix_(elem),_infix_∈>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Element_(mathematics)#Notation_and_terminology>.


Returns C<True> if C<$a> is B<not> an element of C<$b>, else C<False>.
L<More information|/language/operators#infix_∉>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Element_(mathematics)#Notation_and_terminology>.


Returns C<True> if C<$a> B<contains> C<$b> as an element, else C<False>.
L<More information|/language/operators#infix_(cont),_infix_∋>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Element_(mathematics)#Notation_and_terminology>.


Returns C<True> if C<$a> does B<not> contain C<$b>, else C<False>.
L<More information|/language/operators#infix_∌>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Element_(mathematics)#Notation_and_terminology>.


Returns C<True> if C<$a> is a B<subset> or is equal to C<$b>, else C<False>.
L<<More information|/language/operators#infix_(<=),_infix_⊆>>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> is B<not> a B<subset> nor equal to C<$b>, else C<False>.
L<More information|/language/operators#infix_⊈>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> is a B<strict subset> of C<$b>, else C<False>.
L<<More information|/language/operators#infix_(<),_infix_⊂>>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> is B<not> a B<strict subset> of C<$b>, else C<False>.
L<More information|/language/operators#infix_⊄>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> is a B<superset> of or equal to C<$b>, else C<False>.
L«More information|/language/operators#infix_(>=),_infix_⊇»,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> is B<not> a B<superset> nor equal to C<$b>, else C<False>.
L<More information|/language/operators#infix_⊉>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> is a B<strict superset> of C<$b>, else C<False>.
L«More information|/language/operators#infix_(>),_infix_⊃»,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> is B<not> a B<strict superset> of C<$b>, else C<False>.
L<More information|/language/operators#infix_⊅>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Subset#Definitions>.


Returns C<True> if C<$a> and C<$b> are B<identical>, else C<False>.
L<More information|/language/operators#infix_(==),_infix_≡>,
L<Wikipedia definition|https://en.wikipedia.org/wiki/Equality_(mathematics)#Equality_in_set_theory>.


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


Correctly use Raku IO


Input/Output the definitive guide


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


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


Sets, bags, and mixes


A I<regular expression> is a sequence of characters that defines a certain text
pattern, typically one that one wishes to find in some large body of text.


In theoretical computer science and formal language theory, regular expressions
are used to describe so-called
L<I<regular languages>|https://en.wikipedia.org/wiki/Regular_language>. Since
their inception in the 1950's, practical implementations of regular expressions,
for instance in the text search and replace functions of text editors, have outgrown
their strict scientific definition. In acknowledgement of this, and in an attempt
to disambiguate, a regular expression in Raku is normally referred to as a
L<C<Regex>|/type/Regex> (from: I<reg>ular I<ex>pression), a term that is also in common use in
other programming languages.


In Raku, regexes are written in a
L<I<domain-specific language>|https://en.wikipedia.org/wiki/Domain-specific_language>,
i.e. a sublanguage or I<slang>. This page describes this language, and explains how
regexes can be used to search for text patterns in strings in a process called
I<pattern matching>.


X<Lexical conventions|Syntax,/ /;Syntax,rx;Syntax,m>


Fundamentally, Raku regexes are very much like subroutines: both are code
objects, and just as you can have anonymous subs and named subs, you can have
anonymous and named regexes.


A regex, whether anonymous or named, is represented by a L<C<Regex>|/type/Regex>
object. Yet, the syntax for constructing anonymous and named L<C<Regex>|/type/Regex> objects
differs. We will therefore discuss them in turn.


An anonymous regex may be constructed in one of the following ways:


rx/pattern/;          # an anonymous Regex object; 'rx' stands for 'regex'
/pattern/;            # an anonymous Regex object; shorthand for 'rx/.../'


regex { pattern };    # keyword-declared anonymous regex; this form is
                      # intended for defining named regexes and is discussed
                      # in that context in the next section


The C<rx/ /> form has two advantages over the bare shorthand form C</ />.


Firstly, it enables the use of delimiters other than the slash, which may be
used to improve the readability of the regex definition:


rx{ '/tmp/'.* };      # the use of curly braces as delimiters makes this first
rx/ '/tmp/'.* /;      # definition somewhat easier on the eyes than the second


Although the choice is vast, not every character may be chosen as an alternative
regex delimiter:


Secondly, the C<rx> form allows you to insert
L<regex adverbs|/language/regexes#Regex_adverbs> between C<rx> and the
opening delimiter to modify the definition of the entire regex.  This is equivalent to
inserting the adverb at the beginning of the regex, but may be clearer:


rx:r:s/pattern/;            # :r (:ratchet) and :s (:sigspace) adverbs, defining
                            # a ratcheting regex in which whitespace is significant
rx/:r:s pattern/;           # Same, but possibly less readable


Although anonymous regexes are not, as such, I<named>, they may effectively be
given a name by putting them inside a named variable, after which they can be
referenced, both outside of an embedding regex and from within an embedding
regex by means of L<interpolation|/language/regexes#Regex_interpolation>:


my $regex = / R \w+ /;
say "Zen Buddhists like Raku too" ~~ $regex; # OUTPUT: «｢Raku｣␤»


my $regex = /pottery/;
"Japanese pottery rocks!" ~~ / <$regex> /;  # Interpolation of $regex into /.../
say $/;                                     # OUTPUT: «｢pottery｣␤»


A named regex may be constructed using the C<regex> declarator as follows:


regex R { pattern };        # a named Regex object, named 'R'


Unlike with the C<rx> form, you cannot chose your preferred delimiter: curly
braces are mandatory. In this regard it should be noted that the definition of a
named regex using the C<regex> form is syntactically similar to the definition
of a subroutine:


my sub   S { /pattern/ };   # definition of Sub object (returning a Regex)
my regex R {  pattern  };   # definition of Regex object


which emphasizes the fact that a L<C<Regex>|/type/Regex> object represents code
rather than data:


=begin code :preamble<my sub   S { /pattern/ }; my regex R {  pattern  };>
&S ~~ Code;                 # OUTPUT: «True␤»

&R ~~ Code;                 # OUTPUT: «True␤»
&R ~~ Method;               # OUTPUT: «True␤»   (A Regex is really a Method!)
=end code


Also unlike with the C<rx> form for defining an anonymous regex, the definition
of a named regex using the C<regex> keyword does not allow for adverbs to be
inserted before the opening delimiter. Instead, adverbs that are to modify the
entire regex pattern may be included first thing within the curly braces:


regex R { :i pattern };     # :i (:ignorecase), renders pattern case insensitive


Alternatively, by way of shorthand, it is also possible (and recommended) to use
the C<rule> and C<token> variants of the C<regex> declarator for defining a
L<C<Regex>|/type/Regex> when the C<:ratchet> and C<:sigspace> adverbs are of interest:


Named regexes may be used as building blocks for other regexes, as they are
methods that may called from within other regexes using the C«<regex-name>»
syntax. When they are used this way, they are often referred to as I<subrules>;
see for more details on their use L<here|/language/regexes#Subrules>.
L<C<Grammar>|/type/Grammar>s are the natural habitat of subrules, but many common
predefined character classes are also implemented as named regexes.


Regex readability: whitespace and comments


Whitespace in regexes is ignored unless the
L<C<:sigspace>|/language/regexes#Sigspace> adverb is used to make whitespace
syntactically significant.


In addition to whitespace, comments may be used inside of regexes to improve
their comprehensibility just as in code in general. This is true for both
L<single line comments|/language/syntax#Single-line_comments> and
L<multi line/embedded comments|/language/syntax#Multi-line_/_embedded_comments>:


my $regex =  rx/ \d ** 4            #`(match the year YYYY)
                 '-'
                 \d ** 2            # ...the month MM
                 '-'
                 \d ** 2 /;         # ...and the day DD


say '2015-12-25'.match($regex);     # OUTPUT: «｢2015-12-25｣␤»


There are a variety of ways to match a string against a regex. Irrespective of
the syntax chosen, a successful match results in a L<C<Match>|/type/Match>
object. In case the match is unsuccessful, the result is L<C<Nil>|/type/Nil>. In
either case, the result of the match operation is available via the special
match variable L<C<$/>|/syntax/$$SOLIDUS>.


The most common ways to match a string against an anonymous regex C</pattern/> or
against a named regex C<R> include the following:


REPL

Overview

Trap

non-interactive mode

sub repl()

ENVIRONMENT Variables

Get command line history

See Also