NAME
Raku::Elements - The Elements of the Raku Programming Language
SYNOPSIS
use Raku::Elements;
my $info = Raku::Elements.new;
DESCRIPTION
The Raku::Elements distribution attempts to provide a programmatical interface to an alternate description of the Raku Programming Language, inspired by the "Periodic Table of the Operators" by Mark Lentczner.
It basically provides an (incomplete) overview of the features of the Raku Programming Language, sorted into groups in a way similar to the "Periodic Table of Elements".
Please note that this is still very much a work in progress: a lot of explanatory texts still need to be added. Pull requests are very welcome!
CLASSES
Raku::Elements
my $info = Raku::Elements.new;
say "Groups: $info.groups.elems()";
say "Tags: $info.tags.elems()";
The programmatical interface to the elements of the Raku Programming Language. Can be instantiated by calling .new. Provides these methods:
elements
A Map with the elements of the Raku Programming Language. The key represents either the name of an Raku::Element, or one of its alternates. The value is a List of one or more Raku::Element objects that share the same name (but may have different tags).
groups
A Map with Raku::Group objects, keyed to their name.
A Map with Raku::Tag objects, keyed to their name.
Raku::Group
The information about an element group of the Raku Programming Language. It is usually created automatically when a Raku::Elements object is instantiated.
name
The name of the element group.
description
The description of the element group (if any)
elements
A list of Raku::Element objects belonging to this group.
Raku::Element
name
The name of the element. This may be non-alphabetic, specifically in the case of operators such as +.
alternates
Alternate names of the element, for instance an Unicode version versus an ASCII version of an operator, such as ∈ as al alternate name for (elem). Usually empty.
A list of tags that apply to this element, e.g. infix for an infix operator. Has at least one element.
tagline
The tagline of the element: a one-line description.
url
A URL for more information about this element.
description
A more general description of the element. Optional.
Raku::Tag
The information about an element tag of the Raku Programming Language. It is usually created automatically when a Raku::Elements object is instantiated.
name
The name of the tag.
description
The description of the tag (if any)
elements
A list of Raku::Element objects belonging that have this tag set.
ELEMENTS
This section of the documentation is generated from the information supplied by the Raku::Elements object. It is provided here as an example of what can be done with the information provided by this distribution.
boolean circumfix constant dynamic hash infix integer interrupt junction list macro method modifier numeric order pair postfix prefix quanthash range regex sequence statement string sub syntax term thunky topic variable
boolean
Produces a Bool value: either True or False.
circumfix
Operators that consist of an opening and a closing tag, with their arguments between them.
constant
Refers to a constant defined by the Raku Programming Language.
dynamic
Variable lookups happen in the dynamic scope at execution (the current callstack) rather than lookups at compile time. Returns a Failure if the variable could not be found.
hash
Produces a Hash object.
infix
Operators that typically take two values, one to the left and one to the right of the operator.
integer
Produces an Int value.
interrupt
Interrupts the normal flow of execution.
junction
Produces a Junction object.
list
Produces a List or Array object.
macro
Syntax structures that may change the semantics of the code given at compile time.
method
A Callable with a name that takes an invocant as its first argument, and which is typically part of a class, role or grammar.
modifier
A syntax structure at the end of a statement that affects whether the statement will actually be executed.
numeric
Produces a Numeric value.
order
Produces an Order value, as in Less, Same or More.
pair
Produces a Pair object.
postfix
An operator that is placed after the argument it operates on.
prefix
An operator that is placed before the argument it operates on.
quanthash
May produce a QuantHash object (which is one of: Set, SetHash, Bag, BagHash, Mix, MixHash), or uses QuantHash semantics to return a Bool.
range
Produces a Range object.
regex
Related to Raku regexes (aka "regular expressions").
sequence
Produces a lazy Seq (sequence) object.
statement
A syntax structure at the start of a statement.
string
Produces a Str object.
sub
A Callable with a name that can be returned from.
syntax
A syntax element of the Raku Programming Language that typically doesn't have its own (visible) runtime component.
term
Elements of the Raku Programming Language that exists on their own and which are known to not accept any arguments.
thunky
Having special syntax handling causing it to not immediately be executed (like a Callable) but without having an independent scope.
topic
Either sets the topic variable ($_), or uses the topic variable as a default argument.
variable
Refers to a variable defined by the Raku Programming Language.
Raku Element Groups
Addenoid Bindoid Buildoid Condoid Constoid Declaroid Differentoid Dynamoid Equalish Expansive Feedoid Flippant Hyperoid IOoid Incremental Junctive Lexicoid Mathematicals Metaoid Methodic Mixoid Modifoid Multiplicoid Normaloid Orderoid Quantoid Rangoid Reductoid Replicant Sequoid Shortoid Stuboid Talkoid Termoid Throwoid Topicoid
Addenoid
The Addenoid group contains all infix operators that could be considered doing addition or substraction functions.
Coerces both sides to a Numeric value, and then adds them.
Coerces both sides to a Numeric value, and then substracts the right side from the left side.
Coerces both sides to a Str, and then concatenates them.
Coerces both sides to an Int value, and then does a bitwise AND.
Coerces both sides to an Int value, and then does a bitwise OR.
Coerces both sides to an Int value, and then does a bitwise XOR.
Coerces both sides to a Buffer value, and then does a bitwise AND and converts the result back to a Str.
Coerces both sides to a Buffer value, and then does a bitwise OR and converts the result back to a Str.
Coerces both sides to a Buffer value, and then does a bitwise XOR and converts the result back to a Str.
Coerces both sides to a Bool value, and then does a logical AND.
Coerces both sides to a Bool value, and then does a logical OR.
Coerces both sides to a Bool value, and then does a logical XOR.
Bindoid
The Bindoid group contains all macro-ish infix operators that perform raw binding, possibly into a container (which would make it an assignment).
Performs an assignment. The left side is supposed to be either a Scalar, a Positional with Scalar containers (typically an Array such as my @foo), or an Associative with Scalar containers (typically a Hash such as my %bar).
my $a = 42;
my @foo = 1,2,3,4,5;
my %bar = a => 42, b => 666, c => 137;
Performs a binding operation on the lexpad entry on the left. This is generally done to indicate that it is an immutable value, or if you want to alias one container to another.
my $b := 42; # immutable
my $c = 666;
my $d := $c; # alias
$d = 137;
say $c; # 137
Buildoid
The Buildoid group contains all elements that convert a given set of arguments into one of a Scalar, Pair, Positional or Associative object.
Indicates a named argument inside a Capture (for instance, as argument to a subroutine call). Otherwise it functions as a Pair constructor, with the left side being the key.
frobnicate(a => 42); # named argument
my $p = foo => 42; # Pair
Places all of its arguments in a List. Note that parentheses are not needed for a list to be created. The only exception is the empty List, which can be constructed by ().
Creates an Array out of the given arguments, typically used when assigning to a hash.
my %foo;
%foo<bar> = [1,2,3,4];
Either creates a Block object (if it looks like there is Raku code between the brackets), or a Hash built from its arguments (which is usually done when assigning to another Hash or Array)..
my &hello = { say "hello world" } # code, so Block
hello; # hello world
my @menu = { salad => 4.50 }, { steak => 22.50 } # args, so Hash
say @menu[0]<salad>; # 4.5
$( ) turn argument(s) into an item
@( ) turn argument(s) into a list
%( ) turn argument(s) into a hash
Condoid
The Condoid group contains the statement syntaxes to indicate conditional execution of code.
Depending on the condition (before the ??) produces the value of the expression between ?? and !! (if true) or the expression after !! if the condition was not true.
First of one or more blocks of conditional execution. Will execute the block if the condition was true.
Followup of if or another elsif, checked if the first (or previous) condition evaluated to false. Executes the associated block if true.
Final followup of if, elsif, with or orwith. Executes the associated block if none of the previous blocks were executed.
A single block of conditional execution, to be executed if the given condition evaluates to false.
Start of one or more blocks of conditional execution. Depending on whether the expression evaluates to a defined value, the block will be executed with the topic ($_) set to the value inside the block.
Followup of with or another orwith, checked if the first (or previous) expressions did not produce a defined value. Depending on whether the expression evaluates to a defined value, the block will be executed with the topic ($_) set to the value inside the block.
A single block of conditional execution, to be executed if the given expression evaluates to undefined value. Sets the topic ($_) with the value inside the block.
Execute the given block once int the given scope. The code:
once say "foo";
is equivalent to:
state $flag;
say "foo" unless $flag++;
Constoid
The Constoid group contains all constant that are always available for usage.
The type object for the current package (as created by package, module, class, role or grammar).
The type object for the current module. Available only if within a module scope.
The type object for the current class. Available only if within a class or grammar scope, or
The type object for the current role. Available only if within a role scope.
The number of spaces for a TAB character.
What a newline \n means. Can be set with the newline pragma.
The number of bits for native integers, usually 64.
The Routine object of the current sub, method or submethod.
The Block object associated with the current block (code between curly braces).
The (possibly auto-generated) object that performs the Distribution role, expected to contain information usually found in the META6.json file of a distribution. Only available if the compilation unit is executed as a module, not as a program. Otherwise Nil.
Declaroid
The Declaroid group contains the syntax for indicating the scope of an element to be defined.
Differentoid
The Differentoid group contains the infix operators that return True if the compared elements are different in a way, and False if they are considered equal in that way.
before generic less
< numerically less
lt alphabetically less
<= numerically less or equal
le alphabetically less or equal
!= numeric inequality
ne string inequality
>= numerically more or equal
ge alphabetically more or equal
> numerically more
gt alphabetically more
after generic more
!(elem) is not element in
!(cont) does not contain element
!(<) is not a strict quanthash subset
!(<=) is not a quanthash subset
!(==) quanthash inequality
!(>=) is not a quanthash superset
!(>) is not a strict quanthash superset
Dynamoid
The Dynamoid group contains all variables that are always available either in the dynamic scope (looking up the callstack), or in the GLOBAL:: or PROCESS:: stashes. All of these variable can be shadowed by lexically defined variables with the same name.
The file handle for reading input, e.g. with .lines or .slurp.
The file handle for writing standard output to, e.g. with say.
The file handle for writing error output to, e.g. with note.
A hash that contains all of the environment variables of the operating system when Raku is started. May be altered. Serves as a default for environment variables for any forked process.
The Instant the raku process was started.
An IO::Path object that contains the directory that should be considered to be the current working directory. Initialized with the OS's current directory at startup.
An integer value for the PID of the current process.
A string presentation of the path of the currently executing Raku program.
An IO::Path of the currently executing Raku program. Available at compile time, and can thus be used as part of a use lib statement.
use lib $*PROGRAM.sibling("lib");
An IO::Path of the currently running Raku executable (typically "rakudo"). Can be used as the initial argument to e.g. run.
An IntStr with information about the current user (uid and name).
An IntStr with group information about the current user (gid and name) if supported by the operating system.
Equalish
The Equalish group contains the infix operators that return True if the compared elements are considered equal in a way, and False if they are considered different in that way.
Performs a smart-match on the given arguments. Technically, this is calling the .ACCEPTS method on the right side, giving it the left side as the positional argument. Which usually results in a Bool value.
Performs a deep equivalence check logically dependent on the .raku representation.
Coerces both sides to a string and returns True if the resulting strings are equal. Else False.
Coerces both sides to a Numeric value, and then returns True if they are the same. Else False.
Coerces both sides to a Numeric value, and then returns True if they are the same within $*TOLERANCE (defaults to 1e-15). Else False.
Decontainerizes both sides, and then returns True if both sides are the same object. Else False.
Returns True if both sides are the same object without decontainerization. Else False.
Returns True if all values on the left side are part of the right side, using QuantHash semantics. Else False.
Returns True if all values on the right side are part of the left side, using QuantHash semantics. Else False.
Returns True if all values on the left side are part of the right side and the right side has more values, using QuantHash semantics. Else False.
Returns True if all values on the left side are part of the right side, using QuantHash semantics. Else False.
Returns True if both sides contain the same valuies, using QuantHash semantics. Else False.
Returns True if all values on the right side are part of the left side, using QuantHash semantics. Else False.
Returns True if all values on the right side are part of the left side and the left side has more values, using QuantHash semantics. Else False.
Expansive
The Expansive group contains the postfix operators that expand on numeric values.
4i is the same as 0+4i. Needs grouping for variables ($a)i because otherwise the i will be considered part of the variable name.
So $a² is the same as $a ** 2, etc. Any of ⁰¹²³⁴⁵⁶⁷⁸⁹⁺¯¯ may be used.
Feedoid
The Feedoid group contains the operators that provide an alternate syntax for creating a sequence of operations, where the result of one such operation become the argument(s) for the next operation.
(1,2,3,4) ==> sum() ==> say() as opposed to say sum (1,2,3,4) or (1,2,3,4).sum.say.
say() <== sum() <== (1,2,3,4) as opposed to say sum (1,2,3,4) or (1,2,3,4).sum.say.
Flippant
The Flippant group contains the operators that produce True or False depending on multiple conditions.
Hyperoid
The Hyperoid group contains the operators that take the name of an infix operator and repeatedly perform that operator on the provided argument list(s).
Repeat the operation on each of the associated elements of two Iterables with the same number of elements. Throws an exception if they are not equal.
Repeat the operation on each of the associated elements of two Iterables for each element on the left side. Missing values on the right side will be repeated.
Repeat the operation on each of the associated elements of two Iterables for each element on the right side. Missing values on the left side will be repeated.
Repeat the operation on each of the associated elements of two Iterables for each element on the side with the most elements. Missing values on the other side will be repeated.
[Zop produce operator result, shortest side leading](Default for op is ,)
[Xop produce operator result for combinations](Default for op is ,)
IOoid
The IOoid group contains the functions that are available for input / output of data.
get Read a line from C<$*STDIN> / C<$*ARGFILES>
getc Read a character from C<$*STDIN> / C<$*ARGFILES>
read Read bytes from an IO::Handle
write Write bytes to an IO::Handle
slurp Read entire contents of IO::Path / IO::Handle
spurt Replace content of IO::Path / IO::Handle with argument
Incremental
The Incremental group contains the infix operators for incrementing / decrementing (usually) numeric values.
The atomic versions of -- and ++ were implemented for 6.d. They can only be applied to atomic integers.
++ pre-increment by 1
⚛++ atomic pre-increment by 1
-- pre-decrement by 1
⚛-- atomic pre-decrement by 1
++ post-increment by 1
⚛++ atomic post-increment by 1
-- post-decrement by 1
⚛-- atomic post-decrement by 1
Junctive
The Junctive group contains the infix operators and the functions that produce Junction objects.
& junctive all
| junctive any
^ junctive one
all junctive all
any junctive any
one junctive one
none junctive none
Lexicoid
The Lexicoid group contains all variables that are always available for usage in a lexical scope.
The anonymous state variable can be used without an explicit state declaration. Each reference to $ within a lexical scope is in effect a separate variable.
Every block has its own topic variable. It can be set directly, or is set automatically with statements such as given, with and for.
Results of many actions related to regular expressions set this variable. Each Routine has its own copy of it. It also provides Positional functionality, so that $/[0] refers to the first positional capture (which can be shortened to $0). And it also provides the Associative functionality so that that $/<foo> refers to the named capture "foo" (which can be shortened to $<foo>.
Typically contains the last caught exception seen. Each Routine has its own copy of it.
Mathematicals
The Mathematicals group contains the mathematical terms that are provided by the core.
pi The number π (3.1415...)
tau The number τ (6.2831...)
e Euler's number (2.7182...)
i The imaginary unit (√-1)
Inf Infinity
The Metaoid group contains the meta operators that take an infix operator and do something special with its result or its arguments.
op= store result of infix operator on left side
Rop produce result of infix operator with arguments reversed
!op negate result of iffy infix operator on arguments
Methodic
The Methodic group contains the ways a method can be called on an object.
Dotted postfix operators must be followed by a method name or a subroutine name prefixed with & (possibly fully qualified), a postfix operator, a prefix operator within :<>, or one of the postcircumfixes ( ) [ ] { } < > « ».
.method method call
. method dotty infix method call
.?method call method if any
.*method call all methods if any
.+method call all methods
!method private method call
.=method incovant mutating method call
Mixoid
The Mixoid group contains the functions that allow mixing in functionality into an existing class or instantiation.
does mutating role mixin
but cloning role mixin
Modifoid
The Modifoid group contains the statement modifiers to indicate conditional execution of the preceding thunk.
Executes the thunk if the condition is true.
Executes the thunk if the condition is false.
Execute thunk if given expression produces a defined value, sets topic inside thunk.
Execute thunk if given expression does not produce a defined value, sets topic inside thunk.
Execute thunk if given expression smartmatches with the topic ($_).
Multiplicoid
The Multiplicoid group contains all infix operators that are related to multiplication in some way.
div integer divide
mod integer modulus
gcd greatest common divisor
lcm lowest common multiple
* multiply
/ divide
** exponentiation
% modulus
%% is divisible
+< integer shift left
+> integer shift right
Normaloid
The Normaloid group contains the operators that somehow normalize the given arguments into something else, either in time or in value.
+ numerify
+^ numeric complement
- numeric negation
^ numeric from zero upto
~ stringify
? boolify
so low precedence boolify
! boolean negation
not low precedence boolean negation
// is defined
The meaning of prefix | was expanded in 6.c to be beyond the use within signatures, to mean converting any iterable to a Slip (a special type of list that will always be iterated).
Ensures the latest update of a value in the target is produced in multi-threaded situations.
Orderoid
The Orderoid group contains the infix operators that return an Order value.
cmp equivalence order comparison
<=> numerical order comparison
leg string order comparison
Quantoid
The Quantoid group contains the functions that return a QuantHash (a Set, SetHash, Bag, BagHash, Mix or MixHash given any set or arguments.
∅ empty Set
(|) quanthash union
(+) quanthash addition
(.) quanthash multiplication
(-) quanthash difference
(^) quanthash symmetric difference
Rangoid
The Rangoid group contains the infix operators that produce a Range.
.. range inclusive
^.. range excluding start
..^ range excluding end
^..^ range exclusive
minmax range including min and max value
Reductoid
The Reductoid group contains the functions that reduce a given set of arguments into a single value (or produces the steps to produce that value).
min reduce values to smallest value
max reduce values to largest value
[op] reduce using given infix operator
[\op] produce steps of reduction using given infix operator
Replicant
The Replicant group contains the infix operators that reproduce the left value repeatedly.
x string repetition
xx item repetition
Sequoid
The Sequoid group contains the infix operators that create a smart sequence (one that inspect the arguments and interpretes special, almost magic, meaning).
... smart sequence inclusive
^... smart sequence excluding start
...^ smart sequence excluding end
^...^ smart sequence exclusive
Shortoid
The Shortoid group contains the infixish macros that exhibit short-cicuiting behaviour, where the right hand side will not be evaluated if a certain condition on the left hand side was met.
&& high precedence logical AND
and low precedence logical AND
|| high precedence logical OR
or low precedence logical OR
^^ high precedence logical XOR
xor low precedence logical XOR
// high precedence is defined OR
notandthen Empty if first defined, else last
Stuboid
The Stuboid group contains the functionality that can be used to indicate that code will need to be added at a later time (e.g. in the development cycle of the code), or at compilation time by mixing in a role.
??? warn about stub code executed
... fail with stub code executed error
!!! die with stub code executed error
Talkoid
The Talkoid group contains the functions that are generally used to display messages to a user.
print stringify argument(s), write to $*STDOUT
say create gist of argument(s), add newline, write to $*STDOUT
put stringify argument(s), add newline, write to $*STDOUT
note create gist of argument(s), add newline, write to $*STDERR
Termoid
The Termoid group contains the functions that act as a term, but do not produce a constant value.
self invocant in method
rand pseudo-random Num in range
now Instant of current time
time POSIX time in seconds
nano POSIX time in nano seconds
Throwoid
The Throwoid group contains the functions that somehow interrupt the normal flow of execution either very noticeably, or very much under the hood.
die halt execution, or be caught by CATCH
warn show error message, or be caught by CONTROL
fail return from Routine with Failure, or be caught by CATCH
return return from Routine with given value, or be caught by CONTROL
next proceed with next iteration, or be caught by CONTROL
redo restart current iteration, or be caught by CONTROL
last stop iterating, or be caught by CONTROL
proceed continue with next when/default, or be caught by CONTROL
succeed continue after last when/default, or be caught by CONTROL
done call "done" callback on taps, or be caught by CONTROL
emit emit given value to active supply, or be caught by CONTROL
take produce a value in a gather sequence, or be caught by CONTROL
Topicoid
The Topicoid group contains the functions that topicalize (set $_) in some situations.
given topicalize argument for scope
when if smartmatched topicalize argument for scope
andthen topic topicalize left for right thunk
orelse topic low precedence if defined OR, topicalizing left for right thunk
RESOURCE FILES
This distribution keeps all of the text files as resources, to be read when they are needed (as opposed to keeping them all in the binary).
The resources directory contains a groups directory that contains all of the information for each group in a separat file.
The format of the group file is very simple line based.
All entries are separated by an empty line. The first line contains the names of the element separated by the string | (space, pipe, space). There must be at least one name. The first name becomes the name of the element, the others become aliases.
The second line contains theo tags as space separated words. There must be at least a single tag.
The third line contains the tagline of the element.
The fourth line (if not empty) contains the URL for more information,
Any other lines until an empty line, contains the description of the element. It may contain RakuDoc markup codes.
If the first line is empty, then the rest of the file contains the description of the group (so you can recognize the description as the text after the first 2 empty lines). It may contain RakuDoc markup codes. If there are no 2 empty lines, then there is no description (yet) for the group.
The whole text of a tag file becomes the .description of the tag with the name of the file.
AUTHOR
Elizabeth Mattijsen liz@raku.rocks
Source can be located at: https://github.com/lizmat/Raku-Elements . Comments and Pull Requests are welcome.
If you like this module, or what I’m doing more generally, committing to a small sponsorship would mean a great deal to me!
COPYRIGHT AND LICENSE
Copyright 2025 Elizabeth Mattijsen
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.