Forem: Elizabeth Mattijsen

Definitely How What Where, Who?

Elizabeth Mattijsen — Tue, 24 Feb 2026 13:29:22 +0000

This is part thirteen in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the various introspection methods that you can use on objects in the Raku Programming Language. Note that in some documentation these methods are also referred to as Metamethods.

Turtles All The Way Down

In Raku everything is an object, or can be thought of as an object. An object is an instantiation of a class (usually made by calling the new method on it). A class is represented by a so-called "type object". Such a type object in turn is an instantation of a so-called meta class. And these meta classes are themselves built out of more primitive representations.

Going this deep would most definitely be out of scope for these blog posts. But yours truly does intend to go there at some point in the future.

WHAT

The WHAT method returns the type object of the given invocant. Not much else to tell about it really.

say 42.WHAT;     # (Int)
say "foo".WHAT;  # (Str)
say now.WHAT;    # (Instant)

HOW

The HOW method returns the meta-object of the class of the given invocant. The HOW (b)acronym stands for "Higher Order Workings". It allows one to introspect the class of the invocant.

say 42.HOW.name(42);        # Int
say "foo".HOW.name("foo");  # Str
say now.HOW.name(now);      # Instant

Note that the invocant of the HOW method needs to be repeated in the introspection method's call as the first argument. Why? Well, this is really to be possibly compatible with future versions of Raku.

Since one is usually only interested in the introspection aspect of HOW, a shortcut method invocation was created that allows one to directly call the introspection method without needing to repeat oneself: .^:

say 42.^name;     # Int
say "foo".^name;  # Str
say now.^name;    # Instant

Some other common introspection methods are mro (showing the base classes of the class of the value) and methods (which returns the method objects of the methods that can be called on the value):

say 42.^mro;           # ((Int) (Cool) (Any) (Mu))
say 42.^methods.sort;  # (ACCEPTS Bool Bridge Capture Complex...

Note that these meta-classes are classes themselves, so can have meta-methods on them called as well:

say 42.HOW.^name;  # Perl6::Metamodel::ClassHOW

Yeah, there's still some legacy code that will need renaming under the hood!

WHERE

The WHERE method returns the memory address of the invocant. It is of limited use in the Rakudo implementation as the memory location of an object is not guaranteed to be constant. As such, it is intended for (core) debugging only.

say 42.WHERE;  # 2912024602280 (or some other number)

VAR

In the previous blog post the Scalar object was described. But the Scalar objects are nearly invisible. How can one obtain a Scalar object from a given variable? And find out its name from that?

The "secret" to that is the VAR method.

my $a;
say $a.VAR.^name;  # Scalar

Each Scalar object provides at least these introspection methods: of, name, default and dynamic.

my Int $a is default(42) = 666;
say $a;              # 666
say $a.VAR.of;       # (Int)
say $a.VAR.name;     # $a
say $a.VAR.default;  # 42
say $a.VAR.dynamic;  # False

The of method returns the constraint that needs to be fulfilled in order to be able to assign to the variable. The name method returns the name of the variable. The default method returns the default value (Any if none is specified).

The dynamic method returns True or False whether the variable is visible for dynamic variable lookups. This usually only returns True for variables with the * twigil.

WHO

The WHO method (for "who lives here?) is actually a bit of a misnomer. It should probably have been called OUR because it returns the Stash of the type object of the invocant. And a stash is an object that does the Associative role, and as such can be accessed as if it were a Hash. And the stash of a type object is the same namespace as our inside that package.

So for instance if you would like to know all classes that live in the IO package:

say IO.WHO.keys.sort;  # (ArgFiles CatHandle Handle Notification Path Pipe Socket Spec Special)

Of course, you would know them more by their complete names such as IO::ArgFiles, IO::CatHandle, IO::Handle, etc. In fact the :: delimiter is shortcut for using WHO:

say IO.WHO<Handle>;  # (Handle)
say IO::Handle;      # (Handle)

And that goes even further: foo:: is just short for foo.WHO:

say IO::.keys.sort;  # (ArgFiles CatHandle Handle Notification Path Pipe Socket Spec Special)

A little closer to home: how would that look in a package that you define yourself and have an our scoped variable in there:

package A {
    our $foo = 42;
}
say A.WHO<$foo>;  # 42
say A::<$foo>;    # 42
say $A::foo;      # 42

The careful reader will have noticed that package was used in the example. A very simple reason: class, role, grammar are all just packages with different HOWs. And WHO doesn't care why kind of package it is.

REPR

The REPR method returns the name of the memory representation of the class of the invocant. For most of the objects this is "P6opaque".

This is basically the representation used by class and its attribute specifications.

The NativeCall module provides a number or alternate memory representations, such as CStruct, CPointer and Cunion. Native arrays also have a different representation (VMArray).

say 42.REPR;  # P6opaque
my int @a;
say @a.REPR;  # VMArray

When a class is defined, it gets the P6opaque representation by default.

class Foo { }
say Foo.REPR;  # P6opaque

Unless one is doing very deep core-ish work, how an object is represented in memory should not be of concern to you.

DEFINITE

The DEFINITE method returns either True or False depending on whether the invocant has a concrete representation. This is almost always the same as calling the defined method. But in some cases it makes more sense in Raku to return the opposite with the defined method.

An example of this is the Failure class:

say Failure.new.DEFINITE;  # True
say Failure.new.defined;   # False

In general the defined method should be used. The DEFINITE method is intended to be used in very low-level (core) code. It's not all uppercase for nothing!

The reason Failure.new.defined always returns False is to make it compatible with with.

Macroish

All of the introspection "metamethods" described in this blog post are actually parsed as macros directly generating low-level execution opcodes. This is really necessary in some cases (as otherwise information can be lost), and in other cases it's just for performance.

This doesn't mean that it's not possible to call this introspection functionality as a method: you can. For example:

my $a;
say "macro: "  ~ $a.VAR.name;      # macro: $a
say "method: " ~ $a."VAR"().name;  # method: $a

Furthermore for consistency, the same functionality of these methods is also available as subroutines.

my $b;
say "sub: " ~ VAR($b).name;  # sub: $b

So if you're more at home in imperative programming, you can do that as well!

Conclusion

This concludes the thirteenth episode of cases of UPPER language elements in the Raku Programming Language, the sixth episode discussing interface methods.

In this episode the following macro-like introspection methods were discussed (in alphabetical order): DEFINITE, HOW, REPR, VAR, WHAT, WHERE, WHO.

Stay tuned for the next episode!

Raku Resolutions #3

Elizabeth Mattijsen — Sun, 22 Feb 2026 14:23:48 +0000

This is a third follow-up on Raku Resolutions series.

The third meeting was held on 21 February 2026 at 19:00 UTC. Apart from 3 Raku Steering Council members, only 1 other person attended. In the end, 7 issues were discussed within the allotted time (1 hour).

Separate Community Resource page

After some discussion, it became clear that this issue basically has gone stale in light of the new raku.org site. Richard Hainsworth will create a new issue, after which this one can be closed.

What makes `unit` be too late?

After some discussion it was agreed that from a language design point of view, it shouldn't really matter when the unit occurs in the code, as long as there's only one of them. And that the rest of the source would be considered to be part of that scope.

It was agreed that the documentation will describe this future state with the caveat that this is currently not yet the case. Eric Forste agreed to make a PR accordingly, after which the issue can be closed.

The point of being able to specify an EXPORT sub before a unit would be technically correct, but not very useful in practice as an EXPORT sub usually needs to refer to objects/classes that have already been defined in the code (and thus should logically be positioned after the scope).

Errors indexing past the end of a `List`

After some discussion it was decided that the current behaviour of returning Nil for List elements beyond the end is correct. And that returning a Failure for negative index values is the most consistent behaviour, especially in light of Array doing that as well. So the issue could be closed.

Some useful math/statistics functions are missing

Consensus was that it would be nice to have all of these math / statistics methods, but that these should live in module land for the foreseeable future. So the issue could be closed.

There's a huge PR/issue deficit in the Rakudo repo

It was recognized that there are indeed quite a few open issues in Rakudo (although much less than there have been in the past). However, there will always be open issues. And with the current size of the core team, the number of issues will not significantly reduce in the future (with the current rate of new issues coming in).

So it was decided to close the issue as "unresolvable".

New named parameters to `.classify`

It was decided that the issue has gone a bit stale, and thus ask the OP (Original Poster) whether this should stay open, especially since it was suggested that .classify / .categorize maybe should need an overhaul (at least internally).

Need a substitute for Perl 5 `die` with newline for raising end-user errors?

After explaining the esoteric rule in Perl 5 with regards to die with a message with and without a new line, it was agreed that it would be nice to have such a feature. Especially since at least 2 of the attendees had been using a note $message; exit 1 sequence to achieve just that. Disadvantage to this is that such a sequence can not be caught by a CATCH.

After some discussion, a :no-backtrace named argument to die() was suggested, and that the issue could be closed if a Pull Requst had been created for this. This has since then been implemented in #6076, so the issue was closed.

Next meeting

The next meeting will be held at 7 March 2026 at 19:00 UTC (20:00 CET, 14:00 EST, 11:00 PST, 04:00 JST (22 Jan), 06:00 AEST (22 Jan)), and again at a one hour maximum. If not all of these issues have been resolved, they will be moved to a future meeting.

Since Jitsi is still working out so far, the next one will be held at the same URL: https://meet.jit.si/SpecificRosesEstablishAllegedly. The reason Jitsi was selected, is that it has proven to be working with minimal hassle for at least the Raku Steering Council meetings. As the only thing you need to be able to attend, is a modern browser, a camera, and a microphone. No further installation required.

A new set of issues has been selected by yours truly (in issue number order, oldest first):

Preparation

Any Raku Community member is welcome to these meetings. Do you consider yourself a Raku Community member? You're welcome. It's as simple as that.

But please make sure you have looked at the issues that will be discussed before attending the meeting. And if you already have any comments to make on these issues, make them with the issue beforehand.

The original contributors to these issues will also be notified (unless they muted themselves from these issues). We hope that they also will be able to attend.

Small steps

If you consider yourself a Raku Community member, please try to attend! If anything, it will allow you to put faces to the names that you may be familiar with.

Hope to see you there!

Store Proxy Fetch

Elizabeth Mattijsen — Fri, 20 Feb 2026 11:39:50 +0000

This is part twelve in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the various aspects of containers in the Raku Programming Language.

Containers and binding

This may come as a shock to some, but Raku really only knows about binding (:=) values. Assignment is syntactic sugar.

What?

Most of the scalar variables that you see in Raku, are really objects that have an attribute to which the value is bound when you assign to the variable. These objects are called Scalar containers, or just short "containers".

In short: assignment in Raku is binding to an attribute in a Scalar object. Grokking how containers work in Raku (as opposed to many other programming languages) is one of the rites of passage to becoming an experienced and efficient developer in Raku. It sure was a rite of passage for yours truly!

In a simplified representation (almost pseudocode) one can think of these Scalar objects like this:

class Scalar {
    has $!value;
    method STORE($new-value) {
        $!value := $new-value
    }
    method FETCH() {
        $!value
    }
}

And an assignment such as:

my $a;
$a = 42;

can be thought of as:

my $a := Scalar.new;
$a.STORE(42);

and showing the value of a variable (as in say $a), can be thought of as:

say $a.FETCH;

In reality it's of course slightly more complicated, because there are such things as type constraints that can exist on a variable (such as my Int $a). And variables may have a default value (as in my $a is default(42)).

This type of information is kept in a so-called "container descriptor", which is considered to be an implementation detail (as in: don't depend on its functionality directly, the interface to it might change at any time).

Many shortcuts are made in implementing this, in the interest of performance. Because assignments are one of the very basic operations in a programming language. And you want those to be fast!

As a mental model, this is very useful for understanding quite a few constructs in Raku.

Return values

In Raku any value returned at the end of a block (or with the return statement) are de-containerized by default. This means that something like this:

my $a = 42;
sub foo() { $a }
foo() = 666;  # Cannot modify an immutable Int (42)

will not work. What if you could return the container from a block? Then you could just assign to it! There are indeed two easy ways to return something with the container intact: the is rw trait:

my $a = 42;
sub foo() is rw { $a }
foo() = 666;
say $a;  # 666

Alternately, one can use the return-rw statement.

my $a = 42;
sub foo() { return-rw $a }
foo() = 666;
say $a;  # 666

This feature is for instance used if you want to assign to an array element. In part 9 of this series it was shown that the AT-POS method is what is being called by postcircumfix [ ]. In the core, both the postcircumfix [ ] operator as well as the underlying AT-POS method have this trait set for performance (as the return-rw statement has slightly more overhead).

Binding to containers

If an array is initialized with values, it will create containers for each element and put the right value in the right place. So you cannot only fetch the values from there, but you can also assign to these containers. And it is also possible to bind such a container to another variable.

Binding to containers allows for features in Raku that are considered "magic" by some, and maybe "too magic" by others. They are part of common idioms in the Raku Programming Language.

For instance: incrementing all values in an array:

my @a = 1,2,3,4,5;
$_++ for @a;
say @a;  # [2 3 4 5 6]

The topic variable $_ binds to the elements of the array in a for loop. So in each iteration it actually represents the container at that location and can thus be incremented.

People coming from other languages may think that $_ is a "reference" (or "pointer") to the actual memory location of the element in the array. This notion is incorrect in Raku. The topic variable $_ is bound to the container of each element. The container object itself is completely agnostic as to where it lives. It's just a simple object that knows how to FETCH and STORE.

Slices to arrays also return containers. For instance to increment only the first and last element in an array without knowing its size:

my @a = 1,2,3,4,5;
$_++ for @a[0, *-1];
say @a;  # [2 2 3 4 6]

The slice [0, *-1] produces 2 containers (one for the first element (0) and one for the last (*-1). Only these containers get incremented, thus giving the expected result.

The same logic applies to the values in hashes.

my %h = a => 42, b => 666;
$_++ for %h.values;
say %h;  # {a => 43, b => 667}

But binding containers can also be done directly in your code. A contrived example:

my $a = 42;
my $b := $a;
$b = 666;
say $a;  # 666

Note that by assigning to $b, you're assiging to the container that lives in $a. Because the binding of $b to $a effectively aliased the container in $a.

Special containers

In Raku it is possible to assign to elements in an array that do not exist yet.

my @a;
@a[3] = 42;
say @a;  # [(Any) (Any) (Any) 42]

So there's no container yet the element at index 3. Yet it is possible to assign to it! How does that work?

The secret is really in the "container descriptor". So let's refine our pseudocode representation of the Scalar class:

class Scalar {
    has $!descriptor;
    has $!value;
    method STORE($value) {
        $!value := $!descriptor.process($value);
    }
    method FETCH() {
        $!value
    }
}

Note that storing a value has now become a little more complicated ($!descriptor.process($value) rather than just $!value). So the descriptor object's process method takes the value, does what it needs to do with it, and then returns it so that it can be bound to the attribute.

This descriptor object is typically responsible for remembering the name of the variable, the default type, perform type checking and keep a default value of a container. And any additional logic that is needed.

There are many different types of container descriptor classes in the Rakudo implementation, all starting with the ContainerDescriptor:: name. And all are considered to be implementation detail.

For instance, when an AT-POS method is called on a non-existing element in an array, a container with a special type of descriptor is created that "knows" to which Array it belongs, and at which index it should be stored. The same is true for the descriptor of the container returned by AT-KEY (as seen in part 10) which knows in which Hash it should store when assigned to, and what key should be used.

It's this special behaviour that allows arrays and hashes to really just DWIM.

Action at a distance

These special descriptors of containers for arrays and hashes also introduce an action-at-a-distance feature that you may or may not like.

my @a;
my $b := @a[3];
say @a;  # []
$b = 42;
say @a;  # [(Any) (Any) (Any) 42]

Note that the element in the array was not initialized after the binding, but only after a value was assigned to $b. This behaviour was specifically implemented this way to prevent accidental auto-vivification. For example:

my %h;
say %h<a><b>:exists;  # False
say %h;               # {}
%h<a><b> = 42;
say %h;               # {a => {b => 42}}

So even though %h<a> is considered to be an Associative because of the <b>, the :exists test will not create a Hash in %h<a>. Only after a value has been assigned does %h<a> and %h<a><b> actually spring to life.

Proxy

This rather lengthy introduction / diversion was to make you aware of some of the underlying mechanics of containers. Because Raku supplies a full customizable class that allows you to create your own container logic: Proxy. And understanding what containers are about is helpful when working with that class.

Creation of such a container is quite easy: all you need to supply are a method for fetching the value, and a method for storing a value (very similar to the pseudocode representation at the start of this blog post). This is done with the named arguments FETCH and STORE. Creation of a Proxy object is usually done inside a subroutine for convenience. A contrived example:

sub answer is rw {
    my $value = 42;
    Proxy.new(
      FETCH => method () {
          $value
      },
      STORE => method ($new) {
          say "storing $new";
          $value = $new;
      }
    )
}
my $a := answer;
say $a;    # 42
$a = 666;  # storing 666
say $a;    # 666

The careful reader will have noticed that the is rw attribute needs to be specified on the subroutine, otherwise the Proxy would be de-containerized on return. And that the result of calling the answer subroutine was bound (:=) instead of assigned, because assignment would also cause de-containerization and thus completely defeat the purpose of this exercise.

Because the code in the supplied methods closes over the lexical variable $value, that variable stays alive until the Proxy object is destroyed. So it offers an easy way to actually store the value for this Proxy object.

Inside the supplied methods you are completely free to put whatever code that you want. As an example how that could work in a module, the Hash::MutableKeys distribution was created. Another case of BDD (Blog Driven Development)!

You may have observed that the Proxy object does not allow for a descriptor. It was not considered to be needed, as you have all the flexibility you could possibly want. If you want one in your Proxy objects, you can create one yourself.

Conclusion

This concludes the twelfth episode of cases of UPPER language elements in the Raku Programming Language, the fifth episode discussing interface methods.

In this episode containers were described, as well as the special Proxy class with its named arguments STORE and FETCH. This Proxy class provides a fully customizable container implementation.

Stay tuned for the next episode!

Method Not Found Fallback

Elizabeth Mattijsen — Tue, 17 Feb 2026 15:22:31 +0000

This is part eleven in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the interface method that can be provided in a class to handle calls to methods that do not actually exist in this class (or its parents).

Some background

Method dispatch in the Raku Programming Language is quite complicated, especially in the case of multi-dispatch. But the first step is really to see if there is any (multi) method with the given name.

Internally this is handled by the find_method method on the meta-object of the class (which is typically called with the .^method syntax on the class).

So for example:

# an empty class
class A { }

dd A.^find_method("foobar");  # Mu
dd A.^find_method("gist");    # proto method gist (Mu $:: |) {*}

Note that an empty class A (which by default inherits from the Any class) does not provide a method "foobar" (indicated by the Mu type object). But it does provide a gist method (indicated by the proto method gist (Mu $:: |) {*} representation of a Callable) because that is inherited from the Any class.

It's this logic that is internally used by the dispatch logic to link a method name to an actual piece of code to be executed.

Method not found

If the dispatch logic can not find a method by the given name, then it will throw an X::Method::NotFound error. One could of course use a CATCH phaser to handle such cases (as seen in part 6 of this series).

But there's a better and easier way to handle method names that could not be found. That is, if you're interested in somehow making them less fatal.

FALLBACK

If a class provides a FALLBACK method (either directly in its class, or by one of its base classes, or by ingestion of a role), then that method will be called whenever a method could not be found. The name of the method will be passed as the first argument, and all other arguments will be passed verbatim.

A contrived example in which a non-existing method returns the name of the method, but only if there were no arguments passed:

class B {
    method FALLBACK($name) { $name }
}
say B.foo;      # foo
say B.bar(42);  # Too many positionals passed; expected 2 arguments but got 3

So is there something special about the FALLBACK method? No, its only specialty is when it is being called. So you can make it a multi method:

class C {
    multi method FALLBACK($name) {
        $name
    }
    multi method FALLBACK($name, $value) {
        "$value.raku() passed to '$name'"
    }
}
say C.foo;      # foo
say C.bar(42);  # 42 passed to 'bar'

On the other hand if you don't care about any arguments at all and just want to return Nil, you can specify the nameless capture | as the signature:

class D {
    method FALLBACK(|) { Nil }
}
say D.foo;      # Nil
say D.bar(42);  # Nil

An actual application

The Raku Programming Language allows hyphens in identifier names (usually referred to as "kebab case"). Many programmers coming from other programming languages are not really used to this: they are more comfortable with using underscores in identifiers ("Snake case").

Modern Raku programs usually use kebab case in identifiers. So it's quite common for programmers to make the mistake of using an underscore where they should have been using a hyphen. If such an error is made when writing a program, it will be a runtime error. Which can be annoying. In such a case, a FALLBACK method can be a useful thing to have if it could correct such mistakes.

This could look something like this:

class E {
    method foo-bar() { "foobar" }

    method FALLBACK($name, |c) {
        my $corrected = $name.trans("_" => "-");
        if self.^find_method($corrected, :no_fallback) -> &code {
            code(self, |c)
        }
        else {
            X::Method::NotFound.new(
              :invocant(self), :method($name), :typename(self.^name)
            ).throw;
        }
    }
}

The "E" class has a method "foo-bar". And a method "FALLBACK" that takes the name of the method that was not found (and putting any additional arguments in the Capture "c").

Note that the "c" is just an idiom for the name of a capture. It could have any name, but "c" is nice and short. If you want to use a name that's more clear to you, then please do so. As long as you use the same name later on.

It then converts all occurrences of underscore to hyphen in the name and then tries to find a Callable for that name. If that is successful it will execute the code with any arguments that were given by flattening the |c capture. Otherwise it throws a "method not found" error.

The :no_fallback argument is needed to prevent the method lookup from producing the "FALLBACK" method if the method was not found. Otherwise the code would loop forever.

So now this code will work instead of causing an execution error.

say E.foo-bar;  # foobar
say E.foo_bar;  # foobar

To make this more generally usable this code could be put into a role and have that live as an installable module. But that would be extra work, wouldn't it?

Fortunately the writing of this blog post initiated the development of such a role (and associated distribution) called Method::Misspelt. How's that for BDD (Blog Driven Development)?

Note that the module introduces a few more features and optimizations, while handling keeping track of multiple classes ingesting the same role. See the internal documentation for more information.

Conclusion

This concludes the eleventh episode of cases of UPPER language elements in the Raku Programming Language, the fourth episode discussing interface methods.

In this episode the FALLBACK method was described, as well as some simple customizations. And a bonus module created for this blog post only.

Stay tuned for the next episode!

Associative Methods

Elizabeth Mattijsen — Thu, 12 Feb 2026 19:28:15 +0000

This is part ten in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the interface methods that one can implement to provide a custom Associative interface in the Raku Programming Language. Associative access is indicated by the postcircumfix { } operator (aka the "hash indexing operator").

In a way this blog post is a cat license ("a dog licence with the word 'dog' crossed out and 'cat' written in crayon") from the previous post. But there are some subtle differences between the Positional and the Associative roles, so just changing all occurrences of "POS" in "KEY" will not cut it.

Some background

The Associative role is really just a marker, just as the Positional role. It does not enforce any methods to be provided by the consuming class. So why use it? Because it is that constraint that is being checked for any variable with a % sigil. An example:

class Foo { }
my %h := Foo;

will show an error:

Type check failed in binding; expected Associative but got Foo (Foo)

However, if we make that class ingest the Associative marker role, it works:

class Foo does Associative { }
my %h := Foo;
say %h<bar>;  # (Any)

and it is even possible to call the postcircumfix { } operator on it! Although it doesn't return anything really useful.

Note that the binding operator := was used: otherwise it would be interpreted as initializing a hash %h with a single value, which would complain with an "Odd number of elements found where hash initializer expected: Only saw: type object 'Foo'" execution error.

Postcircumfix { }

The postcircumfix { } operator performs all of the work of slicing and dicing objects that perform the Associative role, and handling all of the adverbs: :exists, :delete, :p, :kv, :k, and :v. But it is completely agnostic about how this is actually done, because all it does is calling the interface methods that are (implicitely) provided by the object, just as with the Positional role. Except the names of the interface methods are different. For instance:

say %h<bar>;

is actually doing:

say %h.AT-KEY("bar");

under the hood. So these interface methods are the ones that actually know how to work on an Hash, Map or a PseudoStash, or any other class that does the Associative role.

The Interface Methods

Let's introduce the cast of this show (the interface methods associated with the Associative role):

AT-KEY

The AT-KEY method is the most important method of the interface methods of the Associative role: it is expected to take the argument as a key, and return the value associated with that key.

Note that the key does not need to be a string, it could be any object. It's just that the implenentation of Hash and Map will coerce the key to a string.

The AT-KEY method should return a container if that is appropriate, which is usually the case. Which means you probably should specify is raw on the AT-KEY method if you're implementing that yourself.

say %h<bar>;  # same as %h.AT-KEY("bar")

EXISTS-KEY

The EXISTS-KEY method is expected to take the argument as a key, and return a Bool value indicating whether that key is considered to be existing or not. This is what is being called when the :exists adverb is specified.

say %h<bar>:exists;  # same as %h.EXISTS-KEY("bar")

DELETE-KEY

The DELETE-KEY method is supposed to act very much like the AT-KEY method. But it is also expected to remove the key so that the EXISTS-KEY method will return False for that key in the future. This is what is being called when the :delete adverb is specified.

say %h<bar>:delete;  # same as %h.DELETE-KEY("bar")

ASSIGN-KEY

The ASSIGN-KEY method is a convenience method that may be called when assigning (=) a value to a key. It takes 2 arguments: the key and the value, and is expected to return the value. It functionally defaults to object.AT-KEY(key) = value. A typical reason for implementing this method is performance.

say %h<bar> = 42;  # same as @a.ASSIGN-KEY("bar", 42)

BIND-KEY

The BIND-KEY method is a method that will be called when binding (:=) a value to a key. It takes 2 arguments: the key and the value, and is expected to return the value.

say %h<bar> := 42;  # same as %h.BIND-KEY("bar", 42)

STORE

The STORE method accepts the values (as an Iterable) with which to (re-)initialize the hash, and returns the invocant.

The :INITIALIZE named argument will be passed with a True value if this is the first time the values are to be set. This is important if your data structure is supposed to be immutable: if that argument is False or not specified, it means a re-initialization is being attempted.

say %h = a => 42, b => 666;  # same as %h.STORE( (a => 42, b => 666) )

keys

Although not an uppercase named method, it is an important interface method: the keys method is expected to return the keys in the object.

my %h = a => 42, b => 666;
say %h.keys;  # (a b)

Handling simple customizations

Again, that's a lot to take in (especially if you didn't read the previous post)! But if it is just a simple customization you wish to do to the basic functionality of e.g. a hash, you can simply inherit from the Hash class. Here's a simple, contrived example that will return any values doubled as string:

class Hash::Twice is Hash {
    method AT-KEY($key) { callsame() x 2 }
}
my %h is Hash::Twice = a => 42, b => 666;
say "$_: %h{$_}" for %h.keys;

will show:

a: 4242
b: 666666

Note that in this case the callsame function is called to get the actual value from the array.

Helpful modules

If you want to be able to do more than just simple modifications, but for instance have an existing data structure on which you want to provide an Associative interface, it becomes a bit more complicated and potentially cumbersome.

Fortunately there are a number of modules in the ecosystem that will help you to create a consistent Associative interface for your class.

Hash::Agnostic

The Hash::Agnostic distribution provides a Hash::Agnostic role with all of the necessary logic for making your object act as a Hash. The only methods that must be provided, are the AT-KEY and keys methods. Your class may provide more methods for functionality or performance reasons.

Map::Agnostic

The Map::Agnostic distribution provides a Map::Agnostic role with all of the necessary logic for making your object act as a Map. The only methods that you must be provided, are the AT-KEY and keys methods. As with Hash::Agnostic, your class may provide more methods for functionality or performance reasons.

Example class

A very contrived example in which a Hash::Int class is created that provides an Associative interface in which the keys can only be integer values. Under the hood it uses an array to store values:

use Hash::Agnostic;

class Hash::Int does Hash::Agnostic {
    has @!values;
    method AT-KEY(Int:D $index) {
        @!values.AT-POS($index)
    }
    method keys() {
        (^@!values).grep: { @!values.EXISTS-POS($_) }
    }
    method STORE(\values) {
        my @values;
        for Map.CREATE.STORE(values, :INITIALIZE) {
            @values.ASSIGN-POS(.key.Int, .value)
        }
        @!values := @values;
    }
}

and can be used like this:

my %h is Hash::Int = <42 a 666 b 137 c>;
say %h<42>;
dd %h;

which would show:

a
Hash::Int.new(42 => "a",137 => "c",666 => "b")

Again, note that the STORE method had to be provided by the class to allow for the is Hash::Int syntax to work.

If you're wondering what's happening with Map.CREATE.STORE(values, :INITIALIZE): the initialization logic of hashes and maps allows for both separate key,value initialization, as well as key=>value initialization. And any mix of them. So this is just a quick way to use that rather specialized logic of Map.new to create a consistent Seq of Pairs with which to initialize the underlying array.

Raku actually has a syntax for creating a Hash that only takes Int values as keys: my %h{Int}. This creates a so-called "object hash" with different performance characteristics to the approach taken with Hash::Int.

Conclusion

This concludes the tenth episode of cases of UPPER language elements in the Raku Programming Language, the third episode discussing interface methods.

In this episode the AT-KEY family of methods were described, as well as some simple customizations and some handy Raku modules that can help you create a fully functional interface: Map::Agnostic and Hash::Agnostic.

Stay tuned for the next episode!

Positional Methods

Elizabeth Mattijsen — Wed, 11 Feb 2026 11:45:37 +0000

This is part nine in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the interface methods that one can implement to provide a custom Positional interface in the Raku Programming Language. Positional access is indicated by the postcircumfix [ ] operator (aka the "array indexing operator").

Some background

The Positional role is really just a marker. It does not enforce any methods to be provided by the consuming class. So why use it? Because it is that constraint that is being checked for any variable with an @ sigil. An example:

class Foo { }
my @a := Foo;

will show an error:

Type check failed in binding; expected Positional but got Foo (Foo)

However, if we make that class ingest the Positional marker role, it works:

class Foo does Positional { }
my @a := Foo;
say @a[0];  # (Foo)

and it is even possible to call the postcircumfix [ ] operator on it!

Note that the binding operator := was used: otherwise the array @a would just be initialized with the Foo type object as its first element.

So why is that possible? That's really possible because each item in Raku can be considered as a single element list. And thus the first element (aka [0]) will always provide the invocant.

say 42[0];  # 42
say 42[1];  # Index out of range. Is: 1, should be in 0..0

Which in turn is why the Positional role does not enforce any methods. Because they are always already provided by the Any class, so it would never complain about methods not having been provided.

Postcircumfix [ ]

The postcircumfix [ ] operator performs all of the work of slicing and dicing objects that perform the Positional role, and handling all of the adverbs: :exists, :delete, :p, :kv, :k, and :v. But it is completely agnostic about how this is actually done, because all it does is calling the interface methods that are (implicitely) provided by the object. For instance:

say 42[0];  # 42

is actually doing:

say 42.AT-POS(0);

under the hood. So these interface methods are the ones that actually know how to work on an Array, a List or a Blob, or any other class that does the Positional role.

The Interface Methods

Let's introduce the cast of this show (the interface methods associated with the Positional role):

AT-POS

The AT-POS method is the most important method of the interface methods: it is expected to take the integer index of the element to be returned, and return that. It should return a container if that is appropriate, which is usually the case. Which means you probably should specify is raw on the AT-POS method if you're implementing that yourself.

say @a[$index];  # same as @a.AT-POS($index)

EXISTS-POS

The EXISTS-POS method is expected to take the integer index of an element, and return a Bool value indicating whether that element is considered to be existing or not. This is what is being called when the :exists adverb is specified.

say @a[$index]:exists;  # same as @a.EXISTS-POS($index)

DELETE-POS

The DELETE-POS method is supposed to act very much like the AT-POS method. But is also expected to remove the element so that the EXISTS-POS method will return False for that element in the future. This is what is being called when the :delete adverb is specified.

say @a[$index]:delete;  # same as @a.DELETE-POS($index)

ASSIGN-POS

The ASSIGN-POS method is a convenience method that may be called when assigning (=) a value to an element. It takes 2 arguments: the index and the value. It functionally defaults to object.AT-POS(index) = value. A typical reason for implementing this method is performance.

say @a[$index] = 42;  # same as @a.ASSIGN-POS($index, 42)

BIND-POS

The BIND-POS method is a method that will be called when binding (:=) a value to an element. It takes 2 arguments: the index and the value. If not implemented, binding will always fail with an execution error.

say @a[$index] := 42;  # same as @a.BIND-POS($index, 42)

STORE

The STORE method accepts the values to be (re-)initializing with as an Iterable and returns the invocant (self).

say @a = 42, 666, 137;  # same as @a.STORE( (42, 666, 137) )

elems

Although not an uppercase named method, it is an important interface method: the elems method is expected to return the number of elements in the object. Basically the highest index value + 1 that can be specified expected to return a value (because indexing starts at 0).

Handling simple customizations

Wow, that's a lot to take in! But if it is just a simple customization you wish to do to the basic functionality of e.g. an array, you can simply inherit from the Array class. Here's a simple, contrived example that will return any content of the array doubled as string:

class Array::Twice is Array {
    method AT-POS(Int:D $index) { callsame() x 2 }
}
my @a is Array::Twice = <a b c>;
say "\@a[$_] = @a[$_]" for ^@a;

will show:

@a[0] = aa
@a[1] = bb
@a[2] = cc

Note that in this case the callsame function is called to get the actual value from the array.

Another contrived example where the customization initializes the array with given values in random order (using .pick):

class Array::Confused is Array {
    method STORE(\values) { self.Array::STORE(values.pick(*)) }
}
my @a is Array::Confused = <a b c>;
say "\@a[$_] = @a[$_]" for ^@a;

will show something like:

@a[0] = b
@a[1] = a
@a[2] = c

Note that this example uses the fully qualified method syntax (self.Array::STORE) to set the values in the array.

Helpful modules

If you want to be able to do more than just simple modifications, but for instance have an existing data structure on which you want to provide a Positional interface, it becomes a bit more complicated and potentially cumbersome.

Fortunately there are a number of modules in the ecosystem that will help you creating a consistent Positional interface for your class.

Array::Agnostic

The Array::Agnostic distribution provides an Array::Agnostic role with all of the necessary logic for making your object act as an Array. The only methods that must be provided, are the AT-POS and elems methods. Your class may provide more methods for functionality or performance reasons.

List::Agnostic

The List::Agnostic distribution provides a List::Agnostic role with all of the necessary logic for making your object act as a List. The only methods that you must be provided, are the AT-POS and elems methods. As with Array::Agnostic, your class may provide more methods for functionality or performance reasons.

Example class

A very contrived example in which a Date object is going to represented by a 3-element array. The class looks like:

use List::Agnostic;

class Date::Indexed does List::Agnostic {
    has $!date;
    method AT-POS(Int:D $index) {
        try (*.year, *.month, *.day)[$index]($!date)
    }
    method elems() { 3 }
    method STORE(\values) {
        $!date := Date.new(|values) // Date.today; self
    }
}

and can be used like this:

my @a is Date::Indexed = "2026-02-11";
say "\@a[$_] = @a[$_]" for ^@a;

which would show:

@a[0] = 2026
@a[1] = 2
@a[2] = 11

Note that the STORE method had to be provided by the class to allow for the is Date::Indexed syntax to work.

If you're wondering what's happening with try (*.year, *.month, *.day)[$index]($!date): that's a list built of 3 WhateverCodes with the specified index selecting the appropriate entry and executing that with the $!date attribute as the invocant. If that would fail (probably because the index was out of range), then the try will make sure that the error is caught and a Nil is returned.

Conclusion

This concludes the ninth episode of cases of UPPER language elements in the Raku Programming Language, the second episode discussing interface methods.

In this episode the AT-POS family of methods were described, as well as some simple customizations and some handy Raku modules that can help you create a fully functional interface: List::Agnostic and Array::Agnostic.

Stay tuned for the next episode!

The second two

Elizabeth Mattijsen — Sun, 08 Feb 2026 19:29:26 +0000

This is a second follow-up on Raku Resolutions series.

The second meeting was held on 7 February 2026 at 19:00 UTC. Apart from 4 Raku Steering Council members, up to 5 other people attended with a true worldwide spread: local times spanning from UTC-8 to UTC+11! Thank you all for your attendance and your feedback!

In the end, 2 issues were discussed within the allotted time (1 hour). Both had extensive discussions, but no immediate resoluton.

Raku Classification System

This discussion took most of the time, as it is indeed could be a very big project. It was felt that this was a project worth pursuing, and that having more meta-data on Raku and its uses would be very valuable. Tim Nelson replied after the meeting. To be continued (but probably through the issue, and not merely at these meetings).

Function return types should also tell about the used assignment/container

It became clear that this is not just a documentation issue, but in a way a language design (and implementation) issue as well. The argument was made that when some functionality is made that returns a mutable entity, it should be clearly visible (for instance substr versus substr-rw). Márton Polgar summarized the result.

The next meeting

The next meeting will be held at 21 February 2026 at 19:00 UTC (20:00 CET, 14:00 EST, 11:00 PST, 04:00 JST (22 Jan), 06:00 AEST (22 Jan)), and again at a one hour maximum. If not all of these issues have been resolved, they will be moved to a future meeting.

The remaining issues that will be discussed, are:

and any other issues that people want to discuss.

Preparation

Any Raku Community member is welcome to this meeting. Do you consider yourself a Raku Community member? You're welcome. It's as simple as that.

The original contributors to these issues will also be notified (unless they muted themselves from these issues). We hope that they also will be able to attend.

Small steps

If you consider yourself a Raku Community member, please try to attend! If anything, it will allow you to put faces to the names that you may be familiar with.

Hope to see you there!

Tweak Build

Elizabeth Mattijsen — Sun, 08 Feb 2026 13:08:48 +0000

This is part eight in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the interface methods that one can provide to tweak the creation of objects in the Raku Programming Language.

But first some background

If you are unfamiliar as to how Raku allows one to create classes, describe attributes and methods, it is recommended to first have a look at Classes and objects - A tutorial about creating and using classes in Raku.

In short: by default, objects are created with the .new method (which is provided by the Mu base class). This .new method takes named arguments and tries to match these with attribute names that are supposed to be set with .new. Any unmatched named arguments are silently ignored.

Attributes that are settable with .new that are not specified will have any default value applied to them. A small example:

class Foo {
    has $.bar = 42;  # attribute + accessor
}
say Foo.new.bar;               # 42
say Foo.new( :bar(666) ).bar;  # 666

Well, actually that is a little white lie. But it is true in most cases.

The thing is that you can also specify your own .new method in your class, and still have all of the attribute initialization work done for you. The reason for this is that it's not really the .new method that is doing the work, but the .bless method that is also provided by the Mu class.

Functionally the .new method supplied by Mu is:

method new() { self.bless(|%_) }

although in reality it's a little bit more complex more allowing for some optimizations. Object creation occurs a lot when you're executing a Raku program, so it makes sense to try to optimize that!

Note that methods in Raku always have a *%_ (aka a "slurpy hash") added to their signature, unless there is already a slurpy hash in the signature.

An example of a custom .new method that takes a single positional argument:

class Foo {
    has $.bar = 42;
    multi method new($bar) {
        self.bless(:$bar, |%_)
    }
}
say Foo.new.bar;               # 42
say Foo.new( :bar(666) ).bar;  # 666
say Foo.new( 137 ).bar;        # 137

The reason that this also allows the named argument way, is because of the multi. This adds a candidate to the existing dispatch table for the .new method, so the Mu.new candidate can still be dispatched to. Without the multi there would only be the one .new method in the dispatch table for class Foo.

Also note the |%_ in the self.bless call: this makes sure that any additional named argments are also passed to .bless if you specify a positional argument.

BUILD vs TWEAK

Any class in Raku can have a BUILD and/or a TWEAK method specified. Both are called by the object building logic, but only if it is possible to call them. Both methods receive the same arguments as having been (indirectly) passed to .bless. The return value of these methods will be ignored.

The BUILD method is called instead of attribute initializations from the named arguments. Specifying the BUILD method means needing to mimic all named argument setting in that BUILD method..

Any default values for attributes are assigned if the attribute did not receive a value yet (either from attribute initializations from the named arguments, or having been initialized in the BUILD method).

The TWEAK method is called as the last stage of object instantiation. Nowadays it is the recommended way of altering the named argument -> attribute initialization logic for a class (after all initializations and default setting has been done).

BUILDPLAN

The Rakudo distribution comes with a handy introspection module that shows what steps are taken (in pseudo-code) in the creation of an instance of a class: BUILDPLAN. It's use is pretty simple: use BUILDPLAN class.

class Foo {
    has $.bar = 42;
}
use BUILDPLAN Foo;

will show:

class Foo BUILDPLAN:
 0 nqp::getattr(obj,Foo,'$!bar') = :$bar if possible
 1 nqp::getattr(obj,Foo,'$!bar') = 42 if not set

Note that there are two steps:

assign value of named argument "bar" to the attribute "$!bar" if specified
assign value 42 to the "$!bar" attribute if it has not been set yet

Now, if we add a BUILD method to it:

class Foo {
    has $.bar = 42;
}
submethod BUILD() { }
use BUILDPLAN Foo;

the build plan changes to:

class Foo BUILDPLAN:
 0 call obj.Foo::BUILD
 1 nqp::getattr(obj,Foo,'$!bar') = 42 if not set

Note that the first step changed from "nqp::getattr(obj,Foo,'$!bar') = :$bar if possible" to "call obj.Foo::BUILD". So instead of looking for a named argument "bar", it is now just calling the "BUILD" method.

Also note that second step stayed the same: so if the BUILD method doesn't assign anything to the $!bar attribute, the default value will still be set.

Tricks and Tips

Historically the BUILD method was one of the first things actually implemented in Raku, and thus a lot of (older) code in the wild uses the BUILD method. Since then many features have been added to the way one can specify attributes, obsoleting some of the common BUILD uses.

Here are some examples of outdated idioms:

Making a named argument required

The BUILD method can make a named argument for the creation of the object mandatory by making it a required named argument of BUILD (by adding a ! in the signature):

class Foo {
    has $.bar;
    submethod BUILD( :$bar! ) { $!bar = $bar }
}

The better way is to use the is required trait on attributes.

class Foo {
    has $.bar is required;
}

Allowing a named argument without automatic accessor

By allowing a named argument in the BUILD signature and assigning that to the attribute in the body, you're effectively mimicing the . twigil in the attribute definition without having an accessor made automatically.

class Foo {
    has $!bar;
    submethod BUILD( :$bar ) { $!bar = $bar }
}

The better way is to use the is built attribute trait:

class Foo {
    has $!bar is built;
}

When to use TWEAK

Looking at the modules in the ecosystem, the TWEAK method is oftentimes being used for:

throwing an error if some complicate condition is not met
throwing an error if conflicting arguments have been specified
starting async workers once the object is fully fleshed
setting up a (fast) data-structure based on the attributes supplied
setting attributes from information supplied in a (JSON) hash
reading / parsing a file into additional attributes
inform a logger when an object has been created

You typically should not use a TWEAK method if you can achieve the same effect with an extensive specification of the attributes. First of all the declarative manner in which these are specified is easier to comprehend. Secondly, the processing of the named arguments and their specificaton is highly optimized. Compare:

$ raku -e 'class A { has $.a = 42 }; A.new for ^1000000; say now - ENTER now'
0.080668357
$ raku -e 'class A { has $.a; method TWEAK(:$a) { $!a = $a // 42 }; A.new for ^1000000; say now - ENTER now'
0.122443318

which shows that using proper attribute declarations is at least 30% faster. Well in this case. YMMV.

If you're more comfortable with using a TWEAK method, then please do. There's more than one way to do it!

submethod vs method

A submethod is a special type of public method, but which is not inherited by subclasses. TWEAK and BUILD methods should be made submethods, because otherwise they can get executed more than once if they are in a base class, and the inheriting class does not specify its own TWEAK or BUILD method.

class A {
    method TWEAK() { say "A" }
}
class B is A { }
B.new;

will show:

A
A

because class "B" inherited the TWEAK method from "A". And at object initialization, the BUILDPLAN of each class in the class hierarchy is executed.

Conclusion

This concludes the eight episode of cases of UPPER language elements in the Raku Programming Language, the first discussion interface methods.

In this episode the TWEAK and BUILD methods were described, with a supporting role for the BUILDPLAN module. In short: don't use BUILD if you can use TWEAK. Don't use TWEAK if you can describe the same logic in the attribute specifications.

Stay tuned for the next episode!

Doc Mirages

Elizabeth Mattijsen — Wed, 04 Feb 2026 22:18:26 +0000

This is part seven in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the final set of (non-)existing phasers in the Raku Programming Language.

But first: --doc

The --doc command line argument to raku is described as:

--doc         extract documentation and print it as text
--doc=module  use Pod::To::[module] to render inline documentation

So what that basically does, is process the source of the program to be executed as documentation, and render that documentation in various forms.

Internally this is achieved by loading the Pod::To::xxx module (with "xxx" defaulting to "Text" in case of --doc without arguments). It then installs an INIT phaser that basically does:

INIT {
    say Pod::To::xxx.render($=pod);
    exit;
}

Note that the Pod::To::Text module is installed as part of the rakudo distribution (whether it should be considered part of the Raku Programming Language specification is yet unclear).

Other renderers such as Pod::To::HTML, Pod::To::PDF and Pod::To::Markdown would have to be installed first from the ecosystem (e.g. zef install Pod::To::Markdown).

With that under our belt, we can start discussing the DOC phaser.

DOC

There is not one single DOC phaser, there are actually three of them:

DOC BEGIN - add BEGIN phaser but only if --doc is set
DOC CHECK - add CHECK phaser but only if --doc is set
DOC INIT - add INIT phaser but only if --doc is set

Another way of thinking about this, is that the DOC phaser could be thought of as a sort of statement prefix that will add the phaser only if --doc was specified on the command line. In pseudo-code, for DOC BEGIN:

if --doc is set {
    BEGIN ...;
}

Note that if the --doc is not specified, the phasers will not be executed. Observe the difference between:

$ raku -e 'DOC BEGIN say "begin"; DOC CHECK say "check"; DOC INIT say "init"'

not showing anything, while:

$ raku --doc -e 'DOC BEGIN say "begin"; DOC CHECK say "check"; DOC INIT say "init"'
begin
check
init

will execute the phasers and shows the output.

There's only one "but": even though the DOC phasers are only added if --doc is specified, they must contain valid Raku code to prevent errors:

$ raku -e 'DOC BEGIN +-+'            
===SORRY!=== Error while compiling -e
Prefix + requires an argument, but no valid term found.
Did you mean + to be an opening bracket for a declarator block?
at -e:1

So what use are they? Looking at the ecosystem, there actually only appears to be one type of use that makes sense. And that is functionality offered by the POD::EOD module, which places declarator documentation at the end of the documentation, rather than where they occur in the source code. Which works because it directly modifies the content of the $=pod variable.

Yours truly has not been able to find any other (correct) usage.

TEMP

The TEMP phaser is a bit of a mirage. In the old design documents it was mentioned in S06 - Temporization.

However it looks like sometime in May 2012 let and temp were implemented. But the described TEMP phaser never was implemented in all of the years since then. Probably because the functionality of temp and let covered almost all use cases, combined with the KEEP and UNDO phasers, so nobody felt the need to actually implement support for it.

Oddly enough the syntax for the TEMP phaser does exist.

$ raku -e 'TEMP say "temp"; say "alive";
alive

But it just doesn't do anything. And after this blog post, chances are that the support for the syntax will be removed (see problem solving issue).

COMPOSE

The COMPOSE phaser is even more of a mirage, as it is not even partly implemented. Its only mention is in the S04 - Phasers section of the old design documentation.

However developers wanting to use roles when composing another role or class often refer to the lack of its existence.

The thing is that most of the functionality of the mythical COMPOSE phaser is already available: any code that exists in the mainline of a role, will be executed every time the role is consumed by a class at compile time. A small contrived example:

role A {
    say "composing $?CLASS.^name()";
}
class B does A { }
class C does A { }
BEGIN say "begin";

will show:

composing B
composing C
begin

Note that the $?CLASS compile time variable contains the type object of the class being composed. And in August 2020 it basically became clear that a COMPOSE phaser would not be needed. Well, at least not until someone can show that a COMPOSE phaser offers more functionality than the current way of executing the mainline of the role is offering.

Conclusion

The DOC set of phasers is activated with the --doc command line argument: without that having been specified, all DOC phasers are no-ops but need to be syntactically correct. Their use appears to be limited.

The TEMP phaser was never implemented, but the temp and let prefix operators, as well as the KEEP and UNDO phasers, provide the functionality promised by TEMP phaser.

The COMPOSE phaser was never implemented, because the mainline of a role is executed when a role is consumed in a class, effectively providing exactly the functionality promised by that phaser. At least so far.

This concludes the seventh episode of cases of UPPER language elements in the Raku Programming Language. This also concludes all phasers in Raku. Next up will describe the uppercase methods that you, as a user of the Raku Programming Language, can provide in your code to tweak behaviour. Stay tuned!

Catch Control

Elizabeth Mattijsen — Tue, 03 Feb 2026 19:25:53 +0000

This is part six in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the phasers that catch exceptions of various kinds.

CATCH

Many programming languages have a try / catch mechanism. Although it is true that the Raku Programming Language does have a try statement prefix, and it does have a CATCH phaser, you should generally not use both at the same time.

In Raku any scope can have a single CATCH block. The code within it will be executed as soon as any runtime exception occurs in that scope, with the exception that was thrown topicalized in $_.

This is the reason you cannot have a CATCH thunk: it needs to have a scope to be able to set $_ in there, without affecting anything outside of that scope.

It does not matter where in a scope you put the CATCH block. But it is recommended for clarity's sake to put a CATCH block as early in the scope as possible (rather than "hiding" it somewhere near the end of a scope): when reading the code, you will almost immediately see that there is something special going on with regards to exceptions.

Handling exceptions

Let's start again with a contrived example:

{ 
    CATCH {
        when X::AdHoc {
            say "naughty: $_.message()";
        }
    }
    die "urgh";  # throws an X::AdHoc exception
    say "after";
}
say "alive still";

Running the above code will show:

naughty: urgh
alive still

Note that having the exception in $_ smart-matching with when effectively disables the exception so it won't be re-thrown on scope exit. Because of that, the say "alive still" will be executed. Any other type of error would not be disabled, although you could if you wanted do that with a default block.

The careful reader will have noticed that the say "after" was not executed. That's because the current scope was left as if a return Nil was executed in the scope where the CATCH block is located.

If you feel like the exception in question is benign, you can make execution continue in the statement following the one that caused the exception. You can do this by calling the .resume method on the exception object.

So let's assume all errors we get in that block are benign, and we want to just continue after each exception:

{ 
    CATCH { .resume }
    die "urgh";
    say "after";
}
say "alive still";

would show:

after
alive still

However, not all exceptions are resumable! So your program may stop nonetheless if the exception can not be actually resumed. For instance, division by 0 errors are not resumable:

CATCH { .resume }
say 1/0;

would show:

This exception is not resumable
  in block foo at bar line 42

Trying code

The try statements prefix (which either takes a thunk or a block) is actually a simplified case of a CATCH handler that disarms all errors, sets $! and returns Nil. The code:

say try die "urgh";  # Nil
dd $!;               # $! = X::AdHoc.new(payload => "urgh")

is actually pretty much short for:

say {
    CATCH {
        CALLERS::<$!> = $_;  # set $! in right scope
        default { }          # disarm exception
    }
    die "urgh";
}();    # Nil
dd $!;  # $! = X::AdHoc.new(payload => "urgh")

Note that even though die "urgh" is a thunk, the compiler turned this into its own scope internally to be able to handle the return from the thunk.

CONTROL

Apart from runtime exceptions, many other types of exceptions are used in Raku. They all consume the X::Control role and are therefore referred to as "control exceptions". They are used for the following Raku features (in alphabetical order):

done - call "done" callback on all taps
emit - send item to all taps of supply
last - exit the loop structure
next - start next iteration in loop structure
proceed - resume after given block
redo - restart iteration in loop structure
return - return from sub / method
succeed - exit given block
take - pass item to gather
warn - warn with given message

Just as runtime exceptions they all perform the work they are expected to do without needing any specific action from a user. However, you can not catch these exceptions with a CATCH phaser, you need a CONTROL phaser for that.

Handling control exceptions yourself

Suppose you have a pesky warning that you want to get rid of:

say $_ ~ "foo";

which would show:

Use of uninitialized value element of type Any in string context.
Methods .^name, .raku, .gist, or .say can be used to stringify it to something meaningful.
  in block foo at bar line 42
foo

Since warnings are control exceptions, you can "catch" them in a CONTROL phaser like this:

CONTROL {
    when CX::Warn { .resume }
}
say $_ ~ "foo";

The class names for these control exceptions can be determined from title casing the name of the feature, and then prefixing with CX::. So "warn" throws an instance of the CX::Warn class.

which would just show:

foo

Pretty simple, eh? Well, by popular demand there is actually a shortcut for this case, called the quietly statement prefix:

quietly say $_ ~ "foo";

The standard way of handling warnings only produces the exact call-site where the warning occurred. Which sometimes is just not enough to find the reason for the warning, because you would need a full stack trace for that. Well, you can do that as well with a CONTROL block:

CONTROL {
    when CX::Warn {
        note .message;
        note .backtrace.join;
        .resume;
    }
}
say $_ ~ "foo"

would show:

Use of uninitialized value element of type Any in string context.
Methods .^name, .raku, .gist, or .say can be used to stringify it to something meaningful.
  in sub warn at SETTING::src/core.c/control.rakumod line 267
  in method Str at SETTING::src/core.c/Mu.rakumod line 817
  in method join at SETTING::src/core.c/List.rakumod line 1200
  in sub infix:<~> at SETTING::src/core.c/Str.rakumod line 3995
  in block foo at bar line 42

Or if you would like to turn any warning into a runtime exception:

CONTROL {
    when CX::Warn { .throw }
}
say $_ ~ "foo";

would show:

Use of uninitialized value $_ of type Any in string context.
Methods .^name, .raku, .gist, or .say can be used to stringify it to something meaningful.
  in block foo at bar line 42

and not show the "foo" because it would never get to that.

Building your own control exceptions

Can you build you own control exceptions? Yes, you can. Are they useful? Probably not. But just in case someone finds a way to make this useful, here's how you do it. You start with a class that consumes the X::Control role:

class Frobnicate does X::Control {
    has $.message;
}

Then you create a nice subroutine to make it easier to create an instance of that class, pass it any arguments and throw the instantiated control exception object:

sub frobnicate($message) {
    Frobnicate.new(:$message).throw
}

Then in your code, make sure there is a CONTROL phaser in the dynamic scope that handles the control exception:

CONTROL {
    when Frobnicate {
        say "Caught a frobnication: $_.message()";
        .resume;
    }
}

And then execute the nice subroutine at will:

say "before";
frobnicate "This";
say "after";

which would show:

before
Caught a frobnication: This
after

Final notes

Even though the CATCH and CONTROL phasers are scope based, you can not introspect a given Block to see whether it has CATCH or CONTROL phasers. This is because you can only have one of them in a scope, and handling exceptions in these phasers actually needs to be built into the bytecode generated for a block. So from a runtime point of view, there was no need to put them as attributes into the Block object.

Exception handling in Raku is built on delimited continuations. If you really want to get into the nitty gritty of this feature, you might be interested in reading "Continuations in NQP".

Conclusion

The CATCH phaser catches exceptions that are supposed to be fatal. The CONTROL phasers catches exceptions for all sorts of "normal" functionality, such as next, last, warn, etc.

You can build your own control exceptions, but the utility of these remains unclear as of yet.

Exceptions are built on top of so-called "delimited continuations".

This concludes the sixth episode of cases of UPPER language elements in the Raku Programming Language. Stay tuned for more!

Last Close, and Quitting

Elizabeth Mattijsen — Wed, 28 Jan 2026 15:41:34 +0000

This is part five in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the phasers related to concurrent and async structures, and will go into some of the mechanics behind the scenes.

Concurrency and Async

If you're unaware of the concurrency and async features of the Raku Programming Language (especially about what supply / emit and react / whenever do), it might be a good idea to read up on the Supplies section of the Raku documentation on Concurrency.

LAST, CLOSE, QUIT

We have seen in the previous episode that one can have a LAST phaser in loop structures. But one can also have a LAST phaser in supplies.

In fact, there are three asynchronous phasers: LAST, CLOSE and QUIT.

LAST - as soon as a supply is done / last is executed
CLOSE - as soon as supply / react is done
QUIT - when an exception occurs in the supplier

Let's start with an example with LAST and CLOSE. We create a supply that will produce 5 values, and a react block with a single whenever that will handle the values produced by the supply.

This example is completely synchronous because the supply keyword creates an "on-demand" supply, which isn't really "event" processing. However, any other supply (e.g. a "live" supply created by the signal would be handled in the same way and that would be event processing).

my $supply = supply {
    CLOSE say "Supply was closed.";
    emit($_) for ^5;
}

react {
    CLOSE say "Shutting down react.";
    whenever $supply {
        .say;
        LAST say "Supply is done.";
    }
}
say "React has been shut down";

will show:

0
1
2
3
4
Supply is done.
Supply was closed.
Shutting down react.
React has been shut down.

Note that the LAST phaser inside the whenever fires before the CLOSE phaser in the supply. That's because the supply needs to inform each tap that it is done, before it can shutdown itself.

Also note that when the last (in this case only) whenever is done in a react block, that the react block will end and the code following it will be executed.

But what now if an execution error happens in the supply when it is producing values? That's when the QUIT phaser becomes handy:

my $supply = supply {
    CLOSE say "Supply was closed.";
    for ^5 {
        die "Urgh" if $_ == 2;
        emit($_);
    }
}

react {
    CLOSE say "Shutting down react";
    whenever $supply {
        .say;
        LAST say "Supply is done.";
        QUIT {
            when X::AdHoc {
                say "Supply Error: $_.message()";
            }
        }
    }
}
say "React has been shut down";

will show:

0
1
Supply was closed.
Supply Error: Urgh.
Shutting down react.
React has been shut down.

Note that the LAST phaser will not fire when an execution error occurs in the supply, only the QUIT phaser will execute. Also note that the X::AdHoc execution error is what die creates and throws, and that the when will cause the execution error to be disarmed. Any other execution error will be propagated.

For instance, replacing the line die "Urgh" if $_ == 2; by 42[1] if $_ == 2;, will cause this output:

0
1
Supply was closed.
Shutting down react.
A react block:
  in block <unit> at foo line 9

Died because of the exception:
    Index out of range. Is: 1, should be in 0..0

Note that in that case, execution will not continue after the react block because the execution error was not disarmed (because it was not an X::AdHoc).

Yes, the use of 42[1] may be weird, but it is one of the quickest ways to create an execution error that is not an X::AdHoc. This is an error because any value in Raku can be considered a one-element list. So foo[0] will return foo, but foo[1] will cause an out-of-bounds error.

Under the hood

All of the block related phasers that have been discussed so far are stored as additional information in the Block object. Basically when the Raku grammar is parsing your code and it sees something that looks like a phaser, it just adds that to the surrounding block (represented by a Block object). Then later, when the situation is right, the runtime inspects the Block object for any phasers that are applicable in that situation by name. And if found, executes them.

This results in the (possibly unexpected) situation that you are allowed to specify a phaser that will never be fired in that context. For instance:

{
    CLOSE say "closed";
    say "inside block";
}

will just show inside block, simply because the CLOSE phaser only makes sense inside an concurrent / async structure such as a supply.

One could argue that the above example should be a compilation error, as the CLOSE phaser will never be called. However, it is pretty difficult to be 100% sure at compile time how a block will actually be used in the code, and what phasers could be called. And from a performance point of view, checking for not-applicable phasers at runtime would incur a significant performance penalty. So it was decided to not do that and consider this way of improperly using of phasers a case of DIHWIDT (aka Doctor, It Hurts When I Do This. "so don't do that then").

However, it is possible to introspect Block objects in Raku, because everything in Raku is an object (or can be thought of as one). Consider this example:

my $block = {
    CLOSE say "closed";
    say "inside block";
}
$block();                           # inside block
$_() for $block.phasers("CLOSE");  # closed

Note that by adding () after the variable, you're telling Raku to execute the contents of that variable without giving any arguments.

The Block.phasers method takes the name of a block-oriented phaser and returns a List of Block objects representing each phaser seen by that name (usually one, but there can be more than one).

Now, from a performance point of view it might not be a good idea to do a lookup in the Block information for a phaser by a given name if there are no phasers associated with the block at all. Each time the block is executed. Fortunately the Block object also has a has-phasers method that provides an efficient way to check that.

my $block = {
    CLOSE say "closed";
    say "inside block";
}
$block();                              # inside block
if $block.has-phasers {
    $_() for $block.phasers("CLOSE");  # closed
}

These features allow developers to handle special features for blocks on top of what Raku already provides.

Unfortunately there's no way (yet) to add arbitrarily named phasers in Raku code: this will probably require creating a "slang".

Conclusion

The LAST, CLOSE and QUIT phasers can be used in supply, react and whenever blocks and will be called at the appropriate times.

Under the hood block-oriented phasers are stored as additional information in the surrounding Block object. They can be introspected with the has-phasers and phasers methods.

This concludes the fifth episode of cases of UPPER language elements in the Raku Programming Language. Stay tuned for more!

First Next, then Last

Elizabeth Mattijsen — Mon, 26 Jan 2026 14:47:35 +0000

This is part four in the "Cases of UPPER" series of blog posts, describing the Raku syntax elements that are completely in UPPERCASE.

This part will discuss the phasers related to loop structures (the code between curly braces that is being repeatedly called)

But first, a statement

The second episode already saw the use of the state declarator in one of the examples, without going into it much. Since state is affecting some aspects handled in this blog post, it felt important to first circle back to it before going on.

In short, a state variable is a lexically scoped variable that will keep its value between invocations of the scope in which it is defined. For example:

sub frobnicate() {
  state $times += 1;  # defined inside "frobnicate"
  END say "Frobnicated $times times.";
}
frobnicate for ^5;

will show:

Frobnicated 5 times.

It is really as if the variable $times has been defined in the outer scope. This gives the same result:

my $times;  # defined outside of "frobnicate"
sub frobnicate() {
  $times += 1;
  END say "Frobnicated $times times.";
}
frobnicate for ^5;

The difference being that the my $times variable is visible to other pieces of the program, where as the state $times variable is not.

A slightly adapted example:

sub frobnicate() {
  for ^3 {
    state $times += 1;  # defined inside "for" loop
    END say "Frobnicated $times times.";
  }
}
frobnicate for ^5;

will show:

Frobnicated 3 times.

Not 5. Not 15. But 3. That's because the above code could also be written as:

sub frobnicate() {
  my $times;
  for ^3 {
    $times += 1;  # defined outside of "for" loop
    END say "Frobnicated $times times.";
  }
}
frobnicate for ^5;

As you can see in this case each invocation of "frobnicate" will get a fresh my $times. And since the END phaser occurs only once in the code, it will only see the value of $times from the last time that "frobnicate" had been called.

The way initialization of state variables is organized is slightly more complex than described above. In most cases the above explanation is correct, and when it is not you're probably getting into DIHWIDT (Doctor, It Hurts When I Do This: "so don't do that") territory.

Finally it should be noted that state variables, like any other non-atomic variables, are not thread-safe.

sub frobnicate() {
  state $times += 1;
  END say "Frobnicated $times times";
}
await start {  # wait for jobs to finish
  sleep rand;  # create some chaos
  frobnicate;
} xx 100;      # start 100 async jobs

will show fewer than 100 frobnications.

This is caused by multiple threads trying to update the $times variable simultaneously. This may miss updates, because $times += 1 is essentially $times = $times + 1. If two threads fetch the value of $times simultaneously, then one of the threads will lose its update to $times because it didn't "see" the update of the other thread before fetching it.

It's important to recognize this behaviour of state variables, before they are being used. However, the system uses some state variables under the hood. So your code may be affected by this behaviour without you as a develeoper realizing that.

Loop-di-loop

All loop structures in the Raku Programming Language (for, while / until and loop) allow for the specification of an additional 3 types of phaser: FIRST, NEXT and LAST.

The names of these phasers are pretty self-explanatory:

FIRST - runs the first time a loop structure is entered
NEXT - runs each time after an iteration is done
LAST - runs after the last iteration is done

A simple example:

my $left;
my $right;
for ^5 -> $id {
  $left  += $id;
  $right += $id + 2;
  FIRST say "ID | +2\n===+===";
  NEXT say " $id |  { $id + 2 }";
  LAST say "===+=== +\n$left | $right";
}

will show:

ID | +2
===+===
 0 |  2
 1 |  3
 2 |  4
 3 |  5
 4 |  6
===+=== +
10 | 20

Using the FIRST and LAST phaser allows one to easily add a header and a footer using variables that only exist inside the loop structure.

The NEXT phaser runs when an iteration is ended normally, or is started with a next command. The LAST phaser is run after the last iteration is done, or when leaving the scope is initiated with a last command.

The FIRST phaser uses an invisible state variable under the hood, so depends on the peculiarities of its implementation.

It is possible to use the other Block oriented phasers in loop structures as well. But generally only the LEAVE phaser makes sense in that case: it effectively can be used if you want the same code to be executed in both the NEXT and the LAST case.

FIRST in the future

In the next language level of Raku, the FIRST phaser will become active for any scope, not just inside of loop structures. It will then also return the value produced by the FIRST phaser.

$ RAKUDO_RAKUAST=1 raku -e '{ say now - FIRST now }'
0.000048209

This functionality is similar to what is provided by once. But that looks phaser-like? Why isn't once a phaser and thus in all uppercase?

There have been a lot of discussions about that, but in the end it was decided that it is not a phaser because it runs in-line like other statement prefixes (decision from 2013). So:

$ raku -e '{ say now - once now }'
-0.000055917

will show a negative value because the once now is executed after the first now.

The FIRST phaser however will run when the scope is entered, not where the FIRST phaser occurs in code.

Conclusion

The FIRST, NEXT and LAST phasers apply to a scope that is being used in a loop structure.

The FIRST phaser depends on a state variable under the hood.

With the next language level, the FIRST phaser will become active for any scope and return the value it produced. This is like once but at entry of the scope (not in-line).

This concludes the fourth episode of cases of UPPER language elements in the Raku Programming Language. Stay tuned for more!