use Terminal::ANSIColor, but Compiler Explorer doesn't have raku libraries yet. For this case it doesn't really matter that it only supports green and red, and trying to choose any other color just makes no text come out at all 
Raku RSS Feeds
Elizabeth Mattijsen (Libera: lizmat #raku) / 2025-06-21T01:59:25
A few weeks ago I was chatting with coralina and she linked me 4:19 of The Zipf Mystery but every time he repeats a word it loops.
It's an instance of a meme format I don't think I had seen before. The basic conceit is, as the title states, every time a word that has been said before is said again, the video loops back to that time.
As I interpret it, the instances of words inside of looped sections don't count for determining the "last time" each word has been said, though it's only a little extra work to implement that interpretation as well.
As a Rakunaut it of course didn't take me long to make an attempt at implementing a script that turns a bit of text into the "but every time it repeats a word it loops it repeats the text in between".
After a bit of hacking, I fed the introductory paragraph of the raku website into my script and got the following result. Each time a repetition is done, the word that caused the repetition is printed in red blue, and the repeated text is printed in green:
There's definitely some funny bits in there. My favorites include:
You can help too. The only requirement is Camelia.
You can help too. The only requirement is that you can
help too. The only requirement is that you know how to be developed.
Go to #raku (irc.libera.chat) and someone will be glad to help you know how to be nice to all kinds of people (and butterflies).
I think I might make a recording of reading the text and edit it to do the correct looping, maybe I'll see if Whisper can give precise per-word timestamps that I could turn into a command line with sox or ffmpeg to create the final result.
But for now, I'll go through the actual code I used for this. You can already look at and play with the final version on Compiler Explorer here.
The version I linked to on Compiler Explorer begins with a tiny implementation of Terminal::ANSIColor's sub colored:
The alternative is of course to use Terminal::ANSIColor, but Compiler Explorer doesn't have raku libraries yet. For this case it doesn't really matter that it only supports green and red, and trying to choose any other color just makes no text come out at all
Oh and to top it off, I accidentally switched the codes for green and red around in the sub, and I have the same switch-around in the code that uses the sub, so both mistakes cancel each other out here. Don't look too closely, haha 
Next is the text we want to put in. Since I was prototyping this with my code editor (vim) and executing it again after making a change, I didn't want to paste the source text in every time. For that reason, the input text is part of the source file, instead of reading from $*IN (aka stdin). It could have gone into a separate file as well just as easily with my @input = "text.txt".IO.words for example.
I chose the Q quoting construct here with square brackets because square brackets aren't in the source text, but using heredocs with Q:to/INPUT-TEXT/ for example would have been just as clean.
In that case, the .words can go directly after the Q while the input text goes below, with indentation if you like, followed by a line with just INPUT-TEXT in it. The .words method makes line wrapping and indentation in the output
Next up, we do a loop over the input array. Using the .pairs method on the array will give us a Pair object each iteration that has a .key with the index of the item and a .value of the word in question.
The result of the for loop goes directly into a result variable. For that purpose, we take the for that by itself is a statement and adapt it into an expression with the do prefix. That lets us put the result of every iteration directly into our array:
You can see that instead of giving a variable to put the pair object into, we just use the default, which is $_, the "topic variable". This lets us refer to .key and .value just like that.
Next up, inside the for loop we declare a state variable to hold information about words we've seen already. A state variable behaves like a variable you declared outside of the loop in terms of keeping values from one round to the next, but is only visible inside of the curly braces. I find that this makes it a bit clearer where the variable belongs. After the loop it is no longer relevant, and trying to address it there is just a case of "undeclared variable".
I mentioned earlier that the .words method gives us a list of consecutive non-whitespace, and that includes punctuation. We don't want the punctuation to be counted when looking up when a word was seen the last time, and also want to count capitalized and lower cased versions of words as the same, so we normalize the words before looking them up or storing them in our %last hash:
We use a simple regex with the .comb method that gives us every alphabetical character from the input, joins them into one string without spaces, and turns it into fold-case (it's kind of like lower case, but different for some scripts.)
The next few lines set up the logic to put the index we saw the word at into the hash. Since we want to get whatever was already in the hash before we assign the new value, we have a few ways to make that happen, but the implementation I chose here is a LEAVE block, which is executed when the body of the loop has finished.
I made the choice to use LEAVE rather than just putting the code at the end of the block because I'm also using the last statement of the loop body to give the value that the for loop puts into the result list.
The block itself is pretty straight-forward:
When leaving the for block, we set the value in %last for the $keyword to the .key, i.e. the index of the word from the input list.
We're almost done! 
We now want to grab a "previous position" from the hash, if it exists, and make the repetition happen. Otherwise, the word just goes straight through to the result:
The with construct lets us check a value for definedness and assign it into a variable for the block.
The if statement can do the same variable assignment, but it checks for truth value. The very first word in our array would have the index 0, which would count as False, and not execute the block.
So for the result of our iteration in case there is a previous position for our keyword should be the word itself, followed by the repeated content. $prevp is the index where the current word was seen before and .key will give us the current index. We use ^.. which creates a Range just like .., but skips the first value.
We use colored for the .value as well as every word we copied out of the @input list with the [] postcircumfix operator to make the first word green and the copied words red respectively.
Now that I've looked at the code again and again for writing this post, it occurs to me that there's not really a good reason to pass every word individually through the colored sub with a map. Instead, I could have turned the list I took out of the @input array into a String joined by spaces, which is conveniently exactly what the .Str method on it would do. That can then be fed into colored and we've saved maybe a third of the whole line.
Ah well, what can you do! I'm not really golfing the code down to the shortest it could possibly be. It would probably look a bit different if I did 
For the case where we didn't actually have an entry in the %last hash yet for the $keyword we would land in the else branch of this construct. We take the value we got into a named variable so that our $_ doesn't get scribbled over. We could still refer to the $_ from the outer block with $OUTER::_ but I thought that's less pleasing.
All that this block needs to do is get the .value out from the pair so it's just the word, and it's done!
Here's the whole loop in one uninterrupted piece:
Now all that's left is to print it out to the terminal.
Just putting the text on the screen as one long string doesn't look good, so I want it word-wrapped. There is a method called naive-word-wrapper on the Str class, however it is marked is implementation-detail.
What that means is that we get no guarantees that it will stay around, or behave the same on a different version of rakudo. It's also not expected to be present on other implementations of Raku. For this use case, I think it's totally fine. If the method is gone, we can just output the string without any wrapping of words, and maybe expect our caller to pipe it through some program that does word wrapping.
Incidentally, when trying that out, I found that neither fmt nor par understand that ANSI color formatting codes have zero visible width when printed 
Even though the naive-word-wrapper implements greedy line wrapping like fmt rather than an algorithm that tries to find a globally optimal solution for how many words should go on each line which par has, the result still looks a lot more correct since it actually strips color formatting codes before doing its calculations 
Again, you can copy out or play with the whole code, put in your own input text, try to make the code shorter, or whatever you like by following this link to Compiler Explorer.
Normally I'd tell you to leave a comment if you liked the post, but I haven't set up anything yet that would make that easy. Maybe soon I will have the experimental Ghost ActivityPub thing running? But until then, you can reply to this toot.
If you don't have an account that can post to the fediverse, you can also find me on IRC, on the raku mailing list, and if there's a discussion on one of the typical social media discussion sites I might see it.
I hope you'll come back when I publish my next post! Don't forget this blog has an RSS feed 
Hi! It's me again, the timotimo you may know & love from the Raku community.
I used to have a blog years ago when I was writing and posting reports for a TPF Grant for the Rakudo / MoarVM profilers, and some other stuff related to Rakudo and MoarVM development.
At some point I stopped taking care of the blog, and shut down the webspace.
Well, I had an export of the blog from back then, so I imported that in this fresh instance of Ghost. Some images, mostly screenshots, didn't make it into the export, unfortunately. The posts are back, and I believe the old URLs are still valid where they were linking to my blog.
I'm also planning to write more posts again in the future, so stay tuned, keep your RSS / ATOM feed reader aimed at my blog, or maybe you're already subscribed to the raku weekly blog, which many of my posts will hopefully be mentioned in 
So for now, take care and you'll read from me soon!
The Raku Programming Language was originally started as the next version of the Perl Programming Language (then at version 5.6.0, now at 5.40.2). Unfortunately the implementation of this next version took much longer than expected. In the eyes of many Perl users the new version also changed the character of the language, which caused a rift in the Perl community.
When in late 2015 the initial release of what was then called "Perl6" came out, the rift only deepened: not wanting to relinquish the "Perl6" nomer was felt by many in the Perl community as name squatting. In late 2019 the name squatting issue was resolved by changing the name of "Perl6" to the "Raku Programming Language".
Open source projects that exist beyond the scope of their original developer need to have a way to be represented, and usually also a way to finance vital project infrastructure: technical infrastructure (such as providing websites and testing services), as well as organisational infrastructure (such as regular user events, Code of Conduct -both online and at events-, and project course decisions) and developmental support (such as grants).
Because of Raku's historical roots, this has been taken care of (or was sponsored by) Yet Another Society (or YAS, to most better known as "TPF" or "The Perl Foundation"). After the name change of the language, YAS acquired a new alias: "The Perl and Raku Foundation" (or short: TPRF). But it has always felt like a remnant of historical connection that Raku had with Perl, rather than something that was a natural result of the developing situation.
Keeping an Open Source foundation running requires volunteers willing to spend a sizeable amount of their free time on foundation matters. And it requires a source of funds to keep the foundation in working order.
Historically YAS has received funding from many sources. Initially to support just Perl, later this was separated into support for Perl 5 and what was to be Perl 6. Over the years it has become more difficult for YAS to obtain funding. And has not received much funding for what is now Raku: there are probably many reasons for that, one of them being that Raku as a separate target for funding is not very visible on the foundation's website.
Now, more than five years after the name change, it feels like a good time for the Raku community to be standing on its own feet, without support by YAS. After several weeks of discussing this with several people involved in YAS and the Raku Community, I hereby announce the intent to set up a completely separate Raku Foundation, based in Europe, but global in reach.
This would allow YAS to be fully focussing on the one programming language that instigated the creation of the foundation: Perl. And it would allow the Raku Community to be served by a foundation that is solely dedicated to the Raku Programming Language.
To gather comments and suggestions about this proposed endeavour, I have opened a problem solving issue in which hopefully many will let their opinions be known. If you don't have a Github account, please send an email to [email protected]: I will then include your comments / opinions on the issue.
Founding a non-profit foundation that is supported by donations, is a bit of a chicken / egg situation: one needs to pay some instances (such as a notary public, and possibly some other regulatory instances). I volunteer to be advancing these costs to make this process easier. As soon as the foundation is set up, a bank account can be opened, and a website can be set up with a donate button linked to the foundation's bank account.
And hopefully, YAS will be able to fund such a Raku Foundation with the remaining funds earmarked for Raku. Which should really give such a Raku Foundation a boost, both financially as well as from a PR point of view.
A foundation needs to have bylaws, which need to be approved by a notary public. The regulations of a foundation can be changed by the board, provided they are not in conflict with the bylaws. It is therefore customary to keep the bylaws simple and general, usually in the language of the country in which it is founded. And have the board adjust the regulations as necessary over time.
A foundation needs board members. A small number of them need to be registered as the legal board: others may be appointed by the board without needing formal registration. Who could be a board member? I'm thinking of people who in the past have been (deeply) involved in the development of what is now Raku, but who have drifted away from active development. But still have a place for Raku in their heart. Please let it be known in a comment if any of this applies to you, and you want to become a board member! Or if you know of someone who you think would be a good board member.
The copyright of the Raku Programming Language currently lies with YAS. Whether or not this copyright should be passed on to a Raku Foundation, is something that should be figured out whether that is a. possible, and b. a good thing to do.
One of the big challenges coming up for Open Source communities, is the upcoming enforcement of the Cyber Resilience Act in 2027. I believe a strong Raku Foundation will be able to take advantage of the opportunities this act brings to Open Source communities by being an Open Source Steward for the Raku Community.
Please check out the problem solving issue and let us know your thoughts!
It looks like AI has reached Raku: in the article Let’s Teach An LLM To Write A New Programming Language Matt of the Nurture the Vibe website shows how an LLM can be created to write programs in the Raku Programming Language. The flood of new modules this week shows that at least one person was paying attention.
Fernando Correa de Oliveira blogged about Deps, a minimalist Raku module for exploring dependency injection patterns through a clear, trait-based API (/r/rakulang comments).
Anton Antonov published part 2 and 3 of the LLM Function calling workflows series:
Steve Roe has published another HARC Stack blog post, this time about setting up a Hamburgers menu, and how Air makes life easy for the HARC Stack website developer!
A gist that Ralph Mellor posted a few years ago about Raku’s metamodel called “Raku’s core” got quite a lot of attention on the interwebs the past week: on lobste.rs, on /r/programming.
The video of Herbert Breunung‘s presentation at the German Workshop called “Raku Quiz” has been published (German spoken).
Weekly Challenge #325 and #326 are available for your perusal.
slurp() for small files, and made nqp::normalizecodes be more memory efficient.In RakuAST developments in the past 2 weeks:
IMPL-WRAP-LIST, and, together with Stefan Seifert, fixed a really pesky issue with EVAL at BEGIN-time.$?CHECKSUM (a checksum of the source) and $?SOURCE compiler variables (the actual source from which the bytecode of the compilation unit was compiled), fixed an issue with --rakudoc, made the environment variable RAKU_LANG_VERSION actually work, and fixed several issues that would have showed up if the default language version would be 6.e.use statement.About a week ago, a large number of new modules authored by Danslav Slavenskoj started appearing completely out of the blue. The sheer magnitude of new modules (about 3 per day), as well as the size of the code and documentation produced, points to the use of AI in the creation of these modules.
Thank you all for your patience! The second Raku Core Summit was a packed long weekend of discussions and hacking, about which some blog posts will appear in the coming week(s). Please stay tuned!
Please keep staying safe and healthy, and keep up the good work! Even after week 20/21 of hopefully only 209.
Meanwhile, still: Слава Україні! Героям слава!
If you like what I’m doing, committing to a small sponsorship would mean a great deal!
This is the seventh of the HARC Stack essays. Previous <=
As you know, HARC Stack combines HTMX with raku Air, Red and Cro to supply a fresh approach to web design.
Go on take a look at the HARC Stack again … maybe open in a new browser window. Here’s the source code for that site (you may want to zoom your browser):
So – pretty good to see an entire, yet simple website written with clarity in a way that is easy to comprehend and to maintain. I hope that this is why you are here – if you like complex and confusing there are other front end frameworks!
We have encountered many of these blocks already:
Now – downsize the site in your browser window – maybe open the responsive developer tools and select iPhone, or just slide over a window edge.
WTF – a Hamburger menu for smaller screens. Where did that come from.
Digs around in the Pico CSS nav docs , since HARC stack leans heavily into Pico CSS for semantic styles. Yet not a hint of hamburger.
So – you guessed, the Air::Base role Nav supplies an automatic responsive hamburger that auto appears on the same size breaks as the Pico CSS standard.
Another Nav item, seem as the sun/moon icon at the right end of the nav bar is the Air::Base role LightDark does Widget {}.
Have a monkey around… you should see something like this:
This time Pico CSS provides a bit more help. Turns out the way to trigger the Pico light or dark modes is via the html tag:
<html lang="en" data-theme="dark">The initial thought was to use HTMX to swap this attribute in / out according to the setting … but that failed for a few reasons:
<html> tagSo – HARC stack ships with a Light Dark Mode Widget that does all this for you ;-).
For those who are students of JavaScript this is done with the following code:
Really HARC Stack adheres to the Keep It Simple, Stupid philosophy. We have to, after all we are Grug-brained developers.
Keep watching this channel if it feels good. Next time we are going to start lifting the abstractions to Air::Components and introduce the power of raku Red. Even better, follow the Getting Started and try it out for yourself.
As usual, comments and feedback welcome. We are a friendly bunch over on the raku IRC chat and Discord.
~librasteve
This document (notebook) shows how to efficiently do streamlined Function Calling workflows with Large Language Models (LLMs) of Gemini.
The Raku package “WWW::Gemini”, [AAp2], is used.
The rest of the document gives concrete code how to do streamline multiple-tool function calling with Gemini’s LLMs using Raku. Gemini’s function calling example “Parallel Function Calling”, [Gem1], is followed.
This document belongs to a collection of documents describing how to do LLM function calling with Raku.
Compared to the previously described LLM workflows with OpenAI, [AA1], and Gemini, [AA2], the Gemini LLM workflow in this document demonstrates:
The streamlining is achieved by using the provided by “LLM::Functions”, [AAp3]:
LLM::Tool, LLM::ToolRequest, and LLM::ToolResultllm-tool-definition and generate-llm-tool-result
Load packages:
use JSON::Fast;
use Data::Reshapers;
use Data::TypeSystem;
use LLM::Tooling;
use WWW::Gemini;
Choose a model:
my $model = "gemini-2.0-flash";
Define a few subs — tools — with sub- and argument descriptions (i.e. attached Pod values, or declarator blocks):
#| Powers the spinning disco ball.
sub power-disco-ball-impl(
Int:D $power #= Whether to turn the disco ball on or off.
) returns Hash {
return { status => "Disco ball powered " ~ ($power ?? 'on' !! 'off') };
}
#= A status dictionary indicating the current state.
#| Play some music matching the specified parameters.
sub start-music-impl(
Int:D $energetic, #= Whether the music is energetic or not.
Int:D $loud #= Whether the music is loud or not.
) returns Hash {
my $music-type = $energetic ?? 'energetic' !! 'chill';
my $volume = $loud ?? 'loud' !! 'quiet';
return { music_type => $music-type, volume => $volume };
#= A dictionary containing the music settings.
}
#| Dim the lights.
sub dim-lights-impl(
Numeric:D $brightness #= The brightness of the lights, 0.0 is off, 1.0 is full.
) returns Hash {
return { brightness => $brightness };
}
#= A dictionary containing the new brightness setting.
Remark: See the corresponding Python definitions in the section “Parallel Function Calling” of [Gem1].
The sub llm-tool-definition can be used to automatically generate the Raku-hashmaps or JSON-strings of the tool descriptors in the (somewhat universal) format required by LLMs:
llm-tool-definition(&dim-lights-impl, format => 'json')
# {
# "function": {
# "type": "function",
# "name": "dim-lights-impl",
# "strict": true,
# "description": "Dim the lights.",
# "parameters": {
# "required": [
# "$brightness"
# ],
# "additionalProperties": false,
# "type": "object",
# "properties": {
# "$brightness": {
# "type": "number",
# "description": "The brightness of the lights, 0.0 is off, 1.0 is full."
# }
# }
# }
# },
# "type": "function"
# }
Remark: The sub llm-tool-description is invoked in LLM::Tool.new. Hence (ideally) llm-tool-description would not be user-invoked that often.
These are the tool descriptions to be communicated to Gemini:
my @tools =
{
:name("power-disco-ball-impl"),
:description("Powers the spinning disco ball."),
:parameters(
{
:type("object")
:properties( {"\$power" => {:description("Whether to turn the disco ball on or off."), :type("integer")}}),
:required(["\$power"]),
}),
},
{
:name("start-music-impl"),
:description("Play some music matching the specified parameters."),
:parameters(
{
:type("object")
:properties({
"\$energetic" => {:description("Whether the music is energetic or not."), :type("integer")},
"\$loud" => {:description("Whether the music is loud or not."), :type("integer")}
}),
:required(["\$energetic", "\$loud"]),
}),
},
{
:name("dim-lights-impl"),
:description("Dim the lights."),
:parameters(
{
:type("object")
:properties({"\$brightness" => {:description("The brightness of the lights, 0.0 is off, 1.0 is full."), :type("number")}}),
:required(["\$brightness"]),
}),
};
deduce-type(@tools)
# Vector(Struct([description, name, parameters], [Str, Str, Hash]), 3)
Here are additional tool-mode configurations (see “Function calling modes” of [Gem1]):
my %toolConfig =
functionCallingConfig => {
mode => "ANY",
allowedFunctionNames => <power-disco-ball-impl start-music-impl dim-lights-impl>
};
# {functionCallingConfig => {allowedFunctionNames => (power-disco-ball-impl start-music-impl dim-lights-impl), mode => ANY}}
Initialize messages:
# User prompt
my $prompt = 'Turn this place into a party!';
# Prepare the API request payload
my @messages = [{role => 'user',parts => [ %( text => $prompt ) ]}, ];
# [{parts => [text => Turn this place into a party!], role => user}]
Send the first chat completion request:
my $response = gemini-generate-content(
@messages,
:$model,
:@tools,
:%toolConfig
);
deduce-type($response)
# Struct([candidates, modelVersion, responseId, usageMetadata], [Hash, Str, Str, Hash])
deduce-type($response)
# Struct([candidates, modelVersion, responseId, usageMetadata], [Hash, Str, Str, Hash])
The response is already parsed from JSON to Raku. Here is its JSON form:
to-json($response)
# {
# "candidates": [
# {
# "avgLogprobs": -0.0012976408004760742,
# "content": {
# "parts": [
# {
# "functionCall": {
# "name": "start-music-impl",
# "args": {
# "$energetic": 1,
# "$loud": 1
# }
# }
# },
# {
# "functionCall": {
# "name": "power-disco-ball-impl",
# "args": {
# "$power": 1
# }
# }
# },
# {
# "functionCall": {
# "args": {
# "$brightness": 0.5
# },
# "name": "dim-lights-impl"
# }
# }
# ],
# "role": "model"
# },
# "safetyRatings": [
# {
# "probability": "NEGLIGIBLE",
# "category": "HARM_CATEGORY_HATE_SPEECH"
# },
# {
# "probability": "NEGLIGIBLE",
# "category": "HARM_CATEGORY_DANGEROUS_CONTENT"
# },
# {
# "probability": "NEGLIGIBLE",
# "category": "HARM_CATEGORY_HARASSMENT"
# },
# {
# "probability": "NEGLIGIBLE",
# "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT"
# }
# ],
# "finishReason": "STOP"
# }
# ],
# "usageMetadata": {
# "candidatesTokensDetails": [
# {
# "tokenCount": 30,
# "modality": "TEXT"
# }
# ],
# "promptTokensDetails": [
# {
# "tokenCount": 113,
# "modality": "TEXT"
# }
# ],
# "promptTokenCount": 113,
# "candidatesTokenCount": 30,
# "totalTokenCount": 143
# },
# "responseId": "sOxFaOrFF-SfnvgPgITLqQ8",
# "modelVersion": "gemini-2.0-flash"
# }
The following copy of the messages is not required, but it makes repeated experiments easier:
my @messages2 = @messages;
# [{parts => [text => Turn this place into a party!], role => user}]
Let us define an LLM::Tool object for each tool:
my @toolObjects = [&power-disco-ball-impl, &start-music-impl, &dim-lights-impl].map({ LLM::Tool.new($_) });
.say for @toolObjects
# LLMTool(power-disco-ball-impl, Powers the spinning disco ball.)
# LLMTool(start-music-impl, Play some music matching the specified parameters.)
# LLMTool(dim-lights-impl, Dim the lights.)
Make an LLM::Request object for each request from the (first) LLM response:
my @requestObjects = $response<candidates>»<content>»<parts>.&flatten»<functionCall>.map({ LLM::ToolRequest.new( $_<name>, $_<args>) });
.say for @requestObjects
# LLMToolRequest(start-music-impl, :$loud(1), :$energetic(1), :id(Whatever))
# LLMToolRequest(power-disco-ball-impl, :$power(1), :id(Whatever))
# LLMToolRequest(dim-lights-impl, :$brightness(0.5), :id(Whatever))
Using the relevant tool for each request compute tool’s response (which are LLM::ToolResponse objects):
.say for @requestObjects.map({ generate-llm-tool-response(@toolObjects, $_) })».output
# {music_type => energetic, volume => loud}
# {status => Disco ball powered on}
# {brightness => 0.5}
Alternatively, the LLM::ToolResponse objects can be converted into hashmaps structured according a particular LLM function calling style (Gemini in this case):
.say for @requestObjects.map({ generate-llm-tool-response(@toolObjects, $_) })».Hash('Gemini')
# {functionResponse => {name => start-music-impl, response => {content => {music_type => energetic, volume => loud}}}}
# {functionResponse => {name => power-disco-ball-impl, response => {content => {status => Disco ball powered on}}}}
# {functionResponse => {name => dim-lights-impl, response => {content => {brightness => 0.5}}}}
Process the response:
my $assistant-message = $response<candidates>[0]<content>;
if $assistant-message<parts> {
# Find function call parts and make corresponding tool objects
my @requestObjects;
for |$assistant-message<parts> -> %part {
if %part<functionCall> {
@requestObjects.push: LLM::ToolRequest.new( %part<functionCall><name>, %part<functionCall><args> )
}
}
# Add assistance message
@messages2.push($assistant-message);
# Compute tool responses
my @funcParts = @requestObjects.map({ generate-llm-tool-response(@toolObjects, $_) })».Hash('Gemini');
# Make and add the user response
my %function-response =
role => 'user',
parts => @funcParts;
@messages2.push(%function-response);
# Send the second request with function result
my $final-response = gemini-generate-content(
@messages2,
:@tools,
:$model,
format => "raku"
);
say "Assistant: ", $final-response<candidates>[0]<content><parts>».<text>.join("\n");
} else {
say "Assistant: $assistant-message<content>";
}
# Assistant: Alright! I've started some energetic and loud music, turned on the disco ball, and dimmed the lights to 50% brightness. Let's get this party started!
Remark Compared to the workflows in [AA1, AA2] the code above in simpler, more universal and robust, and handles all tool requests
We can observe and conclude that LLM function calling workflows are greatly simplified by:
LLM::Tool)LLM::ToolRequest)LLM::ToolResponse)generate-llm-tool-response) that automatically matches request objects to tool objects and produces the corresponding response objects.
Raku’s LLM tools automation is similar to Gemini’s “Automatic Function Calling (Python Only)”.
The Wolfram Language LLM tooling functionalities are reflected in Raku’s “LLM::Tooling”, [WRI1].
[AA1] Anton Antonov, “LLM function calling workflows (Part 1, OpenAI)”, (2025), RakuForPrediction at WordPress.
[AA2] Anton Antonov, “LLM function calling workflows (Part 2, Google’s Gemini)”, (2025), RakuForPrediction at WordPress.
[AA3] Anton Antonov, “LLM function calling workflows (Part 3, Facilitation)”, (2025), RakuForPrediction at WordPress.
[Gem1] Google Gemini, “Gemini Developer API”.
[WRI1] Wolfram Research, Inc. “LLM-Related Functionality” guide.
[AAp1] Anton Antonov, WWW::OpenAI Raku package, (2023-2025), GitHub/antononcube.
[AAp2] Anton Antonov, WWW::Gemini Raku package, (2023-2025), GitHub/antononcube.
[AAp3] Anton Antonov, LLM::Functions Raku package, (2023-2025), GitHub/antononcube.
This document (notebook) shows how to do Function Calling workflows with Large Language Models (LLMs) of Google’s Gemini.
The Raku package “WWW::Gemini”, [AAp2], is used.
The rest of the document gives concrete code how to do function calling with Gemini’s LLMs using Raku.
There are similar workflows, [AA1], with other LLM providers. (Like, OpenAI.) They follow the same structure, although there are some small differences. (Say, in the actual specifications of tools.)
This document belongs to a collection of documents describing how to do LLM function calling with Raku.
The Gemini LLM workflow in this document is quite similar to the OpenIA workflow described in [AA1]. While there are variations in the tool configurations and how the elements of the LLM responses are obtained, the overall procedure outline and diagrams in [AA1] also apply to the workflows presented here.
Load packages:
use WWW::Gemini;
use JSON::Fast;
Choose a model:
my $model = "gemini-2.0-flash";
This is the “tool” to be communicated to Gemini. (I.e. define the local function/sub.)
sub get-current-weather(Str:D $location, Str:D $unit = "fahrenheit") returns Str {
return "It is currently sunny in $location with a temperature of 72 degrees $unit.";
}
Define the function specification (as prescribed in Gemini’s function calling documentation):
my %weather-function = %(
name => 'get-current-weather',
description => 'Get the current weather in a given location',
parameters => %(
type => 'object',
properties => %(
location => %(
type => 'string',
description => 'The city and state, e.g., Boston, MA'
)
),
required => ['location']
)
);
Initialize messages and tools:
# User prompt
my $prompt = 'What is the weather like in Boston, MA, USA?';
# Prepare the API request payload
my @messages = [{role => 'user',parts => [ %( text => $prompt ) ]}, ];
my @tools = [%weather-function, ];
# [{description => Get the current weather in a given location, name => get-current-weather, parameters => {properties => {location => {description => The city and state, e.g., Boston, MA, type => string}}, required => [location], type => object}}]
Send the first chat completion request:
my $response = gemini-generate-content(
@messages,
:$model,
:@tools
);
The response is already parsed from JSON to Raku. Here is its JSON form:
to-json($response)
# {
# "usageMetadata": {
# "totalTokenCount": 50,
# "promptTokensDetails": [
# {
# "tokenCount": 41,
# "modality": "TEXT"
# }
# ],
# "candidatesTokenCount": 9,
# "candidatesTokensDetails": [
# {
# "tokenCount": 9,
# "modality": "TEXT"
# }
# ],
# "promptTokenCount": 41
# },
# "modelVersion": "gemini-2.0-flash",
# "candidates": [
# {
# "finishReason": "STOP",
# "safetyRatings": [
# {
# "category": "HARM_CATEGORY_HATE_SPEECH",
# "probability": "NEGLIGIBLE"
# },
# {
# "probability": "NEGLIGIBLE",
# "category": "HARM_CATEGORY_DANGEROUS_CONTENT"
# },
# {
# "probability": "NEGLIGIBLE",
# "category": "HARM_CATEGORY_HARASSMENT"
# },
# {
# "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
# "probability": "NEGLIGIBLE"
# }
# ],
# "content": {
# "parts": [
# {
# "functionCall": {
# "args": {
# "location": "Boston, MA"
# },
# "name": "get-current-weather"
# }
# }
# ],
# "role": "model"
# },
# "avgLogprobs": -3.7914659414026473e-06
# }
# ],
# "responseId": "zDpEaIClFpu97dcPpqOWiA8"
# }
The following copy of the messages is not required, but it makes repeated experiments easier:
my @messages2 = @messages;
# [{parts => [text => What is the weather like in Boston, MA, USA?], role => user}]
Process the response — invoke the tool, give the tool result to the LLM, get the LLM answer:
my $assistant-message = $response<candidates>[0]<content>;
if $assistant-message<parts> {
for |$assistant-message<parts> -> %part {
if %part<functionCall> {
@messages2.push($assistant-message);
my $func-name = %part<functionCall><name>;
my %args = %part<functionCall><args>;
if $func-name eq 'get-current-weather' {
my $location = %args<location>;
my $weather = get-current-weather($location);
my %function-response =
role => 'user',
parts => [{
functionResponse => {
name => 'get-current-weather',
response => %( content => $weather )
}
}];
@messages2.push(%function-response);
# Send the second request with function result
my $final-response = gemini-generate-content(
@messages2,
:@tools,
:$model,
format => "raku"
);
say "Assistant: ", $final-response<candidates>[0]<content><parts>».<text>.join("\n");
last
}
}
}
} else {
say "Assistant: $assistant-message<content>";
}
# Assistant: The weather in Boston, MA is currently sunny with a temperature of 72 degrees Fahrenheit.
Remark: Note that if get-current-weather is applied then the loop above immediately finishes.
[AA1] Anton Antonov, “LLM function calling workflows (Part 1, OpenAI)”, (2025), RakuForPrediction at WordPress.
[AA2] Anton Antonov,
“LLM function calling workflows (Part 2, Google’s Gemini)”, (2025), RakuForPrediction at WordPress.
[AAp1] Anton Antonov, WWW::OpenAI Raku package, (2023-2025), GitHub/antononcube.
[AAp2] Anton Antonov, WWW::Gemini Raku package, (2023-2025), GitHub/antononcube.
[AAp3] Anton Antonov, LLM::Functions Raku package, (2023-2025), GitHub/antononcube.
Deps is a minimalist Raku module for exploring dependency injection patterns through a clear, trait-based API. It offers both low‑level and high‑level interfaces, supports named registrations, trait‑driven function injection, and automatic instantiation of classes, while providing precise control over resolution lifecycles—New, Store, and Scope—and resolution precedence via priority.
Dependency injection decouples construction of dependencies from their use, improving modularity, testability, and configuration flexibility. Deps serves as an educational playground for understanding inversion of control in Raku and experimenting with DI concepts without the complexity of heavy frameworks.
Deps exposes:
deps { ... } to create nested containers and perform inline registrations or imports.is injected to functions/subroutines to have parameters auto‑provided.my Deps $deps .= new;
$deps.register: Bla;
$deps.register:
-> Int $a, Int :$b --> Str { "$a - $b" },
:name<value>
;
$deps.register: 13;
$deps.register: 42, :name<a>;
# Resolve
$deps.get(Bla); # Bla.new(value => "42 - 13", a => 42, b => 13)
$deps.get(Int, :name<a>); # 42
$deps.get(Int); # 13
deps {
injectable C.new: :13attr;
injected my C $obj;
# $obj == C.new(attr => 13)
}
sub handle-request(UInt $id) is injected {
injectable UserIdStorage.new: :$id;
process-request
}
Parameters typed as registered types are injected at call time.
class Example { has Int $.x; has Str $.y }
deps {
injectable 7;
injectable "hello", :name<y>;
instantiate(Example); # Example.new(x => 7, y => "hello")
}
Deps supports three built‑in lifecycles:
.get creates a fresh instance..get.deps { ... } block; fresh when entering a new block but reused within it.Specify with :lifecycle<New|Store|Scope>:
# Transient (default)
$deps.register: -> Int $n --> Int { $n * 2 };
# Singleton
$deps.register: MyService.new, :lifecycle<Store>;
# Scoped
$deps.register: RequestToken.new, :lifecycle<Scope>;
When multiple providers match a type (and optional name), :priority<Strict|Defer> determines which wins.
$deps.register:
FileLogger.new,
:lifecycle<Store>,
:priority<defer>
;
$deps.register:
ConsoleLogger.new,
:lifecycle<Store>,
:priority<strict>
;
# .get(Logger) returns ConsoleLogger
role Repo {}
class RealRepo does Repo { has Str $.dsn }
class MockRepo does Repo { }
my Deps $deps .= new;
# Real (singleton)
$deps.register:
RealRepo.new(
|(dsn => $_ with %*ENV<DB>)
),
:lifecycle<store>,
:priority<defer>,
:name<repo>
;
# Mock (transient)
$deps.register:
MockRepo,
:lifecycle<new>,
:priority<strict>,
:name<repo>
;
deps-scope :parent($deps), {
injected my Repo $repo; # MockRepo wins by priority
}
With its lightweight core and idiomatic Raku traits, Deps is ideal for learning DI patterns. Correct lifecycle names—New, Store, and Scope—and built‑in priority give precise control over object lifetimes and resolution. Future enhancements may include circular dependency detection, named scopes, and asynchronous resolution workflows.
Several people have pointed out that the yearly StackOverflow Developer Survey is online. Please take the survey and put in “Raku” when being questioned about programming languages (as it is not listed as a standard option yet), so that it may show up as an option next year. Thank you!
This week Steve Roe is inviting people to think about a new version of the raku.org website, as Steve has volunteered to make a prototype of such a website. Any feedback will be thoroughly appreciated!
Anton Antonov started a new series about LLM function calling, the first part tackling the weather (as an example of a question) using OpenAI.
Weekly Challenge #324 is available for your perusal.
DateTime.(modified-)julian-date take timezone into accountIMPL-UNWRAP-LISTIn RakuAST developments this week:
⚛+= , ⚛-= and ⚛−= operators.Next week’s Weekly may be a day (or possibly a week) late on account of the second Raku Core Summit.
Please keep staying safe and healthy, and keep up the good work! Even after week 19 of hopefully only 209.
Meanwhile, still: Слава Україні! Героям слава!
If you like what I’m doing, committing to a small sponsorship would mean a great deal!
This document (notebook) shows how to do Function Calling workflows with Large Language Models (LLMs) of OpenAI.
The Raku package “WWW::OpenAI”, [AAp1], is used.
The overall process is (supposed to be) simple:
(Currently) OpenAI indicates its tool evaluation requests with having the rule finish_reason => tool_calls in its responses.
Here is a Mermaid-JS diagram that shows single-pass LLM-and-tool interaction:
Remark: Instead of a loop — as in the outline above — only one invocation of a local tool is shown in the diagram.
The rest of the document gives concrete code how to do function calling with OpenAI’s LLMs using Raku.
There are similar workflows with other LLM providers. (Like, Google’s Gemini.) They follow the same structure, although there are some small differences. (Say, in the actual specifications of tools.)
It would be nice to have:
This document belongs to a collection of documents describing how to do LLM function calling with Raku.
Load packages:
use WWW::OpenAI;
use JSON::Fast;
Choose a model:
my $model = "gpt-4.1";
This is the “tool” to be communicated to OpenAI. (I.e. define the local function/sub.)
sub get-current-weather(Str $location, Str $unit = "fahrenheit") returns Str {
return "It is currently sunny in $location with a temperature of 72 degrees $unit.";
}
Define the function specification (as prescribed in OpenAI’s function calling documentation):
my $function-spec = {
type => "function",
function => {
name => "get-current-weather",
description => "Get the current weather for a given location",
parameters => {
type => "object",
properties => {
'$location' => {
type => "string",
description => "The city and state, e.g., San Francisco, CA"
},
'$unit' => {
type => "string",
enum => ["celsius", "fahrenheit"],
description => "The temperature unit to use"
}
},
required => ["location"]
}
}
};
Initialize messages and tools:
my @messages =
{role => "system", content => "You are a helpful assistant that can provide weather information."},
{role => "user", content => "What's the weather in Boston, MA?"}
;
my @tools = [$function-spec,];
Send the first chat completion request:
my $response = openai-chat-completion(
@messages,
:@tools,
:$model,
max-tokens => 4096,
format => "raku",
temperature => 0.45
);
# [{finish_reason => tool_calls, index => 0, logprobs => (Any), message => {annotations => [], content => (Any), refusal => (Any), role => assistant, tool_calls => [{function => {arguments => {"$location":"Boston, MA"}, name => get-current-weather}, id => call_ROi3n0iICSrGbetBKZ9KVG4E, type => function}]}}]
The following copy of the messages is not required, but it makes repeated experiments easier:
my @messages2 = @messages;
Process the response — invoke the tool, give the tool result to the LLM, get the LLM answer:
my $assistant-message = $response[0]<message>;
if $assistant-message<tool_calls> {
@messages2.push: {
role => "assistant",
tool_calls => $assistant-message<tool_calls>
};
my $tool-call = $assistant-message<tool_calls>[0];
my $function-name = $tool-call<function><name>;
my $function-args = from-json($tool-call<function><arguments>);
if $function-name eq "get-current-weather" {
my $result = get-current-weather(
$function-args{'$location'} // $function-args<location>,
$function-args{'$unit'} // $function-args<unit> // "fahrenheit"
);
@messages2.push: {
role => "tool",
content => $result,
tool_call_id => $tool-call<id>
};
# Send the second request with function result
my $final-response = openai-chat-completion(
@messages2,
:@tools,
#tool_choice => "auto",
:$model,
format => "raku"
);
say "Assistant: $final-response[0]<message><content>";
}
} else {
say "Assistant: $assistant-message<content>";
}
# Assistant: The weather in Boston, MA is currently sunny with a temperature of 72
Show all messages:
.say for @messages2
# {content => You are a helpful assistant that can provide weather information., role => system}
# {content => What's the weather in Boston, MA?, role => user}
# {role => assistant, tool_calls => [{function => {arguments => {"$location":"Boston, MA"}, name => get-current-weather}, id => call_ROi3n0iICSrGbetBKZ9KVG4E, type => function}]}
# {content => It is currently sunny in Boston, MA with a temperature of 72 degrees fahrenheit., role => tool, tool_call_id => call_ROi3n0iICSrGbetBKZ9KVG4E}
In general, there should be an evaluation loop that checks the finishing reason(s) in the LLM answers and invokes the tools as many times as it is required. (I.e., there might be several back-and-forth exchanges in the LLM, requiring different tools or different tool parameters.)
[AAp1] Anton Antonov, WWW::OpenAI Raku package, (2023-2025), GitHub/antononcube.
[AAp2] Anton Antonov, WWW::Gemini Raku package, (2023-2025), GitHub/antononcube.
[AAp3] Anton Antonov, LLM::Functions Raku package, (2023-2025), GitHub/antononcube.
Steve Roe continued their stack of essays on HARC with a sixth episode: HARC Stack: Navigation in which it is shown how easy it is to add navigation components to your web pages.
Anton Antonov returned with an extensive blog post about visualizing the Collatz conjecture with some really visually compelling graphics! And there’s also a Bulgarian version in honor of the most Bulgarian holiday!
Weekly Challenge #323 is available for your perusal.
libuv to version 1.51.0.[\,].In RakuAST developments this week:
repl as a function by Ralph Mellor.Please keep staying safe and healthy, and keep up the good work! Even after week 18 of hopefully only 209.
Meanwhile, still: Слава Україні! Героям слава!
If you like what I’m doing, committing to a small sponsorship would mean a great deal!
This is the sixth of the HARC Stack essays. Previous <=
As you know, HARC Stack combines HTMX with raku Air, Red and Cro to supply a fresh approach to web design.
Last time we took a look at a Minimal single page website.
Today, we are going to add in a navigation bar, or two.
A main idea of HARC is to hide unnecessary complexity, to cut out boilerplate and to focus on the salient features of your site.
This code packs a whole Single Page Application (SPA) into 47 lines. We have already seen a chunk of this example.
The new parts are:
my $Content1 = content [...] [lines 16-24]my $Google = external :href<https://google.com> [line 26]nav => nav( ... ) [lines 33-37]
logo => safe('hÅrc'),items => [:$Content1, :$Content2, :$Google],widgets => [lightdark],main $Content1 [line 46]What’s occuring?
As with most features of HARC, there is a close mapping to the stylistic components provided by Pico CSS. Specifically our nav tag implements https://picocss.com/docs/nav …
The essential navbar component in pure semantic HTML.
<nav>
<ul>
<li><strong>Acme Corp</strong></li>
</ul>
<ul>
<li><a href="#">About</a></li>
<li><a href="#">Services</a></li>
<li><a href="#">Products</a></li>
</ul>
</nav>So, we have two areas, the logo (which left aligns) and a list of NavItems (which align right).
The HARC nav embellishes the features a little, but retains the core Pico design.
You can put any HTML in the logo field, in our case, the ‘hÅrc‘ logo is a typographical construct, but images, SVGs etc can all be used. The safe function tells HARC not to HTML escape the literal HTML.
logo => safe('<a href="/">h<b>Å</b>rc</a>'),The rest of our nav is an unordered list of Pair s of type NavItem.
Here’s how that is declared in the Air::Base code:
subset NavItem of Pair where .value ~~ Internal | External | Content | Page;This covers all the key options for navigation targets:
Internal – jump to an anchor on this pageExternal – open an external page in a new tabContent – use HTMX to hot swap the <content> ... </content> tagPage – open a new HTML page in this tabYou can also append Widget items to the end of the Nav list – in our example the LightDark widget is provided.
Custom Widgets can easily be created and consumed.
Why, I hear you ask, do we declare NavItem types as raku Pair s … boiling it down, a nav item has two parts – a display name (the thing you click) and a target (the place you go). The raku Pair type is the ideal way to represent this.
It also means we can leverage the raku Pair syntax to make our code crystal clear:
items => [:$Content1, :$Content2, :$Google],Here we use the Pair colon syntax, which is another way to write this:
items => [
Content1 => $Content1,
Content2 => $Content2,
Google => $Google,
],A good way to keep our code nice and DRY.
If you recap the example code at the top of this post, it should now be clear what is going on. If not, please do come and ask us on Discord or IRC(!)
Here is the HTML that our nav element generates:
<nav>
<ul>
<li href="/" class="logo"><a href="/">h<b>Å</b>rc</a></li>
</ul>
<ul hx-target="#content" hx-swap="outerHTML" class="nav-links">
<li>
<a hx-get="/nav/1/Content1">Content1</a></li>
<li>
<a hx-get="/nav/1/Content2">Content2</a></li>
...
</ul>
</nav>We use HTMX to swap our new payload into the content tag here, so we need to be sure to give our index page a content section inside the main block.
<main class="container">
<content id="content">
<h3>Content 1</h3>
<table class="striped">No need to worry about this implementation detail – all the class names and targets are handled by HARC.
While all of the NavItem types have the same fundamental Pair syntax, their implementations are quite distinct. Section items use the power of HTMX to hot swap the content tag for a Single Page Application.
Here’s how the Single Page App we showed at the top can be refactored as a Multi Page App.
Page items tell Cro to make a new http route and to serve it and then to load that as a new page when clicked.
The key code changes are:
my $nav = Nav.new:
logo => safe( '<a href="/">h<b>Å</b>rc</a>' ),
items => [Page1 => $page1, Page2 => $page2];
$page1.nav = $page2.nav = $nav;
sub SITE is export {
Site.new: pages => [$page1, $page2]
}The keen observer of Dependency Injections (DI) will note that there is an inherent circularity in a multi-page web application. Each page typically has the same nav, and all pages are represented in the navigation items.
In raku terms our example assigns each page to a variable which can then be reused as shown.
The flexibility and power of expression stands in contrast to less rich coding environments such as template engines. The deliberate mixing of HTML functions and full raku code is a key strength of HARC stack.
Beginners: look away now.
For those who are wondering why raku was chosen as the base language for HARC, the primary factors are code clarity and the ability to seamlessly combine multiple paradigms in an elegant way. Here is the raku source in role Nav (Air::Base):
By using a power tool language, we can keep our code intent crystal clear and easy to maintain and extend.
We haven’t had space here to do justice to the LightDark widget or the reactive Hamburger menu included in Air::Base. These will be covered in future episodes. Watch this space.
As usual, comments and feedback welcome. We are a friendly bunch over on the raku IRC chat and Discord.
~librasteve
This blog post (notebook) presents various visualizations related to the Collatz conjecture, [WMW1, Wk1] using Raku.
The Collatz conjecture, a renowned, unsolved mathematical problem, questions whether iteratively applying two basic arithmetic operations will lead every positive integer to ultimately reach the value of 1.
In this notebook the so-called “shortcut” version of the Collatz function is used:
That function is used repeatedly to form a sequence, beginning with any positive integer, and taking the result of each step as the input for the next.
The Collatz conjecture is: This process will eventually reach the number 1, regardless of which positive integer is chosen initially.
Raku-wise, subs for the Collatz sequences are easy to define. The visualizations are done with the packages “Graph”, [AAp1], “JavaScript::D3”, [AAp2], and “Math::NumberTheory”, [AAp3].
There are many articles, blog posts, and videos dedicated to visualizations of the Collatz conjecture. (For example, [KJR1, PZ1, Vv1]).
Remark: Consider following the warnings in [Vv1] and elsewhere:
Do not work on this [Collatz] problem! (Do real math instead.)
Remark: Notebook’s visualizations based on “JavaScript::D3” look a lot like the visualizations in [PZ1] — D3js is used in both.
Remark: See the Bulgarian version of this post: “Визуализации свързани с хипотезата на Колац”.
use Data::Reshapers;
use Data::Summarizers;
use Data::TypeSystem;
use Data::Translators;
use Graph;
use JavaScript::D3;
use Math::NumberTheory;
#%javascript
require.config({
paths: {
d3: 'https://d3js.org/d3.v7.min'
}});
require(['d3'], function(d3) {
console.log(d3);
});
my $background = 'none';
my $stroke-color = 'Ivory';
my $fill-color = 'none';
my $title-color = 'DarkGray';
Additional subs are defined for getting color-blending sequences.
sub darker-shades(Str $hex-color, Int $steps) {
my @rgb = $hex-color.subst(/ ^ '#'/).comb(2).map({ :16($_) });
my @shades;
for 1..$steps -> $step {
my @darker = @rgb.map({ ($_ * (1 - $step / ($steps + 1))).Int });
@shades.push: '#' ~ @darker.map({ sprintf '%02X', $_ }).join;
}
return @shades;
}
#say darker-shades("#34495E", 5);
sub blend-colors(Str $color1, Str $color2, Int $steps) {
my @rgb1 = $color1.subst(/ ^ '#'/).comb(2).map({ :16($_) });
my @rgb2 = $color2.subst(/ ^ '#'/).comb(2).map({ :16($_) });
my @blended;
for ^$steps -> $step {
my @blend = (@rgb1 Z @rgb2).map({
($_[0] + ($step / $steps) * ($_[1] - $_[0])).Int
});
@blended.push: '#' ~ @blend.map({ sprintf '%02X', $_ }).join;
}
return @blended;
}
#say blend-colors("#34495E", "#FFEBCD", 5);
Here is a sub for the shortcut version of the Collatz function:
sub collatz(UInt $n is copy, Int:D $max-steps = 1000) {
return [] if $n == 0;
my @sequence = $n;
while $n != 1 && @sequence.elems < $max-steps {
$n = ($n %% 2 ?? $n div 2 !! (3 * $n + 1) / 2).Int;
@sequence.push: $n;
}
return @sequence;
}
Here is an example using as a sequence seed (i.e. starting value):
collatz(26)
# [26 13 20 10 5 8 4 2 1]
The next integer, , produces a much longer sequence:
collatz(27).elems
# 71
Here is the simplest, informative Collatz sequence — or hailstone numbers — plot:
#% js
js-d3-list-line-plot(collatz(171), :$background, :$title-color, title => 'Hailstone numbers of 171')
Let us make a multi-line plot for a selection of seeds.
my @data = (1..1_000).map({ collatz($_) }).grep({ 30 ≤ $_.elems ≤ 150 && $_.max ≤ 600 }).pick(10).sort(*.head).map({my $i = $_.head; $_.kv.map(-> $x, $y {%(group => $i, :$x, :$y )}).Array }).map(*.Slip).Array;
deduce-type(@data)
# Vector(Assoc(Atom((Str)), Atom((Int)), 3), 320)
#% js
js-d3-list-line-plot(@data.flat, :$background)
Remark: Using simple sampling like the code block below would generally produce very non-uniform length- and max-value sequences.
Hence, we do the filtering above.
my @data = (^100).pick(9).sort.map(-> $i {collatz($i).kv.map(-> $x, $y {%(group => $i, :$x, :$y )}).Array }).map(*.Slip).Array;
Here are Collatz sequences and their corresponding lengths and max-values:
my $m = 100_000;
my @cSequences = (1..$m).map({ collatz($_) });
my @cLengths = @cSequences».elems;
my @cMaxes = @cSequences».max;
my @dsCollatz = (1...$m) Z @cLengths Z @cMaxes;
@dsCollatz = @dsCollatz.map({ <seed length max>.Array Z=> $_.Array })».Hash;
sink records-summary(@dsCollatz, field-names => <seed length max>)
# +-------------------+--------------------+------------------------+
# | seed | length | max |
# +-------------------+--------------------+------------------------+
# | Min => 1 | Min => 1 | Min => 1 |
# | 1st-Qu => 25000.5 | 1st-Qu => 47 | 1st-Qu => 42272 |
# | Mean => 50000.5 | Mean => 72.88948 | Mean => 320578.18243 |
# | Median => 50000.5 | Median => 68 | Median => 85292 |
# | 3rd-Qu => 75000.5 | 3rd-Qu => 97 | 3rd-Qu => 162980 |
# | Max => 100000 | Max => 222 | Max => 785412368 |
# +-------------------+--------------------+------------------------+
Here are histograms of the Collarz sequences lengths and max-value distributions:
#% js
js-d3-histogram(
@cLengths,
100,
:$background,
:600width,
:400height,
title => "Collatz sequences lengths distribution (up to $m)",
:$title-color
)
~
js-d3-histogram(
@cMaxes».log(10),
100,
:$background,
:600width,
:400height,
title => "Collatz sequences lg(max-value) distribution (up to $m)",
:$title-color
)
Here is a scatter plot of seed vs. sequence length:
#% js
js-d3-list-plot(
@cLengths,
:$background,
:2point-size,
:800width,
:400height,
title => 'Collatz sequences lengths',
x-label => 'seed',
y-label => 'sequence length',
:$title-color
)
It is of interest to see the manifestation of Benford’s law for the first digits of Collatz hailstones.
Here is the corresponding digit tally:
my %digitTally = @cSequences.race(:4degree).map({ $_».comb».head }).flat.&tally
# {1 => 2067347, 2 => 1375360, 3 => 870823, 4 => 857427, 5 => 581237, 6 => 448351, 7 => 334441, 8 => 443043, 9 => 310919}
Here is a comparison with the corresponding Benford’s law values:
#% html
sub benford-law(UInt:D $d, UInt:D $b = 10) { log($d + 1, $b) - log($d, $b) };
my @dsDigitTally =
%digitTally.sort(*.key.Int).map({%(
digit => $_.key,
value => round($_.value / %digitTally.values.sum, 10 ** -7),
benford => round(benford-law($_.key.Int), 10 ** -7)) })
==> to-html(field-names => <digit value benford>)
| digit | value | benford |
|---|---|---|
| 1 | 0.2836276 | 0.30103 |
| 2 | 0.1886912 | 0.1760913 |
| 3 | 0.1194717 | 0.1249387 |
| 4 | 0.1176338 | 0.09691 |
| 5 | 0.0797422 | 0.0791812 |
| 6 | 0.0615111 | 0.0669468 |
| 7 | 0.0458833 | 0.0579919 |
| 8 | 0.0607828 | 0.0511525 |
| 9 | 0.0426562 | 0.0457575 |
Good adherence is observed for a relatively modest number of sequences.
Here is a corresponding bar chart:
#% js
my @data =
|@dsDigitTally.map({ <x y group>.Array Z=> [|$_<digit value>, 'Collatz'] })».Hash,
|@dsDigitTally.map({ <x y group>.Array Z=> [|$_<digit benford>, 'Benford'] })».Hash;
js-d3-bar-chart(
@data,
title => "First digits frequencies (up to $m)",
:$title-color,
x-label => 'digit',
y-label => 'frequency',
:!grid-lines,
:$background,
:700width,
:400height,
margins => { :50left }
)
A certain concentric pattern emerges in the spiral embedding plots of the Collatz sequences lengths mod 8. (Using mod 3 makes the pattern clearer.)
Similarly, a clear spiral pattern is seen for the maximum values.
#% js
my @sunflowerLengths = sunflower-embedding(16_000, with => { collatz($_).elems mod 8 mod 3 + 1}):d;
my @sunflowerMaxes = sunflower-embedding(16_000, with => { collatz($_).max mod 8 mod 3 + 1}):d;
js-d3-list-plot(@sunflowerLengths,
background => 'none',
point-size => 4,
width => 500, height => 440,
:!axes,
:!legends,
color-scheme => 'Observable10',
margins => {:20top, :20bottom, :50left, :50right}
)
~
js-d3-list-plot(@sunflowerMaxes,
background => 'none',
point-size => 4,
width => 500, height => 440,
:!axes,
:!legends,
color-scheme => 'Observable10',
margins => {:20top, :20bottom, :50left, :50right}
)
Define a sub for graph-edge relationship between consecutive integers in Collatz sequences:
proto sub collatz-edges(|) {*}
multi sub collatz-edges(Int:D $n) {
($n mod 3 == 2) ?? [$n => 2 * $n, $n => (2 * $n - 1) / 3] !! [$n => 2 * $n,]
}
multi sub collatz-edges(@edges where @edges.all ~~ Pair:D) {
my @leafs = @edges».value.unique;
@edges.append(@leafs.map({ collatz-edges($_.Int) }).flat)
}
# &collatz-edges
For didactic purposes let use derive the edges of a graph using a certain small number of iterations:
my @edges = Pair.new(2, 4);
for ^12 { @edges = collatz-edges(@edges) }
deduce-type(@edges)
# Vector((Any), 536)
Make the graph:
my $g = Graph.new(@edges.map({ $_.value.Str => $_.key.Str })):directed
# Graph(vertexes => 155, edges => 154, directed => True)
Plot the graph using suitable embedding:
#% html
$g.dot(
engine => 'dot',
:$background,
vertex-label-color => 'Gray',
vertex-shape => 'ellipse',
vertex-width => 0.8,
vertex-height => 0.6,
:24vertex-font-size,
edge-thickness => 6,
graph-size => 12
):svg
The Collatz sequence paths can be easily followed in the tree graph.
Let us make a bigger, visually compelling graph:
my $root = 64;
my @edges = Pair.new($root, 2 * $root);
for ^20 { @edges = collatz-edges(@edges) }
my $gBig = Graph.new(@edges.map({ $_.value.Str => $_.key.Str })):!directed;
# Graph(vertexes => 2581, edges => 2580, directed => False)
Next we find the path lengths from the root to each vertex in order to do some sort concentric coloring:
my %path-lengths = $gBig.vertex-list.race(:4degree).map({ $_ => $gBig.find-path($_, $root.Str).head.elems });
%path-lengths.values.unique.elems
# 22
We make a blend of these colors:
JavaScript::D3::Utilities::get-named-colors()<darkred plum orange>
# (#8B0000 #DDA0DD #FFA500)
Here is the graph plot:
#%html
my %classes = $gBig.vertex-list.classify({ %path-lengths{$_} });
my @colors = |blend-colors("#8B0000", "#DDA0DD", 16), |blend-colors("#DDA0DD", "#FFA500", %classes.elems - 16);
my %highlight = %classes.map({ @colors[$_.key - 1] => $_.value });
$gBig.dot(
engine => 'neato',
:%highlight,
:$background,
vertex-shape => 'circle',
vertex-width => 0.55,
:0vertex-font-size,
vertex-color => 'Red',
vertex-stroke-width => 2,
edge-thickness => 8,
edge-color => 'Purple',
graph-size => 10
):svg
[KJR1] KJ Runia, “The Collatz Conjecture”, (2020), OpenCurve.info.
[PZ1] Parker Ziegler, “Playing with the Collatz Conjecture”, (2021), ObservableHQ.
[Wk1] Wikipedia entry, “Collatz conjecture”.
[WMW1] Wolfram Math World entry, “Collatz Problem”.
[AAp1] Anton Antonov, Graph Raku package, (2024-2025), GitHub/antononcube.
[AAp2] Anton Antonov, JavaScript::D3 Raku package, (2022-2025), GitHub/antononcube.
[AAp3] Anton Antonov, Math::NumberTheory Raku package, (2025), GitHub/antononcube.
[Vv1] Veritasium, “The Simplest Math Problem No One Can Solve – Collatz Conjecture”, (2021), YouTube@Veritasium.
Този блог пост (“notebook”) представя различни визуализации, свързани с хипотезата на Колац, [WMW1, Wk1] използвайки Raku.
Хипотезата на Колац, известен, нерешен математически проблем, поставя въпроса дали итеративното прилагане на две основни аритметични операции ще доведе всяко положително цяло число в крайна сметка до стойността 1.
В този блог пост се използва така наречената “съкратена” версия на функцията на Колац:
f(n) =
| n⁄2 | if n ≡ 0 (mod 2) |
| 3n + 1⁄2 | if n ≡ 1 (mod 2) |
С тази функция многократно се формира редица, започвайки с произволно положително цяло число и приемайки резултата от всяка стъпка като вход за следващата.
Хипотезата на Колац е: Този процес в крайна сметка ще достигне числото 1, независимо кое положително цяло число е избрано първоначално.
От гледна точка на Raku, процедури (“subs”) за редиците на Колац се дефинират лесно. Визуализациите са направени с пакетите “Graph”, [AAp1], “JavaScript::D3”, [AAp2], и “Math::NumberTheory”, [AAp3].
Има много статии, публикации в блогове и видео-доклади, посветени на визуализации на хипотезата на Колац. (Например, [KJR1, PZ1, Vv1]).
Забележка: Вземете предвид предупрежденията във [Vv1] и на други места:
Не работете по този [Колац] проблем! (Вместо това правете истинска математика.)
Забележка: Доста от визуализациите в този тефтер са базирани на “JavaScript::D3” и много приличат на визуализациите в [PZ1] — D3js се използва и на двете места.
use Data::Reshapers;
use Data::Summarizers;
use Data::TypeSystem;
use Graph;
use JavaScript::D3;
use Math::NumberTheory;
#%javascript
require.config({
paths: {
d3: 'https://d3js.org/d3.v7.min'
}});
require(['d3'], function(d3) {
console.log(d3);
});
my $background = 'none';
my $stroke-color = 'Ivory';
my $fill-color = 'none';
my $title-color = 'DarkGray';
sub darker-shades(Str $hex-color, Int $steps) {
my @rgb = $hex-color.subst(/ ^ '#'/).comb(2).map({ :16($_) });
my @shades;
for 1..$steps -> $step {
my @darker = @rgb.map({ ($_ * (1 - $step / ($steps + 1))).Int });
@shades.push: '#' ~ @darker.map({ sprintf '%02X', $_ }).join;
}
return @shades;
}
#say darker-shades("#34495E", 5);
sub blend-colors(Str $color1, Str $color2, Int $steps) {
my @rgb1 = $color1.subst(/ ^ '#'/).comb(2).map({ :16($_) });
my @rgb2 = $color2.subst(/ ^ '#'/).comb(2).map({ :16($_) });
my @blended;
for ^$steps -> $step {
my @blend = (@rgb1 Z @rgb2).map({
($_[0] + ($step / $steps) * ($_[1] - $_[0])).Int
});
@blended.push: '#' ~ @blend.map({ sprintf '%02X', $_ }).join;
}
return @blended;
}
#say blend-colors("#34495E", "#FFEBCD", 5);
Ето една процедура за съкратената версия на функцията на Колац:
sub collatz(UInt $n is copy, Int:D $max-steps = 1000) {
return [] if $n == 0;
my @sequence = $n;
while $n != 1 && @sequence.elems < $max-steps {
$n = ($n %% 2 ?? $n div 2 !! (3 * $n + 1) / 2).Int;
@sequence.push: $n;
}
return @sequence;
}
Ето пример, използващ като семе на редицата (т.е. начална стойност):
collatz(26)
# [26 13 20 10 5 8 4 2 1]
Следващото цяло число, , произвежда много по-дълга редица:
collatz(27).elems
# 71
Ето най-простата, информативна редица на Колац — или градушкови числа — графика:
#% js
js-d3-list-line-plot(collatz(171), :$background, :$title-color, title => 'Числа на Колатц за 171')
Нека направим многолинейна графика за подходящо избрано множество от семена.
my @data = (1..1_000).map({ collatz($_) }).grep({ 30 ≤ $_.elems ≤ 150 && $_.max ≤ 600 }).pick(10).sort(*.head).map({my $i = $_.head; $_.kv.map(-> $x, $y {%(group => $i, :$x, :$y )}).Array }).map(*.Slip).Array;
deduce-type(@data)
# Vector(Assoc(Atom((Str)), Atom((Int)), 3), 322)
#% js
js-d3-list-line-plot(@data.flat, :$background)
Забележка: Използването на просто семплиране като кодовия блок по-долу обикновено би довело до много неравномерни по дължина и максимална стойност редици.
Следователно, ние правим филтрирането по-горе.
my @data = (^100).pick(9).sort.map(-> $i {collatz($i).kv.map(-> $x, $y {%(group => $i, :$x, :$y )}).Array }).map(*.Slip).Array;
Ето редици на Колац и съответните им дължини и максимални стойности:
my $m = 100_000;
my @cSequences = (1..$m).map({ collatz($_) });
my @cLengths = @cSequences».elems;
my @cMaxes = @cSequences».max;
my @dsCollatz = (1...$m) Z @cLengths Z @cMaxes;
@dsCollatz = @dsCollatz.map({ <seed length max>.Array Z=> $_.Array })».Hash;
sink records-summary(@dsCollatz, field-names => <seed length max>)
# +-------------------+--------------------+------------------------+
# | seed | length | max |
# +-------------------+--------------------+------------------------+
# | Min => 1 | Min => 1 | Min => 1 |
# | 1st-Qu => 25000.5 | 1st-Qu => 47 | 1st-Qu => 42272 |
# | Mean => 50000.5 | Mean => 72.88948 | Mean => 320578.18243 |
# | Median => 50000.5 | Median => 68 | Median => 85292 |
# | 3rd-Qu => 75000.5 | 3rd-Qu => 97 | 3rd-Qu => 162980 |
# | Max => 100000 | Max => 222 | Max => 785412368 |
# +-------------------+--------------------+------------------------+
Ето хистограми на разпределенията на дължините на редиците на Колац и максималните им стойности:
#% js
js-d3-histogram(
@cLengths,
100,
:$background,
:600width,
:400height,
title => "Разпределение на дължините на редиците на Колац (до $m)",
:$title-color
)
~
js-d3-histogram(
@cMaxes».log(10),
100,
:$background,
:600width,
:400height,
title => "Разпределение на lg(максимална стойност) на редиците на Колац (до $m)",
:$title-color
)
Ето точкова графика на семената срещу дължините на съответните редици:
#% js
js-d3-list-plot(
@cLengths,
:$background,
:2point-size,
:800width,
:400height,
title => 'Дължини на редиците на Колац',
x-label => 'seed',
y-label => 'дължина на редицата',
:$title-color
)
Определен концентричен шаблон се появява в графиките на спираловидното вграждане на дължините на редиците на Колац mod 8. (Използването на mod 3 прави шаблона по-ясен.)
По същия начин, ясен спирален шаблон се вижда и за максималните стойности.
#% js
my @sunflowerLengths = sunflower-embedding(16_000, with => { collatz($_).elems mod 8 mod 3 + 1}):d;
my @sunflowerMaxes = sunflower-embedding(16_000, with => { collatz($_).max mod 8 mod 3 + 1}):d;
js-d3-list-plot(@sunflowerLengths,
background => 'none',
point-size => 4,
width => 500, height => 440,
:!axes,
:!legends,
color-scheme => 'Observable10',
margins => {:20top, :20bottom, :50left, :50right}
)
~
js-d3-list-plot(@sunflowerMaxes,
background => 'none',
point-size => 4,
width => 500, height => 440,
:!axes,
:!legends,
color-scheme => 'Observable10',
margins => {:20top, :20bottom, :50left, :50right}
)
Дефиниция на процедура за ръбовете на граф представящ връзките между последователни цели числа в редиците на Колац:
proto sub collatz-edges(|) {*}
multi sub collatz-edges(Int:D $n) {
($n mod 3 == 2) ?? [$n => 2 * $n, $n => (2 * $n - 1) / 3] !! [$n => 2 * $n,]
}
multi sub collatz-edges(@edges where @edges.all ~~ Pair:D) {
my @leafs = @edges».value.unique;
@edges.append(@leafs.map({ collatz-edges($_.Int) }).flat)
}
За дидактични цели нека извлечем ръбовете на един граф получен с определен малък брой итерации:
my @edges = Pair.new(2, 4);
for ^12 { @edges = collatz-edges(@edges) }
deduce-type(@edges)
# Vector((Any), 536)
Създаване графа:
my $g = Graph.new(@edges.map({ $_.value.Str => $_.key.Str })):directed
# Graph(vertexes => 155, edges => 154, directed => True)
Начертаване на графа, използвайки подходящо разположение на върховете:
#% html
$g.dot(
engine => 'dot',
:$background,
vertex-label-color => 'Gray',
vertex-shape => 'ellipse',
vertex-width => 0.8,
vertex-height => 0.6,
:24vertex-font-size,
edge-thickness => 6,
graph-size => 12
):svg
Пътищата на редицата на Колац могат лесно да бъдат проследени в графа-дърво.
Нека направим един по-голям, визуално завладяващ граф:
my $root = 64;
my @edges = Pair.new($root, 2 * $root);
for ^20 { @edges = collatz-edges(@edges) }
my $gBig = Graph.new(@edges.map({ $_.value.Str => $_.key.Str })):!directed;
# Graph(vertexes => 2581, edges => 2580, directed => False)
След това намираме дължините на пътя от корена до всеки връх, с цел да направим определено концентрично оцветяване:
my %path-lengths = $gBig.vertex-list.race(:4degree).map({ $_ => $gBig.find-path($_, $root.Str).head.elems });
%path-lengths.values.unique.elems
# 22
По-долу ползваме смес от тези цветове:
JavaScript::D3::Utilities::get-named-colors()<darkred plum orange>
# (#8B0000 #DDA0DD #FFA500)
Ето графиката на графа:
#%html
my %classes = $gBig.vertex-list.classify({ %path-lengths{$_} });
my @colors = |blend-colors("#8B0000", "#DDA0DD", 16), |blend-colors("#DDA0DD", "#FFA500", %classes.elems - 16);
my %highlight = %classes.map({ @colors[$_.key - 1] => $_.value });
$gBig.dot(
engine => 'neato',
:%highlight,
:$background,
vertex-shape => 'circle',
vertex-width => 0.55,
:0vertex-font-size,
vertex-color => 'Red',
vertex-stroke-width => 2,
edge-thickness => 8,
edge-color => 'Purple',
graph-size => 10
):svg
[KJR1] KJ Runia, “The Collatz Conjecture”, (2020), OpenCurve.info. Бг. “Хипотезата на Колац”.
[PZ1] Parker Ziegler, “Playing with the Collatz Conjecture”, (2021), ObservableHQ. Бг. “Игра с хипотезата на Колац”.
[Wk1] Wikipedia entry, “Collatz conjecture”. Бг. “Хипотеза на Колац”.
[WMW1] Wolfram Math World entry, “Collatz Problem”. Бг. “Проблем на Колац”.
[AAp1] Антон Антонов, Graph Raku package, (2024-2025), GitHub/antononcube.
[AAp2] Антон Антонов, JavaScript::D3 Raku package, (2022-2025), GitHub/antononcube.
[AAp3] Антон Антонов, Math::NumberTheory Raku package, (2025), GitHub/antononcube.
[Vv1] Veritasium, “The Simplest Math Problem No One Can Solve – Collatz Conjecture”, (2021), YouTube@Veritasium. Бг. “Най-простият математически проблем, който никой не може да реши – Хипотезата на Колац”.
Steve Roe continued their stack of essays on HARC with a fifth episode: HARC Stack: Mini(mal) in which they show how to use the .assuming method to set up the contents of a not so simple web page.
Justin DeVuyst has produced the fifth release of the Rakudo compiler for the Raku Programming Language in 2025: 2025.05. This release fixes a nasty bug in LEAVE handling on MoarVM, makes .classify / .categorize return proper object hashes, adds an IO::Path.readlink method and makes locally defined entities visible as arguments to MAIN handling.
Weekly Challenge #322 is available for your perusal.
A bit of a quiet week. Please keep staying safe and healthy, and keep up the good work! Even after week 17 of hopefully only 209.
Meanwhile, still: Слава Україні! Героям слава!
If you like what I’m doing, committing to a small sponsorship would mean a great deal!
This is the fifth of the HARC Stack essays. Previous <=> Next
If you have made it to this episode, further congratulations! You will know that HARC Stack combines HTMX with raku Air, Red and Cro to supply a fresh approach to web design.
We have already seen how to get started and you have made a trivial website with this code (you have, haven’t you?)…
HARC makes it easy to write & maintain low scale, low complexity websites, with UX dynamism in the HTMX sweet spot. (If you are making a new Google Maps or Facebook, then react may be a better option for you….)
Now it’s time to get serious with a more complete, yet minimal single page web app.
Here’s the source:
That’s quite a lot in only a few lines – yes, HARC does come with a bit of a learning curve. It helps to speak raku – for starters, I recommend the excellent raku guide. Other docs are to be had at HTMX, Air, Red and Cro.
This code kicks off with a table. Here in our IDE, yellow represents a raku function call. Since functions are first class entities in raku, we can use the ampersand sigil to declare a new function as a var – my &planets = ... and then call it later with planets(). And our function call can drop the parens which leaves us with lovely clean code planets.
Now Air::Base is a library of pre-built Air functions and includes a table function. In the docs it says:
role Table does Tag
Attrs thead, tbody and tfoot can each be a 2D Array [[values],] that iterates to row and columns or a Tag Component - if the latter then they are just rendered via their .HTML method. This allow for multi-row thead and tfoot.
Table applies col and row header tags as required for Pico styles.
Attrs provided as Pairs via tbody are extracted and applied. This is needed for :id where HTMX is targetting the table body.
has Mu $.tbody
default = [] is provided
has Mu $.thead
optional
has Mu $.tfoot
optional
has Mu $.class
class for table
method new
method new(
*@tbody,
*%h
) returns Mu
.new positional takes tbody [[]]All Air::Base library items such as role Table are exported as a function with the role name in .lc. The does Tag part tells other Air functions that Table is a well behaved inner for other tags when we assemble our page at the end of the code.
The assuming method primes our new planets function from the base table function.
method .assuming(Callable:D $self: |primers)
Returns a new Callable that has been primed with the arguments passed to assuming. In other words, the new function implements the same behavior as the original, but has the values passed to .assuming already bound to the corresponding parameters.So, here we are passing the table content as named attributes :thead[[]], :tbody[[]] and :tfoot[[]] to the table function and making a new planets function with the result.
Here is the HTML in the resulting page – so we took 6 lines of content and generated 42 lines of output. Saving a lot of pinky dancing on the angle brackets. And imo the Air source is more true to the rendered webpage since the content is laid out in rows and columns in the first place.
<table>
<thead>
<tr>
<th scope="col">Planet</th>
<th scope="col">Diameter (km)</th>
<th scope="col">Distance to Sun (AU)</th>
<th scope="col">Orbit (days)</th>
</tr></thead>
<tbody>
<tr>
<th scope="row">Mercury</th>
<td>4,880</td>
<td>0.39</td>
<td>88</td>
</tr>
<tr>
<th scope="row">Venus</th>
<td>12,104</td>
<td>0.72</td>
<td>225</td>
</tr>
<tr>
<th scope="row">Earth</th>
<td>12,742</td>
<td>1.00</td>
<td>365</td>
</tr>
<tr>
<th scope="row">Mars</th>
<td>6,779</td>
<td>1.52</td>
<td>687</td>
</tr>
</tbody>
<tfoot>
<tr>
<th scope="row">Average</th>
<td>9,126</td>
<td>0.91</td>
<td>341</td>
</tr></tfoot>
</table>Hopefully this table example looks familiar from the Pico CSS docs. The row and column header cells are preserved so that the standard in Pico styling is applied without cluttering the web page source.
You want a striped table? Then just add class striped like this:
my &planets = &table.assuming( :class<striped>,
:thead[["Planet", "Diameter (km)",...
(A bit hard to see since the Pico styling is quite subtle in dark mode, but trust me it’s there)
Sharp eyed readers will note that we also passed in a custom bold colour to the site function:
sub SITE is export {
site :bold-color<blue>,
index...Assuming you have been paying attention (?), a lot of the tricks in our &planets code will now be familiar and you will see the same pattern when we make a custom &index from the Air::Base library page function.
my &index = &page.assuming( #:REFRESH(5),
title => 'hÅrc',
description => 'HTMX, Air, Red, Cro',
footer => footer p ['Aloft on ', b 'Åir'],
);In this case the raku fat arrow pair syntax is a bit clearer name => 'value' … so we can make light work of adding title, description and footer content. And we can use Air::Functional code anywhere to make literal HTML – such as in our footer value.
To wrap up, once we have pre-made all our functions via assuming (or raku function composition, or currying, or wrapping) we can compose our web application in a few lines of crystal clear code:
sub SITE is export {
site :bold-color<blue>,
index
main
div [
h3 'Planetary Table';
planets;
]
}If you are developing locally, it can be useful to have a browser window open alongside your IDE (we are using IntelliJ with plugin Raku 2.0 for the code highlighting here btw) and to auto-refresh the browser with new styles and content.
#:REFRESH(5), <= uncomment meThe number is the seconds to refresh and if you launch your dev web server with cro run that will autodetect and restart the server too.
I hope you will agree that combining the power of the raku language & eco-system with HTMX and Pico CSS makes for an intriguing and refreshing new take on web development. Subscribe to this feed if you don’t want to miss the next thrilling installment.
As usual, comments and feedback welcome. We are a friendly bunch over on the raku IRC chat and Discord.
~librasteve
Steve Roe continued their stack of essays on HARC with a fourth episode: HARC Stack: Semantic Time in which they show how to do it right without repeating yourself!
Alexey Melezhik provided a brief overview of Sparky’s architecture design, a distributed jobs framework for orchestration of remote tasks (/r/rakulang /c/rakulang comments).
Weekly Challenge #321 is available for your perusal.
Parameter constructor.Feeling much better the past week, thank you for all best wishes!
Please keep staying safe and healthy, and keep up the good work! Even after week 16 of hopefully only 209.
Meanwhile, still: Слава Україні! Героям слава!
If you like what I’m doing, committing to a small sponsorship would mean a great deal!
This is the fourth of the HARC Stack essays. Previous <=> Next.
If you have made it to this episode, congratulations! You will know that HARC Stack combines HTMX with raku Air, Red and Cro to make a fresh approach to web design with server side functional code.
In the last instalment, you will have learned that – in line with HTMX – we rely on writing websites in HTML and we value keeping our tags uncluttered with a semantic approach.
We saw how tags like header, footer, nav, article, section, aside carry meaning and even self-describe their location. They help accessibility too. A full list of HTML tags considered to carry semantic weight is here.
In that article, one part of the Air::Functional source was:
section :id<blog>, [
h2 'Latest Blog Posts';
article [
h3 'The Importance of Semantic HTML';
p 'Published on ', time(:datetime<2025-03-11>);
p 'Semantic HTML is crucial for accessibility, ...';
button 'Read More';
];
...
];The bold line includes a time tag. This tag is implemented in the Air::Base component library. This source is rendered to HTML like this:
<p>Published on
<time datetime="2025-03-11">March 11, 2025</time>
</p>
The HTML tag is used to represent a specific period in time—either a time on a clock, a calendar date, or both. It’s useful for marking up dates and times in a machine-readable way, which helps with things like search engine optimization, accessibility, and microdata extraction.
Annoyingly, this aspiration is failed by the syntax of the tag. The HTML version needs us to code in both the machine readable part datetime="2025-03-11" and the human readable part March 11, 2025 side by side. This is not just the hassle of typing the same thing twice in two different ways, but also the potential for error.
Thanks to the power of HTMX we can shift the website code to the server side. Air::Base is a prebuilt library of Air::Components. And Air::Functional lets us compose our HTML tags and components in a, err, functional code style. With the time tag, the result is to Do Not Repeat Yourself when it comes to writing the date or time – the compiler will generate the human readable form automatically from the programmatic.
Here’s the full source code of the tag:
role Time does Tag[Regular] {
use DateTime::Format;
multi method HTML {
my $dt = DateTime.new(%.attrs<datetime>);
sub inner {
given %.attrs<mode> {
when 'time' { strftime('%l:%M%P', $dt) }
when 'datetime' { strftime('%l:%M%P on %B %d, %Y', $dt) }
default { strftime('%B %d, %Y', $dt) }
}
}
do-regular-tag( $.name, [inner], |%.attrs )
}
}In HTML the time tag is typically of the form < time datetime=”2025-03-13″ > 13 March, 2025 < /time > . In Air you can just go time(:datetime < 2025-02-27 > ); and raku will auto format and fill out the inner human readable text. Optionally specify mode => [time | datetime], mode => date is default.
Even more importantly, the semantic notion of time that is published via the tag and is read by external scrapers and robots is aligned to the programmatic time value that is generated by your code.
And since Air is embedded in a full power language (instead of, say, a templating language) you can use high level language constructs to have that be part of a logical pattern – a calendar or blog web application.
You will note that the role Time itself can be composed into your own raku role or class – that you can curate in your own Air::Site::Lib or even publish for others to use.
I hope you agree that a DRY approach to time tags is in line with the aims of HARC Stack … combining HTMX with raku Air, Red and Cro so that you can just build websites the right way
.
If this micro cosmic view of how HARCStack does time tags has whetted your appetite to learn more about this fresh approach to web development. All the source is available in GitHub here for you to fork and try out. Come over to the raku Discord or IRC if you want support to get started, or to feedback and collaborate…
~librasteve
Automated testing is crucial in modern software development. It helps ensure quality and prevent regressions by quickly verifying if the system continues working after code changes. Unlike manual tests, automated tests can be run repeatedly, ensuring consistency and speeding up validation. Moreover, they improve reliability by confirming that software inputs and outputs remain correct and aligned with requirements.
In this article, we’ll explore how to test applications written in Raku using three main tools: Cro, Red, and RedFactory.
Combining Cro, Red, and RedFactory, we can create web applications in Raku backed by a database and write efficient automated tests for them. Let’s walk step-by-step through setting up a simple project with these tools, defining database models, using factories to generate test data, and writing automated tests—including full HTTP integration tests using Cro::HTTP::Test.
To set up a basic project using Cro, Red, and RedFactory:
zef install cro Red RedFactory
cro stub http MyApp myapp
This creates a project under myapp/ with initial files and structure.
use Red:api<2>;
Configure the database connection:
red-defaults "SQLite", database => "myapp.db";
Now your environment is ready: a basic Cro project running, Red handling database interaction, and RedFactory set up to create test data easily.
Models represent database tables as Raku classes. Let’s define a simple model for children, storing their name and country:
use Red:api<2>;
model Child {
has UInt $.id is serial;
has Str $.name is column;
has Str $.country is column;
}
is serial marks the ID as an auto-increment primary key.is column indicates the attribute maps to a database column.Before using the model, ensure the table exists:
Child.^create-table: :unless-exists;
Now you can create records:
Child.^create: name => "Alice", country => "Brazil";
Or query them:
for Child.^all -> $child {
say $child.name, " - ", $child.country;
}
Red abstracts away SQL, making database operations much simpler and safer.
Factories allow us to create consistent test data easily. Define them like this in Factories.rakumod:
use RedFactory;
use Child;
factory "child", :model(Child), {
.name = "Test";
.country = "Unknown";
}
Now you can create test records in one line:
my $child = factory-create "child";
Or override attributes:
factory-create "child", :name<Alice>;
You can even create multiple records:
factory-create 5, "child";
Factories make tests cleaner and easier to maintain.
Testing HTTP routes without running a real server is made easy by Cro::HTTP::Test.
This module allows you to:
Example:
use Test;
use Cro::HTTP::Test;
use MyApp::Routes;
test-service routes(), {
test get("/hello/World"),
status => 200,
content-type => 'text/plain',
body => "Hello, World!";
};
done-testing;
test-service wraps your routes for testing.
test sends a request and checks expectations like status code, content type, and body.
No need to bind to ports or manage real HTTP connections—everything is fast and isolated.
Let’s use RedFactory and Cro::HTTP::Test together.
Imagine we have this API route:
get -> 'children', 'count', $country {
my $count = Child.^all.grep(*.country eq $country).elems;
content 'application/json', { :count($count) };
}
We can test it:
use Test;
use Cro::HTTP::Test;
use Factories;
use MyApp::Routes;
factory-run {
Child.^create-table: :unless-exists;
.create: 10, "child", :country<UK>;
test-service routes(), {
test get("/children/count/UK"),
status => 200,
content-type => 'application/json',
json => { :count(10) };
};
}
done-testing;
This shows how Cro, Red, and RedFactory work together cleanly.
Suppose our API has:
We can test the full flow:
use Test;
use Cro::HTTP::Test;
use Factories;
use MyApp::Routes;
factory-run {
Child.^create-table: :unless-exists;
test-service routes(), {
test get("/children"),
status => 200,
content-type => 'application/json',
json => [];
};
my %new-data = ( name => "John", country => "Portugal" );
test-service routes(), {
test post("/children", json => %new-data),
status => 201,
content-type => 'application/json',
json => { :name("John"), :country("Portugal"), *%_ };
};
test-service routes(), {
test get("/children"),
status => 200,
json => [ { :name("John"), :country("Portugal"), *%_ } ];
};
}
done-testing;
We:
Simple, clean, and fully automated.
Good practices help you keep tests maintainable, readable, and fast.
In this article, we showed how to test Raku applications using Cro, Red, and RedFactory:
The Red ORM helps you avoid boilerplate SQL and interact with the database elegantly.
RedFactory makes test data creation effortless.
Cro::HTTP::Test allows fast, isolated HTTP testing.
If you’re building web applications in Raku, combining these tools will dramatically boost your productivity and confidence in your code quality.
Give Red a try in your next Raku project—you’ll love how much easier database interactions and testing become!
In a previous article, I described how to take a web page source file, edit it, then send the edited source back to Github.
In that post, the authorisation token id-token was one I generated for myself as a Github user. It would also be possible to assign to the hallowed glade (see previous article) an authorisation for a pseudo user or bot specifically set up to take user generated editing.
However, when the edit is merged into the source, the author of the commit would be the bot, and not the author of the edit.
Suppose, though, we want a 'credits' page listing authors and the number of commits they have made. We could run a command in the repo such as:
git log --pretty="%an %n" | sort | uniq -c | sort -n -r
and filter the results into a table. But authors who have entered our hallowed glade will not be listed.
Another concern is spamming. If we require a community user to have a Github identity, then Github will handle authorisation. If there is spamming by a forest troll, it is in Github's best interest to hold that troll to account.
This post explains (mostly to myself) the steps that are needed to insert a login layer.
When I finally got the whole thing working, it was like a weird dance between three different entities. Looking at the documentation for the first time, all the steps seemed odd and unrelated, but once they were all put into motion, there is a logic to the whole thing.
We already have a hallowed glade, which is the suggestion_box server. The server runs in a docker container, and has a Cro server to handle input from a websocket, a Cro client to interact with Github to create a new branch, store the edited file, and raise a Pull Request.
Github allows the owner of a repo to register a 'Github app' and assign it permissions. So, the token granted during the authorisation process is a combination of the permissions of the app and those of a user.
It is always scary for a user to have to authorise someone else to do something on their behalf, so here is what Github says about the authorisation token:
A token has the same capabilities to access resources and perform actions on those resources that the owner of the token has, and is further limited by any scopes or permissions granted to the token. A token cannot grant additional access capabilities to a user. Github authorisation documentation
Here is diagram of the interaction between the browser, the server (in our case suggestion_box) and Github from a great article by Tony on OAuth2:
Suppose we add in the request that if an editor wants to make edits on several documents (which means the page is refreshed), then it is inefficient for Github to generate an id-token for each page.
We can keep an object in local storage with the name of the editor and the time the first submission is accepted.
Note that Github issues its web tokens for a fixed period of time, by default 8 hours.
A pre-requisite is that the Github app, which is our suggestion-box is already registered with Github.
The brief laid out above suggests the following series of steps:
editor field in the submission form must be consistent with Github rules:
-, with a minimum of three characters and a maximum of 39. -.state string that contains information for the suggestion_box to be able to issue a successful submission message back to the browser.Inside the suggestion_box server:
In this scheme,
In the previous post, the Cro app had a route for the websocket and a Client section to handle putting suggestions into Github.
We need to modify the Client section to use the editor's id-token, but essentially it remains the same.
We also need to add a route which is used by Github to send login information to the server. In addition, there needs to be a way for the webserver route and the authorisation route to interact.
These modifications imply a shared resource to match editor-name, id-token, id-token expiration date. Since Cro assumes concurrency, the storage has to be thread-safe and ensure that only one thread at a time can access it.
Although the Cro documentation uses
OO::Monitorfor this purpose, I prefer the simplerMethod::Protectedmodule. Theis protectedtrait ensures that only one thread at a time can access the shared resource. For example,
use Method::Protected;
class Editor-Store {
#| has key = editor, with two attributes :token and :time (a Date::Time)
has %!storage;
#| if False, makes sure editor key is deleted
method is-editor-active( $editor --> Bool) is protected {
return False unless %!storage{ $editor }:exists;
return True if %!storage{ $editor }<expiration> > (now.DateTime + Duration.new(10 * 60));
sink %!storage{$editor}:delete;
return False
}
#| if there is no editor, an emptry string is returned
method get-token( $editor --> Str) is protected {
if self.is-editor-active( $editor ) { %!storage{$editor}<token> }
else { '' }
}
#| expiration date
method expiration( $editor ) is protected { %!storage{$editor} }
#| returns the remaining time in seconds as an integer
method time-remaining( $editor --> Int ) is protected {
if self.is-editor-active( $editor ) { ( %!storage{ $editor }<expiration> - now.DateTime).Int }
else { 0 }
}
#| adds editor
method add-editor( Str $editor, DateTime $expiration, Str $token ) is protected {
%!storage{$editor} = :$expiration, :$token;
}
}
The Websocket route of the Cro app needed refactoring completely. Instead of getting all the information for an edit from the browser, typically, the edit suggestion comes first but the editor and their id-token comes later. So the Webocket needs to create a promise and also to put a timer on it.
My first-draft solution is (the code needs to be cleaned up somewhat):
get -> 'suggestion_box' {
web-socket :json, -> $incoming {
supply whenever $incoming -> $message {
my $json = await $message.body;
# first filter out the handshake signal for opening a websocket
if $json<loaded> {
say strftime(DateTime.now, '%v %R') ~ ': connection made'
if $debug;
emit({ :connection<Confirmed> })
}
else {
if $debug {
say strftime(DateTime.now, '%v %R') ~ ': got suggestion, now at ' ~ +@suggestions;
for $json.kv -> $k, $v {
say "KEY $k =>\n$v"
}
say "edit suggestion finished\n";
}
my $response = sanitise( $json ); # sanitise returns an error message or 'ok'
my $editor := $json<editor>;
if $response ne 'OK' {
emit( {
:timestamp( DateTime.now.Str ),
:$response,
:$editor,
})
}
# handle the socket with an active editor
elsif $store.is-editor-active($editor) {
say strftime(DateTime.now, '%v %R') ~ ': editor is registered' if $debug;
# too little time left for token
if $store.time-remaining( $editor ) <= 10 * 60 {
say strftime(DateTime.now, '%v %R') ~ ': not enough time' if $debug;
emit( {
:timestamp( DateTime.now.Str ),
:response<TooLittleTimeOnToken>,
:$editor,
})
}
else {
say strftime(DateTime.now, '%v %R') ~ ': handling with stored token' if $debug;
$json<id-token> = $store.get-token($editor);
@suggestions.push: $json;
emit( {
:timestamp( DateTime.now.Str),
:response<OK>,
:$editor,
:expiration( strftime($store.expiration($editor), '%v %R'))
} )
}
}
# the editor does not have a token, but may have in some period of time
else {
say strftime(DateTime.now, '%v %R') ~ ': editor without authorisation' if $debug;
my $timestamp;
my $response = 'NoAuthorisation';
my $expiration = '';
my $token = '';
my Promise $tapped-out .= new;
my $tap = $see-new-auths.tap( -> %a {
if %a<editor> eq $editor {
$timestamp = DateTime.now.Str;
$response = 'OK';
$token = %a<token>;
$expiration = %a<expiration>;
$tapped-out.keep;
}
});
await Promise.anyof(
$tapped-out,
my $timer = Promise.in($auth-wait-time).then: {
$response = 'NoAuthorisation';
}
).then( { $tap.close } );
if $response eq 'OK' {
$json<id-token> = $token;
@suggestions.push: $json;
say strftime(DateTime.now, '%v %R') ~ ": authorising suggestion {$json.raku}, now at " ~ +@suggestions if $debug;
}
emit( %( :$timestamp, :$response, :$expiration, :$editor) )
}
}
}
}
The $tapped-out Promise is created so that it can be kept with .keep inside the code that listens for an authorisation event.
Then a separate Promise composed of the $tapped-out Promise and a timer Promise is created so that whichever comes first triggers the next step. If the timer exits before an authorisation, then the edit suggestion is discarded, otherwise it is combined with the id-token and queued.
In the code section above, the webserver is a supply and when the emit sub is called, the hash argument is mapped by Cro into a JSON object and returned to the browser that has connected to the Cro app. So it can be picked by the Javascript's websocket's onmessage function, and the data used by the browser program.
When a Github app is registered, a route is supplied for the authorisation data. Consequently, the server section of the Cro app has to be set up to service this route. I chose the route /raku-auth (and in my code comes before the websocket, but since we are dealing with concurrent processes, the order of websocket and raku-auth is irrelevant):
get -> 'raku-auth', :%params {
CATCH {
default {
content 'text/html', '<h1>Raku documentation</h1><p>Authorisation error.</p><p>Please report</p>';
say 'error is: ', .message;
for .backtrace.reverse {
next if .file.starts-with('SETTING::');
next unless .subname;
say " in block { .subname } at { .file } line { .line }";
last if .file.starts-with('NQP::')
}
}
}
my %decoded = from-json( base64-decode( %params<state>).decode );
say strftime(DateTime.now, '%v %R') ~ ': got from Github params: ', %params , ' state decoded: ', %decoded
if $debug;
my $editor = %decoded<editor>;
my $resp = await Cro::HTTP::Client.post(
"https://github.com/login/oauth/access_token",
query => %(
:$client_id,
:$client_secret,
:code( %params<code> ),
),
);
# Github returns an object with keys access_token, expires_in (& others not needed)
my $body = await $resp.body;
my %data = $body.decode.split('&').map(|*.split("=",2));
# first store the data for future suggestions
my $token = %data<access_token>;
my $expiration = now.DateTime + Duration.new( %data<expires_in>);
$store.add-editor($editor, $expiration, $token );
# next put the data in a stream for suggestions that have already arrived
$auth-stream.emit( %( :$editor, :$expiration, :$token ) );
content 'text/html', '<h1>Raku documentation</h1><p>Editing has been authorised.</p><p>Thank you</p>';
}
get -> 'suggestion_box' {
The CATCH phaser is only ever triggered if there is an error processing the route. If it is triggered, then the string after content is sent back to Github, which displays it in the tab containing the authorisation button. The HTML could be improved.
At the end of the code, the content sub similarly sends back an HTML string to indicated authorisation is successful.
When a route has a query appended to it, the Cro route function get captures the data into a named hash, which I have called %params. Github recommends that a state variable is sent when sending the user to Github for authorisation. I have chosen to send the name submitted by the editor with Base64 encoding. Since the editor name in the form and the user's Github id could be different, this adds some complexity to improve security.
I have to say that the Cro syntax is easy to work with. When the data is transmitted as a JSON, there is the named :body field, and with the data is transmitted as a query, there is the named :query field. Otherwise the get sub has a consistent syntax. Compare this to a cURL command.
The parameters sent to the route include a code field, which is then returned (again as a query) to Github. When it receives the code, it returns the id-token for the editor. This two-fold handshake makes it difficult to impersonate someone else.
In addition, Github returns the number of seconds the id-token is valid for. So this needs to be combined into a DateTime both for the suggestion-box server and the browser.
Finally, the editor name, id-token and expiration date are both stored in a thread-safe Hash, and placed in an event stream into which the websocket has tapped.
Raku's concurent structures make it easy to set up the event loop into which the raku-auth route injects information and the websocket listens for information. At the start of the code we have
my $auth-stream = Supplier.new;
my $see-new-auths = $auth-stream.Supply;
As can be seen from the code fragments, the raku-auth route has the line $auth-stream.emit( %(...) ) and the websocket code has the line my $tap = $see-new-auths.tap( -> %a { ... }).
The first stanza supplies an item, in this case as hash, while the second listens for all items supplied. The second then determines which item to react to.
One of the pieces of data required by a Github app is a 'secret' for the app. There are also several items to be provided to the Cro app.
Since this Cro app is intended for a docker container, the configuration data is conveyed in Environment variables. So at the start of the app, several secret variables are extracted as (just an example here):
my $client_id = %*ENV<CLIENT_ID>;
and these data can be temporarily saved in an environment file env-file. Then when the docker image is invoked the data can be supplied:
sudo docker run -d --rm --env-file env-file my-docker-image
As can be seen from the diagram above, getting authorisation is delicate dance, and it took me days to stop the browser, Github and the suggestion-box treading on each others' toes.
First, the interaction between Github and the suggestion-box server to exchange a code for an id-token are all conducted using the query format. That is a url ending ?data-item=stuff&item-two=nonsense, which is in turn Base64 encoded. All the Github API calls use JSON data with authorisation headers.
In hindsight, we can recognise that the OAuth protocol is an industry standard, while the Github API protocols are not, so can be different. But it took me a while to work out what the strange data was being received by the server. I did not come across this behaviour as being explicitly documented.
Second, Github requires that the suggestion-box server is registered by the owner of the repo as a Github app and specific permissions need to be allocated to it. There are dozens of permissions in over a dozen categories and the correct ones have to be given to the Github app. I thought - mistakenly - that the permissions for Pull requests was what I needed.
Actually this was the last bug I had to overcome and it took a couple of days to figure out that the error was not in the server code, but that I had not allocated enough permissions.
To summarise, the suggestion-box server uses four separate Github API calls and the permissions are different:
api.github.com/repos/{$repo-name}/git/ref/heads/main to get the commit sha for the repo-name - this is public data and the permission is mandatory for an App, so it does not need to be specifically addedapi.github.com/repos/{$repo-name}/git/refs (with data) to create a reference - this requires the Contents permission with read/writeapi.github.com/repos/{$repo-name}/contents/{$file-path} to supply the edited - this requires the Contents permissionapi.github.com/repos/{$repo-name}/pulls to create a pull request of the new branch - this requires the Pull Request permissionSome 'simple' requests have complex solutions. Although Cro and Raku's concurrent structures take a while to understand, they are easy to apply.
MCP (Model Context Protocol) is an open and evolving protocol (see modelcontextprotocol.io) that defines how large language models (LLMs) can understand and interact with structured external capabilities.
Instead of relying solely on natural language parsing and undocumented APIs, MCP enables LLMs to introspect and call tools, retrieve and reason with resources, and invoke reusable prompts. This introduces clarity, reusability, and extensibility into AI assistant systems.
MCP defines three types of components:
These are described using JSON-compatible schemas and loaded at runtime by a supporting server. The protocol encourages modular design and agent composability.
⚠️ Note: This post presents an experimental implementation of an MCP-compatible framework for the Raku programming language. It is a work in progress, and community input is welcome.
Raku is well-suited to building MCP tooling due to its:
%?RESOURCES
These features allow developers to:
The goal is to provide an ergonomic, modular Raku framework to define and serve MCP-compatible components. The core elements are:
does MCP::Tool
%?RESOURCES), or environment variablesmcp.json file describes each group’s capabilitiesExecution is powered by servers (e.g. STDIO or HTTP), and applications can load multiple groups at once.
#| Adds two integers and returns the result
sub add(
Int $a, #= The first integer
Int $b #= The second integer
--> Int
) is export {
$a + $b
}
This produces an MCP schema and validates input before execution. Traits like is different(0) can further restrict behavior.
unit class WeatherLookup::Tool::Forecast does MCP::Tool;
has Str $.location;
#| Returns a simple forecast string
method call(--> Str) {
"The weather in $!location will be sunny."
}
MCP::Tool provides a Callable interface and derives the schema from class attributes and the return type of call().
To support legacy or utility modules:
{
"type": "function",
"module": "Math::Utils",
"function": "add"
}
Resources provide configuration, secrets, or contextual data to the assistant. You can define them as:
"resources": [ "My::Class::Name" ]
%?RESOURCES)
{
"name": "city-list",
"type": "resource",
"value": "data/cities.json"
}
{
"name": "api-key",
"type": "env",
"value": "API_KEY"
}
Prompts can be:
class GreetingPrompt {
method run() {
"Hello! How can I assist you today?"
}
}
{
"type": "string",
"name": "greeting",
"value": "Hello! How can I assist you today?"
}
Use:
mcp create prompt greeting --string "Hello! How can I assist you today?"
mcp.json
Each MCP group is a Raku module with a resources/mcp.json file listed in META6.json. This file declares the group's:
Example:
{
"tools": [
"WeatherLookup::Tool::Forecast",
{
"type": "function",
"module": "Math::Utils",
"function": "add"
}
],
"resources": [ ... ],
"prompts": [ ... ]
}
The module should implement MCP::Group and define:
unit class WeatherLookup does MCP::Group;
method group-data { %?RESOURCES<mcp.json> }
This exposes the tools, resources, and prompts using helper methods.
The mcp create commands not only generate boilerplate code but also update the group's resources/mcp.json file automatically. This file is the core of group definition and gets listed in META6.json so the framework knows how to load tools, prompts, and resources at runtime.
For example:
mcp new WeatherLookup
cd WeatherLookup
mcp create tool forecast
mcp create resource cities --file cities.json
mcp create resource api-key --env API_KEY
mcp create prompt greeting --string "Hello!"
Then run:
mcp run WeatherLookup ExtraUtils --server=stdio
This idea is still experimental. We're exploring how to best represent and serve LLM functionality in Raku using the MCP protocol.
📣 Join us in the #raku channel on Libera.Chat IRC or drop your thoughts on GitHub.
Whether you want to test ideas, write components, improve the CLI, or critique design—your help is welcome!
💡 Let’s build something great together!
The ask, expressed by our website users, is simple enough, edit a source from a GitHub repo in a browser, then save the edited version back.
How difficult is that? It's easy to point the browser at the file in the repo, and GitHub has an editor ...
The problem comes from authorisation, and bad actors wanting to add stupid stuff to files - like: I'm the brilliantish shop for high-ent wazzoo's. Come take a look at http://rip-me-off.darkweb.cosmo
Github's editor is easy to use - if you have commit permissions on the repo, otherwise:
But its only one letter!??
Also, our website text source is written in RakuDoc (not MarkDown, but that's another story) and so it would be nice to be able to see what the change looks like. As always a seemingly trivial mistake, such as deleting a < in the wrong place, can have severe effects.
So, it would be nice to see an HTML rendering of the edited text before submitting it back.
It seems doable:
fetch function. Rakuast::RakuDoc::Render into a docker container, wrote a very simple Cro app that has all the logic for a websocket. The app expects RakuDoc source, and sends back the rendered HTML, which is then added into a div next to the online editor. I'll not explain tasks 1-3 above and focus on task 4.
While getting the content is easy, returning it is hard. The API documentation is written for developers who understand Github and HTTP requests.
I spent two days wandering though the API documentation, searching for tutorials, (and Github's own discussion forum seems to be flooded with trolls, so is not a good place to look).
I even resorted - gasp - to ChatGPT. Whilst the code it suggested was not remotely what I wanted, the 'solutions' demonstrated a remarkably simple truth. Perhaps I should have realised it on my own, but in all my documentation searches I had not read a hint about it.
The simple truth: getting a patch of a file to the repo maintainers could only be done in a sequence of steps, not the single step that I was looking for.
It is obvious that Github wants to ensure that only authorised users can change the state of a repo. Authorisation is accomplished by accompanying any request for a change with a token that has a limited duration, is unique to a recognised user on Github, and has permissions for the repo.
While it is possible to get and use such a token for an arbitrary user, by sending them to Github to log in, the process is an added layer of complexity. For simplicity, we shall consider that a token has been generated and call it id-token. (For development, I used one generated for myself)
In generalised terms, here are the steps to sending a suggestion for editing a file to the Github repo. (I'll explain some of the jargon with each step).
Obtain the contents of the file and its sha from repo.
Raku/doc Github storage, where Raku is the organisation that owns the storage, and doc is the repo in which Raku holds its documentation suite.sha is the encrypted sum of the entire file, and is presented as a 40 digit hexadecimal string. The maths of shas is quite interesting but not relevant here. Suffice it to say that if a file is changed at all, the shas of the two files (before the edit and after it) will be different (for the pedantic, I'll add 'with high probability').Obtain the latest sha or commit for the repo.
Create a new branch or reference point in the repo.
Move a copy in BASE64 format of the edited file to the new branch
Raise a PR for the branch
PR is a pull request, and it is a suggestion to the repo maintainer to merge the suggested changes of the file into the main content of the repo.Even though only one letter in one file may need to be changed, the API is set up (reasonably) for many changes to many files.
Can we do this in the browser? Uh, well ... yes, but No.
The problem is that everything in a browser can be examined by the world. So if you put an id-token in a browser, it can be extracted from the browser, and then a bad actor can use the token to do silly stuff.
So, each of the steps above which require an id-token have to be executed from a place that can be defended, such as inside a container where the id-token can be hidden and renewed on a regular basis.
The solution is to create a safe location - hallowed glade - in which the id-token can be stored, and from which the calls to Github can safely be executed.
So let us create a container with a Cro application. The container will have a websocket to accept the edited file from the browser, and then separately interact with Github.
The Cro documentation was written by a genius for developers with experience, unlike me. They are daunting and confusing - it took days of work to figure things out. However, Cro does make it easy to set up the steps listed above.
The first thing to realise is that Cro::HTTP::Client and Cro::HTTP::Server / Cro::HTTP::Router are - at least externally - independent of each other, but we will need both.
We will need the Server to listen for the data coming down the websocket, and then Client to move the edited file to the Github repo.
Since step 1 above is done in-browser, it needs to be implemented in Javascript. I will not deal with that here, except to say, that when the content is fetched from Github, the sha of the file is saved. The in-browser code finally sends along a websocket a JSON object with the following fields:
The last three are not strictly needed, but can be used for some sanity testing.
Lets assume the web socket has a route suggestion_box, then the following is the code for a Cro application to get the data
use Cro::HTTP::Log::File;
use Cro::HTTP::Server;
use Cro::HTTP::Router;
use Cro::HTTP::Client;
use Cro::HTTP::Router::WebSocket;
use DateTime::strftime; # a helper to provide nice time formats
my $patch-limit = 5 * 2 ** 10; # 5k limit of chars
my $comment-limit = 1 * 2 ** 10; # 1k limit of chars
my $pr-update-duration = 10 * 60 * 60; # every ten minutes
my $host = '0.0.0.0';
my $port = 60005;
my @suggestions;
my $busy = False;
my Cro::Service $http = Cro::HTTP::Server.new(
http => <1.1>,
:$host,
:$port,
application => routes(),
after => [
Cro::HTTP::Log::File.new(logs => $*OUT, errors => $*ERR)
]
);
say strftime(DateTime.now, '%v %R') ~ ': starting up.';
$http.start; # this starts the server part of the application
# the following is an asynchronous structure which listens for events
# then does the block for that event. The main event is to stop
# the app when a control signal is raised.
react {
whenever signal(SIGINT) {
$http.stop;
say strftime(DateTime.now, '%v %R') ~ ': closing down.';
done;
}
whenever Supply.interval($pr-update-duration) {
# every pr-update-duration seconds, this block is run
# it calls the code for raising a PR
unless $busy {
$busy = True;
raise-pr( @suggestions.pop ) while @suggestions;
$busy = False;
}
}
}
# these routes are what define the application
sub routes() {
route {
get -> 'suggestion_box' { # the route for the websocket
web-socket :json, -> $incoming {
supply whenever $incoming -> $message {
my %json = await $message.body;
if %json<sha> { # no sha, no play
my $response = sanitise( $json );
# place limitations on the incoming data
# add 'cancel' to ignore data
@suggestions.push: $json.hash.clone
unless $json<cancel>;
# store the data to be sent as PR
emit({
:timestamp( strftime(DateTime.now, '%v %R')),
:$response
})
# send back to the websocket JSON with
# a time stamp and a reponse code
}
elsif $json<loaded> {
# send back a handshake when websocket opens
emit({ :connection<Confirmed> })
}
}
}
}
}
}
sub sanitise( %edit --> Str ) {
my $response = 'OK';
for %edit.keys {
when 'editor' {
%edit<editor> .= subst(/\W/, '_', :g)
.substr( ^21 )
}
when 'patch' {
if %edit<patch>.chars > $patch-limit {
%edit<cancel> = True;
$response = 'TooManyChanges'
}
}
when 'comment' { %edit<comment> .= substr(^$comment-limit) }
when <sha repo content>.any {}
default { %edit{ $_ }:delete }
# remove unwanted fields
}
$response
}
sub raise-pr( %an-edit ) { ... }
The Server code handles all the interaction between the browser and the 'Hallowed Circle'.
Now we execute the remaining steps ( 2 - 5 ) of the Github sequence.
sub raise-pr( %edit ) {
#| Define the secret token. When the container is run,
#| the token can be passed as an environment parameter.
#| Later, we can refactor to obtain it to identify the
#| user making the edits.
my $id-token = %*ENV<ID_TOKEN>;
my $base = 'https://api.github.com/repos';
# create a descriptive branch name
my $branch = strftime(DateTime.now, '%v')
~ "_{ %edit<editor> }";
# get the repo information
my $resp = await Cro::HTTP::Client.get(
"/{%edit<repo>}/git/ref/heads/main"
);
my %data = await $resp.body;
my $commit = %data<object><sha>;
# create a new branch
$resp = await Cro::HTTP::Client.post(
"$base/{%edit<repo>}/git/refs",
content-type => 'application/vnd.github+json',
auth => { bearer => $id-token },
headers => [ X-GitHub-Api-Version => '2022-11-28' ],
body => %(:sha($commit), :ref("refs/heads/$branch"))
);
%data = await $resp.body;
# update file into new branch
$resp = await Cro::HTTP::Client.put(
"$base/{%edit<repo>}/contents/{%edit<path>}",
content-type => 'application/vnd.github+json',
auth => { bearer => $id-token },
headers => [ X-GitHub-Api-Version => '2022-11-28' ],
body => %(
:sha(%edit<sha>),
:$branch,
:content(%edit<content>),
:message(%edit<comment>),
)
);
%data = await $resp.body;
# should check to make sure OK
# Raise a PR for the new branch
$resp = await Cro::HTTP::Client.post(
"$base/{%edit<repo>}/pulls",
content-type => 'application/vnd.github+json',
auth => { bearer => $id-token },
headers => [ X-GitHub-Api-Version => '2022-11-28' ],
body => %(
:title("Web edit of {%edit<path>}"),
:head($branch),
:base<main>,
:body("Edit suggested by ｢{%edit<editor>}｣ because ｢{%edit<comment>｣}"),
)
);
}
The Github documentation for the PR was particularly confusing because head, base, and body did not seem to be intuitive taken on their own.
I have documented my journey into and out of the woods using as little jargon as possible. My purpose in doing this was to describe it so I could understand it myself, and also in the hope that the gods of the internet (aka search engines) will guide someone else who may have a similar set of issues.
Naturally, the container is part of a bigger system, and it needs to be tested. But that raises more questions, so I will only be brief.
It is not so easy to test a websocket. My approach was:
localhost.Following up from the Raku Codeboard post, here’s a small but exciting addition: a new Cromponent to render Raku code with syntax-aware highlighting — but not by guessing or string-parsing. This one uses RakuAST to actually deparse the code and generate a formatted view.
The Cromponent comes from a new experimental project called RakuCode. It's an early-stage attempt to use RakuAST for analyzing and rendering code — and while it’s not ready for every use case, it’s already quite promising.
This Cromponent renders Raku code inside your app (like Codeboard), but instead of:
…it parses the code with RakuAST, and then deparses it using a custom renderer. That means you’re not just styling code — you’re formatting the actual language structure.
RakuCode is itself a Cromponent, so usage is simple and clean. Here's an example taken from the README:
<:use Boilerplate>
<:use RakuCode>
<|Boilerplate(:htmx, :title('Testing Raku Code Component'), :style-sheets('/css'))>
<|RakuCode>
class :: {
has UInt $!id;
has Str $.key;
has $.value;
}
</|>
</|>
This uses <|RakuCode> ... </|> to embed code that will be parsed using RakuAST and displayed in a formatted way. This allows you to display actual Raku code with structure-aware formatting in any Cromponent-based view.
No client-side syntax highlighter is needed. This is all done on the server using real AST analysis.
This is very early. Some known issues:
But it works well for basic expressions, function definitions, variable usage, and more.
Even this small feature opens the door to things like:
RakuCode is open-source and very early. If you like where this is going, contributions are welcome — whether you:
Check out the repo and feel free to open issues or PRs.
This is just the beginning. Integrating RakuAST into UI components is a powerful concept, and Cromponent makes it easy to plug in clean rendering into your Raku web apps.
With RakuCode, we can explore what it means to truly understand and render code — not just decorate it.
👉 Try it out: https://github.com/FCO/RakuCode
Let me know what you'd like to see next!
This is the third of the HARC Stack essays. Previous <=> Next.
In previous instalments, you have learned how I fell in love with HTMX. The power to build websites on the server side in my favourite language (raku, since you ask) was back in my hands and all the react / vue complexity could be swept away.
As you have seen, HARC Stack is there so that you can just build websites the right way. This is a lofty goal and everyone has their own opinion. Maybe you will agree. I hope so. Or maybe I am just howling at the moon.
So as I started to research HTMX, with the idea to start building some real websites, it seemed that many HTMX projects use Pico CSS. I took a look and it was clear why this is such a good pairing. Here’s what it says on the Pico home page hero section:
[there will be more (much more) on CSS later in the series, this one is about Semantic HTML]
Digging in a bit on the topic, I learned some cool stuff.
Semantic HTML refers to the use of HTML elements that convey meaning about the content they contain, beyond just how they appear visually. Instead of using generic tags like <div> or <span> for everything, semantic HTML encourages using elements such as <article>, <section>, <header>, <footer>, <nav>, and <main> to structure content in a way that reflects its purpose and role within a document.
This approach improves accessibility, SEO, and maintainability. Assistive technologies, like screen readers, rely on semantic elements to provide users with context and navigation capabilities. Search engines also parse these elements to better understand page content, which can improve indexing and ranking. From a developer perspective, semantic HTML contributes to cleaner, more readable markup and encourages modular, predictable structures.
While CSS and JavaScript can often recreate the behaviours or appearances associated with semantic elements, they do not replace the inherent value of semantic markup in conveying meaning. For expert developers, adopting semantic HTML is less about learning new tags and more about being intentional with markup choices, aligning with web standards and best practices for long-term scalability and clarity.
Excellent. Use HTMX and Semantic HTML together. Put HTML tags at the centre of the design. Apply HTMX to bring in dynamic behaviours and Semantic tags for clarity.
What’s not to like?
So, here’s how that looks in HTML proper (sorry it’s a bit long but I felt that you would like to see how a whole page of Semantic HTML looks in practice):
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
<header>
<h1>Welcome to My Blog</h1>
<nav>
<ul>
<li><a href="#home">Home</a></li>
<li><a href="#blog">Blog</a></li>
<li><a href="#about">About</a></li>
<li><a href="#contact">Contact</a></li>
</ul>
</nav>
</header>
<main>
<div>
<section id="blog">
<h2>Latest Blog Posts</h2>
<article>
<h3>The Importance of Semantic HTML</h3>
<p>Published on <time datetime="2025-02-23">February 23, 2025</time></p>
<p>Semantic HTML is crucial for accessibility,....</p>
<a href="#" role="button">Read More</a>
</article>
<article>
<h3>Getting Started with Pico CSS</h3>
<p>Published on <time datetime="2025-02-20">February 20, 2025</time></p>
<p>Pico CSS is a minimal CSS framework ...</p>
<a href="#" role="button">Read More</a>
</article>
...
</section>
<section id="contact">
<h2>Contact Us</h2>
<form>
...
</form>
</section>
</div>
<aside>
<h2>About Me</h2>
<p>I'm a web developer passionate about...</p>
<h3>Recent Posts</h3>
<ul>
<li><a href="#">The Future of Web Design</a></li>
...
</ul>
<h3>Follow Me</h3>
<nav>
<ul>
<li><a href="#">Twitter</a></li>
...
</ul>
</nav>
</aside>
</main>
<footer>
<p>© 2025 My Blog. All rights reserved.</p>
</footer>
</body>
</html>
The full code is at https://github.com/librasteve/Air-Play/blob/main/semantic-example.html.
Already the semantic intent is clearly visible. Much better for maintainers. If you like to write your websites in HTML templates, then this works great with Cro template.
Now, applying the Air::Functional twist (remember that the raku Air module is the “glue” in the HARC Stack), we can further strip out a lot of angle bracket <> line noise:
use Air::Functional :BASE;
use Air::Base;
site
page [
header [
h1 'Welcome to My Blog';
nav [
:Home(internal :href<#home>),
:Blog(internal :href<#blog>),
:About(internal :href<#about>),
:Contact(internal :href<#contact>),
];
];
main [
div [
section :id<blog>, [
h2 'Latest Blog Posts';
article [
h3 'The Importance of Semantic HTML';
p 'Published on ', time(:datetime<2025-02-27>);
p 'Semantic HTML is crucial for accessibility, ...';
button 'Read More';
];
article [
h3 'Getting Started with Pico CSS';
p 'Published at ', time(:datetime<2025-02-20>);
p 'Pico CSS is a minimal CSS framework ...';
button 'Read More';
];
...
];
section :id<contact>, [
h2 'Contact Us';
form [
...
];
];
];
aside :id<about>, [
h2 'About Me';
p "I'm a web developer passionate about ...";
h3 'Recent Posts';
ul [
li a :href<#>, 'The Future of Web Designs';
...
];
h3 'Follow Me';
nav [
:Twitter(external :href<#>),
...
];
];
];
footer
p safe '© 2025 My Blog. All rights reserved.';
]
The full code is at https://github.com/librasteve/Air-Play/blob/main/lib/Air/Play/Site06-Semantic.rakumod
Very clean, crystal clear. This is the way!
I have turned off the (rather poor) WordPress syntax highlighting to allow a like for like comparison.
This is how the two full code pages (raku & HTML) appear side by side in Intellij Universal (with Raku plugin v2.0).
I leave this post with a few words from the dead:
HTMX complements Semantic HTML by:
Preserving Element Roles: Interactive elements retain their native semantics (e.g., buttons trigger actions, forms submit data).
Avoiding Div Soup: Updates target specific elements using CSS selectors, reducing reliance on non-semantic wrappers.
Progressive Enhancement: Works alongside standard HTML attributes like href and action, ensuring baseline functionality without JavaScript
What’s not to like, indeed. Well – tune in for the next episode to see how HTMX attribute noise can be tamed….
As usual, comments and feedback welcome. We are a friendly bunch over on the raku IRC chat and Discord.
~librasteve
Welcome to a walkthrough of Raku Codeboard — a small but complete full-stack web application built entirely in Raku. It lets you submit, store, and discuss code or comments under different topics. This blog post explains how it works using your actual code and shows how it leverages Red, Cromponent, and HTMX together.
👉 Source Code: https://github.com/FCO/Discuss
Raku Codeboard is a lightweight app where users can:
The stack:
This is your full app.raku, setting up Cro and wiring routes to Cromponents:
#!/usr/bin/env raku
use lib "lib";
use lib "bin/lib";
use Cro::HTTP::Router;
use Cro::HTTP::Server;
use Cro::WebApp::Template;
use Red:api<2>;
use Topic;
use Topics;
use People;
use Person;
use Message;
my $routes = route {
red-defaults "SQLite";
my $schema = schema(Topic, Person, Message).create;
Topic.^add-cromponent-routes;
Topics.^add-cromponent-routes;
People.^add-cromponent-routes;
template-location "resources/";
get -> {
template "index.crotmp", %(
topics => Topic.^all,
people => Person.^all,
)
}
}
my Cro::Service $http = Cro::HTTP::Server.new(
http => <1.1>,
host => "0.0.0.0",
port => 3013,
application => $routes,
);
$http.start;
say "Listening at http://0.0.0.0:3013";
react {
whenever signal(SIGINT) {
say "Shutting down...";
$http.stop;
done;
}
}
Your template renders two Cromponents: <&People> and <&Topics>:
<:use Boilerplate>
<|Boilerplate(:title('Todo - test cromponent'), :htmx)>
<style>
div.topics:empty:before {
content: "No topics yet. Be the first to start one!";
}
div.messages:empty:before {
content: "No messages yet. Be the first to create one!";
}
div.people:empty:before {
content: "No people yet. Be the first one!";
}
</style>
<a
href="/topics"
hx-get="/topics"
hx-target=".main"
>
Topics
</a>
<a
href="/people"
hx-get="/people"
hx-target=".main"
>
People
</a>
<h1>Raku Codeboard</h1>
<div class="main" hx-trigger="load" hx-get="/topics"></div>
</|>
use Cromponent;
use Topic;
unit class Topics does Cromponent;
has @.topics = Topic.^all;
method LOAD { ::?CLASS.new }
method RENDER {
Q:to/HTML/;
<h2>Create a new topic</h2>
<form
method="post"
action="/topic"
hx-post="topic"
hx-target=".topics"
hx-swap="beforeend"
hx-on::after-request="this.reset()"
>
<input type="text" name="nick" placeholder="Your nick" required>
<input type="text" name="title" placeholder="Topic title" required>
<button>Start Topic</button>
</form>
<h2>Topics</h2>
<div class="topics"><@.topics.Seq><&HTML(.Card)></@></div>
HTML
}
sub EXPORT { Topics.^exports }
use Red:api<2>;
use Cromponent;
use Person;
use Topic::Card;
unit model Topic does Cromponent is table<topic>;
has UInt $.id is serial;
has Str $.title is unique{ :nullable };
has @.messages is relationship(*.topic-id, :model<Message>);
has UInt $.author-id is referencing(*.id, :model<Person>);
has UInt $.author is relationship(*.author-id, :model<Person>);
method LOAD(UInt() $id) { ::?CLASS.^load: $id }
method DELETE { $.^delete }
method CREATE(Str :$nick, Str :$title) {
Topic.^create(:$title, :author{ :$nick }).Card
}
method message(Str :$body!, Str :$nick!, Bool :$code = False) is accessible{ :http-method<POST> } {
$.messages.create: :$body, :$code, :author{ :$nick }
}
method RENDER {
Q:to/HTML/;
<div class="topic">
<strong><.title></strong> <small>by <.author.nick></small>
<div class=messages><@.messages.Seq><&HTML($_)></@></div>
<form
method="POST"
action="/topic/<.id>/message"
hx-post="/topic/<.id>/message"
hx-target=".main"
hx-on::after-request="this.reset()"
>
User name: <input name="nick"><br>
<input type="checkbox" name="code"> code<br>
<textarea name="body"></textarea><br>
<button>Send</button>
</form>
</div>
HTML
}
method Card {
Topic::Card.new: :$!id, :$!title, :$!author
}
sub EXPORT { Topic.^exports }
use Red;
use Cromponent;
unit model Topic::Card does Cromponent;
has UInt $.id is required;
has Str $.title is required;
has $.author is required;
method RENDER {
Q:to/HTML/
<div class="topic">
<a
href="/topic/<.id>"
hx-get="/topic/<.id>"
hx-target=".main"
>
<strong><.title></strong>
</a>
<small>by <.author.nick></small>
</div>
HTML
}
use Red;
use Cromponent;
unit model Message does Cromponent is table<message>;
has UInt $.id;
has UInt $.topic-id is referencing(*.id, :model<Topic>);
has $.topic is relationship(*.topic-id, :model<Topic>);
has Str $.body;
has UInt $.author-id is referencing(*.id, :model<Person>);
has $.author is relationship(*.author-id, :model<Person>);
has Bool $.code;
method LOAD(Str() $id) { ::?CLASS.^load: $id }
method DELETE { $.^delete }
method RENDER {
Q:to/HTML/
<div class="message">
<.author.nick><br>
<.body>
</dev>
HTML
}
subset Text is sub-model of Message where *.code.not;
subset Code is sub-model of Message where *.code.so;
use Cromponent;
use Person;
unit class People does Cromponent;
has @.people = Person.^all;
method LOAD { ::?CLASS.new }
method RENDER {
Q:to/HTML/;
<h2>People</h2>
<div class="people"><@.people.Seq><div><&HTML($_)></div></@></div>
HTML
}
sub EXPORT { People.^exports }
Everything works together like this:
hx-post to Cromponent route methods (e.g., CREATE, message).main or .topics)All routes are declared using .^add-cromponent-routes, so you don’t need to write routing logic by hand.
This app is fully functional and real — and it’s all in Raku. It combines:
🔗 https://github.com/FCO/Discuss
Let me know what you’d like to add!
This is part 2 in the REPL Avalanche blog series.
The REPL distribution also offers a repl subroutine apart from a command-line interface (CLI). A call to this subroutine can be placed in source code during development of a code-base, and then allows for some ad-hoc interactive debugging features.
For the purpose of fun and taste, I will be calling such a (temporary) placement of a call to the repl sub a "sprinkle".
All of the examples in this blog post assume that the
REPLdistribution has been installed, and has been loaded either explicitely with ause REPLcommand in your code, or by setting theRAKUDO_OPTenvironment variable to include-MREPL.
One of the ways you can use the REPL distribution is as a debugging tool. Instead of putting print or dd statements in your code, you can sprinkle repl statements in your code. And then interactively check out the situation when that repl statement is executed. A very contrived and simplified example:
#line 666 foo.raku
my $answer = 42;
if $answer == 42 {
repl
}
would open the REPL with:
block at foo.raku line 666
[0] >
Note that it does not show the standard REPL header, which would look like this:
Welcome to Rakudo™ v2025.02.
Implementing the Raku® Programming Language v6.d.
Built on MoarVM version 2025.02.
To exit type '=quit' or '^D'. Type '=help' for help.
because that would become very annoying for regular users of the repl subroutine.
Instead of that, it shows the location of the block in which the repl subroutine was called. This should give you a rough idea of where you are in the code at the moment the repl is called. Which can be handy if you have a number of repl calls sprinkled in your code.
If you would like to know the value of the variable $answer once in the REPL, then you can enter that variable as you could any other expression:
[0] > $answer
42
[1] >
Because the repl subroutine knows about the runtime context it is being called, it can look up any variable that could be referenced in the location of the code where the repl subroutine was called.
Not only can you look up values in variables, you can also change them! Continiuing the above sprinkle:
[1] > $answer = 137
137
[2] > $answer
137
[3] >
This allows one to explore "what-if" scenarios, and the like. Of course, changes are only allowed on things that are changeable, just like they would be in normal execution of code.
If you would only like to open a REPL if something unexpected happens, you can of course do that as well. Again, a contrived example:
if 42 -> $answer {
repl if $answer != 42;
}
would only open up a REPL if the answer was wrong. In this example, that will of course be never. But I hope you get the picture!
Sometimes you are not so much interested in the exact location in the code, but are more interested in a logical step in your code. To allow easy identification of the sprinkle, you can pass a string in the call to the repl subroutine:
if 42 -> $answer {
repl "What did Deep Thought say?";
}
would then open the REPL with:
What did Deep Thought say?
[0] >
If you want to get a little more whimsical: all of the expansions that are possible in the prompt are also possible in this string. And since we could always use a little fun, why not identify your sprinkle with:
if 42 -> $answer {
repl ":clown-face:";
}
which would then open the REPL with:
🤡
[0] >
Or you could express your feeling about this debugging session with "😕" (😕) or ":exploding-head:" (🤯).
See the
Text::Emojidocumentation for some inspiration.
Once in the REPL again you could enter "$answer" to find out the answer. But that would get pretty boring in a loop pretty quickly!
If you'd like to know the value of one or more variables or expressions at a specific sprinkle, you can also prime the sprinkle with named arguments. For instance:
if 42 -> $answer {
repl "Ready!", :$answer, :time<:HHMM:>;
}
would then open the REPL with:
Ready!
answer: 42
time: 15:10
[0] >
which not only would give you the value of the "$answer" variable immediately so you wouldn't have to ask for the answer every time you enter that sprinkle.
And you'd know the time: if the value of a primed expression in the call to repl is a string, it will allow for all the expansions that are possible in the prompt as well. In this example ":HHMM:" expands to the current hour and minute.
Check the
DateTime::strftimedocumentation for more inspiration.
Generally, once you're done with a specific sprinkle, you'd like to continue executing your code. So you'd need to leave the REPL with "=quit" (or its shortening: "=q"). That also can get annoying after a while.
That's why the REPL gets in a special mode when called as a sprinkle. The "empty" command is then the same as "=quit", so you only need to press ENTER without having entered anything to continue execution.
By using sprinkles in your code, you can both interactively look up values in your code, as well as immediately see any values / expressions that you would be interested in for a specific sprinkle.
This is the second part of a series of blog posts about the REPL distribution. Future installments will look at the available commands, and the completions logic.
Image courtesy of Salve J. Nilsen.
If you like what I'm doing, committing to a small sponsorship would mean a great deal to me!
The Raku Programming Language has a nice feature that goes by different names: "currying", "priming" or "partial application". Oddly enough, the method name associated with the feature is called assuming.
So what does the .assuming method do? In short, it creates a subroutine from an existing subroutine (or method, or pointy block) with one or more arguments already "filled in". For instance:
sub hello($firstname, $lastname) {
say "Hello, $firstname $lastname";
}
hello "Joe", "Smith"; # Hello, Joe Smith
my &hi-smith = &hello.assuming(*, 'Smith'); # fill in 2nd positional
hi-smith("Joe"); # Hello, Joe Smith
This is a simple example in which one positional parameter is replaced. Replacing named arguments is also possible, and adding values to slurpy arrays as well.
Let's take the max subroutine that returns the maximum of the given values. In this case we make sure that the maximum value of any number of values given, is at least 0. By making sure that the value 0 is always added to any list of values specified. Which also handles the case if called without any arguments.
my &max0 = &max.assuming(0); # always add 0 as a value to be checked
say max -1, -2, -3; # -1
say max0 -1, -2, -3; # 0, because 0 is greater than -1;
say max; # -Inf, smallest possible numeric value
say max0; # 0, because max(0) is 0
The original implementation of .assuming was done by Brian S. Julin in July 2015. The commit message mentioned:
This currently uses EVAL to construct the closure, which is LTA, but it gives us something functional/testable to work forward from.
In the close to 10 years since then, only small tweaks and fixes have been applied by a group of Rakudo core developers. But the essentially hacky approach of building a string with Raku code, and then EVAL it, did not change. Simply because there were no alternative solutions.
Apart from being hacky, the EVAL approach added quite a bit of runtime overhead. Not only would it take time to create the string with Raku code to be evaluated, and run the evaluation itself (which could potentially happen at compile time, so not a real worry for modules). It would also process arguments at runtime. That runtime overhead also caused an issue to be made in early 2019: .assuming is painfully slow. But since there was no alternative approach available, the issue remained dormant for more than 6 years.
Fastforward to today. There is now an alternative way of building code that is to be executed: RakuAST.
The RakuAST project was started by Jonathan Worthington. From the grant proposal:
The goal of RakuAST is to provide an AST that is part of the Raku language specification, and thus can be relied upon by the language user. Such an AST is a prerequisite for a useful implementation of macros that actually solve practical problems, but also offers further powerful opportunities for the module developer.
About two years ago yours truly blogged a little about it already: RakuAST for Early Adopters. Since then, development has continued to a point where almost all features of Raku can be expressed using the new Raku grammar, which builds its AST using RakuAST (now at 94.9% of test files completely passing).
Having looked at making .assuming produce faster code in 2019 already, it felt like a good time to do another attempt. But this time using RakuAST!
The goal would be that for a simple case like:
sub foo(Int $a) { ... }
my &bar = &foo.assuming(42)
.assuming would effectively create a subroutine bar that would just be:
sub bar() { foo(42) }
without any additional runtime overhead.
Just over two weeks ago a prototype was created. Outside of the core setting, just in a simple script. And the initial results turned out to be promising: some simple examples turned out to be already 40x as fast as the original implementation. As more features were added, that number went down for some cases as was to be expected.
As for the "more features" bit: wow, quite a number of features that you can have in the signature of a subroutine!
Or how I learned more about signatures than I would ever like to know. Apart from positional and named arguments, you can also have slurpy arrays (3 types) and slurpy hashes. And captures (named or nameless), without or without sub-signatures. And then you can specify a variable as a value, which can be changed by the subroutine if it was defined with is raw. Various constraints can be applicable: as code blocks, or as types: possibly parameterized, and/or coerced and/or with a type smiley. And then there are generics (aka type object placeholders). Put them all together in a mix and let the fun begin!
That was actually the most work: getting all of the interactions right. And while doing that, 3 bugs were found that had to do with the use of generics in parameterization, and role composition. One of them is fortunately already fixed.
In any case, as of this writing it appears that every possible combination of signature features are supported by the new implementation of .assuming.
In Raku one can easily introspect aspects of code: given a Sub object, one can ask for its signature (which is a Signature object). And given a Signature object, one can ask for its parameters (which would be Parameter objects), and one can ask for the return value / type constraint (which would generally be a type object. And given a Parameter object, one can ask whether it is a named or positional parameter, whether it optional or not, its constraint and many other aspects.
To be able to build a new Sub object, these aspects of signatures, parameters and types need to be converted to RakuAST objects. Any code trying to do similar things as .assuming, could benefit from this logic. Therefore this part of the work on .assuming has also been published as the RakuAST::Utils distribution.
To give you an idea how this looks like:
use RakuAST::Utils;
sub foo(Int $a, Int(Str) $b --> Str:D) { "foo" }
say SignatureAST(&foo.signature);
# RakuAST::Signature.new(
# parameters => (
# RakuAST::Parameter.new(
# type => RakuAST::Type::Simple.new(
# RakuAST::Name.from-identifier("Int")
# ),
# target => RakuAST::ParameterTarget::Var.new(
# name => "\$a"
# )
# ),
# RakuAST::Parameter.new(
# type => RakuAST::Type::Coercion.new(
# base-type => RakuAST::Type::Simple.new(
# RakuAST::Name.from-identifier("Int")
# ),
# constraint => RakuAST::Type::Simple.new(
# RakuAST::Name.from-identifier("Str")
# )
# ),
# target => RakuAST::ParameterTarget::Var.new(
# name => "\$b"
# )
# ),
# ),
# returns => RakuAST::Type::Definedness.new(
# base-type => RakuAST::Type::Simple.new(
# RakuAST::Name.from-identifier("Str")
# ),
# definite => True
# )
# )
The functionality offered by this distribution could possibly become core at some point, but the interface / API should mature a bit before that. Also, the RakuAST interface itself isn't fully stable yet, so this module can provide a more stable interface as a central place to handle any RakuAST interface changes.
There were quite a few tests for the .assuming logic in the official Raku test suite (aka "roast"). Alas, many of them were testing implementation details of the signatures created by the old (incomplete) implementation. They have either been adjusted, or removed altogether. And some new tests have been added, to cover some features that were not supported yet.
Benchmarking during the development process showed that the RakuAST approach to .assuming was between 2.5x and 50x faster than the old string EVAL. However, the slowdown that was mentioned in the issue turned out to be underestimated: quite a few tests showed an actual slowdown of up to 80x. So even being 50x faster on a 80x slower case, is still significantly slower :-(
A small benchmark on a 2020 M1 Apple Silicon processor (no JIT available):
sub a($a) { $a }
sub b() { a(42) }
BEGIN my &c = &a.assuming(42);
my &d = &a.assuming(42);
{ a(42) for ^10_000_000; say now - ENTER now } # 0.352358404
{ b() for ^10_000_000; say now - ENTER now } # 0.415636707
{ c() for ^10_000_000; say now - ENTER now } # 1.234486065
{ d() for ^10_000_000; say now - ENTER now } # 1.404967796
Which shows that the new .assuming approach (c) is still almost 3x as slow (1.234486065 / 0.415636707 = 2.97) as a handmade intermediate subroutine (b).
Also note that running .assuming at runtime makes it even slower still (3.38x): probably because it then misses some static optimizations that are run at compile time.
With more work done on RakuAST, specifically with regards to optimizations, it should be possible to eliminate the difference between b() and c().
On the other hand, please keep in perspective that these benchmarks were run for 10 million times, where the runtime was mostly spent in calling a subroutine, and not much else. In any fleshed out subroutine, the .assuming overhead will probably be drowned away in the time needed to execute the rest of the code in the subroutine.
The RakuAST project has reached such a maturity that it could be used to re-imagine the currying / priming / partial applocation logic of the Raku Programming Language. And that this re-imagination has made that functionality an order of magnitude faster, while still not being fully optimized yet.
Thanks to the Raku Foundation for supporting this work on .assuming.
If you like what I'm doing, committing to a small sponsorship would mean a great deal to me!
Sometime in early November, I decided to have a look at re-imagining the REPL (Read, Eval, Print, Loop) that is provided by default by the Raku Programming Language. Little did I know that that work would in the end result in six new distributions. Each providing some useful sub-functionality of the REPL, but also providing useful functionality outside of the REPL context.
Parallel to this effort, a Problem Solving Issue was created about the lack of configurability of the standard REPL, and a proof of concept Pull Request was made by Will Coleda, which proved to be inspirational.
But first, for the uninitiated, a small introduction. The Raku standard REPL can be invoked by calling raku from the command line without any arguments:
$ raku
Welcome to Rakudo™ v2025.01.
Implementing the Raku® Programming Language v6.d.
Built on MoarVM version 2025.01.
To exit type 'exit' or '^D'
[0] >
And then you can enter Raku code and have it immediately executed. For example:
[0] > my $a = 42
42
[1] > say "a = $a"
a = 42
[1] > say $*0
42
[1] > exit
$
The number between square brackets indicates the number of expression values that have been saved. It is also the index at which the next expression value will be saved.
Note that that number went from 0 to 1 after the first line entered. But not after the second line entered. This is because the first line did not cause any output. In that case, the REPL will show the value of the expression and keep it for future reference.
The second line entered did cause some output, so the value was not saved, and the index was not incremented.
Finally, the third line shows how you can refer to the originally saved value, by accessing the dynamic variable $*0 (with the number corresponding to the index at which the value was saved).
There is no help available in the standard REPL: it doesn't even have any commands! The way to exit the REPL is to type "exit". Which is in fact calling the Raku
exitfunction that exits the current process.
Three months on since November 2024, the REPL distribution provides a REPL that is ready for production (so to speak, as the use of this tool in production would be limited).
zef install REPLis enough to install this distribution and all of its dependencies.
The REPL distribution provides the same features as the standard Raku REPL, but also provides:
repl subrepl for direct accessREPL role to facilitate further customizationOver the coming months, a number of additional features will probably be added as well, depending on demand. But first, let's have a look at one of the features.
When using the repl command line script, one can customize the prompt with the --the-prompt and --symbols named arguments. For example:
$ repl --the-prompt='[:index:] :HHMM: :symbol: ' --symbols=🦋,🔥
Welcome to Rakudo™ v2025.01.
Implementing the Raku® Programming Language v6.d.
Built on MoarVM version 2025.01.
To exit type '=quit' or '^D'. Type '=help' for help.
[0] 20:51 🦋 if 42 {
[0] 20:51 🔥 say "foo"
[0] 20:51 🔥 }
foo
[0] 20:52 🦋
The --the-prompt part of the customization exists of a string that can hold any Unicode codepoints, as well as:
\e[33m)strftime escape codes (e.g. %R)strftime placeholder (.e.g. :HHMM:)That's quite a lot of possibilities: the
Prompt::Expanddistribution provides an overview, as well as theText::Emojidistribution for the emojis.
The same applies for the --symbols argument. This argument specifies what the :symbol: placeholder should be converted to. This symbol indicates the state of the REPL with regards to code compilation. Two states are currently recognized:
Note that the different states are separated by a comma in the specification.
If the --the-prompt part does not contain a :symbol: placeholder, it will be automatically added at the end. So the above example could also be written as:
$ repl --the-prompt='[:index'] %R' --symbols=':butterfly:,:fire:'
"That's all nice, but I really don't want to enter all of those arguments every time", you might think, or even say out loud. Fear not, there are also environment variables that you can set to achieve the same result. The above example could also be written as:
$ export RAKUDO_REPL_PROMPT='[:index:] :HHMM:'
$ export RAKUDO_REPL_SYMBOLS=':butterfly:,:fire:'
$ repl
[0] 20:57 🦋
If you want, you can put those environment variables in your startup script, so that these settings always apply by default.
A word of caution: yours truly has spent a lot of time playing with the prompt settings. It can be a serious time-sink.
And of course, if you're only interested in removing the [0] part from the prompt (as was the original reason for the Problem Solving Issue), you can just export an empty RAKUDO_REPL_PROMPT: export RAKUDO_REPL_PROMPT=.
Although it was my original intent that the REPL module would be incorporated into the core, it now feels like it has gotten so many features (and dependencies) that it has probably become too big to be incorporated in the Raku core. Which leads to the question whether a subset of the functionality should be incorporated in core, or that maybe the REPL should be removed from core altogether. And include the REPL distribution and its dependencies in all derived packaging, such as Rakudo Star.
This is the first part of a series of blog posts about the REPL distribution. Future installments will look at the available commands, the completions logic, and how the repl subroutine can be used in debugging your code.
If you're curious as to which new distributions that were created to supporte the REPL distribution, and can't wait, here they are (in alphabetical order):
CodeUnit - provide a unit for execution of codeCommands - handle interactive user commandsDateTime::strftime - provide strftime() formatting for DateTime objectsPrompt - a smarter prompt for user interactionPrompt::Expand - provide prompt expansion logicText::Emoji - provide :text: to emoji translationImage courtesy of Salve J. Nilsen
If you like what I'm doing, committing to a small sponsorship would mean a great deal to me!
This is part 4 in the "Towards more coverage" blog series.
The first blog post showed the basic usage of the Test::Coverage distribution. But it can do more!
If you have a situation where all of the test in a distribution cover all of the executable code, you can simplify the test file to:
use Test::Coverage;
must-be-complete;
This will set the plan to 1 test, and mark it ok if indeed all code is covered.
Should that fail for some reason, then the report and source-with-coverage subroutines will be called, providing the developer with feedback on which lines were not covered.
If you want to be clear to yourself what the goal is for coverage testing, you could mark this subroutine as "todo":
use Test::Coverage;
todo "needs more tests!";
must-be-complete;
This will make sure that on the one hand the failure of coverage testing will not stop you from uploading a new release with e.g. App::Mi6, but will make it clear to any current or future maintainer that the intent was to cover all code in tests.
Personally, I wouldn't do this though. Coverage testing feels too much like bondage to me then, and programming really should be fun!
Even if the tests say that all lines of code are covered, does that guarantee that all code paths are covered? Probably not. Why is that?
Well, that's because the granularity of code coverage is source line based. And a lot can happen in one line of Raku source code! For example, take this simple ternary:
my $a = <foo frobnicate>.pick; # either "foo" or "frobnicate"
my $b = $a eq "foo" ?? "bar" !! "baz";
From a code coverage point of view, it doesn't matter whether $a had the value "foo" or "frobnicate" in the assignment to $b. But for the execution of your code, that might really have different results!
One way around that, might be to split that ternary over multiple lines:
my $a = <foo frobnicate>.pick; # either "foo" or "frobnicate"
my $b = $a eq "foo"
?? "bar"
!! "baz"
;
But that also feels a bit icky: adapting your coding style just to satisfy any coverage testing.
It's probably better to realize that 100% coverage testing is still no guarantee that all possible code paths are tested. And that you should always remain vigilant with regards to testing your code: find new ways to break it, and make tests to spot such breakage!
Of the 225 distributions that I am currently personally maintaining, 108 of them now have coverage testing enabled. 32 of them have complete coverage testing. So that's still a lot of modules not being tested, and definitely a lot not fully covered. After the initial push to test the coverage testing itself, I did about 100 of them. That gave me a good idea of all of the corner cases.
Now I add coverage testing only if a distribution needs updating. And any new distribution gets coverage testing, of course!
The new Slang::Lambda is a very small distribution that allows one to use λ as a synonym for the pointy block starter -> in Raku source code. This is a really small module, so coverage testing should be easy, one would think.
The problem is that one piece of code is executed when the legacy grammar is used, and the other piece of code is executed if the new Raku grammar (RakuAST) is used. And one can only be executing code in one or the other grammar!
Fortunately, the Test::Coverage distribution allows one to handle that case as well, by being a little more verbose. The test file looks like:
use Test::Coverage;
default-coverage-setup;
run;
%*ENV<RAKUDO_RAKUAST>=1;
run;
must-be-complete;
Note that now we explicitely run the default-coverage-setup and run subroutines (which would normally be run under the hood by the test routines).
Just before the second time the run subroutine is called, the RAKUDO_RAKUAST environment variable is set: this will cause the raku executable to use the new Raku grammar when parsing code. In this case, it will mark the RakuAST specific code in the Lambda slang as executed.
The call to must-be-complete will then see that all is ok, and mark the test is ok.
Coverage testing will help you determine which parts of the code in a distribution are not tested yet. But is no guarantee that really all possible code path have been tested.
Adding coverage testing at a later stage is a lot of work. Make sure that you add it during development of a distribution, as you would with any other tests.
The Test::Coverage distribution allows for further flexibility in a lot of corner cases as well, not just for the simple, straightforward testing cases.
This concludes this series of blog posts for now. New episodes may be added at a later stage: never say never!
If you like what I'm doing, committing to a small sponsorship would mean a great deal to me!
In real world we have a lot of pure structured or structured in hard to parse formats configuration files:
/etc/default/nginx, /etc/default/grub, logrotate.conf, sysctl.conf - to name a few.
In configuration management it's not only important to maintain specific configurations but also validate those changes to make it sure we don't break things.
Sparrow - is an automation tool written on Raku that allow to make such a validation by leveraging Task::Check DSL rules which underneath are just Raku regular expressions.
In the rest of this post we take a look at real life example.
Consider linux GRUB boot loader file /etc/default/grub with following configuration:
GRUB_DEFAULT=0
#GRUB_HIDDEN_TIMEOUT=0
GRUB_HIDDEN_TIMEOUT_QUIET=true
GRUB_TIMEOUT=2
GRUB_DISTRIBUTOR=`lsb_release -i -s 2> /dev/null || echo Debian`
GRUB_CMDLINE_LINUX_DEFAULT="rootfstype=ext4 quiet splash acpi_osi="
GRUB_CMDLINE_LINUX=""
GRUB_ENABLE_CRYPTODISK=true
# Uncomment to enable BadRAM filtering, modify to suit your needs
# This works with Linux (no patch required) and with any kernel that obtains
# the memory map information from GRUB (GNU Mach, kernel of FreeBSD ...)
#GRUB_BADRAM="0x01234567,0xfefefefe,0x89abcdef,0xefefefef"
# Uncomment to disable graphical terminal (grub-pc only)
#GRUB_TERMINAL=console
# The resolution used on graphical terminal
# note that you can use only modes which your graphic card supports via VBE
# you can see them in real GRUB with the command `vbeinfo'
#GRUB_GFXMODE=640x480
# Uncomment if you don't want GRUB to pass "root=UUID=xxx" parameter to Linux
#GRUB_DISABLE_LINUX_UUID=true
# Uncomment to disable generation of recovery mode menu entries
#GRUB_DISABLE_RECOVERY="true"
# Uncomment to get a beep at grub start
#GRUB_INIT_TUNE="480 440 1"
GRUB_DISABLE_OS_PROBER="true"
Though configuration format is quite simple, based on VAR=value semantics, it still allows some freedom in specification.
For example to enable variables we could use one of many forms - yes/"yes", true/"true" and just 1. Another challenge is to check that some variable are disabled - they might be just commented or “switched off” via negation form, e.g. VAR=0,false,""
As rigorous operations we want to validate a couple of things:
Boot on crypted disks is supported by setting GRUB_ENABLE_CRYPTODISK to one of the values: 1,yes,true and optional quoted form - "yes","true"
OS prober capability is disabled or in other words GRUB_DISABLE_OS_PROBER is not set by using any of forms - 1,yes,true,"yes","true"
Before go parsing let's create simple Raku program (Sparrow task), that dumps out configuration removing empty and commented lines, the whole output will be placed inside >>>, <<< markers for visibility:
task.raku
#!raku
my $path = config()<path>;
say "validate config {$path} ...";
say ">>>";
my @out;
for $path.IO.lines -> $i {
$i.chomp;
next unless $i ~~ /\S+/;
@out.push($i) unless $i ~~ /^ \s* '#'/;
};
say sort(@out).join("\n");
say "<<<";
Now let's write verification scenario by creating rules in Sparrow::Task::Check DSL format:
task.check
note: validate config
between: {'>>>'} {'<<<'}
note: allow to boot on crypted disks
regexp: ^^ \s* "GRUB_ENABLE_CRYPTODISK=" (<[y 1 true]> | '"true"' | '"yes"' )
note: never allow to enable os prober
!regexp: ^^ \s* "GRUB_DISABLE_OS_PROBER=" (<[y 1 true]> | '"true"' | '"yes"' )
end:
The DSL code has there major parts:
between: {'>>>'} {'<<<'}Setting a context for a search in between >>> ... <<< delimiter, this is an example of so called search context modifiers, in this case - Range modifier.
In other words this is precaution that we only search within specific boundaries of text output
regexp: ^^ \s* "GRUB_ENABLE_CRYPTODISK=" (<[y 1 true]> | '"true"' | '"yes"' )
Verifying that we have GRUB_ENABLE_CRYPTODISK set to one of values (y,1,true,"true","yes").
regexp: marker means Raku regular expression is used for validation.
note: never allow to enable os prober
!regexp: ^^ \s* "GRUB_DISABLE_OS_PROBER=" (<[y 1 true]> | '"true"' | '"yes"' )Verifying we DON'T(*) have GRUB_ENABLE_CRYPTODISK set to one of values (y,1,true,"true","yes"), in other words that GRUB_ENABLE_CRYPTODISK is disabled.
(*) ! sign before regexp: marker means negation logic.
Note: expressions are human readable comments that are showed up in a report to help us correlate every check to business logic
Now let's run our script and get a result of test. As this is Sparrow scenario, we use s6 - Sparrow CLI runner:
#!bash
s6 --task-run .@path=/etc/default/grub
14:09:20 :: [sparrowtask] - run sparrow task .@path=/etc/default/grub
14:09:20 :: [sparrowtask] - run thing .
[task run: task.raku - .]
[task stdout]
14:09:21 :: validate config examples/grub ...
14:09:21 :: >>>
14:09:21 :: GRUB_CMDLINE_LINUX=""
14:09:21 :: GRUB_CMDLINE_LINUX_DEFAULT="rootfstype=ext4 quiet splash acpi_osi="
14:09:21 :: GRUB_DEFAULT=0
14:09:21 :: GRUB_DISABLE_OS_PROBER="true"
14:09:21 :: GRUB_DISTRIBUTOR=`lsb_release -i -s 2> /dev/null || echo Debian`
14:09:21 :: GRUB_ENABLE_CRYPTODISK=true
14:09:21 :: GRUB_HIDDEN_TIMEOUT_QUIET=true
14:09:21 :: GRUB_TIMEOUT=2
14:09:21 :: <<<
[task check]
# validate config
# allow to boot on crypted disks
stdout match (r) <^^ \s* "GRUB_ENABLE_CRYPTODISK=" (<[y 1 true]> | '"true"' | '"yes"' )> True
# never allow to enable os prober
stdout match (r) <!^^ \s* "GRUB_DISABLE_OS_PROBER=" (<[y 1 true]> | '"true"' | '"yes"' )> False
=================
TASK CHECK FAIL
Expectedly we have following results:
Pretty impressive results considering such a little amount of code has been written!
Sparrow Task::Checks is comprehensive and super flexible tool allowing one to write validation scenarios for arbitrary data formats and complexity, check out documentation pages to know more.
That is it. Thanks for reading
Recently, I've released 2 new Sparrow plugins to help build Golang code:
Simple golang code builder
Golang code formatter
They are simple yet useful, providing two essentials tools to build Golang code in terminal:
Build code
Format code
The rest of the post shows how to use the plugins
To install plugins we need to use Tomtit task runner with profiles - preset of Raku scenarios that grouped by topics:
#!bash
cd /to/you/source/code
tom --init # initialize Tomtit for the first time
tom --profile go # install go profile scenarios
Now once we've installed go profile, we have an access to go-build and go-format scenarios which are just a Raku wrappers to run mentioned plugins. Code is simple enough and editable to adjust your project specific needs
Go-build scenario:
#!bash
tom --cat go-build
#!raku
my $path = [
"cmd/app/main.go",
"cmd/cli/cli.go"
];
task-run "build", "go-build", %(
:$path,
);
Go-format scenario:
#!bash
tom --cat go-format
#!bash
task-run "go format", "go-format";
In case of go-build scenario - adjust path array with files to build for your project specific:
#!bash
export EDITOR=nano
tom --edit go-build
#!raku
my $path = [
"cmd/app/app.go",
"cmd/app2/app2.go",
];
# the rest of the code stays the same
To run plugins - use tom cli runner:
#!bash
tom go-build
11:56:26 :: go build cmd/main.go
11:56:27 :: cmd/main.go
#!bash
tom go-format
11:57:18 :: cmd/main.go
That is it.
Follow plugins documentation to get familiar with plugins parameters.
Thanks for reading
Recently, I've released a simple Sparrow plugin called find to search text in source code, which is based on find and grep core linux utilities.
The rest of the document shows how to perform search in terminal by using Tomtit task runner.
To install the plugin, we need to use Tomtit task runner with profiles - preset of Raku scenarios that grouped by topics:
#!bash
cd /to/you/source/code
tom --init # initialize Tomtit for the first time
tom --profile code # install code profile scenarios
Now once we've installed code profile scenarios (for now it's just a single one), we have an access to search scenario which is just a Raku wrapper to do search with find plugin:
#!bash
tom --cat search
#!raku
my $ext = prompt("ext (go): ");
$ext = "go" unless $ext;
my $search1 = prompt("search1: ");
my $search2 = prompt("search2: ");
my $exclude = prompt("exclude: ");
say "find [$search1] [$search2] !$exclude in $ext";
task-run "find $search1 $search2 in $ext", "find", %(
:$ext,
:$search1,
search2 => $search2 || "",
exclude => $exclude || "",
);
The logic is following:
‘search1’ filters results out by first string and then ‘search2’ filter is applied for final results, ‘ext’ defines files extension to search.
Stub code shipped with Tomtit profile is good enough, we only need to change it a bit, to make default choice for file extenstion suitable for Raku project:
#!bash
export EDITOR=nano
tom --edit search
#!raku
my $ext = prompt("ext (rakumod): ");
$ext = "rakumod" unless $ext;
# ... the rest of the code is the same
Now let's search files in my Tomtit repository. Say, I want to find all exported functions.
#!bash
tom search
load configuration from /home/melezhik/projects/Tomtit/.tom/env/config.raku
ext (rakumod):
search1: sub
search2: is export
exclude:
find [sub] [is export] ! in rakumod
23:09:06 :: find [sub] [is export] [!] in *.rakumod
23:09:06 :: ===
23:09:06 :: find . -name *.rakumod -exec grep --color -H 'sub' {} \; | grep 'is export'
23:09:06 :: case2
23:09:06 :: ./lib/Tomtit/Completion.rakumod:sub complete () is export {
23:09:06 :: ./lib/Tomtit.rakumod:our sub check-if-init ( $dir ) is export {
23:09:06 :: ./lib/Tomtit.rakumod:our sub init ($dir) is export {
23:09:06 :: ./lib/Tomtit.rakumod:our sub load-conf () is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub tomtit-usage () is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub tomtit-help () is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub tomtit-clean ($dir) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-last ($dir) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-run ($dir,$scenario,%args?) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-remove ($dir,$scenario) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-cat ($dir,$scenario,%args?) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-edit ($dir,$scenario) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub environment-edit ($dir,$env) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub environment-list ($dir) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub environment-set ($dir,$env) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub environment-show ($dir) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub environment-cat ($dir,$env,%args?) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-doc ($dir,$scenario) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-list ($dir) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub scenario-list-print ($dir) is export {
23:09:06 :: ./lib/Tomtit.rakumod:multi sub profile-list is export {
23:09:06 :: ./lib/Tomtit.rakumod:multi sub profile-list($dir,$profile is copy) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub profile-install ($dir, $profile is copy, %args?) is export {
23:09:06 :: ./lib/Tomtit.rakumod:sub completion-install () is export {
That is it. Follow plugin documentation to get familiar with plugin parameters.
Thanks for reading
Sparrow is very efficient in writing scripts to automate system management using Raku and Bash, in today's post I am going to show an example ...
Let's create a simple plugin that enable / disable some configuration flags in service configuration file and if any changes occur reload a service. Format of flags in configuration file is following:
var=true|false
Here is an example of configuration file:
config.txt
debug=true
sentry=false
tls=false
Usually services are managed as systemd units, so service reload could be used to reload service configuration.
——
Let’s get started and create root folder for the plugin:
#!bash
mkdir -p service-config-reload
cd service-config-reload
Now inside plugin root directory:
hook.raku:
#!raku
my $cfg-orig = config()<path>.IO.slurp();
my $cfg = $cfg-orig;
for config()<enable><> -> $f {
$cfg ~~ s/<?wb> "$f=" \S+ /$f=true/;
}
for config()<disable><> -> $f {
$cfg ~~ s/<?wb> "$f=" \S+ /$f=false/;
}
set_stdout($cfg);
if $cfg ne $cfg-orig {
set_stdout("config changed");
config()<path>.IO.spurt($cfg);
set_stdout("config updated");
run_task "service_restart", %(
service => config()<service>,
path => config()<path>,
);
}
mkdir -p tasks/service_restart/
tasks/service_restart/task.bash
#!bash
sudo service $service reload
In real life applications services might have a linter capability where before configuration is applied it's checked and if any error occur application of changes is terminated:
#!bash
set -e
sudo /usr/bin/$service --check $path
sudo service $service reload
Packaging scenario as a plugin will allow users to reuse it as a library.
sparrow.json
{
"name" : "service-config-reload",
"description" : "Deploy configuration file and restart service upon changes",
"version" : "0.0.1",
"category" : "linux",
"url" : "https://github.com/melezhik/sparrow-plugins/tree/master/service-config-reload"
}
This last command will upload plugin to local Sparrow repository (see this doc for more details)
#!bash
s6 --upload
Anywhere in Raku scenario, just do this:
#!raku
use Sparrow6::DSL;
task-run "apply and reload", "service-config-reload", %(
:path<config.txt>,
:service<app>,
enable => <tls sentry>, # enable TLS and use of Sentry for production
disable => <debug>, # disable debug mode for production
)
Thanks for reading!
Source code of the plugin could be found here - https://github.com/melezhik/sparrow-plugins/tree/master/service-config-reload
(in chronological order, with comment references)
Xmas by Steve Roe.How time flies. Yet another year has flown by. 2024 was a year of changes, continuations and preparations. Let’s start with the changes:
Edument Central Europe, the branch of Edument that is based in Prague (and led by Jonathan Worthington), decided to stop (commercial) development of its Raku related products: Comma (the IDE for the Raku Programming Language) and Cro (a set of libraries for building reactive distributed systems).
The announcement:
With the discrepancy between revenue and development cost to continue being so large, and the prevailing economic environment forcing us to focus on business activities that at least pay for themselves, we’ve made the sad decision to discontinue development of the Comma IDE.
Fortunately, Jonathan Worthington was not only able to release the final commercial version as a free download, but was also able to release all of the sources of Comma. This would allow other people to continue Comma development.
With John Haltiwanger being the now de-facto project leader, this has resulted in a beta of the open source version of a Raku plugin for IntelliJ IDEA, as described on Day 20.
The announcement:
When Edument employees were by far the dominant Cro contributors, it made sense for us to carry the overall project leadership. However, the current situation is that members of the Raku community contribute more. We don’t see this balance changing in the near future.
With that in mind, we entered into discussions with the Raku Steering Council, in order that we can smoothly transfer control of Cro and its related projects to the Raku community. In the coming weeks, we will transfer the GitHub organization and release permissions to steering council representatives, and will work with the Raku community infrastructure team with regards to the project website.
As the source code of Cro had always been open source, this was more a question of handing over responsibilities. Fortunately the Raku Community reacted: Patrick Böker has taken care of making Cro a true open source project related to Raku, and the associated web site https://cro.raku.org is now being hosted on the Raku infrastructure. With many kudos to the Raku Infra Team!
Sadly, Jonathan Worthington also indicated that they would only remain minimally involved in the further development of MoarVM, NQP and Rakudo in the foreseeable future. As such, (almost) all of their modules were moved to the Raku Community Modules Adoption Center, where they were updated and re-released.
It’s hard to overstate the importance of Jonathan Worthington‘s work in the development and implementation of the Raku Programming Language. So on behalf of the current, past and future Raku Community members: Thank You!
At the beginning of October, Elizabeth Mattijsen decided to take on the large number of open Rakudo issues at that time: 1300+. This resulted in the closing of more than 500 issues: some just needed closing, some needed tests, and some could be fixed pretty easily.
They reported on that work in the Raku Fall Issue Cleanup blog post. Of the about 800 open issues remaining, almost 300 were marked as “fixed in RakuAST”, and about 100 were marked as “Will be addressed in RakuAST”. Which still leaves about 400 open because of other reasons, so there’s still plenty of work to be done here.
The original Raku ecosystem (“p6c”) is in the process of being completely removed. Since March 2023, the ecosystem was no longer being refreshed by zef. But it was still being refreshed by the Raku Ecosystem Archiver. But this stopped in August 2024, meaning that any updates of modules in that ecosystem would go unnoticed from then on.
At that time, every author who still had at least one module in the “p6c” ecosystem was given notice by creating an issue in the repository of the first of their modules in the META.list. Luckily many authors responded, either by indicating that they would migrate their module(s) to the “zef” ecosystem, or that they were no longer interested in maintaining.
Since then, most of the modules of the authors that responded, have been migrated. And work has started on the modules of the authors that did not respond. With the following results: at the beginning of 2024, there were still 658 modules in the “p6c” ecosystem (now 427, 35% less), by 230 different authors (now 138, 40% less).
In 2024, 558 Raku modules have been updated (or first released): up from 332 in 2023 (an increase of 68%). There are now 2304 different modules installable by zef by just mentioning their name. And there are now 12181 different versions of Raku modules available from the Raku Ecosystem Archive, up from 10754 in 2023, which means almost 4 module updates / day in 2024.
Rakudo saw about 2000 commits (MoarVM, NQP, Rakudo, doc) this year, which is about the same as in 2023. About one third of these commits were in the development of RakuAST (down from 75% in 2023).
A lot of work was done under the hood of the various subsystems of Rakudo. So was the dispatcher logic simplified by introducing several nqp:: shortcuts, which made the dispatcher code a lot more readable and maintainable.
The Meta-classes of NQP and Raku also received a bit of a makeover, as most of them hadn’t been touched since the 2015 release: this resulted in better documentation, and some minor performance improvements. Support for TWEAK methods and a rudimentary dd functionality were also added to NQP.
The JVM backend also got some TLC in 2024: one under the hood change (by Daniel Green) made execution of Raku code on the JVM backend twice as fast!
Timo Paulssen made the interface with low-level debuggers such as gdb and lldb a lot less cumbersome on MoarVM, which makes adding / fixing MoarVM features a lot easier!
On the MoarVM backend the expression JIT (active on Intel hardware) was disabled by default: it was found to be too unreliable and did not provide any execution speed gains. This change made Rakudo on Intel hardware up to 5% faster overall.
Also on the MoarVM backend, Daniel Green completed the work on optimizing short strings started by Timo Paulssen and Bart Wiegmans, resulting in about a 2% speed improvement of the compilation of Raku code.
Work on the Remote Debugger (which so far had only been really used as part of Comma) has resumed, now with a much better command line interface. And can now be checked in the language itself with the new VM.remote-debugging method.
Some race conditions were fixed: a particularly nasty one on the lazy deserialization of bytecode that was very hard to reproduce, as well as some infiniloops.
A lot of work was done on making the Continuous Integration testing produce fewer (and recently hardly any) false positives anymore. Which makes life for core developers a lot easier!
Two new Routine traits were added to the Raku Programming Language in 2024.
The is item trait can be used on @ and % sigilled parameters to indicate that a Positional (in the @ case) or an Associative (in the % case) is only acceptable in dispatch if it is presented as an item. It only serves as a tie-breaker, so there should always also be a dispatch candidate that would accept the argument when it is not itemized. Perhaps an example makes this more clear:
multi sub foo(@a) { say "array" }
multi sub foo(@a is item) { say "item" }
foo [1,2,3]; # array
foo $[1,2,3]; # itemThe is revision-gated trait fulfils a significant part of the promise of the Raku Programming Language to be a 100-year programming language. It allows a developer to add / keep behaviour of a dispatch to a subroutine or method depending on the language level from which it is being called.
As with is item, this is implemented as a tie-breaker to be checked only if there are multiple candidates in dispatch that match a given set of arguments.
This will allow core and module developers to provide forward compatibility, as well as backward compatibility in their code (as long as the core supports a given language level, of course).
In its current implementation, the trait must be specified on the proto to allow it to work (this may change in the future), and it should specify the lowest language level it should support. An example of a module “FOO” that exports a “foo” subroutine:
unit module FOO;
proto sub foo(|) is revision-gated("v6.c") is export {*}
multi sub foo() is revision-gated("6.c") {
say "6.c";
}
multi sub foo() is revision-gated("6.d") {
say "6.d"
}Then we have a program that uses the “FOO” module and calls the “foo” subroutine. This shows “6.d” because the current default language level is “6.d”.
use FOO;
foo(); # 6.dHowever, if this program would like to use language level 6.c semantics, it can indicate so by adding a use v6.c at the start of the program. And get a different result in an otherwise identical program:
use v6.c;
use FOO;
foo(); # 6.cJohn Haltiwanger has written an extensive blog post about the background, implementation and usage of the is revision-gated trait on Day 16, if you’d like to know more about it.
These are some of the more notable changes in language level 6.d: all of them add functionality, so are completely backward compatible.
The .flat method optionally takes a :hammer named argument, which will deeply flatten any data structure given:
my @a = 1, [2, [3,4]];
say @a.flat; # (1 [2 [3 4]])
say @a.flat(:hammer); # (1 2 3 4)One can now also use HyperWhatever (aka **) in a postcircumfix [ ] for the same semantics:
my @a = 1, [2, [3,4]];
say @a[*]; # (1 [2 [3 4]])
say @a[**]; # (1 2 3 4)The .min / .max / .minmax methods now also accept the :by named argument to make it consistent with the sub versions, which should prevent unexpected breakage when refactoring code from a sub form to a method form (as the :by would previously be silently ignored in the method form).
say min <5 45 345>, :by(*.Str); # 345
say <5 45 345>.min(*.Str); # 345
say <5 45 345>.min(:by(*.Str)); # 345 ADDEDThe .are method now also accepts a type argument. If called in such a manner, it will return True if all members of the invocant matched the given type, and False if not. Apart from allowing better readable code, it also allows shortcutting if any of the members of the invocant did not match the given type. An example:
unless @args.are(Pair) {
die "All arguments should be Pairs";
}The most notable additions to the future language level of the Raku Programming Language:
The .nomark method on Cool objects returns a string with the base characters of any composed characters, effectively removing any accents and such:
use v6.e.PREVIEW;
say "élève".nomark; # eleveThe .contains / .starts-with / .ends-with / .index / .rindex / .substr-eq methods now all accept a :smartcase named argument: a conditional :ignorecase. If specified with a True value, it will look at the needle to see if it is all lowercase. If it is, then :ignorecase semantics will be assumed. If there are any uppercase characters in the needle, then normal semantics will be assumed:
use v6.e.PREVIEW;
say "Frobnicate".contains("frob"); # False
say "Frobnicate".contains("frob", :smartcase); # True
say "Frobnicate".contains("FROB", :smartcase); # FalseThe .stem method on IO::Path objects returns the .basename of the object without any extensions, or with the given number of extensions removed:
use v6.e.PREVIEW;
say "foo/bar/baz.tar.gz".IO.basename; # baz.tar.gz
say "foo/bar/baz.tar.gz".IO.stem; # baz
say "foo/bar/baz.tar.gz".IO.stem(1); # baz.tarAbout one third of this year’s work was done on the RakuAST (Raku Abstract Syntax Tree) project. It basically consists of 3 sub-projects, that are heavily intertwined:
There is little more to say about the development of RakuAST classes other than that there were 440 of them at the start of the year, and 454 of them at the end of the year. As the development of these classes is still very much in flux, they are not documented yet (other than in the test-files in the /t/12rakuast directory).
On the other hand, the RakuAST::Doc classes are documented because they have a more or less stable API to allow for the development of RakuDoc Version 2.
The work on the Raku Grammar and Actions has been mostly about implementing already existing features. This is measured by the number of Rakudo (make test) and roast (make spectest) test-files that completely pass with the new Raku Grammar and Actions. And these are the changes:
make test: 110/151 (72.8%) → 140/156 (89.7%)make spectest: 980/1356 (72.3%) → 1155 / 1359 (85%)A lot of work was done by Stefan Seifert, picking up the compile-time handling refactor that Jonathan Worthington had started in 2023, but was unable to bring to fruition. TPRF continued the funding for this work.
By the way, DuckDuckGo donated US$ 25000 to the foundation to allow this type of development funding to go on! Hint, hint!
Like last year, there are still quite a few features left to implement. Although it must be said that many tests are hinging on the implementation of a single feature, and often cause an “avalanche” of additional test-files passing when it gets implemented.
If you’d like to try out the new Raku Grammar and Actions, you should set the RAKUDO_RAKUAST environment variable to 1. The .legacy method on the Raku class will tell you whether the legacy (older) grammar is being used or not:
$ raku -e 'say Raku.legacy'
True
$ RAKUDO_RAKUAST=1 raku -e 'say Raku.legacy'
FalseA cousin language was created: Draig, allowing you to write Raku code in Welsh!
The RakuAST::Deparse::Highlight module allows customizable Raku syntax highlighting of Raku code that is syntactically correct. It is definitely not usable for real-time syntax highlighting as it a. requires valid Raku code, and b. it may execute Raku code in BEGIN blocks, constant specifications and use statements.
A more lenient alternative is the Rainbow module by Patrick Böker.
The final version of the RakuDoc v2.0 specification can now be completely rendered thanks to the tireless work of Richard Hainsworth and extensive feedback and proofreading by Damian Conway, as shown in Day 1 and Day 14.
Sadly it has turned out to be impossible to organize a Raku Conference (neither in-person or online), nor was it possible to organize a Raku Core Summit. We’re hoping for a better situation in 2025!
Completely out of the blue, a Dr Raku created about 90 Raku beginner videos on YouTube.
Looking back, again an amazing amount of work has been done in 2024!
Hopefully you will all be able to enjoy the Holiday Season with sufficient R&R, especially Kane Valentine (aka kawaii).
The next Raku Advent Blog is only 340 days away!
Amongst all of its features, what do we consider to be the essence of Raku? In this advent post we will explore what makes Raku an exciting programming language and see if we can describe its essence.
Paul Graham wrote an essay about the 100 year language, back in 2003. In it he had this to say:
Who will design the languages of the future? One of the most exciting trends in the last ten years has been the rise of open-source languages like Perl, Python, and Ruby. Language design is being taken over by hackers. The results so far are messy, but encouraging. There are some stunningly novel ideas in Perl, for example. Many are stunningly bad, but that’s always true of ambitious efforts. At its current rate of mutation, God knows what Perl might evolve into in a hundred years.
Larry Wall took Paul Graham’s essay and ran with it:
“It has to do with whether it can be extensible, whether it can evolve over time gracefully.”
Larry referred to the expressiveness of human languages as his inspiration for Raku:
- Languages evolve over time. (“It’s okay to have dialects…”)
- No arbitrary limits. (“And they naturally cover multiple paradigms”)
- External influences on style.
- Fractal dimensionality.
- Easy things should be easy, hard things should be possible.
- “And, you know, if you get really good at it, you can even speak CompSci.”
Naoum Hankache’s Raku Guide introduces Raku:
Raku is a high-level, general-purpose, gradually typed language. Raku is multi-paradigmatic. It supports Procedural, Object Oriented, and Functional programming.
The feature list on Raku.org goes further:
As we can see, Raku has many rich features. Maybe the essence of Raku lies somewhere among them.
It’s the 21st Century and programming languages are finally waking up to the fact that we live in a multi-lingual world. Raku is a Unicode centric language in a way that no other language manages.
Again programming languages are only beginning to catch up with the reality that every computer has multiple cores. Sometimes very many cores. Raku excels, alongside other modern languages, at delivering the tools required for effective concurrent and asynchronous programs.
Raku is a richly functional language that combines the procedural and object oriented encapsulation constructs to span paradigms.
The breadth of the Raku language is indeed impressive. But I don’t think it’s instructive, or even possible to try and distill an essence from such a diverse list of capabilities.
Perl and Raku both adhere to the famous motto:
TMTOWTDI (Pronounced Tim Toady): There is more than one way to do it.
This is indeed demonstrably true as shown by Damian Conway whenever he blogs about or talks about Raku. Indeed in Why I love Raku he sums up with this endorsement:
More than any other language I know, Raku lets you write code in precisely the way that suits you best, at whatever happens to be your (team’s) current level of coding sophistication, and in whichever style you will later find most readable …and therefore easiest to maintain.
How do you identify the essence of a deliberately broad multi-paradigm language? Perhaps the essence is not so much about some aspect of the core language. Perhaps it is much more about the freedom it gives you to choose, instead of the language choosing for you.
Like Raku, the community is not opinionated. If you choose a particular approach, the community is there to help you. If you want to learn what’s possible, the community will offer up multiple approaches, as shown by many Stack Overflow answers.
Which leaves me with this thought:
The essence of Raku is the freedom to choose for yourself. And the freedom to choose differently tomorrow.
A lead-free area
Elf Nebecaneezer (‘Neb’) was welcoming some young new workers to his domain and doing what old folks like to do: pontificate. (His grandchildren politely, but behind his back, call it “bloviating.”)
“In the old days, we used hand-set lead type, then gradually used ever-more-modern methods; now we prepare the content in PDF and send a copy to another company to print the content on real newsprint. It still takes a lot of paper, but much less ink and labor (as well as being safer1).”
“Most young people are very familiar with HTML and online documents, but, unless your browser and printer are very fancy, it’s not easy to create a paper copy of the thing you need to file so that it’s very usable. One other advantage of hard-copy products is that they can be used without the internet or electricity. Remember, the US had a hugely-bad day recently when a major internet service provider had a problem!” [He continued to speak…]
Now let’s get down to ‘brass tacks.’ You all are supposed to be competent Raku users, so I will show you some interesting things you can do with PDF modules. But first, a little background on PDF (Adobe’s Portable Document Format).
The PDF was developed by the Adobe company in 1991 to replace the PostScript (PS) format. In fact, The original PS code is at the heart of PDF. Until 2008, Adobe defined and continued to develop PDF. Beginning in 2008, the ISO defined it in its 32000 standard. That standard is about a thousand pages long and can be obtained online at https://www.pdfa-inc.org at no cost.
One other important piece of the mix is the CLI ghostscript interpreter which can be used, among other things, to compress PDF documents.
Before we continue, remember, we are a Debian shop, and any specific system software I mention is available in current versions.
We are still improving Rakudoc (see the recent Raku Advent post by Richard Hainsworth), but it can be used now for general text to produce PDF output. However, for almost any specific printed product needed, we can create the PDF on either a one-time case or a specific design for reuse.
A good example of that is the module PDF::NameTags which can be modified to use different layouts, colors, fonts, images, and so forth. Its unique output feature is its reversibility–when printed two-sided, the person’s name shows regardless of whether the badge flips around or not. That module was used to create the name tags we are are wearing on our lanyards, and I created that module! I’ll be using parts of that module as an example as I continue.
Actually, I have a GitHub account under an alias, ‘tbrowder’, and I have published several useful modules to help my PDF work. I’ll mention some later.
Note I always publish my finished modules via ‘zef’, the standard Raku package manager. Then they are easily available for installation, and they automatically get listed on https://Raku.land and can easily be found. Why do I do that, especially since no one else may care? (As ‘@raiph’ or someone other Raku user once said, modules are usually created for the author’s use.) Because, if it helps someone else, as the Golden Rule says, it may be the right thing to do (as I believe Font::Utils does).
Fonts used to be very expensive and hard to set type with, so the modern binary font is a huge improvement! Binary fonts come in different formats, and their history is fascinating.
This shop prefers OpenType fonts for two practical reasons: (1) they provide extensive Unicode glyph coverage for multi-language use (we operate world-wide as you well know) and (2) they provide kerning for more attractive type setting.
By using the HarffBuzz library, the final PDF will only contain the glyphs actually used by the text (the process is called ‘subsetting’). If a user is not running Debian 12 or later, then he or she can additionally ‘use’ module Compress::PDF which provides a subroutine which uses Ghostscript to remove unused glyphs. The module also provides a CLI program, pdf-compress, which does the same thing.
For Latin and most European languages we use the following font collections available as Debian packages:
| Font | Debian package |
|---|---|
| GNU Free Fonts | fonts-freefont-otf |
| URW Base 35, | fonts-urw-base35 |
| E B Garamond | fonts-egaramond, fonts-garamond-extra |
| Cantarell | fonts-cantarell |
For other languages we rely on the vast glyph coverage of Google’s Noto fonts (in TrueType format). Debian has many of those fonts, but we find it easier to find the needed font at Google and download them onto our server as zip archives. After unzipping, we move the desired files to ‘/usr/local/share/fonts/noto’. We currently have these 10 Noto fonts available (plus 175 other variants):
| Font |
|---|
| NotoSerif-Regular.ttf |
| NotoSerif-Bold.ttf |
| NotoSerif-Italic.ttf |
| NotoSerif-BoldItalic.ttf |
| NotoSans-Regular.ttf |
| NotoSans-Bold.ttf |
| NotoSans-Italic.ttf |
| NotoSans-BoldItalic.ttf |
| NotoSansMono-Regular.ttf |
| NotoSansMono-Bold.ttf |
Note the file names above are in the family and style order as the Free Fonts in our own $HOME directory.
To get a feel for the span of glyphs in some of the fonts, the FreeSerif font has over 1,000 glyphs and can be used for many languages. We typically use that font, and the rest of that font family, for most of our work around Europe and the Americas. For the rest of the world, Google’s Noto fonts should cover all but a tiny fraction of the population.
One of the many strengths of Raku is its handling of Unicode as a core entity. You can read about Unicode at its website. Of particular interest are the code charts at https://www.unicode.org/charts. If you select any chart you will see that the code points are shown in hexadecimal. In Raku the code points are natively in decimal. Fortunately, Raku has a method to do that:
# convert decimal 178 to hexadecimal (base 16)
say 178.base(16); # OUTPUT: B2
# convert a hexadecimal 'A23' to decimal
say 'A23'.parse-base(16); # OUTPUT: 2595Or we can look at Wikipedia where there are charts showing both hexidecimal and decimal code points (Unicode_chars).
Not released yet is my Raku module PDF::FontCollection which encapsulates useful font collections into a single reference list. The module has routines allowing the user to get a loaded font with a short code mnemonically associated with the font collection (a digit, and a one- or two-letter character for its style). It has an installed binary to show its fonts by number, code, and name. However, my most useful module, Font::Utils, has made this module effectively obsolete.
Font::UtilsI now introduce my almost-released module Font::Utils which uses fonts already installed and collects them into a file called font-files.list which is then placed into the user’s $HOME/.Font-Utils directory.
Since our servers already have the desired OpenType fonts installed, using Font::Utils is actually more convenient since you can arrange the font list any way you want including: (1) creating your own mnemonic keys for easy reference, (2) deleting or adding data lines, and (3) reordering data lines.
Note that the actual OpenType font files are quite large, but a good design will ensure they are not loaded until specifically called for in the program. If they are already loaded, calling the routine will be is a no-op. The Font::Utils module has one such routine.
Other non-Latin languages are covered in many freely available font collections, including right-to-left and other orientations along with layouts for users who need that capability (the Noto fonts are a good example). As noted, those can be easily added to your Font::Utils collection.
Let’s take a look at the first couple of lines in the default installation of my $HOME/.Font-Utils/font-files.list:
# key basename path
1 FreeSerif.otf /usr/share/fonts/opentype/freefont/FreeSerif.otfWe see the comments and the first line of data consisting of three fields. The first field is the unique code which you may change. The second field is the font file’s basename, and the last field is file font file’s path. You may delete or reorder or add new font entries as you wish.
Now let’s say you want to publish some text in Japanese. Oh, you say you don’t know Japanese? And you don’t have a keyboard to enter the characters? No problem!, There is a way to do that.
We first find from Wikipedia that some Unicode characters for the Japanese language are in the Hiragan collection, which covers hexadecimal code points 3041 through 3096 and 3099 through 309F. Then we create a space-separated string of the characters for each word. We’ll use an arbitrary list of them:
my $jword1 = "3059 306A 306B 306C 305D";
my $jword2 = "3059-305D"; # same as $jword1 but with a hyphen for a range
my $jword3 = "306B-306F";Note that we can use a hyphen to indicate a contiguous range of code points. (We could also use decimal code points, but that’s a bit more awkward due to ease and larger number of characters required as well as the confusing use of the joining ‘-‘ with subtraction.)
Oops, what font shall we use? I couldn’t find a suitable font with the searches on Debian, so I went online to Google, searched for Hiragana, and found the font with description Noto Serif Japanese.
I selected it, downloaded it, and got file Noto_Serif_JP.zip. I created a directory named google-fonts and moved the zip file there where I then unpacked them to get directory Noto_Serif_JP with files:
README.txt
NotoSerifJP-VariableFont_wght.ttf
OFL.txt
static
static/NotoSerifJP-Bold.ttf
static/NotoSerifJP-SemiBold.ttf
static/NotoSerifJP-Medium.ttf
static/NotoSerifJP-Light.ttf
static/NotoSerifJP-ExtraLight.ttf
static/NotoSerifJP-ExtraBold.ttf
static/NotoSerifJP-Black.ttf
static/NotoSerifJP-Regular.ttfThe main font is a variable one, so I tried it to see the results.
There are many ways to lay out text on a page. The most useful for general use is to create reusable text boxes.
# define it
my PDF::Content::Text::Box $tb .= new(
:$text, :$font, :$font-size, :$height,
# style it
:WordSpacing(5), # extra spacing for Eastern languages
);
#...clone it and modify it...
$tb.clone(:content-width(200));Use the $page.text context to print a box:
my @bbox;
$page.text: {
.text-position = $x, $y;
# print the box and collect the resulting bounding box coordinates
@bbox = .print: $tb;I won’t go into it very much, but you can do almost anything with PDF. The aforementioned PDF::NameTags module has many routines for drawing and clipping. Another of my modules on deck is PDF::GraphicsUtils which will encompass many similar routines as well as the published PDF::Document module.
I was having trouble with the variable syntax needed testing scripts as well as test modules. Raku user and author @librasteve suggested creating an alias to do that. The result from my .bash_aliases file;
alias r='raku -I.' # adhoc script Raku run command
alias rl='raku -I./lib' # adhoc script Raku run commandI was having problems with modules once and @ugexe suggested always using a load test for checking all modules will compile. Now I always create a test script similar to this:
# file: t/0-load-test.t
use Test;
my @modules = <
Font::Utils
Font::Utils::FaceFreeType
Font::Utils::Misc
Font::Utils::Subs
>;
plan +@modules;
for @modules {
use-ok $_, "Module $_ can be used okay";
}And run it like this: r t/0*t
$ r t/0*t
# OUTPUT:
1..4
ok 1 - Module Font::Utils can be used okay
ok 2 - Module Font::Utils::FaceFreeType can be used okay
ok 3 - Module Font::Utils::Misc can be used okay
ok 4 - Module Font::Utils::Subs can be used okay=finish‘Use =finish to debug a LONG rakumod file. I use it when I’m in the process of adding a new sub or modifying one and commit some error that causes a panic failure without a clear message. I add the =finish after the first routine and see if it compiles. If it does I move the =finish line to follow the next sub, and so on.
When I do get a failure, I have a better idea of where the bad code is. Note I do sometimes have to reorder routines becaause of inter-module dependencies. It’s also a good time to move completely independent routines to a lower-level module as described next.
Sometimes, as in Font::Utils, I create a single, long file with routines that are dependent on other routines so that it is difficult to tell what is dependent upon what. Then I start creating another, lower-level module that has routines that are non-dependent on higher level modules. You can see that structure in the load test output shown above.
BEGIN phaserModule authors often need access to the user’s $HOME directory, so use of the BEGIN phaser as a block can make it easier to access it from the Build module, as well as the base modules. Here is that code from the Font::Utils module:
unit module Font::Utils;
use PDF::Font::Loader :load-font;
our %loaded-fonts is export;
our $HOME is export = 0;
our $user-font-list is export;
our %user-fonts is export;
BEGIN {
if %*ENV<HOME>:exists {
$HOME = %*ENV<HOME>;
}
else {
die "FATAL: The environment variable HOME is not defined";
}
if not $HOME.IO.d {
die qq:to/HERE/;
FATAL: \$HOME directory '$HOME' is not usable.
HERE
}
my $fdir = "$HOME/.Font-Utils";
mkdir $fdir;
$user-font-list = "$fdir/font-files.list";
}
INIT {
if not $user-font-list.IO.r {
create-user-font-list-file;
}
create-user-fonts-hash $user-font-list;
create-ignored-dec-codepoints-list;
}That BEGIN block creates globally accessible variables and enables easy access for any build script to either create a new user fonts list or check an existing one. The INIT block then uses a routine to create the handy %user-fonts hash after the Raku compilation stage enables it.
As @lizmat and others on IRC #raku always warn about global variables: danger lurks from possible threaded use. But our ‘use cases’ should not trigger such a problem. However, other routines may, and we have used a fancy module to help the problem: OO::Monitors by @jnthn. See it used to good effect in the class (monitor) Font::Utils::FaceFreeType.
Currently the PDF standard doesn’t deal with active links, but my Raku friend David Warring gave me a solution in an email. I think I’ve tried it, and I think it works, but YMMV.
David said “Hi Tom, Adding a link can be done. It’s a bit lower level than I’d like and you need to know what to look for. Also needs PDF::API6, rather than PDF::Lite. I’m looking at the pdfmark documentation. It’s a postscript operator and part of the Adobe SDK. It’s not understood directly by the PDF standard, but it’s just a set of data-structures, so a module could be written for it. I’ll keep looking.”
His code:
# Example:
use PDF::API6;
use PDF::Content::Color :&color, :ColorName;
use PDF::Annot::Link;
use PDF::Page;
my PDF::API6 $pdf .= new;
my PDF::Page $page = $pdf.add-page;
$page.graphics: {
.FillColor = color Blue;
.text: {
.text-position = 377, 515;
my @Border = 0,0,0; # disable border display
my $uri = 'https://raku.org';
my PDF::Action::URI $action = $pdf.action: :$uri;
my PDF::Annot::Link $link = $pdf.annotation(
:$page,
:$action, # action to follow the link
:text("Raku homepage"), # display text (optional)
:@Border,
);
}
}
$pdf.save-as: "link.pdf";App::Mi6 and Mi6::HelperBecause of the artistic nature of our work, we often need to create our own modules for new products. In that event, we use module App::Mi6 and its binary mi6 to ease the labor of managing recurring tasks with module development. By using a logical structure and a dist.ini configuration file, the user can create Markdown files for display on GitHub or GitLab, test his or her test files in directories t and xt, and publish the module on ‘Zef/Fez’ with one command each.
By using my module Mi6::Helper, the author can almost instantly create a new module ‘git’ source repository with its structure ready to use app mi6 with much boiler plate already complete.
I’m also working on a dlint program to detect structural problems in the module’s git repository. It is a linter to check the module repo for the following:
META6.json file match those in the module’s /resources directory.use X statements have matching depends entries in the META6.json file.The linter will not correct these problems, but if there is interest, that may be added in a future release.
Neb concluded his presentation:
“Bottom line: Raku’s many PDF modules provide fairly easy routines to define any pre-press content needed. Those modules continue to be developed in order to improve ease of use and efficiency. Graphic arts have always been fun to me, but now they are even ‘funner!'”.
As I always end these jottings, in the words of Charles Dickens’ Tiny Tim, “may God bless Us, Every one!” A Christmas Carol, a short story by Charles Dickens (1812-1870), a well-known and popular Victorian author whose many works include The Pickwick Papers, Oliver Twist, David Copperfield, Bleak House, Great Expectations, and A Tale of Two Cities2.
︎︎In the smoke-filled (virtual) room of the council of the high (from the smoke) elves, the wizened textualist Geoff, said “All of my stuff is in boxes and containers.” Empty shelves behind him indicated he was moving house.
“When you have a complex module,” Geoff continued, “and its difficult to describe how to install it, do all the steps in a container, and show the Dockerfile.”
“Aha!” said the newest member, who drew his vorpal sword, and went forth to slay the Jabberwock, aka putting RakuAST::RakuDoc::Render into a container.
“Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!”
After days of wandering the murky jungle of Docker/Alpine/Github/Raku documentation, the baffled elf wondered if he was in another fantasy:
“So many rabbit holes to fall down.”
Best practice for a container is to chose an appropriate base image. Well obviously, there’s the latest Raku version by the friendly, hard-working gnomes at Rakuland. So, here’s the first attempt at a Dockerfile:
FROM docker.io/rakuland/raku
# Copy in Raku source code and build
RUN mkdir -p /opt/rakuast-rakudoc-render
COPY . /opt/rakuast-rakudoc-render
WORKDIR /opt/rakuast-rakudoc-render
RUN zef install . -/precompile-installIt failed. After peering at the failure message, it seemed that at least one of the dependent modules used by the rakuast-rakudoc-render distribution needs a version of make.
That’s easily fixed, just add in build-essentials, the vorpal-sworded elf thought. Something like:
FROM docker.io/rakuland/raku
# Install make, gcc, etc.
RUN apt-get update -y && \
apt-get install -y build-essential && \
apt-get purge -y
# Copy in Raku source code and build
RUN mkdir -p /opt/rakuast-rakudoc-render
COPY . /opt/rakuast-rakudoc-render
WORKDIR /opt/rakuast-rakudoc-render
RUN zef install . -/precompile-installFailure! No apt.
“How can there not be APT??” the Ubuntu-using elf thought in shock. Turns out that the rakuland/raku image is built on an Alpine base, and Alpine have their own package manager apk.
Unfortunately, build-essential is a debian package, but at the bottom of this rabbit hole lurks an apk equivalent package build-base, leading to:
FROM docker.io/rakuland/raku
# Install make, gcc, etc.
RUN apk add build-base
# Copy in Raku source code and build
RUN mkdir -p /opt/rakuast-rakudoc-render
COPY . /opt/rakuast-rakudoc-render
WORKDIR /opt/rakuast-rakudoc-render
RUN zef install . -/precompile-installLo! upon using the Podman desktop to build an image from the Dockerfile, the process came to a succesful end.
But now to make things easier, there needs to be a link to the utility RenderDocs, which takes all the RakuDoc sources from docs/ and renders them to $*CWD (unless over-ridden by --src or --to, respectively). It will also render to Markdownunless an alternative format is given.
FROM docker.io/rakuland/raku
# Install make, gcc, etc.
RUN apk add build-base
# Copy in Raku source code and build
RUN mkdir -p /opt/rakuast-rakudoc-render
COPY . /opt/rakuast-rakudoc-render
WORKDIR /opt/rakuast-rakudoc-render
RUN zef install . -/precompile-install
# symlink executable to location on PATH
RUN ln -s /opt/rakuast-rakudoc-render/bin/RenderDocs /usr/local/bin/RenderDocs
# Directory where users will mount their documents
RUN mkdir /doc
# Directory where rendered files go
RUN mkdir /to
WORKDIR /AND!!! when a container was created using this Dockerfile and run with its own terminal, the utility RenderDocs was visible. Running
RenderDocs -hproduced the expected output (listing all the possible arguments).
Since the entire distribution is included in the container, running
RenderDocs --src=/opt/rakuast-rakudoc-render/docs READMEwill render README.rakudoc in --src to /to/README.md because the default output format is MarkDown.
“Fab!”, screamed the boomer-generation newbie elf. “It worked”.
“Now lets try HTML”, he thought.
RenderDocs --format=HTML --src=/opt/rakuast-rakudoc-render/docs README
Failure: no sass.
“expletive deleted“, he sighed. “The Jabberwok is not dead!”
There are two renderers for creating HTML. One produces a single file with minimal CSS so that a normal browser can load it as a file locally and it can be rendered without any internet connection. This renderer is triggered using the option --single. Which the containerised RenderDocs handles without problem.
But the normal use case is for HTML to be online, using a CSS framework and JS libraries from CDN sources. Since the renderer is more generic, it needs to handle custom CSS in the form of SCSS. This functionality is provided by calling an external program sass, which is missing in the container.
An internet search yields the following snippet for a container.
# install a SASS compiler
ARG DART_SASS_VERSION=1.82.0
ARG DART_SASS_TAR=dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
ARG DART_SASS_URL=https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/${DART_SASS_TAR}
ADD ${DART_SASS_URL} /opt/
RUN cd /opt/ && tar -xzf ${DART_SASS_TAR} && rm ${DART_SASS_TAR}
RUN ln -s /opt/dart-sass/sass /usr/local/bin/sassThe container image builds nicely, but the RenderDocs command STILL chokes with an unavailable sass.
Except that diving into the container’s murky depths with an ls /opt/dart-sass/ shows that sass exists!
The newbie was stumped.
So rested he by the Tumtum tree
And stood awhile in thought.
Turns out that the Alpine distribution uses a different compiler, and the wonderful dart-sass fae provide a suitable binary so a simple change was enough to get sass working in the container.
- ARG DART_SASS_TAR=dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
+ ARG DART_SASS_TAR=dart-sass-${DART_SASS_VERSION}-linux-x64-musl.tar.gzsimple does not mean found at once, but the container contains RenderDocs, which produces markdown and HTML rendered files.
One, two! One, two! And through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He went galumphing back.
“I can publish this image so everyone can use it,” the FOSS fanatic elf proclaimed.
So the docker container image can be accessed using a FROM or PULL using the URL
docker.io/finanalyst/rakuast-rakudoc-render“And hast thou slain the Jabberwock?
Come to my arms, my beamish boy!
O frabjous day! Callooh! Callay!”
“It would be great,” mused the triumphant elf, “if RakuDoc sources, say for a README could be automatically included as the github README.md of repo”.
“May be as an action?”
Github actions can use containers to process files in a repo. Essentially, in an action, the contents of a repo are copied to a github-workspace, then they can be processed in the webspace, and changes to the workspace have to be committed and pushed back to the repository.
With a container, the contents of the workspace need to be made available to the container. Despite some documentation that starting a container in a github action automatically maps the github-workspace to some container directory, the exact syntax is not clear.
In order to discover how to deal with the multitude of possibilities, a new version of RenderDocs got written, and a new image generated, and again, and again … Unsurprisingly, between one meal and another, the ever hungry elf forgot which version was being tested.
“I’ll just include a --version argument,” thought the elf. “I’ll can ask the Super Orcs!”.
And there behold was an SO answer to a similar question, and it was written by no lesser a high elf than the zefish package manager ugexe, not to be confused with the other Saint Nick, the package deliverer.
Mindlessly copying the spell fragment into his CLI script as:
multi sub MAIN( :version($v)! = False {
say "Using version {$?DISTRIBUTION.meta<version>} of rakuast-rakudoc-render distribution."
if $v;
}the elf thought all done! “Callooh! Callay!”.
Except RenderDocs -v generated Any.
“SSSSSSSSh-,” the elf saw the ominous shadow of Father Christmas looming, “-ine a light on me”.
On the IRC channel, the strong willed Coke pointed out that a script does not have a compile time variable, such as, $?DISTRIBUTION. Only a module does.
The all-knowing elf wizard @lizmat pointed out that command line scripts should be as short as possible, with the code in a module that exports a &MAIN.
Imbibing this wisdom, our protagonist copied the entire script contents of bin/RenderDocs to lib/RenderDocs.rakumod, added a proto sub MAIN(|) is export { {*} }, then made a short command line script with just use RenderDocs.
Inside the container terminal:
# RenderDocs -v
Using version 0.20.0 of rakuast-rakudoc-render distribution.With that last magical idiom, our intrepid elf was ported from one rabbit hole back to the one he had just fallen down.
“Beware the Jubjub bird, and shun
The frumious Bandersnatch!”
“I seem to be going backwards,” our re-ported elf sighed.
Once again, the github documentation was read. After much study and heartbreak, our hero discovered a sequence that worked:
docs containing a file README.rakudoc .github/
workflows/
CreateDocs.ymlCreateDocs.yml name: RakuDoc to MD
on:
# Runs on pushes targeting the main branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the
# Actions tab workflow_dispatch:
jobs:
container-job:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@master
with:
persist-credentials: false
fetch-depth: 0
- name: Render docs/sources
uses: addnab/docker-run-action@v3
with:
image: finanalyst/rakuast-rakudoc-render:latest
registry: docker.io
options: -v ${{github.workspace}}/docs:/docs -v ${{github.workspace}}:/to
run: RenderDocsAfter examining the github actions logs, it seemed the rendered files were created, but the repository was not changed.
“Perhaps I should have used milk and not cream …” thought our fantasy elf.
There is in fact a missing step, committing and pushing from the github-workspace back to the repository. This can be done by adding the following to CreateDocs.yml:
- name: Commit and Push changes
uses: Andro999b/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: 'main'Even this did not work! Github refused absolutely to write changes to the repository.
The weary elf substituted Lemon grass for Lavender in step 1, and just to be certain changed the repo settings following the instructions from the Github grimore
The content – at this stage of the tale – of CreateDocs.yml is
name: RakuDoc to MD
on:
# Runs on pushes targeting the main branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
container-job:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@master
with:
persist-credentials: false
fetch-depth: 0
- name: Render docs/sources
uses: addnab/docker-run-action@v3
with:
image: finanalyst/rakuast-rakudoc-render:latest
registry: docker.io
options: -v ${{github.workspace}}/docs:/docs -v ${{github.workspace}}:/to
run: RenderDocs
- name: Commit and Push changes
uses: Andro999b/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: 'main'It worked. “The Christmas present is now available for anyone who wants it”, thought our elf.
’Twas brillig, and the slithy toves
Did gyre and gimble in the wabe:
All mimsy were the borogoves,
And the mome raths outgrabe.
(Jabberwocky, By Lewis Carroll)
Remember to git pull for the rendered sources to appear locally as well.
“Wouldn’t it be nice to wrap the present in a ribbon? Why not put diagrams in the Markdown file? “
Our elf was on a streak, and fell down another rabbit hole: github does not allow svg in a Markdown file it renders from the repo. “It is impossible,” sighed the tired elf.
Alice laughed. “There’s no use trying,” she said: “one can’t believe impossible things.”
“I daresay you haven’t had much practice,” said the Queen. “When I was your age, I always did it for half-an-hour a day. Why, sometimes I’ve believed as many as six impossible things before breakfast.”
(Through the Looking Glass, Lewis Carroll)
Diagrams can be created using the dot program of Graphviz, which is a package that Alpine provides. So, we can create a custom block for RakuAST::RakuDoc::Render that takes a description of a graph, sends it to dot, gets an svg file back and inserts into the output.
Except: github will not allow svg directly in a markdown file for security reasons.
But: it will allow an svg in a file that is an asset on the repo. So, now all that is needed is to save the svg in a file, reference the file in the text, and copy the asset to the same directory as the Markdown text.
Except: the time stamps on the RakuDoc source files and the output files seem to be the same because of the multiple copying from the repo to the actions workspace to the docker container. So: add a --force parameter to RenderDocs.
So in Raku impossible things are just difficult.
The final content of CreateDocs.yml is now
name: RakuDoc to MD
on:
# Runs on pushes targeting the main branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
container-job:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@master
with:
persist-credentials: false
fetch-depth: 0
- name: Render docs/sources
uses: addnab/docker-run-action@v3
with:
image: finanalyst/rakuast-rakudoc-render:latest
registry: docker.io
options: -v ${{github.workspace}}/docs:/docs -v ${{github.workspace}}:/to
run: RenderDocs --src=/docs --to=/to --force
- name: Commit and Push changes
uses: Andro999b/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: 'main'Try adding a graph to a docs/README.rakudoc in a repo, for instance:
=begin Graphviz :headlevel(2) :caption<Simple example>
digraph G {
main -> parse -> execute;
main -> init;
main -> cleanup;
execute -> make_string;
execute -> printf
init -> make_string;
main -> printf;
execute -> compare;
}
=end Graphviz
Now you will have a README with an automatic Table of Contents, all the possibilities of RakuDoc v2, and an index at the end (if you indexed any items using X<> markup).
(Sigh: All presents leave wrapping paper! A small file called semicolon_delimited_script is also pushed by github’s Commit and Push to the repo.)
So, let's say you're golang developer and want pure Go to write some CICD task:
cat task.go
package main
import "fmt"
func main() {
fmt.Println("Hello, pipeline")
}
Go is cool, but there is one thing that makes it difficult to use in high level scenarios - its verbosity. Passing parameters to go tasks and return them back to main scenario takes some efforts and a lot of boilerplate code. It'd be good to keep main code concise and easy to read.
Rakulang in other hand is perfect language when it comes to munge data in and out, due it's extreme flexibility and expressiveness.
In this post I am going to show how to embed golang tasks into CICD pipelines, with a little help of Sparrow framework.
Let's, first of all, modify our golang task code, new version will be:
cat task.go
package main
import (
"fmt"
"github.com/melezhik/sparrowgo"
)
func main() {
type Params struct {
Message string
}
type Result struct {
Message string
}
var params Params
// sparrowgo takes care about passing
// input parameters from Raku to Go
sparrowgo.Config(¶ms)
// read params from pipeline
fmt.Printf("Task params: %s\n", params.Message)
// return results back to pipeline
sparrowgo.UpdateState(&Results{Message : "Hello from Go"})
}
All we've done here is utilized Sparrowgo package that "convert" golang task into Sparrow task with a benefits of passing and returning data from and to Rakulang.
Finally this how our pipeline will look like, now it's Raku part:
#!raku
my $s = task-run ".", %(
:message<Hello from Raku>
);
say "Result: ", $s<Message>;
High level design.
Now, once we have some prove of concept code in place, we can get a high level picture of what our pipeline system could look like:
[ Raku scenario to pass and handle data in and out ]
\ \ \
task.go -> result -> task.go -> result -> task.go -> ...
So, we have the best of two worlds - Raku to write scenarios with less of code and Golang to do all heaving lifting where performance and strict type checking is required.
I published my new book: A Language a Day, which is a collection of brief overviews to 21 programming languages.
This book provides a concise overview of 21 different programming languages. Each language is introduced using the same approach: solving several programming problems to showcase its features and capabilities. Languages covered in the book: C++, Clojure, Crystal, D, Dart, Elixir, Factor, Go, Hack, Hy, Io, Julia, Kotlin, Lua, Mercury, Nim, OCaml, Raku, Rust, Scala, and TypeScript.
Each chapter covers the essentials of a different programming language. To make the content more consistent and comparable, I use the same structure for each language, focusing on the following mini projects:
Each language description follows—where applicable—this pattern:
You can find all the code examples in this book on GitHub: github.com/ash/a-language-a-day.
You can buy it on Amazon or LeanPub as an electronic or Kindle edition, or as a paper hardcover or paperback version. More information with the links to the shops.
Last Saturday, October 26, 2024, another edition of the London Perl & Raku Workshop took place. It was a reopening after a few years break. London Perl Workshop has a long history, started in 2004, so this year it was formally 20 years old.
For me, it was also a Perl-and-or-Raku event after a break. The last in-person event was PerlCon 2019, which was an annual European Perl conference that was held in Riga that year. Since then, after the Covid’s strike, I have organised a couple of (well, three of them) Raku Conferences, but that was online in Zoom. Online due to lockdown first, and then due to people slowly reinventing the joy of travel.
In-between, there were at least two in-person gatherings, another edition of the German Perl and Raku Workshop in April and the American Perl and Raku Conference in Las Vegas in June. I did not attend any of them, but looked at the photos and videos, so I was envy enough because I missed it.
You should not forget that right now, right today, at this very moment, an on-going war against my beloved Ukraine takes place. During the first months, it was not possible to think about anything else, not to mention any entertainment trips or conferences. But time keeps going… and you see less and less blue-and-yellow flags on the streets. Even at Waterstones, the books about that war are located at the very bottom shelves due to the unfortunate nature of alphabetical sorting.
When this year’s London Perl Workshop was announced, I decided to go. Then, I decided not to go. In the end, one week before the event, I thought that I’d better go. Because of my uncertainty, I did not manage to submit a talk on time, so even a small 5-minute lightning talk submission (which I did on the day of the event, ha-ha), did not have a chance to went through. The venue, apparently, was rented until 6pm sharp, and there was no room for anything else.
So, here are the slides of my talks. I’ve added some comments so that you can enjoy it by following my message.
My journey was quite short, I only had a couple of days in London, but the weather made its present and the plane from Amsterdam landed in Southampton instead. So, I took a chance to see the old walls there and to learn that they offer beans on breakfast at IKEA’s canteen.
I really enjoy London, it’s so huge that you fill extremely comfortable in it, how weird that may sound. Despite only a limited couple of days in London, I tried to use the time to wander around just as a tourist.
I also escaped from the middle of the conference day to see the urban life around venue’s location.
On the day before the conference, I met with an ex-colleague, with whom I worked at two different places, both Perl-related. For a few years, he’s been living in London, and I noticed that he looked so much happier since I last saw him. I hope that is because he lives in this great city now, not because he’s programming in Go, not Perl anymore.
Of course, I was happy to see people I know from the Perl and/or Raku communities. I did not see most of them at least since 2019, so some of them required a few seconds to recognise me, LOL.
The workshop was really well attended. Even taking into account the significant drop in the numbers since the beginning of 2000s, it was more than 100 people, and there were two full tracks of the talks.
Let me not list the talks I attended, as the full schedule is online, and the recordings should appear soon.
There was also a third track, partially filled with regular talks, but partially with a broader-scoped events such as Science Perl Talks. I’ve no idea what they talked about there, but it’s somehow connected with the recently-published first issue of the Science Perl Journal and a traditional drama around its establisher.
But the appearance of the new publication is a good thing in the end. I was also surprised, that in 2024, a few new publications about Perl appeared or are planned to be published. I suspect that some of them issued during the previous years are AI-generated texts, but the rest are quite normal and useful books.
There are no decision yet whether there will be another London Perl Workshop in 2025. On the bright side, there should be a soon announcement on the date and location of the German Perl Workshop 2025. Also, there are plans to have a Dutch Perl Workshop 2025 in Utrecht.
I am thinking of if it’s time to revitalise the annual European Perl and Raku Conference.
NOTE: There is an issue when opening existing Comma projects that were created in earlier versions. Please use New project from Existing Sources... rather than Open and make sure to select Yes when it prompts you about overwriting an existing .idea file in the project directory.
This release represents a major shift for the Comma project in many ways.
From the bottom of my heart, I want to express the deepest gratitude and thanks to Jonathan Worthington (jnthn++),
Edument, and all past and future contributors to the Comma project. There's been
so much effort put into this codebase and it was an honor to be able to work on it.
The most major change is the shift to the IntelliJ Platform Gradle Plugin 2.0. This
allows Comma to be built (as a plugin) without cloning the
intellij-community repo and downloading it's entire dependency tree!
This does seem to preclude building Comma as a standalone IDE, at least for the time being. That appears to be a different beast entirely and we will have to investigate that as the time and tuits allow.
Other major changes included updating the code to correct for broken and (some) deprecated
API changes, as well as the significant cosmetic adjustment of migrating Perl6 to Raku.
The latter should be almost entirely finished, but there might be some stragglers that I've
missed.
Building should be as simple as opening this repository in IntelliJ IDEA (using version 2024.2 or greater), and selecting
build > build from the Gradle build target options. Or, for more immediate gratification, you can select intellij platform > runIde.
Update: If you don't feel like building it yourself, you can now simply download the plugin zip from GitHub. From inside IntelliJ IDEA, open the Settings > Plugins, find the gear icon, and select Install Plugin from Disk....
Next steps:
<Your wishlists go here!>Happy hacking! :D
The question has been raised, how to get named arguments into sub EXPORT via a use-statement. The ever helpful raiph provided an answer, which in turn left me with the question, why he didn’t just use a Capture to move the data around. Well, because that doesn’t work. The compiler actually evaluates the expression \(:1a, :2b) into (1, 2) before passing it on to EXPORT.
If it’s hard, do it functional!
# foo.raku
use v6.d;
constant &transporter = sub { \(:1a, :2b); }
use foo &transporter;
# lib/foo.rakumod
use v6.d;
proto sub EXPORT(|) { * }
multi sub EXPORT(&transporter) {
&EXPORT(|transporter);
}
multi sub EXPORT(:$a, :$b) {
dd $a, $b;
Map.new
}The idea is to hand a function to use to be called by EXPORT, and then redispatch the value that is produced by that function, to take advantage of Raku´s excellent signature binding. The proto and refering to sub EXPORT explicitly is needed because there is also a predefined (and in this case hidden) package called EXPORT.
I’m passing on named arguments to EXPORT, but all kinds of stuff could be returned by &transporter. So long as everything is known pretty early on at compile-time. The use-statement is truly an early bird.
As the title states, I made Raku bigger because lol context (that’s how the Synopsis is calling **@) makes supporting feed operators fairly easy. I wonder if Larry added this syntax to Signature with that goal in mind. With PR#5532 the following becomes possible.
<abc bbc cbc> ==> trans('a' => 'x', 'b' => 'i') ==> say();
# OUTPUT: (xic iic cic)Armed with this I can make a script of mine a little simpler.
use MONKEY-TYPING;
augment class IO::Path {
method trans(|c) {
my $from = self.Str;
my $to = self.Str.trans(|c);
self.rename($to) unless $from eq $to
}
}
sub rename-whitespace(IO::Path $dir where *.d){
dir($dir).grep({ .d || .f && .rw })
==> trans("\c[space]" => "\c[no-break space]", "\c[apostrophe]" => "\c[prime]")
==> sub (*@a) { print '.' for @a}();
dir($dir).grep({ .d && .rw })».&?ROUTINE;
}
rename-whitespace('.'.IO);
put '';I don’t like spaces in filenames, as they are often found with audio or video files. Having auto-complete friendly names makes using a CLI less bumpy. By teaching IO::Path to rename files by providing rules, as they are understood by Str.trans, I can use a feed operator to get the job done. (I wouldn’t be surprised to learn, that anonymous subs DWIM here to be emergent behaviour in Raku.)
Having another PR that adds .trans to IO::Path is tempting but requires more thought.
A follow up to the Welsh dragon.
Firing up another localisation
Steps to Ryuu
Comments on the Raku program
More generally about localisation of coding
If you want to make Ryuu better?
In my previous blog about Y Ddraig, I created a localisation of the Raku Language in Welsh. During a recent conversation, someone mentioned there may be interest in a Japanese localisation, so I thought I would try the same techniques.
I do not speak or read or have ever studied Japanese. The localisation given below will be about as clunky and awkward as any can be. I imagine there may be some hilarious stupidities as well.
So to be clear, this article is about a proof of concept rather than a real effort to create a production-ready program.
However, it took me 40 minutes from start to finish, including setting up the github repo.
Since I like dragons, I named the Japanese cousin to Raku 'Ryuu'. It's a whimsy, not to be treated with much seriousness.
Basically I created a github repo, copied my existing Welsh localisation and changed CY to JA, and draig to ryuu.
Within the automation/ directory I used the translation technique explained for Welsh to create the JA file from the template. The translated.txt file needed some manual cleaning, because the English word for has multiple Japanese equivalents. I chose one more or less at random. In addition, Google translate did some strange things to the order of words and numbers in a line.
After adapting the files in the bin/ directory, and installing the distribution with Raku's zef utility, I ran tr2ryuu on the Raku program simple.raku.
A comment about my Welsh blog was that the program in Y Ddraig was not all in Welsh. And here the program is not all in Japanese.
Remember that the user-facing part of a program will be in the language of the user, in this case it is English. However, the coder-facing part of the program will be in the language of the coder. Below, the coder interface is in Japanese (or rather my ham-fisted attempt at Japanese).
The following is the result (which I put in a file called simple.ryuu):
私の $choice;
私の $continue;
私の @bad = <damn stupid nutcase>;
リピート {
$choice = プロンプト "Type something, like a number, or a string: ";
言う "You typed in ｢" ~ ($choice ~~ 任意(@bad) ?? "*" × $choice.文字 !! $choice) ~ "｣";
与えられた $choice {
いつ "dragon" {
言う "which is 'draig' in Welsh"
}
いつ 任意(@bad) {
言う "wash your mouth with soap"
}
いつ IntStr {
言う "which evaluates to an integer ", $choice
}
いつ RatStr {
言う "which evaluates to a rational number ", $choice
}
デフォルト {
言う "which does not evaluate to a number "
}
}
$continue = プロンプト "Try again? If not type N: "
} まで $continue 当量 任意(<N n>)
What is amazing to me is that when I ran ryuu simple.ryuu, the program ran without error.
The simple.raku program is obviously trivial, but what I wanted to show are some interesting Raku features. Note how I created an array of words with @bad = <damn stupid nutcase>;, and then later I tested to see whether an input word was one of the array elements.
The Raku idiom いつ 任意(@bad) or in English when any( @bad ) compares the topic variable, in this case the input value, with each array element and creates a junction of Boolean results. The 'any' effectively or's the result to collapse the junction.
Junctions are not common in programming languages, so I thought if there would be problems, then it would be there. So I was surprised to find my Raku program works without error in another language.
All the major coding languages are in English. There are, however, coders from all over the world, and the majority of those from non-English speaking nations would have needed to learn English before (or at the same time as) they learnt coding.
We are thus creating a new technological elite: those who can understand English (or some subset of it), and those who cannot. The more coding becomes an essential part of life, the greater the ability divide between coders (who speak English) and non-coders will become.
The aim of localising a programming language is to provide an entry into coding in a form that is more accessible to every human being, whatever their natural language.
However, the aim of this approach is not to eliminate English at every level of complexity, but to provide a sufficiently rich language for most normal coding and educational needs.
In addition, by having a canonical language (Raku, which is based on English) into which all localised languages can be translated, what we get is a universal auxiliary language together with a universality of being able to code.
Having a single auxiliary language means that a non-English speaking person writing in a localised coding language can translate the program with the problem into Raku, have a developer on the other side of the globe find the problem, and suggest a solution in code, then for that solution to be translated back into the local language.
Naturally, a person who wants to learn more about coding, or who needs to delve deeper into the workings of a module, will need to learn English. Learning wider to learn deeper is a normal part of the educational experience.
Ryuu or however it should be called, absolutely is in need of Tender loving care. Please feel free to use the github issues or PR processes to suggest better translations.
At some stage, Ryuu will join the official Raku localisations.
Actually creating a localization of an existing programming language in an existing human language
Introduction
Considerations
The plan for y Ddraig (the dragon in Welsh)
Constraints and first steps
Forwards into Draig and running
Completing the translation
Backwards to canonical form
Drawbacks
Nearly all programming languages that are widely used in the world today have English as their base human language.
This means that a young person living in a non-English environment must first learn English (if only a limited sub-set of English), and then learn the skills needed for coding. This puts the majority of the humanity at a disadvantage.
Would it not be useful to create programming languages that use the script and words of human languages, but which compile into programs that will run with state of the art computer software?
Here is how I created a Welsh cousin of Raku, and I called it y Ddraig - or The dragon.1
There are some practical obstacles to creating any new programming language, and here are some of the ameliorating reasons why the Raku Programming Language is a good choice to base a new one on.
Different human languages use different writing systems and most need extra letters not covered by the ASCII set
;, ,, and {}.Different operating systems
All professional programmers are proficient in English, and so can answer questions about program errors in English. The number of programmers speaking Welsh is quite small, and the same would be true for many other human languages.
Whilst the plan is to create y Ddraig as a language that can be used with as little English as possible, there are several stages:
First is to create a localization (L10N) of Raku, or a module called L10N::CY.
Next, the operating system has to be adapted so that a executable called draig is available, which will also mean that in a graphic interface (GUI), double clicking on a file with a file-extension of .draig will run Raku with the L10N::CY module already loaded. This is trivial.
For personal reasons, I stopped using Windows on my PC, and I use Ubuntu Linux exclusively. So, where there are terminal sessions, I shall be showing how I created Y ddraig using a Linux terminal.
Since Y ddraig is a Raku cousin, or technically a Raku localization, the Raku language needs to be installed. In addition, it needs to be a version of the language released after December 2023. Information about the installation of Raku, and its package manager zef, can be found on the Raku website.
The first stage is to create the L10N::CY module. It is simply a normal Raku module, which is then installed with the zef package manager.
Raku module development is conventionally done by creating a github repository. Working with git is quite simple for the basic functionality, but there is a long learning curve when working with others. But none of that is the topic here.
Elizabeth Mattijsen, who is responsible for all this Raku internationalization magic, has created a template internationalization module for the Klingon language (yep: aliens get to be the first to use localizations of a Terran computer language)2.
So I git cloned the Klingon, and created a github repo for the Welsh. My git nick is finanalyst, so here's the terminal code lines:
git clone https://github.com/lizmat/L10N-TLH.git rakuast-L10N-Klingon
git clone https://github.com/finanalyst/rakuast-L10N-CY.git rakuast-L10N-Welsh
In the following, I shall call Elizabeth's repo, the Klingon repo, and mine, the Welsh repo. If you want to create your own language, the convention being followed is to name the language according to an ISO 639-1 supported language code, at least for the foreseeable future. You should also think of an filename extension (like .draig here) for programs in the new language (Raku cousin).
The two critical parts of the module are update-localization, and a root text file which we will call the localization map. It should be named by the language code. Here it is called CY for Cymraeg or the Welsh language, for Klingon, it is TLH.
The update-localization utility in from the Klingon repo looks for a repo root directory file with 2 or 3 upper case characters. This is taken as the localization map and is automatically converted into all the magical modules.
The biggest step is to translate the terms to be stored in CY. The template for the localization map can be found at Github Raku localizations. To get this as a local text file, I used the following terminal code to download the template in to my working directory.
curl 'https://raw.githubusercontent.com/Raku/L10N/main/TEMPLATE' > CY
The pristine form of CY contains a few lines of comment (starting with the characters '# ', note the space), and then a number of sections starting with
# KEY TRANSLATION
Within each section there is a key and then an English Raku keyword, eg.
#adverb-pc-delete delete
Note that it has been commented out with single #. This means that the update-localization utility will ignore the line.
Now comes the translation part. Each significant commented line (a line with # and no space at the start) has two parts: a KEY and a TRANSLATION, with some spaces between them. The translation process is to substitute the English Raku keyword with the Welsh word, and remove the #. For example, the first significant line becomes
adverb-pc-delete dileu
When starting the translation process, and to see how the system works, it is sufficient to translate a minimum number of keys. (Eg., for the Draig program below, I only need eleven words.)
Once I have enough key words for the program, all that is needed is to run ./update-localization. This then creates a directory tree under lib/.
Here is a short program in Raku (English cousin), which we store in a file called 'simple.raku' in the root directory of the repo.
my $choice;
my $continue;
my @bad = <damn stupid nutcase>;
repeat {
$choice = prompt 'Type something, like a number, or a string: ';
say 'You typed in ｢' ~ ( $choice ~~ any( @bad ) ?? '*' x $choice.chars !! $choice) ~ '｣';
given $choice {
when 'dragon' { say "which is 'draig' in Welsh" }
when any( @bad ) { say "wash your mouth with soap" }
when IntStr { say "which evaluates to an integer ", $choice }
when RatStr { say "which evaluates to a rational number ", $choice }
default { say "which does not evaluate to a number "}
}
$continue = prompt 'Try again? If not type N: ';
} until $continue eq any(<N n>) ;
Try running it in a terminal where the working directory is the root directory of the repo, thus:
raku simple.raku
If you input some words, it will tell you the input is a string, if you input something naughty (well only one of the three words 'damn stupid nutcase'), you will get another response, and then there are responses depending on whether the number is an integer or a rational.
The code uses 11 keywords, which I translated and put into CY. Obviously, there are many strings that form the user interface, and these are hard-coded in this program in English. We are concerned at the moment with the infrastructure keywords that form the programming language.
Now lets translate the Raku program using a simple Raku utility called tr2draig.
We shall specify here that the Raku program is of the form somename.raku and that we want a Draig program of the form somename.draig.
The utility is the following Raku script:
#!/usr/bin/env raku
sub MAIN(
$filename where *.IO.f #= source file to be localized to Welsh
) {
$filename.IO.extension('draig').spurt: $filename.IO.slurp.AST.DEPARSE("CY")
}
Breaking the program down, #!/usr/bin/env raku is standard for a script with execute permission.
$filename where *.IO.f #= ... is a nice Raku idiom for a program called from a terminal. The program expects a string that names a file. It checks that the filename exists and is of type 'f'. If not, then an error message will be provided from the comment following #=.
$filename.IO.extension('draig').spurt: takes the filename, creates a new file with the extension 'draig' replacing the previous extension (which was 'raku'), then spurts text into it, the text it uses being generated by the expression after the :.
$filename.IO.slurp.AST.DEPARSE("CY") takes the filename (which has extension 'raku'), makes it into a filehandle, slurps (sucks) in the text that is in the file, parses the text as a Raku program into an Abstract Symbol Tree (AST), and then deparses the symbol tree using the new Welsh keywords into a new program with Welsh.
For reasons related to distributing Raku software, I have placed the utility in the
bin/directory. There are two ways to get a copy of these files, either by creating a clone of my Github repository (the url is given above), or by installing the Raku distribution, aszef install "L10N::CY". If zef is set up in a typical way, then the utilities below can be run without specifying the path.
The translation utility is run like this
bin/tr2draig simple.raku
This produces a file simple.draig, which contains
fy $choice;
fy $continue;
fy @bad = <damn stupid nutcase>;
ailadrodd {
$choice = prydlon "Type something, like a number, or a string: ";
dywedyd "You typed in ｢" ~ ($choice ~~ unrhyw(@bad) ?? "*" x $choice.golosg !! $choice) ~ "｣";
a-roddwyd $choice {
pryd "dragon" {
dywedyd "which is 'draig' in Welsh"
}
pryd unrhyw(@bad) {
dywedyd "wash your mouth with soap"
}
pryd IntStr {
dywedyd "which evaluates to an integer ", $choice
}
pryd RatStr {
dywedyd "which evaluates to a rational number ", $choice
}
rhagosodedig {
dywedyd "which does not evaluate to a number "
}
}
$continue = prydlon "Try again? If not type N: "
} hyd $continue eq unrhyw(<N n>)
Now we want a way to run draig programs. The easiest way is create another Raku program draig, which we place in the bin/ directory. bin/draig has the following content:
#!/usr/bin/env raku
sub draig(*@_) {
%*ENV<RAKUDO_RAKUAST> = 1;
%*ENV<RAKUDO_OPT> = '-ML10N::CY';
run $*EXECUTABLE, @_;
}
multi sub MAIN() {
draig
}
multi sub MAIN(
$filename where *.IO.f #= source file to be run in Welsh
) {
draig $filename
}
Here's a gloss of the program:
sub draig(*@_) {... This is a helper subroutine called later. It sets up environment variables, and preloads the localization module, before running Raku with the Welsh keywords.
multi sub MAIN() runs the sub draig (above) when no program is given. This puts the user into a REPL, where statements can be input directly, parsed and run immediately. However, draig will run using the Welsh keywords.
multi sub MAIN( handles the case when
$filename where *.IO.f #= source file to be run in Welsh
)draig is given a filename. As explained above, the filename is tested for existence.
Now try running bin/draig simple.draig in a terminal.
If the
RakuAST-L10N-CYdistribution has been installed withzef, then all you will need isdraig simple.draig.
The running code produces exactly the same output as the English Raku program. The user interface output is still in English, and for completeness, I should translate all of the text strings to Welsh as well.
At this point, we can translate any English version of a Raku program into a Draig program, and draig will run it, but only if the Raku program uses the 11 keywords I translated.
In order to create a full localization, all of the Translation values need to be converted to Welsh. The first step (and I really must re-emphasise it is a first step) is to use an automated translation tool. A correct localization will need first-language Welsh speakers to go through the CY file and correct the translations.
At the time of writing, the localization has not been properly verified, so it has not yet been added to the official Raku localizations.
For the automated translation, I have created the directory automation/. I again downloaded the TEMPLATE into a CY file in the automation/ directory.
I have written some automation helper utilities, namely:
find-untranslated, takes a CY file and splits it into two new files, with line numbers at the start of each line to help match later. One file is partial.txt with the starting key and comment lines, and the second file is to-be-translated.txt. Both contain approximately 700 lines.combine-translated, takes partial.txt and another file translated.txt (see below) to create a new CY file.Next I copy/pasted the lines for translation (from the file to-be-translated.txt into Google's translate to Welsh page. The operation took a couple of copy/pastes due to size limitations, but the text is not overly large.
The translated text can be copied straight back to a new file (translated.txt), and then recombined with partials.txt to create CY.
As mentioned above, suppose a Welsh-speaker using y Ddraig
runs into a programming problem, a syntax error or logic not working as the programmer assumes. An English speaking programmer will probably not be able to help.
But ... .draig program can be retranslated back to the canonical form of Raku. This is done by a utility called tr2raku. It is almost the inverse of tr2draig, but instead of replacing the file extension .draig with .raku, we add it on to the filename so that its clear it is a canonicalisation of a Raku cousin.
The utility bin/tr2raku contains the following contents.
#!/usr/bin/env raku
sub MAIN(
$filename where *.IO.f #= Welsh source file to be turned to canonical form
) {
$filename.IO.extension('raku', :0parts).spurt: $filename.IO.slurp.AST("CY").DEPARSE
}
The difference can be seen that the language signifier (CY) is a parameter to the AST method, rather than the DEPARSE method.
There should be no reason why this recipe cannot be applied to Mandarin, Hindi, or Japanese.
The problems stem from the development history of Raku. Error messages are in English, and so Raku cousins, like Draig, will have English error messages.
The problem is not insurmountable, but it will take a lot of translator hours.
Another problem is that helper modules, for example, JSON::Fast, which imports/exports structured data from/to .json files into Raku data structures. The module has two main methods to-json and from-json. These names are set by the module, not by Raku.
A program in y Ddraig will be able to access all Raku modules without restriction, but it will need to use the canonical (English) names.
However, if many Raku localizations come into being, and a user base for them develops, these are all soluble problems.
Footnotes
A reader may wonder why the language is Y ddraig, but draig is given in dictionaries as the translation for dragon. Well ..., draig is a feminine word, and the definite particle Y triggers a mutation in the next feminine word, so d mutates to dd.
My next project is to create a localization with Egyptian hieroglyphs
Over on Reddit zeekar wasn’t too happy about Raku’s love of Seq. It’s immutability can be hindering indeed.
my @nums = [ [1..10], ];
@nums[0] .= grep: * % 2;
@nums[0].push(11); # We can't push to a Seq.I provided a solution I wasn’t happy with. It doesn’t DWIM and is anything but elegant. So while heavily digesting on my sofa (it is this time of the year), the problem kept rolling around in my head. At first I wanted to wrap Array.grep(), but that would be rather intrusive and likely break Rakudo itself. After quite a bit of thinking, I ended up with the question. How can I have indexable container (aka Array) that will turn each value on assignment into an (sub-)Array?
my Array() @foo = [ 1..10, ];
dd @foo;
# Array[Array(Any)] @foo = Array[Array(Any)].new($[1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
@foo[0] .= grep: * % 2;
@foo[1] = 42;
dd @foo;
# Array[Array(Any)] @foo = Array[Array(Any)].new($[1, 3, 5, 7, 9], $[42])The answer is obvious. By telling the compiler what I want! Coersion-types have become really hard to distinguish from magic.
I wish you all a Merry Christmas and the very best questions for 2024.
Note: This post is also available as a gist if you find that format more readable.
This research was conducted while preparing an upcoming Raku Advent Calendar post. The Raku code uses a basic supply pipeline to feed $volume objects through a validation stage that requires a CRC32 check before going to the output sink, which prints the processing time of the validation stage.
The "reaction graph" is designed to simulate a stream processing flow, where inputs arrive and depart via Candycane™ queues (that's the name of Santa's Workshop Software's queueing service, in case you weren't familiar).
The entire scenario is contrived in that CRC32 was chosen due to native implementation availability in both Raku and Zig, allowing comparison. It's not an endorsement of using CRC32 in address validation to deliver Santa's, or anyone's, packages.
Also, thanks to the very helpful folks at ziggit.dev for answering my newbie question in depth.
The source code:
At larger volumes, Raku struggles with the initialization speed of the $volume objects that are instantiated. I replaced the native Raku class with one written in Zig, using the is repr('CStruct') trait in Raku and the extern struct qualifier in Zig.
In Zig I use a combination of an arena allocator (for the string passed from Raku) and a memory pool (designed to quicklymake copies of a single type, exactly fitting our use case) to construct Package objects.
Additionally, for Raku+Zig the CRC32 hashing routine from Zig's stdlib is used via a tiny wrapper function.
A --bad-packages option is provided by both Raku scripts, which makes 10% of the objects have a mismatched address/CRC32 pair.
The library tested was compiled with -Doptimize=ReleaseFast.
Batches are repeated $batch times, which defaults to 5.
All results from an M2 MacBook Pro.
This test and its is only intended to reflect the case where an object is constructed in Zig based on input from Raku. It is not intended to be a test of Zig's native speed in the creation of structs.
There is a call to sleep that gives time -- 0.001 seconds -- to get the react block up and running before emitting the first True on the $ticker-supplier. This affects overall runtime but not the batch or initialization metrics.
The speed of Raku+Zig was so fast that the tool used to measure these details (cmdbench) could not find results in ps for the execution because it had already finished. These are marked as Unmeasured.
In the next iteration of this research, there sould be two additional entries in the data tables below for:
| Volume | Edition | Runtime | Batch Time | Initialization | Max bytes |
|---|---|---|---|---|---|
| 10,000 | Raku | 1.072s | 1: 0.146596686s 2: 0.138983732s 3: 0.142380065s 4: 0.136050775s 5: 0.134760525s |
0.008991746s | 180240384 |
| 10,000 | Raku+Zig | 0.44s | 1: 0.010978411s 2: 0.006575705s 3: 0.004145623s 4: 0.004280415s 5: 0.00468929s |
0.020358033s | Unmeasured |
| 10,000 | Raku ( bad-packages) |
1.112s | 1: 0.157788932s 2: 0.149544686s 3: 0.156293433s 4: 0.151365477s 5: 0.147947436s |
0.008059955s | 196263936 |
| 10,000 | Raku+Zig ( bad-packages) |
0.463s | 1: 0.031300276s 2: 0.01006562s 3: 0.010693328s 4: 0.011056994s 5: 0.010770828s |
0.010954495s | Unmeasured |
The Raku+Zig solution wins in performance, but loses the initialization race. Raku is doing a decent showing in comparison to how far it has come performance-wise.
| Volume | Edition | Overall | Batch Time | Initialization | Max bytes |
|---|---|---|---|---|---|
| 100,000 | Raku | 7.163s | 1: 1.360029456s 2: 1.32534014s 3: 1.353072834s 4: 1.346668338s 5: 1.351110502s |
0.062402473s | 210173952 |
| 100,000 | Raku+Zig | 0.75s | 1: 0.079802007s 2: 0.073638176s 3: 0.053291894s 4: 0.05087652s 5: 0.050394687s |
0.05855585s | 241205248 |
| 100,000 | Raku ( bad-packages) |
7.89s | 1: 1.496982355s 2: 1.484494027s 3: 1.497365023s 4: 1.490810525s 5: 1.492416774s |
0.060026016s | 209403904 |
| 100,000 | Raku+Zig ( bad-packages) |
1.076s | 1: 0.16960934s 2: 0.111172493s 3: 0.110844786s 4: 0.113021202s 5: 0.111713535s |
0.051436311s | 242450432 |
We see Raku+Zig take first place in everything but memory consumption, which we can assume is a function of using the NativeCall bridge, not to mention my new-ness as a Zig programmer.
| Volume | Edition | Overall | Batch Time | Initialization | Max bytes |
|---|---|---|---|---|---|
| 1,000,000 | Raku | 68.081s | 1: 13.475302627s 2: 13.161153845s 3: 13.293998956s 4: 13.364662217s 5: 13.474755295s |
0.95481884s | 417103872 |
| 1,000,000 | Raku+Zig | 3.758s | 1: 0.788083286s 2: 0.509883905s 3: 0.492898873s 4: 0.500868284s 5: 0.498677495s |
0.575087671s | 514064384 |
| 1,000,000 | Raku+Zig ( bad-packages) |
75.796s | 1: 14.940173822s 2: 14.632683637s 3: 14.866796226s 4: 15.272903792s 5: 15.027481448s |
0.704549212s | 396656640 |
| 1,000,000 | Raku+Zig ( bad-packages) |
6.553s | 1: 1.362189763s 2: 1.061496504s 3: 1.069134685s 4: 1.062746049s 5: 1.061096044s |
0.528011288s | 462766080 |
Raku's native CRC32 performance is clearly lagging here. Raku+Zig keeps its domination except in the realm of memory usage. It would be hard to justify using the Raku native version strictly on its reduced memory usage, considering the performance advantage on display here
A "slow first batch" problem begins to affect Raku+Zig. Running with bad-packages enabled slows down the Raku+Zig crc32 loop, hinting that there might be some optimizations on either the Raku or the Zig/clang side of things that can't kick in when the looped data is heterogenous.
Dynamic runtime optimization sounds more like a Rakudo thing than a Zig thing, though.
| Volume | Edition | Runtime | Batch Time | Initialization | Max bytes |
|---|---|---|---|---|---|
| 10,000,000 | Raku | 704.852s | 1: 136.588638184s 2: 136.851019628s 3: 138.44696743s 4: 139.777040922s 5: 139.490784317s |
13.299274221s | 2055012352 |
| 10,000,000 | Raku+Zig | 38.505s | 1: 8.843459877s 2: 4.84300835s 3: 4.991842433s 4: 5.077245603s 5: 4.939533707s |
9.375436134s | 2881126400 |
| 10,000,000 | Raku ( bad-packages) |
792.1s | 1: 162.333803401s 2: 174.815386318s 3: 168.299796081s 4: 162.643428135s 5: 163.205406678s |
10.252639311s | 2124267520 |
| 10,000,000 | Raku+Zig ( bad-packages) |
65.174 | 1: 14.41616445s 2: 11.078961309s 3: 10.662389991s 4: 11.20240076s 5: 10.614430063s |
6.778600235s | 2861596672 |
Pure Raku really struggles with a volume of this order of magnitude. But if you add in just a little bit of Zig, you can reasonably supercharge Raku's capabilities.
The "slow first batch" for Raku+Zig has been appearing in more understated forms in other tests. Here the first batch is over double the runtime of the second batch. What is causing this?
This doesn't seem to work. At least, I'm not patient enough. The process seems to stall, growing and shrinking memory but never finishing.
This is a preliminary report in blog post form based on a contrived code sample written for another, entirely different blog post. More data and deeper analysis will have to come later.
Zig's C ABI compatibility is clearly no put on. It works seamlessly with Raku's NativeCall. Granted, we haven't really pushed the boundaries of what the C ABI can look like but one of the core takeaways is actually that with Zig we can design that interface. In other words, we are in charge of how ugly, or not, it gets. Considering how dead simple the extern struct <-> is repr('CStruct') support is, I don't think the function signatures need to get nearly as gnarly as they get in C.
Sussing the truth of that supposition out will take some time and effort in learning Zig. I'm looking forward to it. My first stop will probably be a JSON library that uses Zig. I'm also going to be looking into using Zig as the compiler for Rakudo, as it might simplify our releases significantly.
According to Larry, laziness is a programmers virtue. The best way to be lazy is having somebody else do it. By my request, SmokeMachine kindly did so. This is not fair. We both should have been lazy and offload the burden to the CORE-team.
Please consider the following code.
my @many-things = (1..10).List;
sub doing-one-thing-at-a-time($foo) { ... }
say doing-one-thing-at-a-time(@many-things.all);Rakudo goes out of it’s way to create the illusion that sub doing-one-thing-at-a-time can deal with a Junction. It can’t, the dispatcher does all the work of running code in parallel. There are tricks we can play to untangle a Junction, but there is no guarantee that all values are produced. Junctions are allowed to short-circuit.
This was bouncing around in my head for quite some time, until it collided with my thoughts about Range. We may be handling HyperSeq and RaceSeq wrong.
my @many-things = (1..10).List;
sub doing-one-thing-at-a-time($foo) { ... }
say doing-one-thing-at-a-time(@many-tings.hyper(:degree<10>));As with Junctions doing dispatch-magic to make hyper/race just work, moving the handling to the dispatcher would move the decision from the callee to the caller and, as such, from the author of a module to the user. We can do that by hand already with .hyper.grep(*.foo) or other forms of boilerplate. In Raku-land we should be able to do better and provide a generalisation of transforming calls with the help of the dispatcher.
I now know what to ask Santa for this year.
My version of JSON::Class is now released. The previous post explains why does this worth a note.
Lately, some unhappiness has popped up about Range and it’s incomplete numericaliness. Having just one blogpost about it is clearly not enough, given how big Ranges can be.
say (-∞..∞).elems;
# Cannot .elems a lazy list
in block <unit> at tmp/2021-03-08.raku line 2629I don’t quite agree with Rakudo here. There are clearly ∞ elements in that lazy list. This could very well be special-cased.
The argument has been made, that many operators in Raku tell you what type the returned value will have. Is that so? (This question is always silly or unnecessary.)
say (1 + 2&3).WHAT;
# (Junction)Granted, Junction is quite special. But so are Ranges. Yet, Raku covers the former everywhere but the latter feels uncompleted. Please consider the following code.
multi sub infix:<±>(Numeric \n, Numeric \variance --> Range) {
(n - variance) .. (n + variance)
}
say 2.6 > 2 ± 0.5;
# True
my @heavy-or-light = 25.6, 50.3, 75.4, 88.8;
@heavy-or-light.map({ $_ ≤ 75 ± 0.5 ?? „$_ is light“ !! „$_ is heavy“ }).say;
# (25.6 is heavy 50.3 is heavy 75.4 is heavy 88.8 is heavy)To me that looks like it should DWIM. It doesn’t, because &infix:«≤» defaults to coercing to Real and then comparing numerically.
This could easily be fixed by adding a few more multis and I don’t think it would break any production code. We already provide quite a few good tools for scientists. And those scientists do love their error bars — which are ranges. I would love for them to have another reason to use Raku over … that other language.
This will be a short one. I have recently released a family of WWW::GCloud modules for accessing Google Cloud services. Their REST API is, apparently, JSON-based. So, I made use of the existing JSON::Class. Unfortunately, it was missing some features critically needed for my work project. I implemented a couple of workarounds, but still felt like it’s not the way it has to be. Something akin to LibXML::Class would be great to have…
There was a big “but” in this. We already have XML::Class, LibXML::Class, and the current JSON::Class. All are responsible for doing basically the same thing: de-/serializing classes. If I wanted another JSON serializer then I had to take into account that JSON::Class is already taken. There are three ways to deal with it:
JSON::Class and re-implement it as a backward-incompatible version.The first two options didn’t appeal to me. The third one is now about to happen.
I expect it to be a stress-test for Raku ecosystem as, up to my knowledge, it’s going to be the first case where two different modules share the same name but not publishers.
As a little reminder:
JSON::Class:auth<zef:jonathanstowe> in their dependencies and, perhaps, in their use statement.JSON::Class:auth<zef:vrurg>.There is still some time before I publish it because the documentation is not ready yet.
Let’s 🤞🏻.
In this post I will show you the solution to the Task 2 of this week’s Weekly Challenge 233. This time I was using the help of ChatGPT, which offered a very nice solution.
You are given an array of integers.
Write a script to sort the given array in increasing order based on the frequency of the values. If multiple values have the same frequency then sort them in decreasing order.
Example 1
Input: @ints = (1,1,2,2,2,3)
Ouput: (3,1,1,2,2,2)
'3' has a frequency of 1
'1' has a frequency of 2
'2' has a frequency of 3
Example 2
Input: @ints = (2,3,1,3,2)
Ouput: (1,3,3,2,2)
'2' and '3' both have a frequency of 2, so they are sorted in decreasing order.
Example 3
Input: @ints = (-1,1,-6,4,5,-6,1,4,1)
Ouput: (5,-1,4,4,-6,-6,1,1,1)I asked ChatGPT the following: ‘Create a program. Here is the description of the task.’ To make sure the result is in the Raku programming language, I also added the following instruction in my local settings so that it knows which programming language I prefer by default.
The solution generated by ChatGPT was quite good with a small mistake.
ChatGPT: Sure, here’s a Raku program that implements the described sorting algorithm for the given task:
sub frequency-sort(@arr) {
my %freq;
%freq{$_}++ for @arr;
my @sorted = @arr.sort: {
%freq{$^b} <=> %freq{$^a} ||
$^b <=> $^a
};
return @sorted;
}
my @ints = (1, 1, 2, 2, 2, 3);
my @sorted = frequency-sort(@ints);
say "Input: @ints";
say "Output: @sorted";
First, Raku would not interpolate arrays, so say "Input: @ints" prints the string literary: Input: @ints. Second, in the sorting rule, sorting by frequency must be ascending rather than descending, so we need to switch the placeholder variables $^b and $^a.
In the rest, ChatGPT did a good work. It computed the frequency using a loop, and I especially liked how it addressed the requirement to sort by two dimensions.
Here is the full program with the above-mentioned corrections:
sub frequency-sort(@arr) {
my %freq;
%freq{$_}++ for @arr;
my @sorted = @arr.sort: {
%freq{$^a} <=> %freq{$^b} ||
$^b <=> $^a
};
return @sorted;
}
my @tests =
(1, 1, 2, 2, 2, 3),
(2, 3, 1, 3, 2),
(-1, 1, -6, 4, 5, -6, 1, 4, 1);
say frequency-sort($_) for @tests;
This program prints the following output for the given test cases:
$ raku ch-2.raku [3 1 1 2 2 2] [1 3 3 2 2] [5 -1 4 4 -6 -6 1 1 1]
In this post, I will demonstrate my solution to another Task of The Weekly Challenge, week 233. Here’s how it reads:
You are given an array of words made up of alphabets only.
Write a script to find the number of pairs of similar words. Two words are similar if they consist of the same characters.
Example 1
Input: @words = ("aba", "aabb", "abcd", "bac", "aabc")
Output: 2
Pair 1: similar words ("aba", "aabb")
Pair 2: similar words ("bac", "aabc")
Example 2
Input: @words = ("aabb", "ab", "ba")
Output: 3
Pair 1: similar words ("aabb", "ab")
Pair 2: similar words ("aabb", "ba")
Pair 3: similar words ("ab", "ba")
Example 3
Input: @words = ("nba", "cba", "dba")
Output: 0There’s a slight moment that may be needs extra comments. In the second example all three words constructed of the same two letters, a and b. So, all of the three words match the definition of a ‘similar’ word. But as the task needs to find pairs, we need to construct all the possible pairs out of those three words.
In my solution, I chose to use a handy classify method. For an array, it creates a hash, where the keys are the common classifying symbol, and the values are the lists of the input elements that match this classification property.
Here is the whole first program together with all the test cases provided in the description. The program maps every word to a corresponding string that consists of the sorted unique letters in the word.
my @tests = ["aba", "aabb", "abcd", "bac", "aabc"],
["aabb", "ab", "ba"],
["nba", "cba", "dba"];
for @tests -> @words {
say @words.classify(*.comb.unique.sort.join).grep(*.value.elems > 1);
}
For example, the word aba will be associated with the key ab. The program prints the following output:
$ raku ch-1.raku (ab => [aba aabb] abc => [bac aabc]) (ab => [aabb ab ba]) ()
The format of the output differs from the examples, but it can be enhanced if needed. My goal was to create a compact solution 
But I would assume that you’d be interested in looking at what classify produces. I am also curious. For the same @tests, it returns the following three hashes:
{ab => [aba aabb], abc => [bac aabc], abcd => [abcd]}
{ab => [aabb ab ba]}
{abc => [cba], abd => [dba], abn => [nba]}
As you see, each string was put into one of the classification bins.
The second part of the task is to find pairs. After the grep, we already filtered out everything that has less than two elements, so if data passed through this filter, there will be at least one pair. For bigger arrays, we can use another Raku’s built-in mechanism: the combinations method.
The updated mail loop of the program looks like this now.
for @tests -> @words {
say "Test case: ", @words;
my %classification = @words.classify(*.comb.unique.sort.join).grep(*.value.elems > 1);
my $pairs = 0;
for %classification.kv -> $k, $v {
my @pairs = $v.combinations(2);
$pairs += @pairs.elems;
say "$k: ", @pairs;
}
say "Answer: $pairs pair{$pairs == 1 ?? '' !! 's'}.\n";
}
The ‘redundant’ code here is added just to have a more detailed output so that we can see which pairs were actually found. Let us look at the output for the initial test cases:
$ raku ch-1.raku Test case: [aba aabb abcd bac aabc] ab: [(aba aabb)] abc: [(bac aabc)] Answer: 2 pairs. Test case: [aabb ab ba] ab: [(aabb ab) (aabb ba) (ab ba)] Answer: 3 pairs. Test case: [nba cba dba] Answer: 0 pairs.
On this page, I’ll briefly cover the solutions to the tasks for this week’s Weekly Challenge #231.
You are given an array of distinct integers.
Write a script to find all elements that is neither minimum nor maximum. Return -1 if you can’t.
Example 1
Input: @ints = (3, 2, 1, 4)
Output: (3, 2)
The minimum is 1 and maximum is 4 in the given array. So (3, 2) is neither min nor max.
Example 2
Input: @ints = (3, 1)
Output: -1
Example 3
Input: @ints = (2, 1, 3)
Output: (2)
The minimum is 1 and maximum is 3 in the given array. So 2 is neither min nor max.Here is my original solution in the Raku programming language.
sub solve(@data) {
@data.grep: * != (@data.min, @data.max).any
}
As the tasks requires that we print -1 when there are no elements in the output, let us add an update to satisfy this requirement:
sub solve(@data) {
(@data.grep: * != (@data.min, @data.max).any) || -1
}
The * in this code will actually replace the $_ variable. Would you prefer it, you may use $_, but you’ll need parentheses in this case. So, instead of @data.grep: * != ..., you need @data.grep({$_ != ...}), which may be a less clear code for some people.
Finally, let us use some math notation and replace calling the .any method with a ‘contains’ operator:
sub solve(@data) {
(@data.grep: * ∉ (@data.min, @data.max)) || -1
}
Well, actually, ‘does not contain’. And this is my final solution.
Note that you may want to use the .minmax method instead of two calls to .min and .max, but .minmax returns a range, which is not that suitable for this task.
Adding some test cases and passing them to the solve function:
my @tests = (3, 2, 1, 4), (3, 1), (2, 1, 3); say solve($_) for @tests;
The program prints the expected output:
$ raku ch-1.raku (3 2) -1 (2)
You are given a list of passenger details in the form “9999999999A1122”, where 9 denotes the phone number, A the sex, 1 the age and 2 the seat number.
Write a script to return the count of all senior citizens (age >= 60).
Input: @list = ("7868190130M7522","5303914400F9211","9273338290F4010")
Ouput: 2
The age of the passengers in the given list are 75, 92 and 40.
So we have only 2 senior citizens.
Input: @list = ("1313579440F2036","2921522980M5644")
Ouput: 0Apparently, the solution requires extracting information from a string in a specific format. It is not quite clear from the description whether the strings always contains the same number of characters, and thus the age and seat number are always two-digit values. But let’s use this assumption.
As we do not need any other information from the ticket code, no need to properly parse it, so I preferred anchoring around the only letter in the string and consider the next two digits as the age. Of course, you may make it simpler and just extract the two digits counting from the end of the string.
sub is-sinior($ticket) {
~($ticket ~~ / <alpha> (\d\d) /)[0] >= 75
}
Unlike Perl 5, Raku ignores spaces in regexes by default, so I added some air to it. On the other hand, extracting matches may seem a bit more complicated.
For the first given example (see task’s description), the Match object contains the following information:
｢M75｣ alpha => ｢M｣ 0 => ｢75｣
So, I am taking the 0th element using [0] and stringily it with the ~ prefix operator.
In essence, the task has been solved. Let’s add the test cases and run them:
my @tests = ('7868190130M7522', '5303914400F9211', '9273338290F4010'),
('1313579440F2036', '2921522980M5644');
for @tests -> @tickets {
say [email protected]({is-sinior($_)});
}
The program prints:
$ raku ch-2.raku 2 0
* * *
The second stage in the process to update RakuDoc is now over and the third (GAMMA review) stage is starting. In order not to repeat some history, please take a look at Revising Rakudoc.
An online version is available of the proposed RakuDoc language.
The whole of the Raku documentation suite is written in RakuDoc.
About half of the original design ideas outlined in S26 were documented in current POD6. Some of the ideas were available, but not documented. Some instructions were not realised at all.
It should be remembered that RakuDoc is parsed by the compiler (eg. Rakudo) as part of a Raku program, and is then rendered by the renderer (eg. Raku::Pod::Render) into (for example) HTML. When I use the word 'implemented', I mean that a RakuDoc instruction is properly parsed and rendered. Some of the instructions defined in S26 were parsed by Rakudo, but not rendered, and some were not parsed properly or at all, so could not be rendered.
The revision process has therefore identified and rectified the parsing deficiencies, and identified the rendering flaws. RakuDoc is correctly parsed only on the most recent versions of Rakudo, which at the time of writing has yet to be released. Raku::Pod::Render still does not handle RakuDoc in its entirety.
It became clear that the RakuDoc serves two inter-related use cases:
RakuDoc had a simple table markup, which is very similar to the Markdown syntax. It worked, but the simplicity of the syntax was at the cost of flexibility.
Looking around at other ways of specifying a table, we identified two paradigms (there may be more), namely the one used by HTML and the one used by the GTK grid widget. Both of them allow for cells that span more than one column or row, and both allow for embedding (eg. a table inside a cell of a table).
After several iterations, a new procedural model was created and rendered. The design allows for spanning and embedding, but it also allows an author to specify a table row by row, or column by column, or even using a mixture of both.
An example showing a markup using both rows and columns can be seen in the online draft.
A semantic block is a section of text that should be easily available to another software tool, or can be moved around the final document.
For example, a section on the authors of a document (including contact or affiliations) is most easily written at the top of the document, but often it is better to place the information towards the bottom of the text.
This is done by creating a semantic block (simply by making the calling the block in uppercase letters). The block can be hidden from view by adding the metadata option :hidden. All the data is placed in a special structure.
The rendered text can be placed in the document later using the P<> instruction, or it can be accessed by another tool that may only be wanting the VERSION or LICENSE.
One of the strengths of RakuDoc is the ability to add optional metadata to blocks of text.
The new version of the defining document explains this concept in more detail. Metadata options are optional, with reasonable defaults being assumed. This means that a short form of the block is sufficient in most cases.
In the description above, the option :hidden was mentioned. Another example, is :caption. Suppose you want to write a semantic block called =AUTHORS at the start of the document, but you want for it to appear later in the document as Article authors, then you could specify it as follows:
=for AUTHORS :caption<Article authors> :hidden
A. N. Writer, socMedia nic @psuedonym
M. Z. Orator, socMedia nic @politician
Article text continues
Pages later
P<semantic: AUTHORS>
It is possible to include a link L<for reference see | #A very long title somewhere in the text> where the text on the right-hand side of the | is a heading. However, this can become tiresome if you want to include several links to the same place.
So, a metadata option :id can be included in a heading. This allows you to do the following:
=for head3 :id<lnk>
How to correctly link to other places in a manual
Pages of text
Properly linking is important, L<see for example|#lnk>
RakuDoc has instructions for block level text, such as headings, paragraphs, code.
Typically blocks will be included in the Table of Contents.
It also has markup instructions that work in line, and which do not (typically) affect the ToC.
For example, a simple markup instruction is C< text >, which renders like text. I have used the Markdown equivalent here. In RakuDoc, everything between the C< and > is verbatim and styled differently to normal text, just like the Markdown code quotes. However, RakuDoc also has V< text > which treats everything inside the angle brackets as verbatim but does not style it differently.
A new markup instruction in RakuDoc is M< text | metadata>. A renderer will place the text in the rendered text, but will also provide a mechanism for the user to take the metadata and provide new functionality. For instance, M< fa-copy | font awesome v5 > could be interpreted to insert the font-awesome icon called fa-copy into the text. Or M< Buy now | PayPal, database-id > could expose the API for the PayPal payment platform.
RakuDoc is inherently customisable. It is also designed to be output neutral (although at the moment HTML is the most common output form). Semantic blocks can be invented within a document, and a renderer can allow for other user-defined blocks and markup instructions to be created.
However, RakuDoc is specific about naming rules. A built-in block must be all lower case, and renderers should not allow user-defined blocks to use all lower case. A semantic block is all upper case. And a user-defined block must have at least one upper-case letter and one lower-case letter.
All markup instructions, which are inline instructions, must be a single Unicode character with the property UPPER. Built-in markup instructions are the ASCII characters and Δ. All other codes can be used.
The naming rules have been created to ensure that even if a user-defined block or markup becomes popular, it is not a part of the RakuDoc standard. Renderers are only required to implement the RakuDoc standard, and may render other blocks, or not.
These are some of the interesting additions to RakuDoc that are being proposed. There are more.
Since the Gamma review stage is now underway, it is almost certain that there may be more changes because the revision is now open to the Raku community for comment and requests. Discussion is open both for the language design and for the explanation of the design.
As might be admitted, community requests for changes to the overall design will face significant resistance from the main authors in order to maintain backwards compatibility with the previous version of RakuDoc, and the integrity of the underlying paradigms. New block or inline instructions will be more readily considered, but requests for examples, explanation, and greater clarity will be very much appreciated.
I was always concerned about making things easier.
No, not this way. A technology must be easy to start with, but also be easy in accessing its advanced or fine-tunable features. Let’s have an example of the former.
This post is a quick hack, no proof-reading or error checking is done. Please, feel free to report any issue.
Part of my ongoing project is to deal with JSON data and deserialize it into Raku classes. This is certainly a task
for JSON::Class. So far, so good.
The keys of JSON structures tend to use lower camel case which is OK, but we like
kebabing in Raku. Why not, there is
JSON::Name. But using it:
There are roles. At the point I came to the final solution I was already doing something like1:
class SomeStructure does JSONRecord {...}
Then there is AttrX::Mooish, which is my lifevest on many occasions:
use AttrX::Mooish;
class Foo {
has $.foo is mooish(:alias<bar>);
}
my $obj = Foo.new: bar => "the answer";
say $obj.foo; # the answer
Apparently, this way it would still be a lot of manual interaction with aliasing, and that’s what I was already doing for a while until realized that there is a bettter way. But be back to this later…
And, eventually, there are traits and MOP.
That’s the easiest part. What I want is to makeThisName look like make-this-name. Ha, big deal!
unit module JSONRecord::Utils;
our sub kebabify-attr(Attribute:D $attr) {
if $attr.name ~~ /<.lower><.upper>/ {
my $alias = (S:g/<lower><upper>/$<lower>-$<upper>/).lc given $attr.name.substr(2);
...
}
}
I don’t export the sub because it’s for internal use mostly. Would somebody need it for other purposes it’s a rare case where a long name like JSONRecord::Utils::kebabify-attr($attr) must not be an issue.
The sub is not optimal, it’s what I came up with while expermineting with the approach. The number of method calls and regexes can be reduced.
I’ll get back later to the yada-yada-yada up there.
Now we need a bit of MOP magic. To handle all attributes of a class we need to iterate over them and apply the aliasing. The first what comes to mind is to use role body because it is invoked at the early class composition times:
unit role JSONRecord;
for ::?CLASS.^attributes(:local) -> $attr {
# take care of it...
}
Note the word “early” I used above. It actually means that when role’s body is executed there are likely more roles waiting for their turn to be composed into the class. So, there are likely more attributes to be added to the class.
But we can override Metamodel::ClassHOW compose_attributes method of our target ::?CLASS and rest assured no one would be missed:
unit role JSONRecordHOW;
use JSONRecord::Utils;
method compose_attributes(Mu \obj, |) {
for self.attributes(obj, :local) -> $attr {
# Skip if it already has `is mooish` trait applied – we don't want to mess up with user's intentions.
next if $attr ~~ AttrX::Mooish::Attribute;
JSONRecord::Utils::kebabify-attr($attr);
}
nextsame
}
Basically, that’s all we currently need to finalize the solution. We can still use role’s body to implement the key elements of it:
unit role JSONRecord;
use JSONRecordHOW;
unless ::?CLASS.HOW ~~ JSONRecordHOW {
::?CLASS.HOW does JSONRecordHOW;
}
Job done! Don’t worry, I haven’t forgot about the yada-yada-yada above!
But…
The original record role name itself is even longer than JSONRecord, and it consists of three parts. I’m lazy. There are a lot of JSON structures and I want less typing per each. A trait? is jrecord?
unit role JSONRecord;
multi sub trait_mod:<is>(Mu:U \type, Bool:D :$jrecord) is export {
unless type.HOW ~~ JSONRecordHOW {
type.HOW does JSONRecordHOW
type.^add_role(::?ROLE);
}
}
Now, instead of class SomeRecord does JSONRecord I can use class SomeRecord is jrecord. In the original case the win is even bigger.
There is absolutely nothing funny about it. Just a common way to keep a reader interested!
Seriously.
The reason for the yada in that snippet is to avoid a distraction from the primary purpose of the example. Here is what is going on there:
I want AttrX::Mooish to do the dirty work for me. Eventually, what is needed is to apply the is mooish trait as shown above. But the traits are just subs. Therefore all is needed now is to:
&trait_mod:<is>($attr, :mooish(:$alias));
Because this is what Raku does internally when encounters is mooish(:alias(...)). The final version of the kebabifying sub is:
our sub kebabify-attr(Attribute:D $attr) {
if $attr.name ~~ /<.lower><.upper>/ {
my $alias = (S:g/<lower><upper>/$<lower>-$<upper>/).lc given $attr.name.substr(2);
&trait_mod:<is>($attr, :mooish(:$alias));
}
}
Since the sub is used by the HOW above, we can say that the &trait_mod<is> would be called at compile time2.
Now, it used to be:
class SomeRecord does JSONRecord {
has $.aLongAttrName is mooish(:alias<a-long-attr-name>);
has $.shortname;
}
Where, as you can see, I had to transfer JSON key names to attribute names, decide where aliasing is needed, add it, and make sure no mistakes were made or attributes are missed.
With the above rather simple tweaks:
class SomeRecord is jrecord {
has $.aLongAttrName;
has $.shortname;
}
Job done.
Before I came down to this solution I’ve got 34 record classes implemented using the old approach. Some are little, some are quite big. But it most certainly could’ve taken much less time would I have the trait at my disposal back then…
I have managed to finish one more article in the Advanced Raku For Beginners series, this time about type and object composition in Raku.
It’s likely to take a long before I can write another.
Once, long ago, coincidentally a few people were asking the same question: how do I get a method object of a class?
Answers to the question would depend on particular circumstances of the code where this functionality is needed. One
would be about using MOP methods like .^lookup, the other is to use method name and indirect resolution on invocant:
self."$method-name"(...). Both are the most useful, in my view. But sometimes declaring a method as our can be
helpful too:
class Foo {
our method bar {}
}
say Foo::<&bar>.raku;
Just don’t forget that this way we always get the method of class Foo, even if a subclass overrides method bar.
The first Raku Core Summit, a gathering of folks who work on “core” Raku things, was held on the first weekend of June, and I was one of those invited to attend. It’s certainly the case that I’ve been a lot less active in Raku things over the last 18 months, and I hesitated for a moment over whether to go. However, even if I’m not so involved day to day in Raku things at the moment, I’m still keen to see the language and its ecosystem move forward, and – having implemented no small amount of the compiler and runtime since getting involved in 2007 – I figured I’d find something useful to do there!
The area I was especially keen to help with is RakuAST, something I started, and that I’m glad I managed to bring far enough that others could see the potential and were excited enough to pick it up and run with it.
One tricky aspect of implementing Raku is the whole notion of BEGIN time (of course, this is also one of the things that makes Raku powerful and thus is widely used). In short, BEGIN time is about running code during the compile time, and in Raku there’s no separate meta-language; anything you can do at runtime, you can (in principle) do at compile time too. The problem at hand was what to do about references from code running at compile time to lexically scoped symbols in the surrounding scope. Of note, that lexical scope is still being compiled, so doesn’t really exist yet so far as the runtime is concerned. The current compiler deals with this by building up an entire flattened table of everything that is visible, and installing it as a fake outer scope while running the BEGIN-time code. This is rather costly, and the hope in RakuAST was to avoid this kind of approach in general.
A better solution seemed to be at hand by spotting such references during compilation, resolving them, and fixating them – that is, they get compiled as if they were lookups into a constant table. (This copies the suggested approach for quasiquoted code that references symbols in the lexical scope of where the quasiquoted code appears.) This seemed promising, but there’s a problem:
my $x = BEGIN %*ENV<DEBUG> ?? -> $x { note "Got $x"; foo($x) } !! -> $x { foo($x) };It’s fine to post-declare subs, and so there’s no value to fixate. Thankfully, the generalized dispatch mechanism can ride to the rescue; we can:
When compiling Raku code, timing is everything. I knew this and tried to account for it in the RakuAST design from the start, but a couple of things in particular turned out a bit awkward.
I got a decent way into this restructuring work during the core summit, and hope to find time soon to get it a bit further along (I’ve been a mix of busy, tired, and had an eye infection to boot since getting back from the summit, so thus far there’s not been time for it).
I also took part in various other discussions and helped with some other things; those that are probably most worth mentioning are:
Thanks goes to Liz for organizing the summit, to Wendy for keeping everyone so well fed and watered, to the rest of attendees for many interesting discussions over the three days, to TPRF and Rootprompt for sponsoring the event, and to Edument for supporting my attendance.
Hi hackers! Today the MoarVM JIT project is nearly 9 years old. I was inspired by Jonathan's presentation reflecting on the development of MoarVM, to do the same for the MoarVM JIT, for which I have been responsible.
For those who are unfamiliar, what is commonly understood as 'JIT compilation' for virtual machines is performed by two components in MoarVM.
This post refers only to the native code generation backend component. It, too, is split into two mostly-independent systems:
One one hand, as a result of my limited experience, time and resources, and on the other hand as a result of the design of MoarVM.
MoarVM was originally designed as a traditional interpreter for a high level language (much like the Perl interpreter). Meaning that it has a large number of different instructions and many instructions operate on high-level data structures like strings, arrays and maps (as opposed to pointers and machine words).
This is by no means a bad or outdated design. Frequently executed routines (string manipulation, hash table lookups etc.) are implemented using an efficient language (C) and driven by a language that is optimized for usability (Raku). This design is also used in modern machine learning frameworks. More importantly, this was a reasonable design because it is a good target for the Rakudo compiler.
For the JIT compiler, this means two things:
The machine code generated by the JIT compiler then will mostly consists of consecutive function calls to VM routines, which is not the type of code where a compiler can really improve performance much.
In other words, suppose 50% of runtime is spent in interpretation overhead (instruction decoding and dispatch), and 50% is spent in VM routines, then removing interpretation overhead via JIT compilation will at best result in a twofold increase in performance. For many programs, the observed performance increase will be even less.
Mind that I'm specifically refering to the improvement due to machine code generation, and not to those due to type specialization, inlining etc. (the domain of 'spesh'). These latter features have resulted in much more significant performance improvements.
For me personally, it was a tremendously valuable learning experience which led directly to my current career, writing SQL compilers for Google Cloud.
For the Raku community, even if we never realized the performance improvements that I might have hoped at the start, I hope that the JIT project (as it exists) has been valuable, if for no other reason than identifying the challenges of JIT compilation for MoarVM. A future effort may be able to do better based on what we learned; and I hope my blog posts are a useful resource from that perspective.
Assuming that time and resources were not an issue:
If any of this comes to pass, you'll find my report on it right here. Thanks for reasding and until then!
I decided to write a simple (but funky) dice roller over the holidays. This led to a number of fun diversions in Raku code that all deserve some highlighting.
Today I'd like to share a pending PR I have for GTK::Simple that I believe highlights one of Raku's strength: compositional concision. That is, code that does a lot in very few words thanks to the composition of various concise-on-their-own details of the language.
GTK::Simple is pretty chill alreadyThis module does a good job of translating the C experience of writing a GTK application into an idiomatic Raku version. It is both easily usable as well as quickly extensible, should you find some corner case of the (massive) GTK that isn't covered.
I'll be updating with some more in depth discussion of recent changes that have been merged recently.
(Note to self: Fully implementing the afore-linked GTK application in Raku would make for an interesting exercise.)
In GTK::Simple, we map GTK classes into top-level GTK::Simple definitions. So MenuItem becomes GTK::Simple::MenuItem.
This leads to code such as:
use GTK::Simple;
my $app = GTK::Simple::App.new(title => "A fresh new app");
$app.set-content(
GTK::Simple::HBox.new(
GTK::Simple::Label.new(text => "Looking good in that GTK theme")
)
);
$app.run;
Should my PR be accepted, it will allow a short-hand syntax that makes things almost a bit Shoes-like in simplicity.
use GTK::Simple :subs;
my $app = app :title("An alternative");
$app.set-content(
h-box(
label(:text("Shiny slippers"))
)
);
$app.run;
The mapping rule is a simple CamelCase to kebab-case conversion of the class names.
The entire code for adding this feature is as follows:
# Exports above class constructors, ex. level-bar => GTK::Simple::LevelBar.new
my module EXPORT::subs {
for GTK::Simple::.kv -> $name, $class {
my $sub-name = '&' ~ ($name ~~ / (<:Lu><:Ll>*)* /).values.map({ .Str.lc }).join("-");
OUR::{ $sub-name } := sub (|c) { $class.new(|c) };
}
}
This line of code utilizes a Raku convention that allows for custom behavior through specific instructions from the importer of a module, provided in the form of Pair objects (:subs is shorthand for subs => True).
When the importer specifies use GTK::Simple :subs, it looks for a module with the pair's key as the name inside of the imported module. This is often a generated module thanks to the export trait. sub foo() is export :named-option {...} generates a my-scoped module Module::named-option that instructs the importer to include foo in its own my scope.
This is an example of compositional concision right here. The dangling :: is shorthand for .WHO, which when called on a module returns the package meta-object of the module.1 Holding this meta-object, we can call .kv to get the keys (names) and values (package objects) of the packages within that scope.
Because we have loaded all (and only) our relevant classes into the GTK::Simple package scope, the meta-object for that package handily provides a .kv method that delivers the class names as keys and the actual class objects as keys, zipped together.
If there were anything else our scoped in GTK::Simple, it would be in this list too (module and class definitions are our scoped by default). So depending on how complex your module is, you might have to write some filters or guards to make sure you were only processing the actual class objects.
Thanks to a meta-object system designed to be both easy to use and transparently hidden from view until needed, there's nothing to make things feel complicated here.2
This line makes me happy. The crux of the code lies in the advanced Raku regex syntax. <:Lu> and <:Li> are built in character classes in Raku that represent uppercase and lowercase characters, respectively. These are Unicode aware, so no worries there.
The rest is straight-forward: take the .values of the Match object, map them to strings while also lower-casing them and then join the resulting list of strings into a compound string in kebab-case.
We prepend the & sigil to the name in order to register it as a subroutine when it is brought into the importer's scope.
Here's where the actual mapping takes place. OUR::{ $sub-name } is creating a (name for a) sub dynamically in the shared OUR scope between the importer and the imported modules. The import process is such that these dynamically defined modules become available in the scope of the importing module (it's MY scope).
sub (|c) { $class.new(|c) } says create an anonymous subroutine that passes it's arguments (which are, of course, an object themselves) exactly as-is to the constructor of $class.
Now, I do understand that there are aspects of this code that are not obvious: the dangling :: syntax, the necessity of making a my scoped module with a special name of EXPORT, and perhaps the use of the OUR:: package accessor.
It's probably not code that I will necessarily write directly from memory next time I want to dynamically load a bunch of subs into an importer's scope.
At the same time, I would argue that all of these examples very idiomatic to the language: little 'escape hatches' into deeper layers of the language that work as expected once you encounter them. All of this without muddying the waters of what's "in" a module by, for instance, providing methods directly on package objects that would provide similar functionality.3
Raku really is a well-thought over programming language. It's also massive, which can be intimidating. It helps to manage this massivity when pieces fit together in carefully planned ways. In other words, once I had that dangling ::/WHO object to call .kv on, everything else I had to do just fell together.
In order to ensure that everything was indeed working in a systematic way, I needed to write some tests.
use GTK::Simple :subs;
# Other modules are pulled into GTK::Simple namespace by now that we do not want to test
sub skip-test($name) {
state $skip-set = set '&' X~ <app simple raw native-lib g-d-k common property-facade>;
$name (elem) $skip-set
}
for GTK::Simple::.kv -> $name, $class {
my $sub-name = '&' ~ ($name ~~ / (<:Lu><:Ll>*)* /).values.map({ .Str.lc }).join("-");
next if skip-test($sub-name);
my $widget;
lives-ok { $widget = ::{$sub-name}(:label("For Button(s)"), :uri("For LinkButton")) },
"There is a subroutine in scope called '$sub-name'";
ok $widget ~~ $class, "'$sub-name' returns a { $class.^name } object";
}
Here I created a state variable (only defined once per scope, so we don't re-do the variable assignment with each call) to hold a set of names that we want to skip. If the argument is an element of said set, skip the test.
Once again :: shows up to be a Do-What-I-Mean shortcut. This time it is for the package of our current lexical scope. So it means essentially the same thing: let me access the package as if it were a "stash", giving us semantics equivalent to hashes (eg, ::{$sub-name}). A lexical lookup is begun until the subroutine is found in lexical scope. Since the import process implanted it there in lexical scope, it returns with the sub stored with name $sub-name.
We pass two positional arguments to the constructor because they are either required for some constructors and or ignored by those that don't require them.
That wraps up a fairly lengthy post about a very short snippet of code. Please stay tuned for other posts about changes that were made such that my awesome, funky dice roller could exist in ease and comfort.
When .WHO is called on an initialized object, it returns it's respective class object.↩
Compare that to this Java or even that Java without the Reflections library.↩
In Ruby, the same would be done with MyModule.constants.select {|c| MyModule.const_get(c).is_a? Class}. It's MyModule.constants and MyModule.const_get that in my opinion shows a muddier abstraction between package objects and the meta-objects that govern and represent them.↩
It's been over a month since I first came across -- finally -- a clean way to present anyone who runs Linux with a simple, clean, non-"virtualenv" installation of raku: rakudo-pkg to the rescue!
rakudo-pkg vs a virtual environment like rakubrewThere was always a bit of an icky feeling related to relying on rakubrew(and rakudobrew before it) for requiring inquiring minds to first ignore what their system offered them through official channels and instead install some in order to have access to anything remotely resembling an up-to-date version of the raku runtime (or perl6 before it).
Unfortunately, in the case of most official package repositories, the latest officially available versions were often ancient1. It's heartening to note, however, that this situation has improved significantly since the official debut of the "finished" language as 6.c half a decade ago. Still the official repositories lag far behind the improvements that are made, even today.
In my opinion, it is one thing to encounter a virtualenv-style tool after you have hit some limitation with running the system installation of a language. But being exposed to adding a whole new mothball to your home directory and login shell configuration as a requirement to just trying out a language is not the strongest look in terms of an advocacy perspective.
Having a dedicated system path for the tools also fixes issues related to tools that do not inherit environment variables created by executing all of those tweaks stashed in .bash_profile or (in my case) .config/fish/config.fish.
A virtualenv approach is also particularly un-desirable as it is potentially resolvable through guarantees made at the language design layer around Raku's approach to module and language versioning.
Raku naturally shows it's previous life as that caterpillar formerly-known-as-Perl-6 most strongly when you encounter its own versioning.
use v6.c is guaranteed to access a historical standard of Raku behavior. use v6.* optimistically says "use *Whatever* version you consider the newest". use v6.d gives you guarantees that the language won't start spitting deprecation warnings pertaining to later versions, starting with v6.e, while also doing everything exactly as v6.d intended even on a newer release.
It would be interesting to stress test the implicit and explicit language level guarantees of Raku by dog-fooding an old fashioned "smoke test" on our own with regard to the claims made in the designs of the language versioning and the module repositories and authorities concepts. A sort of "distributed DarkPAN simulator" for Raku in the 2020s.
The CompUnit repositories and module authorities are ideas that intend to make backward compatibility easier in a world where sometimes you want to run a locally patched variant of a public module that is otherwise identical (or even wildly incompatible) and other times you want to be able to run two different versions of a library side-by-side -- at the same time.
A/A testing of library upgrades at vanguard for a bit before rolling out to the fleet, anyone? (That's a different, likely far more profitable, library idea for you, my intrepid reader).
Check out the blog post announcement of the new GitHub Task based release flow and the latest iteration of the rakudo-pkg project.
It was a long road to the first official release, so it is not at all fair to blame distribution maintenance teams to not bother with ensuring that the bleeding edge version of a still-baking language was--or is--easily accessible. Things have gotten better since the release of 6.c.↩
I've been using Windows 10 for a while as I wait to install a new m2 SSD in this laptop to provide a dedicated place for Linux. I've noticed some very strange and disappointing issues with Unicode characters when running Raku from a terminal.
Thanks to #raku on Freenode, I managed to find a solution:
chcp 65001
This changes the Unicode code page to 65001 and magically fixes the issues I was seeing.
To make the change more permanent, it is possible to use change some registry key values under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage. Modify ACP, MACCP, and OEMCP all to value 65001, give the OS a reboot, et voila!
Thanks to the ever-present raiph for his reddit comment which pointed me to a Stack Overflow question from a user facing the same problem, which in turn pointed to the solution provided for a question from a C# programmer.
Around 18 months ago, I set about working on the largest set of architectural changes that Raku runtime MoarVM has seen since its inception. The work was most directly triggered by the realization that we had no good way to fix a certain semantic bug in dispatch without either causing huge performance impacts across the board or increasingly complexity even further in optimizations that were already riding their luck. However, the need for something like this had been apparent for a while: a persistent struggle to optimize certain Raku language features, the pain of a bunch of performance mechanisms that were all solving the same kind of problem but each for a specific situation, and a sense that, with everything learned since I founded MoarVM, it was possible to do better.
The result is the development of a new generalized dispatch mechanism. An overview can be found in my Raku Conference talk about it (slides, video); in short, it gives us a far more uniform architecture for all kinds of dispatch, allowing us to deliver better performance on a range of language features that have thus far been glacial, as well as opening up opportunities for new optimizations.
Today, this work has been merged, along with the matching changes in NQP (the Raku subset we use for bootstrapping and to implement the compiler) and Rakudo (the full Raku compiler and standard library implementation). This means that it will ship in the October 2021 releases.
In this post, I’ll give an overview of what you can expect to observe right away, and what you might expect in the future as we continue to build upon the possibilities that the new dispatch architecture has to offer.
The biggest improvements involve language features that we’d really not had the architecture to do better on before. They involved dispatch – that is, getting a call linked to a destination efficiently – but the runtime didn’t provide us with a way to “explain” to it that it was looking at a dispatch, let alone with the information needed to have a shot at optimizing it.
The following graph captures a number of these cases, and shows the level of improvement, ranging from a factor of 3.3 to 13.3 times faster.
Let’s take a quick look at each of these. The first, new-buf, asks how quickly we can allocate Bufs.
for ^10_000_000 {
Buf.new
}
Why is this a dispatch benchmark? Because Buf is not a class, but rather a role. When we try to make an instance of a role, it is “punned” into a class. Up until now, it works as follows:
new methodfind_method method would, if needed, create a pun of the role and cache it-> $role-discarded, |args { $pun."$name"(|args) }This had a number of undesirable consequences:
With the new dispatch mechanism, we have a means to cache constants at a given program location and to replace arguments. So the first time we encounter the call, we:
new method on the class punned from the roleFor the next thousands of calls, we interpret this dispatch program. It’s still some cost, but the method we’re calling is already resolved, and the argument list rewriting is fairly cheap. Meanwhile, after we get into some hundreds of iterations, on a background thread, the optimizer gets to work. The argument re-ordering cost goes away completely at this point, and new is so small it gets inlined – at which point the buffer allocation is determined dead and so goes away too. Some remaining missed opportunities mean we still are left with a loop that’s not quite empty: it busies itself making sure it’s really OK to do nothing, rather than just doing nothing.
Next up, multiple dispatch with where clauses.
multi fac($n where $n <= 1) { 1 }
multi fac($n) { $n * fac($n - 1) }
for ^1_000_000 {
fac(5)
}
These were really slow before, since:
where clause involvedwhere clauses twice in the event the candidate was chosen: once to see if we should choose that multi candidate, and once again when we entered itWith the new mechanism, we:
where clause, in a mode whereby if the signature fails to bind, it triggers a dispatch resumption. (If it does bind, it runs to completion)Once again, after the setup phase, we interpret the dispatch programs. In fact, that’s as far as we get with running this faster for now, because the specializer doesn’t yet know how to translate and further optimize this kind of dispatch program. (That’s how I know it currently stands no chance of turning this whole thing into another empty loop!) So there’s more to be had here also; in the meantime, I’m afraid you’ll just have to settle for a factor of ten speedup.
Here’s the next one:
proto with-proto(Int $n) { 2 * {*} }
multi with-proto(Int $n) { $n + 1 }
sub invoking-nontrivial-proto() {
for ^10_000_000 {
with-proto(20)
}
}
Again, on top form, we’d turn this into an empty loop too, but we don’t quite get there yet. This case wasn’t so terrible before: we did get to use the multiple dispatch cache, however to do that we also ended up having to allocate an argument capture. The need for this also blocked any chance of inlining the proto into the caller. Now that is possible. Since we cannot yet translate dispatch programs that resume an in-progress dispatch, we don’t yet get to further inline the called multi candidate into the proto. However, we now have a design that will let us implement that.
This whole notion of a dispatch resumption – where we start doing a dispatch, and later need to access arguments or other pre-calculated data in order to do a next step of it – has turned out to be a great unification. The initial idea for it came from considering things like callsame:
class Parent {
method m() { 1 }
}
class Child is Parent {
method m() { 1 + callsame }
}
for ^10_000_000 {
Child.m;
}
Once I started looking at this, and then considering that a complex proto also wants to continue with a dispatch at the {*}, and in the case a where clauses fails in a multi it also wants to continue with a dispatch, I realized this was going to be useful for quite a lot of things. It will be a bit of a headache to teach the optimizer and JIT to do nice things with resumes – but a great relief that doing that once will benefit multiple language features!
Anyway, back to the benchmark. This is another “if we were smart, it’d be an empty loop” one. Previously, callsame was very costly, because each time we invoked it, it would have to calculate what kind of dispatch we were resuming and the set of methods to call. We also had to be able to locate the arguments. Dynamic variables were involved, which cost a bit to look up too, and – despite being an implementation details – these also leaked out in introspection, which wasn’t ideal. The new dispatch mechanism makes this all rather more efficient: we can cache the calculated set of methods (or wrappers and multi candidates, depending on the context) and then walk through it, and there’s no dynamic variables involved (and thus no leakage of them). This sees the biggest speedup of the lot – and since we cannot yet inline away the callsame, it’s (for now) measuring the speedup one might expect on using this language feature. In the future, it’s destined to optimize away to an empty loop.
A module that makes use of callsame on a relatively hot path is OO::Monitors,, so I figured it would be interesting to see if there is a speedup there also.
use OO::Monitors;
monitor TestMonitor {
method m() { 1 }
}
my $mon = TestMonitor.new;
for ^1_000_000 {
$mon.m();
}
A monitor is a class that acquires a lock around each method call. The module provides a custom meta-class that adds a lock attribute to the class and then wraps each method such that it acquires the lock. There are certainly costly things in there besides the involvement of callsame, but the improvement to callsame is already enough to see a 3.3x speedup in this benchmark. Since OO::Monitors is used in quite a few applications and modules (for example, Cro uses it), this is welcome (and yes, a larger improvement will be possible here too).
I’ve seen some less impressive, but still welcome, improvements across a good number of other microbenchmarks. Even a basic multi dispatch on the + op:
my $i = 0;
for ^10_000_000 {
$i = $i + $_;
}
Comes out with a factor of 1.6x speedup, thanks primarily to us producing far tighter code with fewer guards. Previously, we ended up with duplicate guards in this seemingly straightforward case. The infix:<+> multi candidate would be specialized for the case of its first argument being an Int in a Scalar container and its second argument being an immutable Int. Since a Scalar is mutable, the specialization would need to read it and then guard the value read before proceeding, otherwise it may change, and we’d risk memory safety. When we wanted to inline this candidate, we’d also want to do a check that the candidate really applies, and so also would deference the Scalar and guard its content to do that. We can and do eliminate duplicate guards – but these guards are on two distinct reads of the value, so that wouldn’t help.
Since in the new dispatch mechanism we can rewrite arguments, we can now quite easily do caller-side removal of Scalar containers around values. So easily, in fact, that the change to do it took me just a couple of hours. This gives a lot of benefits. Since dispatch programs automatically eliminate duplicate reads and guards, the read and guard by the multi-dispatcher and the read in order to pass the decontainerized value are coalesced. This means less repeated work prior to specialization and JIT compilation, and also only a single read and guard in the specialized code after it. With the value to be passed already guarded, we can trivially select a candidate taking two bare Int values, which means there’s no further reads and guards needed in the callee either.
A less obvious benefit, but one that will become important with planned future work, is that this means Scalar containers escape to callees far less often. This creates further opportunities for escape analysis. While the MoarVM escape analyzer and scalar replacer is currently quite limited, I hope to return to working on it in the near future, and expect it will be able to give us even more value now than it would have been able to before.
The benchmarks shown earlier are mostly of the “how close are we to realizing that we’ve got an empty loop” nature, which is interesting for assessing how well the optimizer can “see through” dispatches. Here are a few further results on more “traditional” microbenchmarks:
The complex number benchmark is as follows:
my $total-re = 0e0;
for ^2_000_000 {
my $x = 5 + 2i;
my $y = 10 + 3i;
my $z = $x * $x + $y;
$total-re = $total-re + $z.re
}
say $total-re;
That is, just a bunch of operators (multi dispatch) and method calls, where we really do use the result. For now, we’re tied with Python and a little behind Ruby on this benchmark (and a surprising 48 times faster than the same thing done with Perl’s Math::Complex), but this is also a case that stands to see a huge benefit from escape analysis and scalar replacement in the future.
The hash read benchmark is:
my %h = a => 10, b => 12;
my $total = 0;
for ^10_000_000 {
$total = $total + %h<a> + %h<b>;
}
And the hash store one is:
my @keys = 'a'..'z';
for ^500_000 {
my %h;
for @keys {
%h{$_} = 42;
}
}
The improvements are nothing whatsoever to do with hashing itself, but instead look to be mostly thanks to much tighter code all around due to caller-side decontainerization. That can have a secondary effect of bringing things under the size limit for inlining, which is also a big help. Speedup factors of 2x and 1.85x are welcome, although we could really do with the same level of improvement again for me to be reasonably happy with our results.
The line-reading benchmark is:
my $fh = open "longfile";
my $chars = 0;
for $fh.lines { $chars = $chars + .chars };
$fh.close;
say $chars
Again, nothing specific to I/O got faster, but when dispatch – the glue that puts together all the pieces – gets a boost, it helps all over the place. (We are also decently competitive on this benchmark, although tend to be slower the moment the UTF-8 decoder can’t take it’s “NFG can’t possibly apply” fast path.)
I’ve also started looking at larger programs, and hearing results from others about theirs. It’s mostly encouraging:
Text::CSV benchmark test-t has seen roughly 20% improvement (thanks to lizmat for measuring)Cro::HTTP test application gets through about 10% more requests per secondCORE.setting, the standard library. However, a big pinch of salt is needed here: the compiler itself has changed in a number of places as part of the work, and there were a couple of things tweaked based on looking at profiles that aren’t really related to dispatch.One unpredicted (by me), but also welcome, improvement is that profiler output has become significantly smaller. Likely reasons for this include:
sink method when a value was in sink context. Now, if we see that the type simply inherits that method from Mu, we elide the call entirely (again, it would inline away, but a smaller call graph is a smaller profile).proto when the cache was missed, but would then not call an onlystar proto again when it got cache hits in the future. This meant the call tree under many multiple dispatches was duplicated in the profile. This wasn’t just a size issue; it was a bit annoying to have this effect show up in the profile reports too.To give an example of the difference, I took profiles from Agrammon to study why it might have become slower. The one from before the dispatcher work weighed in at 87MB; the one with the new dispatch mechanism is under 30MB. That means less memory used while profiling, less time to write the profile out to disk afterwards, and less time for tools to load the profiler output. So now it’s faster to work out how to make things faster.
I’m afraid so. Startup time has suffered. While the new dispatch mechanism is more powerful, pushes more complexity out of the VM into high level code, and is more conducive to reaching higher peak performance, it also has a higher warmup time. At the time of writing, the impact on startup time seems to be around 25%. I expect we can claw some of that back ahead of the October release.
Changes of this scale always come with an amount of risk. We’re merging this some weeks ahead of the next scheduled monthly release in order to have time for more testing, and to address any regressions that get reported. However, even before reaching the point of merging it, we have:
blin to run the tests of ecosystem modules. This is a standard step when preparing Rakudo releases, but in this case we’ve aimed it at the new-disp branches. This found a number of regressions caused by the switch to the new dispatch mechanism, which have been addressed.As I’ve alluded to in a number of places in this post, while there are improvements to be enjoyed right away, there are also new opportunities for further improvement. Some things that are on my mind include:
callsame one here is a perfect example! The point we do the resumption of a dispatch is inside callsame, so all the inline cache entries of resumptions throughout the program stack up in one place. What we’d like is to have them attached a level down the callstack instead. Otherwise, the level of callsame improvement seen in micro-benchmarks will not be enjoyed in larger applications. This applies in a number of other situations too.FALLBACK method could have its callsite easily rewritten to do that, opening the way to inlining.Ints (which needs a great deal of care in memory management, as they may box a big integer, not just a native integer).I would like to thank TPF and their donors for providing the funding that has made it possible for me to spend a good amount of my working time on this effort.
While I’m to blame for the overall design and much of the implementation of the new dispatch mechanism, plenty of work has also been put in by other MoarVM and Rakudo contributors – especially over the last few months as the final pieces fell into place, and we turned our attention to getting it production ready. I’m thankful to them not only for the code and debugging contributions, but also much support and encouragement along the way. It feels good to have this merged, and I look forward to building upon it in the months and years to come.
I recently wrote about the new MoarVM dispatch mechanism, and in that post noted that I still had a good bit of Raku’s multiple dispatch semantics left to implement in terms of it. Since then, I’ve made a decent amount of progress in that direction. This post contains an overview of the approach taken, and some very rough performance measurements.
Of all the kinds of dispatch we find in Raku, multiple dispatch is the most complex. Multiple dispatch allows us to write a set of candidates, which are then selected by the number of arguments:
multi ok($condition, $desc) {
say ($condition ?? 'ok' !! 'not ok') ~ " - $desc";
}
multi ok($condition) {
ok($condition, '');
}
Or the types of arguments:
multi to-json(Int $i) { ~$i }
multi to-json(Bool $b) { $b ?? 'true' !! 'false' }
And not just one argument, but potentially many:
multi truncate(Str $str, Int $chars) {
$str.chars < $chars ?? $str !! $str.substr(0, $chars) ~ '...'
}
multi truncate(Str $str, Str $after) {
with $str.index($after) -> $pos {
$str.substr(0, $pos) ~ '...'
}
else {
$str
}
}
We may write where clauses to differentiate candidates on properties that are not captured by nominal types:
multi fac($n where $n <= 1) { 1 }
multi fac($n) { $n * fac($n - 1) }
Every time we write a set of multi candidates like this, the compiler will automatically produce a proto routine. This is what is installed in the symbol table, and holds the candidate list. However, we can also write our own proto, and use the special term {*} to decide at which point we do the dispatch, if at all.
proto mean($collection) {
$collection.elems == 0 ?? Nil !! {*}
}
multi mean(@arr) {
@arr.sum / @arr.elems
}
multi mean(%hash) {
%hash.values.sum / %hash.elems
}
Candidates are ranked by narrowness (using topological sorting). If multiple candidates match, but they are equally narrow, then that’s an ambiguity error. Otherwise, we call narrowest one. The candidate we choose may then use callsame and friends to defer to the next narrowest candidate, which may do the same, until we reach the most general matching one.
Raku leans heavily on multiple dispatch. Most operators in Raku are compiled into calls to multiple dispatch subroutines. Even $a + $b will be a multiple dispatch. This means doing multiple dispatch efficiently is really important for performance. Given the riches of its semantics, this is potentially a bit concerning. However, there’s good news too.
The overwhelmingly common case is that we have:
where clausesprotocallsameThis isn’t to say the other cases are unimportant; they are really quite useful, and it’s desirable for them to perform well. However, it’s also desirable to make what savings we can in the common case. For example, we don’t want to eagerly calculate the full set of possible candidates for every single multiple dispatch, because the majority of the time only the first one matters. This is not just a time concern: recall that the new dispatch mechanism stores dispatch programs at each callsite, and if we store the list of all matching candidates at each of those, we’ll waste a lot of memory too.
The situation in Rakudo today is as follows:
proto holding a “dispatch cache”, a special-case mechanism implemented in the VM that uses a search tree, with one level per argument.proto, it’s not too bad either, though inlining isn’t going to be happening; it can still use the search tree, thoughwhere clauses, it’ll be slow, because the search tree only deals in finding one candidate per set of nominal types, and so we can’t use itcallsame; it’ll be slow tooEffectively, the situation today is that you simply don’t use where clauses in a multiple dispatch if its anywhere near a hot path (well, and if you know where the hot paths are, and know that this kind of dispatch is slow). Ditto for callsame, although that’s less commonly reached for. The question is, can we do better with the new dispatcher?
Let’s start out with seeing how the simplest cases are dealt with, and build from there. (This is actually what I did in terms of the implementation, but at the same time I had a rough idea where I was hoping to end up.)
Recall this pair of candidates:
multi truncate(Str $str, Int $chars) {
$str.chars < $chars ?? $str !! $str.substr(0, $chars) ~ '...'
}
multi truncate(Str $str, Str $after) {
with $str.index($after) -> $pos {
$str.substr(0, $pos) ~ '...'
}
else {
$str
}
}
We then have a call truncate($message, "\n"), where $message is a Str. Under the new dispatch mechanism, the call is made using the raku-call dispatcher, which identifies that this is a multiple dispatch, and thus delegates to raku-multi. (Multi-method dispatch ends up there too.)
The record phase of the dispatch – on the first time we reach this callsite – will proceed as follows:
raku-invoke dispatcher with the chosen candidate.When we reach the same callsite again, we can run the dispatch program, which quickly checks if the argument types match those we saw last time, and if they do, we know which candidate to invoke. These checks are very cheap – far cheaper than walking through all of the candidates and examining each of them for a match. The optimizer may later be able to prove that the checks will always come out true and eliminate them.
Thus the whole of the dispatch processes – at least for this simple case where we only have types and arity – can be “explained” to the virtual machine as “if the arguments have these exact types, invoke this routine”. It’s pretty much the same as we were doing for method dispatch, except there we only cared about the type of the first argument – the invocant – and the value of the method name. (Also recall from the previous post that if it’s a multi-method dispatch, then both method dispatch and multiple dispatch will guard the type of the first argument, but the duplication is eliminated, so only one check is done.)
Coming up with good abstractions is difficult, and therein lies much of the challenge of the new dispatch mechanism. Raku has quite a number of different dispatch-like things. However, encoding all of them directly in the virtual machine leads to high complexity, which makes building reliable optimizations (or even reliable unoptimized implementations!) challenging. Thus the aim is to work out a comparatively small set of primitives that allow for dispatches to be “explained” to the virtual machine in such a way that it can deliver decent performance.
It’s fairly clear that callsame is a kind of dispatch resumption, but what about the custom proto case and the where clause case? It turns out that these can both be neatly expressed in terms of dispatch resumption too (the where clause case needing one small addition at the virtual machine level, which in time is likely to be useful for other things too). Not only that, but encoding these features in terms of dispatch resumption is also quite direct, and thus should be efficient. Every trick we teach the specializer about doing better with dispatch resumptions can benefit all of the language features that are implemented using them, too.
Recall this example:
proto mean($collection) {
$collection.elems == 0 ?? Nil !! {*}
}
Here, we want to run the body of the proto, and then proceed to the chosen candidate at the point of the {*}. By contrast, when we don’t have a custom proto, we’d like to simply get on with calling the correct multi.
To achieve this, I first moved the multi candidate selection logic from the raku-multi dispatcher to the raku-multi-core dispatcher. The raku-multi dispatcher then checks if we have an “onlystar” proto (one that does not need us to run it). If so, it delegates immediately to raku-multi-core. If not, it saves the arguments to the dispatch as the resumption initialization state, and then calls the proto. The proto‘s {*} is compiled into a dispatch resumption. The resumption then delegates to raku-multi-core. Or, in code:
nqp::dispatch('boot-syscall', 'dispatcher-register', 'raku-multi',
# Initial dispatch, only setting up resumption if we need to invoke the
# proto.
-> $capture {
my $callee := nqp::captureposarg($capture, 0);
my int $onlystar := nqp::getattr_i($callee, Routine, '$!onlystar');
if $onlystar {
# Don't need to invoke the proto itself, so just get on with the
# candidate dispatch.
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'raku-multi-core', $capture);
}
else {
# Set resume init args and run the proto.
nqp::dispatch('boot-syscall', 'dispatcher-set-resume-init-args', $capture);
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'raku-invoke', $capture);
}
},
# Resumption means that we have reached the {*} in the proto and so now
# should go ahead and do the dispatch. Make sure we only do this if we
# are signalled to that it's a resume for an onlystar (resumption kind 5).
-> $capture {
my $track_kind := nqp::dispatch('boot-syscall', 'dispatcher-track-arg', $capture, 0);
nqp::dispatch('boot-syscall', 'dispatcher-guard-literal', $track_kind);
my int $kind := nqp::captureposarg_i($capture, 0);
if $kind == 5 {
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'raku-multi-core',
nqp::dispatch('boot-syscall', 'dispatcher-get-resume-init-args'));
}
elsif !nqp::dispatch('boot-syscall', 'dispatcher-next-resumption') {
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'boot-constant',
nqp::dispatch('boot-syscall', 'dispatcher-insert-arg-literal-obj',
$capture, 0, Nil));
}
});
Deferring to the next candidate (for example with callsame) and trying the next candidate because a where clause failed look very similar: both involve walking through a list of possible candidates. There’s some details, but they have a great deal in common, and it’d be nice if that could be reflected in how multiple dispatch is implemented using the new dispatcher.
Before that, a slightly terrible detail about how things work in Rakudo today when we have where clauses. First, the dispatcher does a “trial bind”, where it asks the question: would this signature bind? To do this, it has to evaluate all of the where clauses. Worse, it has to use the slow-path signature binder too, which interprets the signature, even though we can in many cases compile it. If the candidate matches, great, we select it, and then invoke it…which runs the where clauses a second time, as part of the compiled signature binding code. There is nothing efficient about this at all, except for it being by far more efficient on developer time, which is why it happened that way.
Anyway, it goes without saying that I’m rather keen to avoid this duplicate work and the slow-path binder where possible as I re-implement this using the new dispatcher. And, happily, a small addition provides a solution. There is an op assertparamcheck, which any kind of parameter checking compiles into (be it type checking, where clause checking, etc.) This triggers a call to a function that gets the arguments, the thing we were trying to call, and can then pick through them to produce an error message. The trick is to provide a way to invoke a routine such that a bind failure, instead of calling the error reporting function, will leave the routine and then do a dispatch resumption! This means we can turn failure to pass where clause checks into a dispatch resumption, which will then walk to the next candidate and try it instead.
This gets us most of the way to a solution, but there’s still the question of being memory and time efficient in the common case, where there is no resumption and no where clauses. I coined the term “trivial multiple dispatch” for this situation, which makes the other situation “non-trivial”. In fact, I even made a dispatcher called raku-multi-non-trivial! There are two ways we can end up there.
where clauses. As soon as we see this is the case, we go ahead and produce a full list of possible candidates that could match. This is a linked list (see my previous post for why).callsame happens, we end up in the trivial dispatch resumption handler, which – since this situation is now non-trivial – builds the full candidate list, snips the first item off it (because we already ran that), and delegates to raku-multi-non-trivial.Lost in this description is another significant improvement: today, when there are where clauses, we entirely lose the ability to use the MoarVM multiple dispatch cache, but under the new dispatcher, we store a type-filtered list of candidates at the callsite, and then cheap type guards are used to check it is valid to use.
I did a few benchmarks to see how the new dispatch mechanism did with a couple of situations known to be sub-optimal in Rakudo today. These numbers do not reflect what is possible, because at the moment the specializer does not have much of an understanding of the new dispatcher. Rather, they reflect the minimal improvement we can expect.
Consider this benchmark using a multi with a where clause to recursively implement factorial.
multi fac($n where $n <= 1) { 1 }
multi fac($n) { $n * fac($n - 1) }
for ^100_000 {
fac(10)
}
say now - INIT now;
This needs some tweaks (and to be run under an environment variable) to use the new dispatcher; these are temporary, until such a time I switch Rakudo over to using the new dispatcher by default:
use nqp;
multi fac($n where $n <= 1) { 1 }
multi fac($n) { $n * nqp::dispatch('raku-call', &fac, $n - 1) }
for ^100_000 {
nqp::dispatch('raku-call', &fac, 10);
}
say now - INIT now;
On my machine, the first runs in 4.86s, the second in 1.34s. Thus under the new dispatcher this runs in little over a quarter of the time it used to – a quite significant improvement already.
A case involving callsame is also interesting to consider. Here it is without using the new dispatcher:
multi fallback(Any $x) { "a$x" }
multi fallback(Numeric $x) { "n" ~ callsame }
multi fallback(Real $x) { "r" ~ callsame }
multi fallback(Int $x) { "i" ~ callsame }
for ^1_000_000 {
fallback(4+2i);
fallback(4.2);
fallback(42);
}
say now - INIT now;
And with the temporary tweaks to use the new dispatcher:
use nqp;
multi fallback(Any $x) { "a$x" }
multi fallback(Numeric $x) { "n" ~ new-disp-callsame }
multi fallback(Real $x) { "r" ~ new-disp-callsame }
multi fallback(Int $x) { "i" ~ new-disp-callsame }
for ^1_000_000 {
nqp::dispatch('raku-call', &fallback, 4+2i);
nqp::dispatch('raku-call', &fallback, 4.2);
nqp::dispatch('raku-call', &fallback, 42);
}
say now - INIT now;
On my machine, the first runs in 31.3s, the second in 11.5s, meaning that with the new dispatcher we manage it in a little over a third of the time that current Rakudo does.
These are both quite encouraging, but as previously mentioned, a majority of multiple dispatches are of the trivial kind, not using these features. If I make the most common case worse on the way to making other things better, that would be bad. It’s not yet possible to make a fair comparison of this: trivial multiple dispatches already receive a lot of attention in the specializer, and it doesn’t yet optimize code using the new dispatcher well. Of note, in an example like this:
multi m(Int) { }
multi m(Str) { }
for ^1_000_000 {
m(1);
m("x");
}
say now - INIT now;
Inlining and other optimizations will turn this into an empty loop, which is hard to beat. There is one thing we can already do, though: run it with the specializer disabled. The new dispatcher version looks like this:
use nqp;
multi m(Int) { }
multi m(Str) { }
for ^1_000_000 {
nqp::dispatch('raku-call', &m, 1);
nqp::dispatch('raku-call', &m, "x");
}
say now - INIT now;
The results are 0.463s and 0.332s respectively. Thus, the baseline execution time – before the specializer does its magic – is less using the new general dispatch mechanism than it is using the special-case multiple dispatch cache that we currently use. I wasn’t sure what to expect here before I did the measurement. Given we’re going from a specialized mechanism that has been profiled and tweaked to a new general mechanism that hasn’t received such attention, I was quite ready to be doing a little bit worse initially, and would have been happy with parity. Running in 70% of the time was a bigger improvement than I expected at this point.
I expect that once the specializer understands the new dispatch mechanism better, it will be able to also turn the above into an empty loop – however, since more iterations can be done per-optimization, this should still show up as a win for the new dispatcher.
With one relatively small addition, the new dispatch mechanism is already handling most of the Raku multiple dispatch semantics. Furthermore, even without the specializer and JIT really being able to make a good job of it, some microbenchmarks already show a factor of 3x-4x improvement. That’s a pretty good starting point.
There’s still a good bit to do before we ship a Rakudo release using the new dispatcher. However, multiple dispatch was the biggest remaining threat to the design: it’s rather more involved than other kinds of dispatch, and it was quite possible that an unexpected shortcoming could trigger another round of design work, or reveal that the general mechanism was going to struggle to perform compared to the more specialized one in the baseline unoptimized, case. So far, there’s no indication of either of these, and I’m cautiously optimistic that the overall design is about right.
My goodness, it appears I’m writing my first Raku internals blog post in over two years. Of course, two years ago it wasn’t even called Raku. Anyway, without further ado, let’s get on with this shared brainache.
I use “dispatch” to mean a process by which we take a set of arguments and end up with some action being taken based upon them. Some familiar examples include:
$basket.add($product, $quantity). We might traditionally call just $product and $qauntity the arguments, but for my purposes, all of $basket, the method name 'add', $product, and $quantity` are arguments to the dispatch: they are the things we need in order to make a decision about what we’re going to do.uc($youtube-comment). Since Raku sub calls are lexically resolved, in this case the arguments to the dispatch are &uc (the result of looking up the subroutine) and $youtube-comment.At first glance, perhaps the first two seem fairly easy and the third a bit more of a handful – which is sort of true. However, Raku has a number of other features that make dispatch rather more, well, interesting. For example:
wrap allows us to wrap any Routine (sub or method); the wrapper can then choose to defer to the original routine, either with the original arguments or with new argumentsproto routine that gets to choose when – or even if – the call to the appropriate candidate is madecallsame in order to defer to the next candidate in the dispatch. But what does that mean? If we’re in a multiple dispatch, it would mean the next most applicable candidate, if any. If we’re in a method dispatch then it means a method from a base class. (The same thing is used to implement going to the next wrapper or, eventually, to the originally wrapped routine too). And these can be combined: we can wrap a multi method, meaning we can have 3 levels of things that all potentially contribute the next thing to call!Thanks to this, dispatch – at least in Raku – is not always something we do and produce an outcome, but rather a process that we may be asked to continue with multiple times!
Finally, while the examples I’ve written above can all quite clearly be seen as examples of dispatch, a number of other common constructs in Raku can be expressed as a kind of dispatch too. Assignment is one example: the semantics of it depend on the target of the assignment and the value being assigned, and thus we need to pick the correct semantics. Coercion is another example, and return value type-checking yet another.
Dispatch is everywhere in our programs, quietly tieing together the code that wants stuff done with the code that does stuff. Its ubiquity means it plays a significant role in program performance. In the best case, we can reduce the cost to zero. In the worst case, the cost of the dispatch is high enough to exceed that of the work done as a result of the dispatch.
To a first approximation, when the runtime “understands” the dispatch the performance tends to be at least somewhat decent, but when it doesn’t there’s a high chance of it being awful. Dispatches tend to involve an amount of work that can be cached, often with some cheap guards to verify the validity of the cached outcome. For example, in a method dispatch, naively we need to walk a linearization of the inheritance graph and ask each class we encounter along the way if it has a method of the specified name. Clearly, this is not going to be terribly fast if we do it on every method call. However, a particular method name on a particular type (identified precisely, without regard to subclassing) will resolve to the same method each time. Thus, we can cache the outcome of the lookup, and use it whenever the type of the invocant matches that used to produce the cached result.
When one starts building a runtime aimed at a particular language, and has to do it on a pretty tight budget, the most obvious way to get somewhat tolerable performance is to bake various hot-path language semantics into the runtime. This is exactly how MoarVM started out. Thus, if we look at MoarVM as it stood several years ago, we find things like:
where comes at a very high cost)Sub object has a private attribute in it that holds the low-level code handle identifying the bytecode to run)These are all still there today, however are also all on the way out. What’s most telling about this list is what isn’t included. Things like:
$obj.SomeType::method-name())A few years back I started to partially address this, with the introduction of a mechanism I called “specializer plugins”. But first, what is the specializer?
When MoarVM started out, it was a relatively straightforward interpreter of bytecode. It only had to be fast enough to beat the Parrot VM in order to get a decent amount of usage, which I saw as important to have before going on to implement some more interesting optimizations (back then we didn’t have the kind of pre-release automated testing infrastructure we have today, and so depended much more on feedback from early adopters). Anyway, soon after being able to run pretty much as much of the Raku language as any other backend, I started on the dynamic optimizer. It gathered type statistics as the program was interpreted, identified hot code, put it into SSA form, used the type statistics to insert guards, used those together with static properties of the bytecode to analyze and optimize, and produced specialized bytecode for the function in question. This bytecode could elide type checks and various lookups, as well as using a range of internal ops that make all kinds of assumptions, which were safe because of the program properties that were proved by the optimizer. This is called specialized bytecode because it has had a lot of its genericity – which would allow it to work correctly on all types of value that we might encounter – removed, in favor of working in a particular special case that actually occurs at runtime. (Code, especially in more dynamic languages, is generally far more generic in theory than it ever turns out to be in practice.)
This component – the specializer, known internally as “spesh” – delivered a significant further improvement in the performance of Raku programs, and with time its sophistication has grown, taking in optimizations such as inlining and escape analysis with scalar replacement. These aren’t easy things to build – but once a runtime has them, they create design possibilities that didn’t previously exist, and make decisions made in their absence look sub-optimal.
Of note, those special-cased language-specific mechanisms, baked into the runtime to get some speed in the early days, instead become something of a liability and a bottleneck. They have complex semantics, which means they are either opaque to the optimizer (so it can’t reason about them, meaning optimization is inhibited) or they need special casing in the optimizer (a liability).
So, back to specializer plugins. I reached a point where I wanted to take on the performance of things like $obj.?meth (the “call me maybe” dispatch), $obj.SomeType::meth() (dispatch qualified with a class to start looking in), and private method calls in roles (which can’t be resolved statically). At the same time, I was getting ready to implement some amount of escape analysis, but realized that it was going to be of very limited utility because assignment had also been special-cased in the VM, with a chunk of opaque C code doing the hot path stuff.
But why did we have the C code doing that hot-path stuff? Well, because it’d be too espensive to have every assignment call a VM-level function that does a bunch of checks and logic. Why is that costly? Because of function call overhead and the costs of interpretation. This was all true once upon a time. But, some years of development later:
I solved the assignment problem and the dispatch problems mentioned above with the introduction of a single new mechanism: specializer plugins. They work as follows:
The vast majority of cases are monomorphic, meaning that only one set of guards are produced and they always succeed thereafter. The specializer can thus compile those guards into the specialized bytecode and then assume the given target invocant is what will be invoked. (Further, duplicate guards can be eliminated, so the guards a particular plugin introduces may reduce to zero.)
Specializer plugins felt pretty great. One new mechanism solved multiple optimization headaches.
The new MoarVM dispatch mechanism is the answer to a fairly simple question: what if we get rid of all the dispatch-related special-case mechanisms in favor of something a bit like specializer plugins? The resulting mechanism would need to be a more powerful than specializer plugins. Further, I could learn from some of the shortcomings of specializer plugins. Thus, while they will go away after a relatively short lifetime, I think it’s fair to say that I would not have been in a place to design the new MoarVM dispatch mechanism without that experience.
All the method caching. All the multi dispatch caching. All the specializer plugins. All the invocation protocol stuff for unwrapping the bytecode handle in a code object. It’s all going away, in favor of a single new dispatch instruction. Its name is, boringly enough, dispatch. It looks like this:
dispatch_o result, 'dispatcher-name', callsite, arg0, arg1, ..., argN
Which means:
dispatcher-nameresult(Aside: this implies a new calling convention, whereby we no longer copy the arguments into an argument buffer, but instead pass the base of the register set and a pointer into the bytecode where the register argument map is found, and then do a lookup registers[map[argument_index]] to get the value for an argument. That alone is a saving when we interpret, because we no longer need a loop around the interpreter per argument.)
Some of the arguments might be things we’d traditionally call arguments. Some are aimed at the dispatch process itself. It doesn’t really matter – but it is more optimal if we arrange to put arguments that are only for the dispatch first (for example, the method name), and those for the target of the dispatch afterwards (for example, the method parameters).
The new bootstrap mechanism provides a small number of built-in dispatchers, whose names start with “boot-“. They are:
boot-value– take the first argument and use it as the result (the identity function, except discarding any further arguments)boot-constant – take the first argument and produce it as the result, but also treat it as a constant value that will always be produced (thus meaning the optimizer could consider any pure code used to calculate the value as dead)boot-code – take the first argument, which must be a VM bytecode handle, and run that bytecode, passing the rest of the arguments as its parameters; evaluate to the return value of the bytecodeboot-syscall – treat the first argument as the name of a VM-provided built-in operation, and call it, providing the remaining arguments as its parametersboot-resume – resume the topmost ongoing dispatchThat’s pretty much it. Every dispatcher we build, to teach the runtime about some other kind of dispatch behavior, eventually terminates in one of these.
Teaching MoarVM about different kinds of dispatch is done using nothing less than the dispatch mechanism itself! For the most part, boot-syscall is used in order to register a dispatcher, set up the guards, and provide the result that goes with them.
Here is a minimal example, taken from the dispatcher test suite, showing how a dispatcher that provides the identity function would look:
nqp::dispatch('boot-syscall', 'dispatcher-register', 'identity', -> $capture {
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'boot-value', $capture);
});
sub identity($x) {
nqp::dispatch('identity', $x)
}
ok(identity(42) == 42, 'Can define identity dispatch (1)');
ok(identity('foo') eq 'foo', 'Can define identity dispatch (2)');
In the first statement, we call the dispatcher-register MoarVM system call, passing a name for the dispatcher along with a closure, which will be called each time we need to handle the dispatch (which I tend to refer to as the “dispatch callback”). It receives a single argument, which is a capture of arguments (not actually a Raku-level Capture, but the idea – an object containing a set of call arguments – is the same).
Every user-defined dispatcher should eventually use dispatcher-delegate in order to identify another dispatcher to pass control along to. In this case, it delegates immediately to boot-value – meaning it really is nothing except a wrapper around the boot-value built-in dispatcher.
The sub identity contains a single static occurrence of the dispatch op. Given we call the sub twice, we will encounter this op twice at runtime, but the two times are very different.
The first time is the “record” phase. The arguments are formed into a capture and the callback runs, which in turn passes it along to the boot-value dispatcher, which produces the result. This results in an extremely simple dispatch program, which says that the result should be the first argument in the capture. Since there’s no guards, this will always be a valid result.
The second time we encounter the dispatch op, it already has a dispatch program recorded there, so we are in run mode. Turning on a debugging mode in the MoarVM source, we can see the dispatch program that results looks like this:
Dispatch program (1 temporaries)
Ops:
Load argument 0 into temporary 0
Set result object value from temporary 0
That is, it reads argument 0 into a temporary location and then sets that as the result of the dispatch. Notice how there is no mention of the fact that we went through an extra layer of dispatch; those have zero cost in the resulting dispatch program.
Argument captures are immutable. Various VM syscalls exist to transform them into new argument captures with some tweak, for example dropping or inserting arguments. Here’s a further example from the test suite:
nqp::dispatch('boot-syscall', 'dispatcher-register', 'drop-first', -> $capture {
my $capture-derived := nqp::dispatch('boot-syscall', 'dispatcher-drop-arg', $capture, 0);
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'boot-value', $capture-derived);
});
ok(nqp::dispatch('drop-first', 'first', 'second') eq 'second',
'dispatcher-drop-arg works');
This drops the first argument before passing the capture on to the boot-value dispatcher – meaning that it will return the second argument. Glance back at the previous dispatch program for the identity function. Can you guess how this one will look?
Well, here it is:
Dispatch program (1 temporaries)
Ops:
Load argument 1 into temporary 0
Set result string value from temporary 0
Again, while in the record phase of such a dispatcher we really do create capture objects and make a dispatcher delegation, the resulting dispatch program is far simpler.
Here’s a slightly more involved example:
my $target := -> $x { $x + 1 }
nqp::dispatch('boot-syscall', 'dispatcher-register', 'call-on-target', -> $capture {
my $capture-derived := nqp::dispatch('boot-syscall',
'dispatcher-insert-arg-literal-obj', $capture, 0, $target);
nqp::dispatch('boot-syscall', 'dispatcher-delegate',
'boot-code-constant', $capture-derived);
});
sub cot() { nqp::dispatch('call-on-target', 49) }
ok(cot() == 50,
'dispatcher-insert-arg-literal-obj works at start of capture');
ok(cot() == 50,
'dispatcher-insert-arg-literal-obj works at start of capture after link too');
Here, we have a closure stored in a variable $target. We insert it as the first argument of the capture, and then delegate to boot-code-constant, which will invoke that code object and pass the other dispatch arguments to it. Once again, at the record phase, we really do something like:
And the resulting dispatch program? It’s this:
Dispatch program (1 temporaries)
Ops:
Load collectable constant at index 0 into temporary 0
Skip first 0 args of incoming capture; callsite from 0
Invoke MVMCode in temporary 0
That is, load the constant bytecode handle that we’re going to invoke, set up the args (which are in this case equal to those of the incoming capture), and then invoke the bytecode with those arguments. The argument shuffling is, once again, gone. In general, whenever the arguments we do an eventual bytecode invocation with are a tail of the initial dispatch arguments, the arguments transform becomes no more than a pointer addition.
All of the dispatch programs seen so far have been unconditional: once recorded at a given callsite, they shall always be used. The big missing piece to make such a mechanism have practical utility is guards. Guards assert properties such as the type of an argument or if the argument is definite (Int:D) or not (Int:U).
Here’s a somewhat longer test case, with some explanations placed throughout it.
# A couple of classes for test purposes
my class C1 { }
my class C2 { }
# A counter used to make sure we're only invokving the dispatch callback as
# many times as we expect.
my $count := 0;
# A type-name dispatcher that maps a type into a constant string value that
# is its name. This isn't terribly useful, but it is a decent small example.
nqp::dispatch('boot-syscall', 'dispatcher-register', 'type-name', -> $capture {
# Bump the counter, just for testing purposes.
$count++;
# Obtain the value of the argument from the capture (using an existing
# MoarVM op, though in the future this may go away in place of a syscall)
# and then obtain the string typename also.
my $arg-val := nqp::captureposarg($capture, 0);
my str $name := $arg-val.HOW.name($arg-val);
# This outcome is only going to be valid for a particular type. We track
# the argument (which gives us an object back that we can use to guard
# it) and then add the type guard.
my $arg := nqp::dispatch('boot-syscall', 'dispatcher-track-arg', $capture, 0);
nqp::dispatch('boot-syscall', 'dispatcher-guard-type', $arg);
# Finally, insert the type name at the start of the capture and then
# delegate to the boot-constant dispatcher.
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'boot-constant',
nqp::dispatch('boot-syscall', 'dispatcher-insert-arg-literal-str',
$capture, 0, $name));
});
# A use of the dispatch for the tests. Put into a sub so there's a single
# static dispatch op, which all dispatch programs will hang off.
sub type-name($obj) {
nqp::dispatch('type-name', $obj)
}
# Check with the first type, making sure the guard matches when it should
# (although this test would pass if the guard were ignored too).
ok(type-name(C1) eq 'C1', 'Dispatcher setting guard works');
ok($count == 1, 'Dispatch callback ran once');
ok(type-name(C1) eq 'C1', 'Can use it another time with the same type');
ok($count == 1, 'Dispatch callback was not run again');
# Test it with a second type, both record and run modes. This ensures the
# guard really is being checked.
ok(type-name(C2) eq 'C2', 'Can handle polymorphic sites when guard fails');
ok($count == 2, 'Dispatch callback ran a second time for new type');
ok(type-name(C2) eq 'C2', 'Second call with new type works');
# Check that we can use it with the original type too, and it has stacked
# the dispatch programs up at the same callsite.
ok(type-name(C1) eq 'C1', 'Call with original type still works');
ok($count == 2, 'Dispatch callback only ran a total of 2 times');
This time two dispatch programs get produced, one for C1:
Dispatch program (1 temporaries)
Ops:
Guard arg 0 (type=C1)
Load collectable constant at index 1 into temporary 0
Set result string value from temporary 0
And another for C2:
Dispatch program (1 temporaries)
Ops:
Guard arg 0 (type=C2)
Load collectable constant at index 1 into temporary 0
Set result string value from temporary 0
Once again, no leftovers from capture manipulation, tracking, or dispatcher delegation; the dispatch program does a type guard against an argument, then produces the result string. The whole call to $arg-val.HOW.name($arg-val) is elided, the dispatcher we wrote encoding the knowledge – in a way that the VM can understand – that a type’s name can be considered immutable.
This example is a bit contrived, but now consider that we instead look up a method and guard on the invocant type: that’s a method cache! Guard the types of more of the arguments, and we have a multi cache! Do both, and we have a multi-method cache.
The latter is interesting in so far as both the method dispatch and the multi dispatch want to guard on the invocant. In fact, in MoarVM today there will be two such type tests until we get to the point where the specializer does its work and eliminates these duplicated guards. However, the new dispatcher does not treat the dispatcher-guard-type as a kind of imperative operation that writes a guard into the resultant dispatch program. Instead, it declares that the argument in question must be guarded. If some other dispatcher already did that, it’s idempotent. The guards are emitted once all dispatch programs we delegate through, on the path to a final outcome, have had their say.
Fun aside: those being especially attentive will have noticed that the dispatch mechanism is used as part of implementing new dispatchers too, and indeed, this ultimately will mean that the specializer can specialize the dispatchers and have them JIT-compiled into something more efficient too. After all, from the perspective of MoarVM, it’s all just bytecode to run; it’s just that some of it is bytecode that tells the VM how to execute Raku programs more efficiently!
A resumable dispatcher needs to do two things:
When a resumption happens, the resume callback will be called, with any arguments for the resumption. It can also obtain the resume initialization state that was set in the dispatch callback. The resume initialization state contains the things needed in order to continue with the dispatch the first time it is resumed. We’ll take a look at how this works for method dispatch to see a concrete example. I’ll also, at this point, switch to looking at the real Rakudo dispatchers, rather than simplified test cases.
The Rakudo dispatchers take advantage of delegation, duplicate guards, and capture manipulations all having no runtime cost in the resulting dispatch program to, in my mind at least, quite nicely factor what is a somewhat involved dispatch process. There are multiple entry points to method dispatch: the normal boring $obj.meth(), the qualified $obj.Type::meth(), and the call me maybe $obj.?meth(). These have common resumption semantics – or at least, they can be made to provided we always carry a starting type in the resume initialization state, which is the type of the object that we do the method dispatch on.
Here is the entry point to dispatch for a normal method dispatch, with the boring details of reporting missing method errors stripped out.
# A standard method call of the form $obj.meth($arg); also used for the
# indirect form $obj."$name"($arg). It receives the decontainerized invocant,
# the method name, and the the args (starting with the invocant including any
# container).
nqp::dispatch('boot-syscall', 'dispatcher-register', 'raku-meth-call', -> $capture {
# Try to resolve the method call using the MOP.
my $obj := nqp::captureposarg($capture, 0);
my str $name := nqp::captureposarg_s($capture, 1);
my $meth := $obj.HOW.find_method($obj, $name);
# Report an error if there is no such method.
unless nqp::isconcrete($meth) {
!!! 'Error reporting logic elided for brevity';
}
# Establish a guard on the invocant type and method name (however the name
# may well be a literal, in which case this is free).
nqp::dispatch('boot-syscall', 'dispatcher-guard-type',
nqp::dispatch('boot-syscall', 'dispatcher-track-arg', $capture, 0));
nqp::dispatch('boot-syscall', 'dispatcher-guard-literal',
nqp::dispatch('boot-syscall', 'dispatcher-track-arg', $capture, 1));
# Add the resolved method and delegate to the resolved method dispatcher.
my $capture-delegate := nqp::dispatch('boot-syscall',
'dispatcher-insert-arg-literal-obj', $capture, 0, $meth);
nqp::dispatch('boot-syscall', 'dispatcher-delegate',
'raku-meth-call-resolved', $capture-delegate);
});
Now for the resolved method dispatcher, which is where the resumption is handled. First, let’s look at the normal dispatch callback (the resumption callback is included but empty; I’ll show it a little later).
# Resolved method call dispatcher. This is used to call a method, once we have
# already resolved it to a callee. Its first arg is the callee, the second and
# third are the type and name (used in deferral), and the rest are the args to
# the method.
nqp::dispatch('boot-syscall', 'dispatcher-register', 'raku-meth-call-resolved',
# Initial dispatch
-> $capture {
# Save dispatch state for resumption. We don't need the method that will
# be called now, so drop it.
my $resume-capture := nqp::dispatch('boot-syscall', 'dispatcher-drop-arg',
$capture, 0);
nqp::dispatch('boot-syscall', 'dispatcher-set-resume-init-args', $resume-capture);
# Drop the dispatch start type and name, and delegate to multi-dispatch or
# just invoke if it's single dispatch.
my $delegate_capture := nqp::dispatch('boot-syscall', 'dispatcher-drop-arg',
nqp::dispatch('boot-syscall', 'dispatcher-drop-arg', $capture, 1), 1);
my $method := nqp::captureposarg($delegate_capture, 0);
if nqp::istype($method, Routine) && $method.is_dispatcher {
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'raku-multi', $delegate_capture);
}
else {
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'raku-invoke', $delegate_capture);
}
},
# Resumption
-> $capture {
... 'Will be shown later';
});
There’s an arguable cheat in raku-meth-call: it doesn’t actually insert the type object of the invocant in place of the invocant. It turns out that it doesn’t really matter. Otherwise, I think the comments (which are to be found in the real implementation also) tell the story pretty well.
One important point that may not be clear – but follows a repeating theme – is that the setting of the resume initialization state is also more of a declarative rather than an imperative thing: there isn’t a runtime cost at the time of the dispatch, but rather we keep enough information around in order to be able to reconstruct the resume initialization state at the point we need it. (In fact, when we are in the run phase of a resume, we don’t even have to reconstruct it in the sense of creating a capture object.)
Now for the resumption. I’m going to present a heavily stripped down version that only deals with the callsame semantics (the full thing has to deal with such delights as lastcall and nextcallee too). The resume initialization state exists to seed the resumption process. Once we know we actually do have to deal with resumption, we can do things like calculating the full list of methods in the inheritance graph that we want to walk through. Each resumable dispatcher gets a single storage slot on the call stack that it can use for its state. It can initialize this in the first step of resumption, and then update it as we go. Or more precisely, it can set up a dispatch program that will do this when run.
A linked list turns out to be a very convenient data structure for the chain of candidates we will walk through. We can work our way through a linked list by keeping track of the current node, meaning that there need only be a single thing that mutates, which is the current state of the dispatch. The dispatch program mechanism also provides a way to read an attribute from an object, and that is enough to express traversing a linked list into the dispatch program. This also means zero allocations.
So, without further ado, here is the linked list (rather less pretty in NQP, the restricted Raku subset, than it would be in full Raku):
# A linked list is used to model the state of a dispatch that is deferring
# through a set of methods, multi candidates, or wrappers. The Exhausted class
# is used as a sentinel for the end of the chain. The current state of the
# dispatch points into the linked list at the appropriate point; the chain
# itself is immutable, and shared over (runtime) dispatches.
my class DeferralChain {
has $!code;
has $!next;
method new($code, $next) {
my $obj := nqp::create(self);
nqp::bindattr($obj, DeferralChain, '$!code', $code);
nqp::bindattr($obj, DeferralChain, '$!next', $next);
$obj
}
method code() { $!code }
method next() { $!next }
};
my class Exhausted {};
And finally, the resumption handling.
nqp::dispatch('boot-syscall', 'dispatcher-register', 'raku-meth-call-resolved',
# Initial dispatch
-> $capture {
... 'Presented earlier;
},
# Resumption. The resume init capture's first two arguments are the type
# that we initially did a method dispatch against and the method name
# respectively.
-> $capture {
# Work out the next method to call, if any. This depends on if we have
# an existing dispatch state (that is, a method deferral is already in
# progress).
my $init := nqp::dispatch('boot-syscall', 'dispatcher-get-resume-init-args');
my $state := nqp::dispatch('boot-syscall', 'dispatcher-get-resume-state');
my $next_method;
if nqp::isnull($state) {
# No state, so just starting the resumption. Guard on the
# invocant type and name.
my $track_start_type := nqp::dispatch('boot-syscall', 'dispatcher-track-arg', $init, 0);
nqp::dispatch('boot-syscall', 'dispatcher-guard-type', $track_start_type);
my $track_name := nqp::dispatch('boot-syscall', 'dispatcher-track-arg', $init, 1);
nqp::dispatch('boot-syscall', 'dispatcher-guard-literal', $track_name);
# Also guard on there being no dispatch state.
my $track_state := nqp::dispatch('boot-syscall', 'dispatcher-track-resume-state');
nqp::dispatch('boot-syscall', 'dispatcher-guard-literal', $track_state);
# Build up the list of methods to defer through.
my $start_type := nqp::captureposarg($init, 0);
my str $name := nqp::captureposarg_s($init, 1);
my @mro := nqp::can($start_type.HOW, 'mro_unhidden')
?? $start_type.HOW.mro_unhidden($start_type)
!! $start_type.HOW.mro($start_type);
my @methods;
for @mro {
my %mt := nqp::hllize($_.HOW.method_table($_));
if nqp::existskey(%mt, $name) {
@methods.push(%mt{$name});
}
}
# If there's nothing to defer to, we'll evaluate to Nil (just don't set
# the next method, and it happens below).
if nqp::elems(@methods) >= 2 {
# We can defer. Populate next method.
@methods.shift; # Discard the first one, which we initially called
$next_method := @methods.shift; # The immediate next one
# Build chain of further methods and set it as the state.
my $chain := Exhausted;
while @methods {
$chain := DeferralChain.new(@methods.pop, $chain);
}
nqp::dispatch('boot-syscall', 'dispatcher-set-resume-state-literal', $chain);
}
}
elsif !nqp::istype($state, Exhausted) {
# Already working through a chain of method deferrals. Obtain
# the tracking object for the dispatch state, and guard against
# the next code object to run.
my $track_state := nqp::dispatch('boot-syscall', 'dispatcher-track-resume-state');
my $track_method := nqp::dispatch('boot-syscall', 'dispatcher-track-attr',
$track_state, DeferralChain, '$!code');
nqp::dispatch('boot-syscall', 'dispatcher-guard-literal', $track_method);
# Update dispatch state to point to next method.
my $track_next := nqp::dispatch('boot-syscall', 'dispatcher-track-attr',
$track_state, DeferralChain, '$!next');
nqp::dispatch('boot-syscall', 'dispatcher-set-resume-state', $track_next);
# Set next method, which we shall defer to.
$next_method := $state.code;
}
else {
# Dispatch already exhausted; guard on that and fall through to returning
# Nil.
my $track_state := nqp::dispatch('boot-syscall', 'dispatcher-track-resume-state');
nqp::dispatch('boot-syscall', 'dispatcher-guard-literal', $track_state);
}
# If we found a next method...
if nqp::isconcrete($next_method) {
# Call with same (that is, original) arguments. Invoke with those.
# We drop the first two arguments (which are only there for the
# resumption), add the code object to invoke, and then leave it
# to the invoke or multi dispatcher.
my $just_args := nqp::dispatch('boot-syscall', 'dispatcher-drop-arg',
nqp::dispatch('boot-syscall', 'dispatcher-drop-arg', $init, 0),
0);
my $delegate_capture := nqp::dispatch('boot-syscall',
'dispatcher-insert-arg-literal-obj', $just_args, 0, $next_method);
if nqp::istype($next_method, Routine) && $next_method.is_dispatcher {
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'raku-multi',
$delegate_capture);
}
else {
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'raku-invoke',
$delegate_capture);
}
}
else {
# No method, so evaluate to Nil (boot-constant disregards all but
# the first argument).
nqp::dispatch('boot-syscall', 'dispatcher-delegate', 'boot-constant',
nqp::dispatch('boot-syscall', 'dispatcher-insert-arg-literal-obj',
$capture, 0, Nil));
}
});
That’s quite a bit to take in, and quite a bit of code. Remember, however, that this is only run for the record phase of a dispatch resumption. It also produces a dispatch program at the callsite of the callsame, with the usual guards and outcome. Implicit guards are created for the dispatcher that we are resuming at that point. In the most common case this will end up monomorphic or bimorphic, although situations involving nestings of multiple dispatch or method dispatch could produce a more morphic callsite.
The design I’ve picked forces resume callbacks to deal with two situations: the first resumption and the latter resumptions. This is not ideal in a couple of ways:
Only the second of these really matters. The reason for the non-uniformity is to make sure that the overwhelming majority of calls, which never lead to a dispatch resumption, incur no per-dispatch cost for a feature that they never end up using. If the result is a little more cost for those using the feature, so be it. In fact, early benchmarking shows callsame with wrap and method calls seems to be up to 10 times faster using the new dispatcher than in current Rakudo, and that’s before the specializer understands enough about it to improve things further!
Everything I’ve discussed above is implemented, except that I may have given the impression somewhere that multiple dispatch is fully implemented using the new dispatcher, and that is not the case yet (no handling of where clauses and no dispatch resumption support).
Getting the missing bits of multiple dispatch fully implemented is the obvious next step. The other missing semantic piece is support for callwith and nextwith, where we wish to change the arguments that are being used when moving to the next candidate. A few other minor bits aside, that in theory will get all of the Raku dispatch semantics at least supported.
Currently, all standard method calls ($obj.meth()) and other calls (foo() and $foo()) go via the existing dispatch mechanism, not the new dispatcher. Those will need to be migrated to use the new dispatcher also, and any bugs that are uncovered will need fixing. That will get things to the point where the new dispatcher is semantically ready.
After that comes performance work: making sure that the specializer is able to deal with dispatch program guards and outcomes. The goal, initially, is to get steady state performance of common calling forms to perform at least as well as in the current master branch of Rakudo. It’s already clear enough there will be some big wins for some things that to date have been glacial, but it should not come at the cost of regression on the most common kinds of dispatch, which have received plenty of optimization effort before now.
Furthermore, NQP – the restricted form of Raku that the Rakudo compiler and other bits of the runtime guts are written in – also needs to be migrated to use the new dispatcher. Only when that is done will it be possible to rip out the current method cache, multiple dispatch cache, and so forth from MoarVM.
An open question is how to deal with backends other than MoarVM. Ideally, the new dispatch mechanism will be ported to those. A decent amount of it should be possible to express in terms of the JVM’s invokedynamic (and this would all probably play quite well with a Truffle-based Raku implementation, although I’m not sure there is a current active effort in that area).
While my current focus is to ship a Rakudo and MoarVM release that uses the new dispatcher mechanism, that won’t be the end of the journey. Some immediate ideas:
handles (delegation) and FALLBACK (handling missing method call) mechanisms can be made to perform better using the new dispatcherassuming – used to curry or otherwise prime arguments for a routine – is not ideal, and an implementation that takes advantage of the argument rewriting capabilities of the new dispatcher would likely perform a great deal betterSome new language features may also be possible to provide in an efficient way with the help of the new dispatch mechanism. For example, there’s currently not a reliable way to try to invoke a piece of code, just run it if the signature binds, or to do something else if it doesn’t. Instead, things like the Cro router have to first do a trial bind of the signature, and then do the invoke, which makes routing rather more costly. There’s also the long suggested idea of providing pattern matching via signatures with the when construct (for example, when * -> ($x) {}; when * -> ($x, *@tail) { }), which is pretty much the same need, just in a less dynamic setting.
Working on the new dispatch mechanism has been a longer journey than I first expected. The resumption part of the design was especially challenging, and there’s still a few important details to attend to there. Something like four potential approaches were discarded along the way (although elements of all of them influenced what I’ve described in this post). Abstractions that hold up are really, really, hard.
I also ended up having to take a couple of months away from doing Raku work at all, felt a bit crushed during some others, and have been juggling this with the equally important RakuAST project (which will be simplified by being able to assume the presence of the new dispatcher, and also offers me a range of softer Raku hacking tasks, whereas the dispatcher work offers few easy pickings).
Given all that, I’m glad to finally be seeing the light at the end of the tunnel. The work that remains is enumerable, and the day we ship a Rakudo and MoarVM release using the new dispatcher feels a small number of months away (and I hope writing that is not tempting fate!)
The new dispatcher is probably the most significant change to MoarVM since I founded it, in so far as it sees us removing a bunch of things that have been there pretty much since the start. RakuAST will also deliver the greatest architectural change to the Rakudo compiler in a decade. Both are an opportunity to fold years of learning things the hard way into the runtime and compiler. I hope when I look back at it all in another decade’s time, I’ll at least feel I made more interesting mistakes this time around.
Many years back, Larry Wall shared his thesis on the nature of scripting. Since recently even Java gained 'script' support I thought it would be fitting to revisit the topic, and hopefully relevant to the perl and raku language community.
The weakness of Larry's treatment (which, to be fair to the author, I think is more intended to be enlightening than to be complete) is the contrast of scripting with programming. This contrast does not permit a clear separation because scripts are programs. That is to say, no matter how long or short, scripts are written commands for a machine to execute, and I think that's a pretty decent definition of a program in general.
A more useful contrast - and, I think, the intended one - is between scripts and other sorts of programs, because that allows us to compare scripting (writing scripts) with 'programming' (writing non-script programs). And to do that we need to know what other sorts of programs there are.
The short version of that answer is - systems and applications, and a bunch of other things that aren't really relevant to the working programmer, like (embedded) control algorithms, spreadsheets and database queries. (The definition I provided above is very broad, by design, because I don't want to get stuck on boundary questions). Most programmers write applications, some write systems, virtually all write scripts once in a while, though plenty of people who aren't professional programmers also write scripts.
I think the defining features of applications and systems are, respectively:
Consider for instance a mail client (like thunderbird) in comparison to a mailer daemon (like sendmail) - one provides an interface to read and write e-mails (the model) and the other provides functionality to send that e-mail to other servers.
Note that under this (again, broad) definition, libraries are also system software, which makes sense, considering that their users are developers (just as for, say, PostgreSQL) who care about things like performance, reliability, and correctness. Incidentally, libraries as well as 'typical' system software (such as database engines and operating system kernels) tend to be written in languages like C and C++ for much the same reasons.
What then, are the differences between scripts, applications, and systems? I think the following is a good list:
Obviously these distinctions aren't really binary - 'short' versus 'long', 'ad-hoc' versus 'general purpose' - and can't be used to conclusively settle the question whether something is a script or an application. (If, indeed, that question ever comes up). More important is that for the 10 or so scripts I've written over the past year - some professionally, some not - all or most of these properties held, and I'd be surprised if the same isn't true for most readers.
And - finally coming at the point that I'm trying to make today - these features point to a specific niche of programs more than to a specific technology (or set of technologies). To be exact, scripts are (mostly) short, custom programs to automate ad-hoc tasks, tasks that are either to specific or too small to develop and distribute another program for.
This has further implications on the preferred features of a scripting language (taken to mean, a language designed to enable the development of scripts). In particular:
This niche doesn't always exist. In computing environments where everything of interest is adequately captured by an application, or which lacks the ability to effectively automate ad-hoc tasks (I'm thinking in particular of Windows before PowerShell), the practice of scripting tends to not develop. Similarily, in a modern 'cloud' environment, where system setup is controlled by a state machine hosted by another organization, scripting doesn't really have much of a future.
To put it another way, scripting only thrives in an environment that has a lot of 'scriptable' tasks; meaning tasks for which there isn't already a pre-made solution available, environments that have powerful facilities available for a script to access, and whose users are empowered to automate those tasks. Such qualities are common on Unix/Linux 'workstations' but rather less so on smartphones and (as noted before) cloud computing environments.
Truth be told I'm a little worried about that development. I could point to, and expound on, the development and popularity of languages like go and rust, which aren't exactly scripting languages, or the replacement of Javascript with TypeScript, to make the point further, but I don't think that's necessary. At the same time I could point to the development of data science as a discipline to demonstrate that scripting is alive and well (and indeed perhaps more economically relevant than before).
What should be the conclusion for perl 5/7 and raku? I'm not quite sure, mostly because I'm not quite sure whether the broader perl/raku community would prefer their sister languages to be scripting or application languages. (As implied above, I think the Python community chose that they wanted Python 3 to be an application language, and this was not without consequences to their users).
Raku adds a number of features common to application languages (I'm thinking of it's powerful type system in particular), continuing a trend that perl 5 arguably pioneered. This is indeed a very powerful strategy - a language can be introduced for scripts and some of those scripts are then extended into applications (or even systems), thereby ensuring its continued usage. But for it to work, a new perl family language must be introduced on its scripting merits, and there must be a plentiful supply of scriptable tasks to automate, some of which - or a combination of which - grow into an application.
For myself, I would like to see scripting have a bright future. Not just because scripting is the most accessible form of programming, but also because an environment that permits, even requires scripting, is one were not all interesting problems have been solved, one where it's users ask it to do tasks so diverse that there isn't an app for that, yet. One where the true potential of the wonderful devices that surround is can be explored.
In such a world there might well be a bright future for scripting.
I’d like to thank everyone who voted for me in the recent Raku Steering Council elections. By this point, I’ve been working on the language for well over a decade, first to help turn a language design I found fascinating into a working implementation, and since the Christmas release to make that implementation more robust and performant. Overall, it’s been as fun as it has been challenging – in a large part because I’ve found myself sharing the journey with a lot of really great people. I’ve also tried to do my bit to keep the community around the language kind and considerate. Receiving a vote from around 90% of those who participated in the Steering Council elections was humbling.
Alas, I’ve today submitted my resignation to the Steering Council, on personal health grounds. For the same reason, I’ll be taking a step back from Raku core development (Raku, MoarVM, language design, etc.) Please don’t worry too much; I’ll almost certainly be fine. It may be I’m ready to continue working on Raku things in a month or two. It may also be longer. Either way, I think Raku will be better off with a fully sized Steering Council in place, and I’ll be better off without the anxiety that I’m holding a role that I’m not in a place to fulfill.
Hello everyone! In the last report I said that just a little bit of work on the heap snapshot portion of the UI should result in a useful tool.
Photo by Sticker Mule / Unsplash
Here's my report for the first useful pieces of the Heap Snapshot UI!
Last time you already saw the graphs showing how the number of instances of a given type or frame grow and shrink over the course of multiple snapshots, and how new snapshots can be requested from the UI.
The latter now looks a little bit different:
(Sorry, I lost the screenshot when I took down my blog the last time!)
Each snapshot now has a little button for itself, they are in one line instead of each snapshot having its own line, and the progress bar has been replaced with a percentage and a little "spinner".
There are multiple ways to get started navigating the heap snapshot. Everything is reachable from the "Root" object (this is the norm for reachability-based garbage collection schemes). You can just click through from there and see what you can find.
Another way is to look at the Type & Frame Lists, which show every type or frame along with the number of instances that exist in the heap snapshot, and the total size taken up by those objects.
(Sorry, I lost the screenshot when I took down my blog the last time!)
Clicking on a type, or the name or filename of a frame leads you to a list of all objects of that type, all frames with the given name, or all frames from the given file. They are grouped by size, and each object shows up as a little button with the ID:
(Sorry, I lost the screenshot when I took down my blog the last time!)
Clicking any of these buttons leads you to the Explorer.
Here's a screenshot of the explorer to give you an idea of how the parts go together that I explain next:
(Sorry, I lost the screenshot when I took down my blog the last time!)
The explorer is split into two identical panels, which allows you to compare two objects, or to explore in multiple directions from one given object.
There's an "Arrow to the Right" button on the left pane and an "Arrow to the Left" button on the right pane. These buttons make the other pane show the same object that the one pane currently shows.
On the left of each pane there's a "Path" display. Clicking the "Path" button in the explorer will calculate the shortest path to reach the object from the root. This is useful when you've got an object that you would expect to have already been deleted by the garbage collector, but for some reason is still around. The path can give the critical hint to figure out why it's still around. Maybe one phase of the program has ended, but something is still holding on to a cache that was put in as an optimization, and that still has your object in it? That cache in question would be on the path for your object.
The other half of each panel shows information about the object: Displayed at the very top is whether it is an object, a type object, an STable, or a frame.
Below that there is an input field where you can enter any ID belonging to a Collectable (the general term encompassing types, type objects, stables, and frames) to have a look.
The "Kind" field needs to have the number values replaced with human-readable text, but it's not the most interesting thing anyway.
The "Size" of the Collectable is split into two parts. One is the fixed size that every instance of the given type has. The other is any extra data an instance of this type may have attached to it, that's not a Collectable itself. This would be the case for arrays and hashes, as well as buffers and many "internal" objects.
Finally, the "References" field shows how many Collectables are referred to by the Collectable in question (outgoing references) and how many Collectables reference this object in question.
Below that there are two buttons, Path and Network. The former was explained further above, and the latter will get its own little section in this blog post.
Finally, the bottom of the panel is dedicated to a list of all references - outgoing or incoming - grouped by what the reference means, and what type it references.
(Sorry, I lost the screenshot when I took down my blog the last time!)
In this example you see that the frame of the function display from elementary2d.p6 on line 87 references a couple of variables ($_, $tv, &inv), the frame that called this frame (step), an outer frame (MAIN), and a code object. The right pane shows the incoming references. For incoming references, the name of the reference isn't available (yet), but you can see that 7 different objects are holding a reference to this frame.
The newest part of the heap snapshot UI is the Network View. It allows the user to get a "bird's eye" view of many objects and their relations to each other.
Here's a screenshot of the network view in action:
(Sorry, I lost the screenshot when I took down my blog the last time!)
The network view is split into two panes. The pane on the left lists all types present in the network currently. It allows you to give every type a different symbol, a different color, or optionally make it invisible. In addition, it shows how many of each type are currently in the network display.
The right pane shows the objects, sorted by how far they are from the root (object 0, the one in Layer 0, with the frog icon).
Each object has one three-piece button. On the left of the button is the icon representing the type, in the middle is the object ID for this particular object, and on the right is an icon for the "relation" this object has to the "selected" object:
This view was generated for object 46011 (in layer 4, with a hamburger as the icon). This object gets the little "map marker pin" icon to show that it's the "center" of the network. In layers for distances 3, 2, and 1 there is one object each with a little icon showing two map marker pins connected with a squiggly line. This means that the object is part of the shortest path to the root. The third kind of icon is an arrow pointing from the left into a square that's on the right. Those are objects that refer to the selected object.
There is also an icon that's the same but the arrow goes outwards from the square instead of inwards. Those are objects that are referenced by the selected object. However, there is currently no button to have every object referenced by the selected object put into the network view. This is one of the next steps I'll be working on.
Customizing the colors and visibility of different types can give you a view like this:
(Sorry, I lost the screenshot when I took down my blog the last time!)
And here's a view with more objects in it:
(Sorry, I lost the screenshot when I took down my blog the last time!)
Interesting observations from this image:
You have no doubt noticed that the buttons for collectables are very different between the network view and the type/frame lists and the explorer. The reason for that is that I only just started with the network view and wanted to display more info for each collectable (namely the icons to the left and right) and wanted them to look nicer. In the explorer there are sometimes thousands of objects in the reference list, and having big buttons like in the network view could be difficult to work with. There'll probably have to be a solution for that, or maybe it'll just work out fine in real-world use cases.
On the other hand, I want the colors and icons for types to be available everywhere, so that it's easier to spot common patterns across different views and to mark things you're interested in so they stand out in lists of many objects. I was also thinking of a "bookmark this object" feature for similar purposes.
Before most of that, the network viewer will have to become "navigable", i.e. clicking on an object should put it in the center, grab the path to the root, grab incoming references, etc.
There also need to be ways to handle references you're not (or no longer) interested in, especially when you come across an object that has thousands of them.
But until then, all of this should already be very useful!
Here's the section about the heap snapshot profiler from the original grant proposal:
Looking at the list, it seems like the majority of intended features are already available or will be very soon!
Until now the user had to download nodejs and npm along with a whole load of javascript libraries in order to compile and bundle the javascript code that powers the frontend of moarperf.
Fortunately, it was relatively easy to get travis-ci to do the work automatically and upload a package with the finished javascript code and the backend code to github.
You can now visit the releases page on github to grab a tarball with all the files you need! Just install all backend dependencies with zef install --deps-only . and run service.p6!
And with that I'm already done for this report!
It looks like the heap snapshot portion of the grant is quite a bit smaller than the profiler part, although a lot of work happened in moarvm rather than the UI. I'm glad to see rapid progress on this.
I hope you enjoyed this quick look at the newest pieces of moarperf!
- Timo
It has been a while since the last progress report, hasn't it?
Over the last few months I've been focusing on the MoarVM Heap Snapshot Profiler. The new format that I explained in the last post, "Intermediate Progress Report: Heap Snapshots", is available in the master branch of MoarVM, and it has learned a few new tricks, too.
The first thing I usually did when opening a Heap Snapshot in the heapanalyzer (the older command-line based one) was to select a Snapshot, ask for the summary, and then for the top objects by size, top objects by count, top frames by size, and/or top frames by count to see if anything immediately catches my eye. In order to make more sense of the results, I would repeat those commands for one or more other Snapshots.
Snapshot Heap Size Objects Type Objects STables Frames References
======== ================= ======= ============ ======= ====== ==========
0 46,229,818 bytes 331,212 686 687 1,285 1,146,426
25 63,471,658 bytes 475,587 995 996 2,832 1,889,612
50 82,407,275 bytes 625,958 1,320 1,321 6,176 2,741,066
75 97,860,712 bytes 754,075 1,415 1,416 6,967 3,436,141
100 113,398,840 bytes 883,405 1,507 1,508 7,837 4,187,184
Snapshot Heap Size Objects Type Objects STables Frames References
======== ================= ========= ============ ======= ====== ==========
125 130,799,241 bytes 1,028,928 1,631 1,632 9,254 5,036,284
150 145,781,617 bytes 1,155,887 1,684 1,685 9,774 5,809,084
175 162,018,588 bytes 1,293,439 1,791 1,792 10,887 6,602,449
Realizing that the most common use case should be simple to achieve, I first implemented a command summary all and later a command summary every 10 to get the heapanalyzer to give the summaries of multiple Snapshots at once, and to be able to get summaries (relatively) quickly even if there's multiple hundreds of snapshots in one file.
Sadly, this still requires the parser to go through the entire file to do the counting and adding up. That's obviously not optimal, even though this is an Embarrassingly Parallel task, and it can use every CPU core in the machine you have, it's still a whole lot of work just for the summary.
For this reason I decided to shift the responsibility for this task to MoarVM itself, to be done while the snapshot is taken. In order to record everything that goes into the Snapshot, MoarVM already differentiates between Object, Type Object, STable, and Frame, and it stores all references anyway. I figured it shouldn't have a performance impact to just add up the numbers and make them available in the file.
The result is that the summary table as shown further above is available only milliseconds after loading the heap snapshot file, rather than after an explicit request and sometimes a lengthy wait period.
The next step was to see if top objects by size and friends could be made faster in a similar way.
I decided that adding an optional "statistics collection" feature inside of MoarVM's heap snapshot profiler would be worthwhile. If it turns out that the performance impact of summing up sizes and counts on a per-type and per-frame basis makes capturing a snapshot too slow, it could be turned off.
> snapshot 50
Loading that snapshot. Carry on...
> top frames by size
Wait a moment, while I finish loading the snapshot...
Name Total Bytes
==================================== =============
finish_code_object (World.nqp:2532) 201,960 bytes
moarop_mapper (QAST.nqp:1764) 136,512 bytes
!protoregex (QRegex.nqp:1625) 71,760 bytes
new_type (Metamodel.nqp:1345) 40,704 bytes
statement (Perl6-Grammar.nqp:951) 35,640 bytes
termish (Perl6-Grammar.nqp:3641) 34,720 bytes
<anon> (Perl6-BOOTSTRAP.c.nqp:1382) 29,960 bytes
EXPR (Perl6-Grammar.nqp:3677) 27,200 bytes
<mainline> (Perl6-BOOTSTRAP.c.nqp:1) 26,496 bytes
<mainline> (NQPCORE.setting:1) 25,896 bytes
EXPR (NQPHLL.nqp:1186) 25,760 bytes
<anon> (<null>:1) 25,272 bytes
declarator (Perl6-Grammar.nqp:2189) 23,520 bytes
<anon> (<null>:1) 22,464 bytes
<anon> (<null>:1) 22,464 bytes
Showing the top objects or frame for a single snapshot is fairly straight-forward in the commandline based UI, but how would you display how a type or frame develops its value across many snapshots?
Instead of figuring out the best way to display this data in the commandline, I switched focus to the Moarperf Web Frontend. The most obvious way to display data like this is a Line Graph, I believe. So that's what we have now!
And of course you also get to see the data from each snapshot's Summary in graph format:
And now for the reason behind this blog post's Title.
Using Jonathan's module Concurrent::Progress (with a slight modification) I sprinkled the code to parse a snapshot with matching calls of .increment-target and .increment. The resulting progress reports (throttled to at most one per second) are then forwarded to the browser via the WebSocket connection that already delivers many other bits of data.
The result can be seen in this tiny screencast:
The recording is rather choppy because the heapanalyzer code was using every last drop of performance out of my CPU while it was trying to capture my screen.
There's obviously a lot still missing from the heap snapshot analyzer frontend GUI, but I feel like this is a good start, and even provides useful features already. The graphs for the summary data are nicer to read than the table in the commandline UI, and it's only in this UI that you can get a graphical representation of the "highscore" lists.
I think a lot of the remaining features will already be useful after just the initial pieces are in place, so a little work should go a long way.
I didn't spend the whole time between the last progress report and now to work directly on the features shown here. Apart from Life Intervening™, I worked on fixing many frustrating bugs related to both of the profilers in MoarVM. I added a small subsystem I call VMEvents that allows user code to be notified when GC runs happen and other interesting bits from inside MoarVM itself. And of course I've been assisting other developers by answering questions and looking over their contributions. And of course there's the occasional video-game-development related experiment, for example with the GTK Live Coding Tool.
Finally, here's a nice little screencap of that same tool displaying a hilbert curve:
That's already everything I have for this time. A lot has (had to) happen behind the scenes to get to this point, but now there was finally something to look at (and touch, if you grab the source code and go through the needlessly complicated build process yourself).
Thank you for reading and I hope to see you in the next one!
- Timo
This is slightly tangential to the Rakudo Perl 6 Performance Analysis Tooling grant from The Perl Foundation, but it does interact closely with it, so this is more or less a progress report.
The other day, Jonathan Worthington of Edument approached me with a little paid Job: Profiling very big codebases can be tedious, especially if you're interested in only one specific fraction of the program. That's why I got the assignment to make the profiler "configurable". On top of that, the Comma IDE will get native access to this functionality.
The actual request was just to allow specifying whether individual routines should be included in the profile via a configuration file. That would have been possible with just a simple text file that contains one filename/line number/routine name per line. However, I have been wanting something in MoarVM that allows much more involved configuration for many different parts of the VM, not just the profiler.
(There used to be a cat picture here. I described it as: photograph of a cat standing on a shelf. The cat's head is very close to the camera and very out-of-focus)
That's why I quickly developed a small and simple "domain-specific language" for this and similar purposes.
The language had a few requirements:
There's also some things that aren't necessary:
While thinking about what exactly I should build – before I eventually settled on building a "programming language" for this task – I bounced back and forth between the simplest thing that could possibly work (for example, a text file with a list of file/line/name entries) and the most powerful thing that I can implement in a sensible timeframe (for example, allowing a full NQP script). A very important realization was that as long as I require the first line to identify what "version" of configuration program it is, I could completely throw away the current design and put something else instead, if the need ever arises. That allowed me to actually commit to a design that looked at least somewhat promising. And so I got started on what I call confprog.
Here's an example program. It doesn't do very much, but shows what it's about in general:
version = 1
entry profiler_static:
log = sf.name;
profile = sf.name eq "calculate-strawberries"
profile |= sf.cu.filename eq "CustomCode.pm6"
The entry decides which stage of profiling this program is applied to. In this case, the profiler_static means we're seeing a routine for the first time, before it is actually entered. That's why only the information every individual invocation of the frame in question shares is available via the variable sf, which stands for Static Frame. The Static Frame also allows access to the Compilation Unit (cu) that it was compiled into, which lets us find the filename.
The first line that actually does something assigns a value to the special variable log. This will output the name of the routine the program was invoked for.
The next line will turn on profiling only if the name of the routine is "calculate-strawberries". The line after that will also turn on profiling if the filename the routine is from is "CustomCode.pm6".
Apart from profiler_static, there are a couple more entry points available.
profiler_static, which runs the first time any routine is encountered, and stores the decision until the profile run is finished.profiler_dynamic will be evaluated every time a routine gets entered that would potentially be profiled otherwise (for example because a profiler_static program turned it on, or because there is no profiler_static program, which means that every routine is eligible for profiling).heapsnapshot will be run every time a GC run happens. It lets the user decide whether a GC run should result in a heap snapshot being taken or not, based on whether the run has been a minor or major collection, and arbitrary other factors, including time since start of the program, or time since the last heap snapshot was taken.spesh and jit I'm not entirely sure about yet. I want to allow turning the specializer or the jit off completely for certain routines, but I also want to offer control over individual optimizations in spesh (turning off inlining for one particular routine, preventing scalar replacement but only for Rat types, ...) and behaviour of the jit (use the template jit for everything except one specific piece of one particular routine, ...).The syntax is still subject to change, especially before the whole thing is actually in a released version of MoarVM.
There is a whole lot of other things I could imagine being of interest in the near or far future. One place I'm taking inspiration from is where "extended Berkeley Packet Filter" (eBPF for short) programs are being used in the linux kernel and related pieces of software:
Oversimplifying a bit, BPF was originally meant for tcpdump so that the kernel doesn't have to copy all data over to the userspace process so that the decision what is interesting or not can be made. Instead, the kernel receives a little piece of code in the special BPF language (or bytecode) and can calculate the decision before having to copy anything.
eBPF programs can now also be used as a complex ruleset for sandboxing processes (with "seccomp"), to decide how network packets are to be routed between sockets (that's probably for Software Defined Networks?), what operations a process may perform on a particular device, whether a trace point in the kernel or a user-space program should fire, and so on.
So what's the status of confprog? I've written a parser and compiler that feeds confprog "bytecode" (which is mostly the same as regular moarvm bytecode) to MoarVM. There's also a preliminary validator that ensures the program won't do anything weird, or crash, when run. It is much too lenient at the moment, though. Then there's an interpreter that actually runs the code. It can already take an initial value for the "decision output value" (great name, isn't it) and it will return whatever value the confprog has set when it runs. The heap snapshot profiler is currently the only part of MoarVM that will actually try to run a confprog, and it uses the value to decide whether to take a snapshot or not.
Next up on the list of things to work on:
Apart from improvements to the confprog programming language, the integration with MoarVM lacks almost everything, most importantly installing a confprog for the profiler to decide whether a frame should be profiled (which was the original purpose of this assignment).
After that, and after building a bit of GUI for Comma, the regular grant work can resume: Flame graphs are still not visible on the call graph explorer page, and heap snapshots can't be loaded into moarperf yet, either.
Thanks for sticking with me through this perhaps a little dry and technical post. I hope the next one will have a little more excitement! And if there's interest (which you can signal by sending me a message on irc, or posting on reddit, or reaching me via twitter @loltimo, on the Perl 6 discord server etc) I can also write a post on how exactly the compiler was made, and how you can build your own compiler with Perl 6 code. Until then, you can find Andrew Shitov's presentations about making tiny languages in Perl 6 on youtube.
I hope you have a wonderful day; see you in the next one!
- Timo
PS: I would like to give a special shout-out to Nadim Khemir for the wonderful Data::Dump::Tree module which made it much easier to see what my parser was doing. Here's some example output from another simple confprog program:
[6] @0
├ 0 = .Label .Node @1
│ ├ $.name = heapsnapshot.Str
│ ├ $.type = entrypoint.Str
│ ├ $.position is rw = Nil
│ └ @.children = [0] @2
├ 1 = .Op .Node @3
│ ├ $.op = =.Str
│ ├ $.type is rw = Nil
│ └ @.children = [2] @4
│ ├ 0 = .Var .Node @5
│ │ ├ $.name = log.Str
│ │ └ $.type = CPType String :stringy @6
│ └ 1 = String Value ("we're in") @7
├ 2 = .Op .Node @8
│ ├ $.op = =.Str
│ ├ $.type is rw = Nil
│ └ @.children = [2] @9
│ ├ 0 = .Var .Node @10
│ │ ├ $.name = log.Str
│ │ └ $.type = CPType String :stringy §6
│ └ 1 = .Op .Node @12
│ ├ $.op = getattr.Str
│ ├ $.type is rw = CPType String :stringy §6
│ └ @.children = [2] @14
│ ├ 0 = .Var .Node @15
│ │ ├ $.name = sf.Str
│ │ └ $.type = CPType MVMStaticFrame @16
│ └ 1 = name.Str
├ 3 = .Op .Node @17
│ ├ $.op = =.Str
│ ├ $.type is rw = Nil
│ └ @.children = [2] @18
│ ├ 0 = .Var .Node @19
│ │ ├ $.name = log.Str
│ │ └ $.type = CPType String :stringy §6
│ └ 1 = String Value ("i am the confprog and i say:") @21
├ 4 = .Op .Node @22
│ ├ $.op = =.Str
│ ├ $.type is rw = Nil
│ └ @.children = [2] @23
│ ├ 0 = .Var .Node @24
│ │ ├ $.name = log.Str
│ │ └ $.type = CPType String :stringy §6
│ └ 1 = String Value (" no heap snapshots for you my friend!") @26
└ 5 = .Op .Node @27
├ $.op = =.Str
├ $.type is rw = Nil
└ @.children = [2] @28
├ 0 = .Var .Node @29
│ ├ $.name = snapshot.Str
│ └ $.type = CPType Int :numeric :stringy @30
└ 1 = Int Value (0) @31
Notice how it shows the type of most things, like name.Str, as well as cross-references for things that appear multiple times, like the CPType String. Particularly useful is giving your own classes methods that specify exactly how they should be displayed by DDT. Love It!
 |
| Both ADD and SUB refer to the same LOAD node |
 |
| The DO node is inserted for the LET operator. It ensures that the value of the LOAD node is computed before the reference in either branch |
I want to revive Carl Mäsak's Coding Contest as a crowd-sourced contest.
The contest will be in four phases:
For the first phase, development of tasks, I am looking for volunteers who come up with coding tasks collaboratively. Sadly, these volunteers, including myself, will be excluded from participating in the second phase.
I am looking for tasks that ...
This is non-trivial, so I'd like to have others to discuss things with, and to come up with some more tasks.
If you want to help with task creation, please send an email to [email protected], stating your intentions to help, and your freenode IRC handle (optional).
There are other ways to help too:
In these cases you can use the same email address to contact me,
or use IRC (moritz on freenode) or twitter.
After a perilous drive up a steep, narrow, winding road from Lake Geneva we arrived at an attractive Alpine village (Villars-sur-Ollon) to meet with fellow Perl Mongers in a small restaurant. There followed much talk and a little clandestine drinking of exotic spirits including Swiss whisky. The following morning walking to the conference venue there was an amazing view of mountain ranges. On arrival I failed to operate the Nespresso machine which I later found was due to it simply being off. Clearly software engineers should never try to use hardware. At least after an evening of drinking.
Wendy’s stall was piled high with swag including new Bailador (Perl 6 dancer like framework) stickers, a Shadowcat booklet about Perl 6 and the new O’Reilly “Thinking in Perl 6″. Unfortunately she had sold out of Moritz’s book “Perl 6 Fundamentals” (although there was a sample display copy present). Thankfully later that morning I discovered I had a £3 credit on Google Play Books so I bought the ebook on my phone.
The conference started early with Damian Conway’s Three Little Words. These were “has”, “class” and “method” from Perl 6 which he liked so much that he had added them to Perl 5 with his “Dios” – “Declarative Inside-Out Syntax” module. PPI wasn’t fast enough so he had to replace it with a 50,000 character regex PPR. Practical everyday modules mentioned included Regexp::Optimizer and Test::Expr. If the video doesn’t appear shortly on youtube a version of his talk dating from a few weeks earlier is available at https://www.youtube.com/watch?v=ob6YHpcXmTg
Jonathan Worthington returned with his Perl 6 talk on “How does deoptimization help us go faster?” giving us insight into why Perl 6 was slow at the Virtual Machine level (specifically MoarVM). Even apparently simple and fast operations like indexing an array were slow due to powerful abstractions, late binding and many levels of Multiple Dispatch. In short the flexibility and power of such an extensible language also led to slowness due to the complexity of code paths. The AST optimizer helped with this at compile time but itself took time and it could be better to do this at a later compile time (like Just In Time). Even with a simple program reading lines from a file it was very hard to determine statically what types were used (even with type annotations) and whether it was worth optimizing (since the file could be very short).
The solution to these dynamic problems was also dynamic but to see what was happening needed cheap logging of execution which was passed to another thread. This logging is made visible by setting the environment variable MVM_SPESH_LOG to a filename. Better tooling for this log would be a good project for someone.
For execution planning we look for hot (frequently called) code, long blocks of bytecode (slow to run) and consider how many types are used (avoiding “megamorphic” cases with many types which needs many versions of code). Also analysis of the code flow between different code blocks and SSA. Mixins made the optimization particularly problematic.
MoarVM’s Spesh did statistical analysis of the code in order to rewrite it in faster, simpler ways. Guards (cheap check for things like types) were placed to catch cases where it got it wrong and if these were triggered (infrequently) it would deoptimize as well, hence the counterintuitive title since “Deoptimization enables speculation” The slides are at http://jnthn.net/papers/2017-spw-deopt.pdf with the video at https://www.youtube.com/watch?v=3umNn1KnlCY The older and more dull witted of us (including myself) might find the latter part of the video more comprehensible at 0.75 Youtube speed.
After a superb multi-course lunch (the food was probably the best I’d had at any Perl event) we returned promptly to hear Damian talk of “Everyday Perl 6”. He pointed out that it wasn’t necessary to code golf obfuscated extremes of Perl 6 and that the average Perl 5 programmer would see many things simpler in Perl 6. Also a rewrite from 5 to 6 might see something like 25% fewer lines of code since 6 was more expressive in syntax (as well as more consistent) although performance problems remained (and solutions in progress as the previous talk had reminded us).
Next Liz talked of a “gross” (in the numerical sense of 12 x 12 rather than the American teen sense) of Perl 6 Weeklies as she took us down memory lane to 2014 (just about when MoarVM was launched and when unicode support was poor!) with some selected highlights and memories of Perl 6 developers of the past (and hopefully future again!). Her talk was recorded at https://www.youtube.com/watch?v=418QCTXmvDU
Cal then spoke of Perl 6 maths which he thought was good with its Rats and FatRats but not quite good enough and his ideas of fixing it. On the following day he showed us he had started some TDD work on TrimRats. He also told us that Newton’s Method wasn’t very good but generated a pretty fractal. See https://www.youtube.com/watch?v=3na_Cx-anvw
Lee spoke about how to detect Perl 5 memory leaks with various CPAN modules and his examples are at https://github.com/leejo/Perl_memory_talk
The day finished with Lightning Talks and a barbecue at givengain — a main sponsor.
On the second day I noticed the robotic St Bernards dog in a tourist shop window had come to life.
Damian kicked off the talks with my favourite of his talks, “Standing on the Shoulders of Giants”, starting with the Countess of Lovelace and her Bernoulli number program. This generated a strange sequence with many zeros. The Perl 6 version since it used rational numbers not floating point got the zeros right whereas the Perl 5 version initially suffered from floating point rounding errors (which are fixable).
Among other things he showed us how to define a new infix operator in Perl 6. He also showed us a Perl 6 sort program that looked exactly like LISP even down to the Lots of Irritating Superfluous Parentheses. I think this was quicksort (he certainly showed us a picture of Sir Tony Hoare at some point). Also a very functional (Haskell-like) equivalent with heavy use of P6 Multiple Dispatch. Also included was demonstration of P6 “before” as a sort of typeless/multi-type comparison infix. Damian then returned to his old favourite of Quantum Computing.
My mind and notes got a bit jumbled at this point but I particularly liked the slide that explained how factorisation could work by observing the product of possible inputs since this led to a collapse that revealed the factors. To do this on RSA etc., of course, needs real hardware support which probably only the NSA and friends have (?). Damian’s code examples are at http://www.bit.do/Perl6SOG with an earlier version of his talk at https://www.youtube.com/watch?v=Nq2HkAYbG5o Around this point there was a road race of classic cars going on outside up the main road into the village and there were car noises in the background that strangely were more relaxing than annoying.
After Quantum Chaos Paul Johnson brought us all back down to ground with an excellent practical talk on modernising legacy Perl 5 applications based on his war stories. Hell, of course, is “Other People’s Code”, often dating from Perl’s early days and lacking documentation and sound engineering.
Often the original developers had long since departed or, in the worse cases, were still there. Adding tests and logging (with stack traces) were particularly useful. As was moving to git (although its steep learning curve meant mentoring was needed) and handling CPAN module versioning with pinto. Many talks had spoken of the Perl 6 future whereas this spoke of the Perl 5 past and present and the work many of us suffer to pay the bills. It’s at https://www.youtube.com/watch?v=4G5EaUNOhR0
Jonathan then spoke of reactive distributed software. A distributed system is an async one where “Is it working?” means “some of it is working but we don’t know which bits”. Good OO design is “tell don’t ask” — you tell remote service to do something for you and not parse the response and do it yourself thus breaking encapsulation. This is particularly important in building well designed distributed systems since otherwise the systems are less responsive and reliable. Reactive (async) works better for distributed software than interactive (blocking or sync).
We saw a table that used a Perl 6 promise for one value and a supply for many values for reactive (async) code and the equivalent (one value) and a Perl 6 Seq for interactive code. A Supply could be used for pub/sub and the Observer Pattern. A Supply could either be live (like broadcast TV) or, for most Perl 6 supplies, on-demand (like Netflix). Then samples of networking (socket) based code were discussed including a web client, web server and SSH::LibSSH (async client bindings often very useful in practical applications like port forwarding)
https://github.com/jnthn/p6-ssh-libssh
Much of the socket code had a pattern of “react { whenever {” blocks with “whenever” as a sort of async loop.He then moved on from sockets to services (using a Supply pipeline) and amazed us by announcing the release of “cro”, a microservices library that even supports HTTP/2 and Websockets, at http://mi.cro.services/. This is installable using Perl 6 by “zef install –/test cro”.
Slides at http://jnthn.net/papers/2017-spw-sockets-services.pdf and video at https://www.youtube.com/watch?v=6CsBDnTUJ3A
Next Lee showed Burp Scanner which is payware but probably the best web vulnerabilities scanner. I wondered if anyone had dare run it on ACT or the hotel’s captive portal.
Wendy did some cheerleading in her “Changing Image of Perl”. An earlier version is at https://www.youtube.com/watch?v=Jl6iJIH7HdA
Sue’s talk was “Spiders, Gophers, Butterflies” although the latter were mostly noticeably absent. She promises me that a successor version of the talk will use them more extensively. Certainly any Perl 6 web spidering code is likely to fit better on one slide than the Go equivalent.
During the lightning talks Timo showed us a very pretty Perl 6 program using his SDL2::Raw to draw an animated square spiral with hypnotic colour cycling type patterns. Also there was a talk by the author about https://bifax.org/bif/— a distributed bug tracking system (which worked offline like git).
Later in the final evening many of us ate and chatted in another restaurant where we witnessed a dog fight being narrowly averted and learnt that Wendy didn’t like Perl 5’s bless for both technical and philosophical reasons.
Time for some old man's reminiscence. Or so it feels when I realize that I've spent more than 10 years involved with the Perl 6 community.
It was February 2007.
I was bored. I had lots of free time (crazy to imagine that now...), and I spent some of that answering (Perl 5) questions on perlmonks. There was a category of questions where I routinely had no good answers, and those were related to threads. So I decided to play with threads, and got frustrated pretty quickly.
And then I remember that a friend in school had told me (about four years earlier) that there was this Perl 6 project that wanted to do concurrency really well, and even automatically parallelize some stuff. And this was some time ago, maybe they had gotten anywhere?
So I searched the Internet, and found out about Pugs, a Perl 6 compiler written in Haskell. And I wanted to learn more, but some of the links to the presentations were dead. I joined the #perl6 IRC channel to report the broken link.
And within three minutes I got a "thank you" for the report, the broken links were gone, and I had an invitation for a commit bit to the underlying SVN repo.
I stayed.
Those were they wild young days of Perl 6 and Pugs. Audrey Tang was pushing Pugs (and Haskell) very hard, and often implemented a feature within 20 minutes after somebody mentioned it. Things were unstable, broken often, and usually fixed quickly. No idea was too crazy to be considered or even implemented.
We had bots that evaluated Perl 6 and Haskell code, and gave the result directly on IRC. There were lots of cool (and sometimes somewhat frightening) automations, for example for inviting others to the SVN repo, to the shared hosting system (called feather), for searching SVN logs and so on. Since git was still an obscure and very unusable, people tried to use SVK, an attempt to implement a decentralized version control system on top of of the SVN protocol.
Despite some half-hearted attempts, I didn't really make inroads into compiler developments. Having worked with neither Haskell nor compilers before proved to be a pretty steep step. Instead I focused on some early modules, documentation, tests, and asking and answering questions. When the IRC logger went offline for a while, I wrote my own, which is still in use today.
I felt at home in that IRC channel and the community. When the community asked for mentors for the Google Summer of Code project, I stepped up. The project was a revamp of the Perl 6 test suite, and to prepare for mentoring task, I decided to dive deeper. That made me the maintainer of the test suite.
I can't recount a full history of Perl 6 projects during that time range, but I want to reflect on some projects that I considered my pet projects, at least for some time.
It is not quite clear from this (very selected) timeline, but my Perl 6 related activity dropped around 2009 or 2010. This is when I started to work full time, moved in with my girlfriend (now wife), and started to plan a family.
The technologies and ideas in Perl 6 are fascinating, but that's not what kept me. I came for the technology, but stayed for the community.
There were and are many great people in the Perl 6 community, some of whom I am happy to call my friends. Whenever I get the chance to attend a Perl conference, workshop or hackathon, I find a group of Perl 6 hackers to hang out and discuss with, and generally have a good time.
Four events stand out in my memory. In 2010 I was invited to the Open Source Days in Copenhagen. I missed most of the conference, but spent a day or two with (if memory serve right) Carl Mäsak, Patrick Michaud, Jonathan Worthington and Arne Skjærholt. We spent some fun time trying to wrap our minds around macros, the intricacies of human and computer language, and Japanese food. (Ok, the last one was easy). Later the same year, I attended my first YAPC::EU in Pisa, and met most of the same crowd again -- this time joined by Larry Wall, and over three or four days. I still fondly remember the Perl 6 hallway track from that conference. And 2012 I flew to Oslo for a Perl 6 hackathon, with a close-knit, fabulous group of Perl 6 hackers. Finally, the Perl Reunification Summit in the beautiful town of Perl in Germany, which brought together Perl 5 and Perl 6 hackers in a very relaxed atmosphere.
For three of these four events, different private sponsors from the Perl and Perl 6 community covered travel and/or hotel costs, with their only motivation being meeting folks they liked, and seeing the community and technology flourish.
The Perl 6 community has evolved a lot over the last ten years, but it is still a very friendly and welcoming place. There are lots of "new" folks (where "new" is everybody who joined after me, of course :D), and a surprising number of the old guard still hang around, some more involved, some less, all of them still very friendly and supportive
I anticipate that my family and other projects will continue to occupy much of my time, and it is unlikely that I'll be writing another Perl 6 book (after the one about regexes) any time soon. But the Perl 6 community has become a second home for me, and I don't want to miss it.
In the future, I see myself supporting the Perl 6 community through infrastructure (community servers, IRC logs, running IRC bots etc.), answering questions, writing a blog article here and there, but mostly empowering the "new" guard to do whatever they deem best.
After about nine months of work, my book Perl 6 Fundamentals is now available for purchase on apress.com and springer.com.
The ebook can be purchased right now, and comes in the epub and PDF formats (with watermarks, but DRM free). The print form can be pre-ordered from Amazon, and will become ready for shipping in about a week or two.
I will make a copy of the ebook available for free for everybody who purchased an earlier version, "Perl 6 by Example", from LeanPub.
The book is aimed at people familiar with the basics of programming; prior
Perl 5 or Perl 6 knowledge is not required. It features a practical example in most chapters (no mammal hierarchies or class Rectangle inheriting from class Shape), ranging from simple input/output and text formatting to plotting with python's matplotlib libraries. Other examples include date and time conversion, a Unicode search tool and a directory size visualization.
I use these examples to explain subset of Perl 6, with many pointers to more
documentation where relevant. Perl 6 topics include the basic lexicographic
structure, testing, input and output, multi dispatch, object orientation, regexes and grammars, usage of modules, functional programming and interaction
with python libraries through Inline::Python.
Let me finish with Larry Wall's description of this book, quoted from his foreword:
It's not just a reference, since you can always find such materials online. Nor is it just a cookbook. I like to think of it as an extended invitation, from a well-liked and well-informed member of our circle, to people like you who might want to join in on the fun. Because joy is what's fundamental to Perl. The essence of Perl is an invitation to love, and to be loved by, the Perl community. It's an invitation to be a participant of the gift economy, on both the receiving and the giving end.
The Perl 6 naming debate has started again. And I guess with good reason. Teaching people that Perl 6 is a Perl, but not the Perl requires too much effort. Two years ago, I didn't believe. Now you're reading a tired man's words.
I'm glad that this time, we're not discussing giving up the "Perl" brand, which still has very positive connotations in my mind, and in many other minds as well.
And yet, I can't bring myself to like "Rakudo Perl 6" as a name. There are two vary shallow reasons for that: Going from two syllables, "Perl six", to five of them, seems a step in the wrong direction. And two, I remember the days when the name was pretty young, and people would misspell it all the time. That seems to have abated, though I don't know why.
But there's also a deeper reason, probably sentimental old man's reason. I remember the days when Pugs was actively developed, and formed the center of a vibrant community. When kp6 and SMOP and all those weird projects were around. And then, just when it looked like there was only a single compiler was around, Stefan O'Rear conjured up niecza, almost single-handedly, and out of thin air. Within months, it was a viable Perl 6 compiler, that people on #perl6 readily recommended.
All of this was born out of the vision that Perl 6 was a language with no single, preferred compiler. Changing the language name to include the compiler name means abandoning this vision. How can we claim to welcome alternative implementations when the commitment to one compiler is right in the language name?
However I can't weigh this loss of vision against a potential gain in popularity. I can't decide if it's my long-term commitment to the name "Perl 6" that makes me resent the new name, or valid objections. The lack of vision mirrors my own state of mind pretty well.
I don't know where this leaves us. I guess I must apologize for wasting your time by publishing this incoherent mess.
Perl 6 is innovative in many ways, and sometimes we don't fully appreciate all the implications, for good or for bad.
There's one I stumbled upon recently: The use of fancy Unicode symbols for built-in stuff. In this case: the `.gist` output of Match objects. For example
my token word { \w+ } say 'abc=def' ~~ /<word> '=' <word>/;produces this output:
｢abc=def｣ word => ｢abc｣ word => ｢def｣
And that's where the problems start. In my current quest to write a book on Perl 6 regexes, I noticed that the PDF that LeanPub generates from my Markdown sources don't correctly display those pesky ｢｣ characters, which are
$ uni -c ｢｣ ｢ - U+0FF62 - HALFWIDTH LEFT CORNER BRACKET ｣ - U+0FF63 - HALFWIDTH RIGHT CORNER BRACKET
When I copied the text from the PDF and pasted into my editor, they showed up correctly, which indicates that the characters are likely missing from the monospace font.
The toolchain allows control over the font used for displaying code, so I tried all the monospace fonts that were available. I tried them in alphabetical order. Among the earlier fonts I tried was Deja Vu Sans Mono, which I use in my terminal, and which hasn't let me down yet. No dice. I arrived at Noto, a font designed to cover all Unicode codepoints. And it didn't work either. So it turns out these two characters are part of some Noto Sans variants, but not of the monospace font.
My terminal, and even some font viewers, use some kind of fallback where they use glyphs from other fonts to render missing characters. The book generation toolchain does not.
The Google Group for Leanpub was somewhat helpful: if I could recommend an Open Source mono space font that fit my needs, they'd likely include it in their toolchain.
So I searched and searched, learning more about fonts than I wanted to know. My circle of geek friends came up with several suggestions, one of them being Iosevka, which actually contains those characters. So now I wait for others to step up, either for LeanPub to include that font, or for the Noto maintainers to create a monospace variant of those characters (and then LeanPub updating their version of the font).
And all of that because Perl 6 was being innovative, and used two otherwise little-used characters as delimiters, in an attempt to avoid collisions between delimiters and content.
(In the mean time I've replaced the two offending characters with ones that look similar. It means the example output is technically incorrect, but at least it's readable).
At YAPC::EU 2010 in Pisa I received a business card with "Rakudo Star" and the
date July 29, 2010 which was the date of the first release -- a week earlier
with a countdown to 1200 UTC. I still have mine, although it has a tea stain
on it and I refreshed my memory over the holidays by listening again to Patrick
Michaud speaking about the launch of Rakudo Star (R*):
https://www.youtube.com/watch?v=MVb6m345J-Q
R* was originally intended as first of a number of distribution releases (as
opposed to a compiler release) -- useable for early adopters but not initially production
Quality. Other names had been considered at the time like Rakudo Beta (rejected as
sounding like "don't use this"!) and amusingly Rakudo Adventure Edition.
Finally it became Rakudo Whatever and Rakudo Star (since * means "whatever"!).
Well over 6 years later and we never did come up with a better name although there
was at least one IRC conversation about it and perhaps "Rakudo Star" is too
well established as a brand at this point anyway. R* is the Rakudo compiler, the main docs, a module installer, some modules and some further docs.
However, one radical change is happening soon and that is a move from panda to
zef as the module installer. Panda has served us well for many years but zef is
both more featureful and more actively maintained. Zef can also install Perl
6 modules off CPAN although the CPAN-side support is in its early days. There
is a zef branch (pull requests welcome!) and a tarball at:
http://pl6anet.org/drop/rakudo-star-2016.12.zef-beta2.tar.gz
Panda has been patched to warn that it will be removed and to advise the use of
zef. Of course anyone who really wants to use panda can reinstall it using zef
anyway.
The modules inside R* haven't changed much in a while. I am considering adding
DateTime::Format (shown by ecosystem stats to be widely used) and
HTTP::UserAgent (probably the best pure perl6 web client library right now).
Maybe some modules should also be removed (although this tends to be more
controversial!). I am also wondering about OpenSSL support (if the library is
available).
p6doc needs some more love as a command line utility since most of the focus
has been on the website docs and in fact some of these changes have impacted
adversely on command line use, eg. under Windows cmd.exe "perl 6" is no longer
correctly displayed by p6doc. I wonder if the website generation code should be
decoupled from the pure docs and p6doc command line (since R* has to ship any
new modules used by the website). p6doc also needs a better and faster search
(using sqlite?). R* also ships some tutorial docs including a PDF generated from perl6intro.com.
We only ship the English one and localisation to other languages could be
useful.
Currently R* is released roughly every three months (unless significant
breakage leads to a bug fix release). Problems tend to happen with the
less widely used systems (Windows and the various BSDs) and also with the
module installers and some modules. R* is useful in spotting these issues
missed by roast. Rakudo itself is still in rapid development. At some point a less frequently
updated distribution (Star LTS or MTS?) will be needed for Linux distribution
packagers and those using R* in production). There are also some question
marks over support for different language versions (6.c and 6.d).
Above all what R* (and Rakudo Perl 6 in general) needs is more people spending
more time working on it! JDFI! Hopefully this blog post might
encourage more people to get involved with github pull requests.
https://github.com/rakudo/star
Feedback, too, in the comments below is actively encouraged.
There is a Release Candidate for Rakudo Star 2016.11 (currently RC2) available at
http://pl6anet.org/drop/
This includes binary installers for Windows and Mac.
Usually Star is released about every three months but last month's release didn't include a Windows installer so there is another release.
I'm hoping to release the final version next weekend and would be grateful if people could try this out on as many systems as possible.
Any feedback email steve *dot* mynott *at* gmail *dot* com
Full draft announce at
https://github.com/rakudo/star/blob/master/docs/announce/2016.11.md
We turned up in Cluj via Wizz Air to probably one of the best pre YAPC parties ever located on three levels on the rooftop of Evozon’s plush city centre offices. We were well supplied with excellent wine, snacks and the local Ursus beer and had many interesting conversations with old friends.
On the first day Tux spoke about his Text::CSV modules for both Perl 5 and 6 on the first day and I did a short talk later in the day on benchmarking Perl 6. Only Nicholas understood my trainspotter joke slide with the APT and Deltic! Sadly my talk clashed with Lee J talking about Git which I wanted to see so I await the youtube version! Jeff G then spoke about Perl 6 and parsing languages such as JavaScript. Sadly I missed Leon T’s Perl 6 talk which I also plan on watching on youtube. Tina M gave an excellent talk on writing command line tools. She also started the lightning talks with an evangelical talk about how tmux was better than screen. Geoffrey A spoke about configuring sudo to run restricted commands in one directory which seemed a useful technique to me. Dave C continued his conference tradition of dusting off his Perl Vogue cover and showing it again. The age of the image was emphasised by the amazingly young looking mst on it. And Stefan S ended with a call for Perl unification.
The main social event was in the courtyard of the main museum off the central square with free food and beer all evening and an impressive light show on the slightly crumbling facade. There were some strange chairs which resembled cardboard origami but proved more comfortable than they looked when I was finally able to sit in one. The quality of the music improved as the evening progressed (or maybe the beer helped) I was amazed to see Perl Mongers actually dancing apparently inspired by the younger Cluj.pm members.
Day Two started with Sawyer’s State of the Velociraptor which he had, sensibly, subcontracted to various leading lights of the Perl Monger community. Sue S (former London.pm leader) was up first with a short and sweet description of London.pm. Todd R talked about Houston.pm. Aaron Crane spoke about the new improved friendlier p5p. Tina about Berlin.pm and the German Perl community site she had written back in the day. This new format worked very well and it was obvious Perl Mongers groups could learn much from each other. Max M followed with a talk about using Perl and ElasticSearch to index websites and documents and Job about accessibility.
1505 had, from the perspective of London.pm, one of the most unfortunate scheduling clashes at YAPC::EU ever, with three titans of London.pm (all former leaders) battling for audience share. I should perhaps tread carefully here lest bias become apparent but the heavyweight Sue Spence was, perhaps treacherously, talking about Go in the big room and Dave Cross and Tom talking about Perl errors and HTML forms respectively in the other rooms. This momentous event should be reproducible by playing all three talks together in separate windows once they are available.
Domm did a great talk on Postgres which made me keen to use this technology again. André W described how he got Perl 6 running on his Sailfish module phone while Larry did a good impression of a microphone stand. I missed most of Lance Wick’s talk but the bit I caught at the end made me eager to watch the whole thing.
Guinevere Nell gave a fascinating lightning talk about agent based economic modelling. Lauren Rosenfield spoke of porting (with permission) a “Python for CS” book to perl 6. Lukas Mai described his journey from Perl to Rust. Lee J talked about photography before Sue encouraged people to break the London.pm website. Outside the talk rooms on their stall Liz and Wendy had some highly cool stuffed toy Camelia butterflies produced by the Beverly Hills Teddy Bear Company and some strange “Camel Balls” bubblegum. At the end of the day Sue cat herded many Mongers to eat at the Enigma Steampunk Bar in central Cluj with the cunning ploy of free beer money (recycled from the previous year’s Sherry money).
The third day started with Larry’s Keynote in which photographs of an incredible American house “Fallingwater” and Chinese characters (including “arse rice”) featured heavily. Sweth C gave a fast and very useful introduction to swift. Nicholas C then confused a room of people for an hour with a mixture of real Perl 5 and 6 and an alternative timeline compete with T shirts. The positive conclusion was that even if the past had been different the present isn’t likely to have been much better for the Perl language family than it is now! Tom spoke about Code Review and Sawyer about new features in Perl 5.24. Later I heard Ilya talk about running Perl on his Raspberry PI Model B and increasing the speed of his application very significantly to compensate for its low speed! And we finished with lightning talks where we heard about the bug tracker OTRS (which was new to me), Job spoke about assistive tech and Nine asked us to ask our bosses for money for Perl development amongst several other talks. We clapped a lot in thanks, since this was clearly a particularly well organised YAPC::EU (due to Amalia and her team!) and left to eat pizza and fly away the next day. Some stayed to visit a salt mine (which looked most impressive from the pictures!) and some stayed longer due to Lufthansa cancelling their flights back!
The meeting first night was in a large beer bar in the centre of Nuremberg.
We went back to the Best Western to find a certain exPumpkin already resident in the bar.
Despite several of the well named Bitburgers we managed to arrive at the
conference venue on time the following morning. Since my knowledge of German was
limited to a C grade 'O' Level last century my review talks will be mostly
limited to English talks. Apologies in advance to those giving German talks
(not unreasonable considering the country). Hopefully other blog posts will
cover these.
Masak spoke about the dialectic between planning (like physics) and chaos (like
biology) in software development.
http://masak.org/carl/gpw-2016-domain-modeling/talk.pdf
Tobias gave a good beginners guide to Perl 6 in German and I was able to follow
most of the slides since I knew more Perl 6 than German and even learnt a thing
or two.
After lunch Stefan told us he was dancing around drunk and naked on the turn of
the 2000s and also about communication between Perl 6 and Perl 5 and back again
via his modules Inline::Perl5 (from Perl 6) -- the most important take away
being that "use Foo::Bar:from<Perl5>" can be used from Perl 6 and "use
Inline::Perl6" from Perl 5. The modules built bridges like those built in the
old school computer game "Lemmings".
http://niner.name/talks/Perl%205%20and%20Perl%206%20-%20a%20great%20team/Perl%205%20and%20Perl%206%20-%20a%20great%20team.odp
Max told us (in German) about his Dancer::SearchApp search
engine which has based on Elastic Search but I was able to follow along on the
English version of his slides on the web.
http://corion.net/talks/dancer-searchapp/dancer-searchapp.en.html
Sue got excited about this. Tina showed us some slides in Vim and her module
to add command line tab completion to script arguments using zsh and bash. I
wondered whether some of her code could be repurposed to add fish shell man
page parsing autocompletion to zsh. She also had a good lightening talk about
Ingy's command line utility for github.
https://github.com/perlpunk/myslides/tree/master/app-spec
Second day started early with Moritz talking about Continuous Delivery which
could mean just delivering to a staging server. He was writing a book about it
at deploybook.com with slides at:
https://deploybook.com/talks/gpw2016-continuous-delivery.pdf
Salve wanted us to write elegant code as a reply to the Perl Jam guy at CCC in
a self confessed "rant".
Sawyer described writing Ref::Util to optimise things like "ref $foo" in a
Hardcore Perl 5 XS/Core talk and Masak told us about his little 007 language
written in Perl 6 as a proof of concept playroom for future Perl 6 extended
macro support and demonstrated code written over lunch in support of this.
http://masak.org/carl/gpw-2016-big-hairy-yaks/talk.pdf
Stefan gave a great talk about CURLI and explained the complexity of what was
intended.
I gave my talk on "Simple Perl 6 Fractals and Concurrency" on Friday. It
started badly with AV issues my side but seemed well received. It was useful
speaking with people about it and I managed to speed things up *after* the talk
and I should have new material for a 2.0 version.
There were very good talks on extracting data from PDFs and writing JSON apis.
https://github.com/mickeyn/PONAPI
looked very interesting and would have saved me much coding at a recent job.
There were some great lightening talks at th end of the day. Sawyer wanted
people to have English slides and gave his talk in Hebrew to stress this.
Things ended Friday night with great food and beer in a local bar.
To me It seemed a particularly good FOSDEM for both for Perl5/6 and
other talks although very crowded as usual and I didn't see the usual
*BSD or Tor stalls. I was stuck by the statistic that there were
about 500 speakers from many thousands of people so of the order of
one speaker per tens of attendees which is very high.
Videos are already starting to appear at
On Saturday I started with Poettering and systemd which was a keynote
and perhaps a little disappointing since he usually is a better
speaker and the audio was a little indistinct. systemd had won being
used by all distros except gentoo and slackware. They were now working
on a dns resolver component which supported DNSSEC although in
practice validating signed zone files would slow down browsing and
currently only 2% of websites had it activated. He didn't mention
strong criticisms of its security by crypto experts such as DJB.
The most amusing talk was Stark's retro running of Postgres on
NetBSD/VAX which exposed some obscure OS bugs and was livened up by a
man in an impressive Postgres Elephant costume appearing. We later
spoke to Mr Elephant who said he was both blind and very hot at the
time. I then went to the Microkernel room to hear about GNU/Hurd
progress from Thibault since this room is usually "OPEN" and he's an
excellent speaker. I noticed even this obscure room was quite crowded
as compared with previous years so I'd guess total attendees this year
were high. He stressed the advantages of running device drivers in
userspace as allowing more user "freedom" to mount fs etc. without
root and improving kernel stability since the drivers could crash and
restart without bringing down the kernel. In previous years he had
talked of his DDE patches allowing linux 2.6 hardware drivers on Hurd
and this year he was using the NetBSD Rump kernel under Hurd to add
sound support with USB support promised. His demo was RMS singing his
song on his Hurd laptop. The irony was he needed to use BSD code on a
GNU/BSD/Hurd system to do it! There had been some work on X86-64 Hurd
but it wasn't there yet since he needed more help from the community.
I then saw some lightening talks (actually 20 mins long) including a
good one on C refactoring.
The Perl dinner on Saturday night featured the usual good food and
conversation and the devroom was on Sunday. Ovid spoke about Perl 6
and its advantages (such as being able to perform maths on floats
correctly). I had a python guy sitting next to me who admitted he had
never been to a Perl talk before so that was a success in reaching
someone new. Will Braswell spoke next about his "Rperl" compiler
which translated his own quite restricted subset (no regexps yet and
no $_) of Perl 5 line by line into C++ in order to run some of the
language shootups benchmarks (a graphical animation of planetary
motion) at increased speed. I'd not seen Will before and he was an
excellent speaker who left me more impressed than I'd expected and I
hope he gets to YAPC::EU in the summer. I saw some non-Perl stuff
next for variety including a good one on the Go debugger Delve which
was aware of the go concurrency and could be used as a basic REPL. I
returned to Perl to see Bart explain some surprisingly simple X86-64
assembly language to do addition and ROT13 which he interfaced with
Perl 6 using NativeCall (although it stuck me that the
CPAN P5NCI module on Perl 5 would have also worked).
Again an excellent talk and a good start to the a
run of some of the best Perl talks I'd ever seen. Stevan Little's talk
was one of the his most amusing ever and perl wasn't really dead.
Sawyer also did an excellent promotion of Perl 5 targeted at the
people who maybe hadn't used it since the early 2000s explaining what
had changed. Liz finished with her autobiographical account of Perl
development and some nice short Perl 6 examples. We all ate again in
the evening together my only regrets being I'd missed the odd talk or
two (which I should be able to watch on video).
MetaCPAN, like the rest of "CPAN", was built assuming the sole context of Perl5. Which is cool until we want to use it for Perl6 and avoid the troubles associated with different namespaces, dist mgmt, etc... To largely avoid and more easily handle these issues for MetaCPAN it's been suggested that we have separate instances. The existing Perl5 instance only needs to be changed to ignore Perl6 distributions. There has already been some breakage because it didn't ignore a Perl6 dist of mine which exists in the Perl5 world:( And the new Perl6 instance will do just the opposite and only look at Perl6 distributions.
In contrast, and relatedly, on CPAN we've designated a special spot for Perl6 distributions in order to keep them separate from the Perl5 dists. This reserved place is a Perl6 subdir in an author's dir (/author/id/*/*/*/Perl6/). Any dists in or under that spot on the fs will be considered a Perl6 dist; valid or invalid. So this is where the Perl6 MetaCPAN will look and the Perl5 instance will not.
Current development is being done on these temporary branches:
And the main dev instance is running on hack.p6c.org. The web end is at http://hack.p6c.org:5001 and the api is at http://hack.p6c.org:5000.
So far the idea has been to iterate on the aforementioned branches and instance until we have something that works sufficiently well. At that point we'll tidy up the branches and submit them for merging. Shortly after that time the hope is that we'll be able to stand up the official Perl6 instance.
The list of requirements for being adequately cooked is:
All of these have been hacked in and are at various degrees of completeness. Next up is testing and fixing bugs until nothing major is left. To that end I've recently loaded up the dev instance with all the distributions from modules.perl6.org. The dist files were generated, very hackily, with https://github.com/jdv/cpan-api/blob/master/test_p6_eco_to_p6_cpan.pl. I also just loaded them all under one user, mine, for simplicity. That load looks like it has problems of its own as well as revealing a bunch of issues. So in the coming days I hope to get that all sorted out.
In the Perl5 world, just in case anyone is unaware, CPAN is a major factor. Its basically the hub of the Perl5 world.
What I am referring to here as CPAN is not just the mirrored collection of 32K+ distributions. Its the ecosystem that's built up around that collection. This ecosystem has many parts, some more important than others depending on who you talk to, but the most important parts to me are:
These are the 5 aspects of "CPAN" that I'd like to see happen for Perl6. One way to get that would be to write the whole thing from scratch in Perl6. While it may sound cool in some sort of dogfoody and/or bootstrappy kind of way to some, it sounds like a lot of work to me and we're a bit strapped for developer resources. Another way would be to add support for Perl6 to the existing CPAN bits. The hope there being, primarily, that it'd be a lot less work. The latter approach is what I've been working on lately. And if we want to refactor ourselves off the Perl5 bits in the future we can take our time doing it; later.
At this time we have:So we can publish Perl6 distributions to CPAN and search that collection. Well, sort of on that last bit. The metacpan prototype instance is not currently tracking CPAN. Its actually been loaded up with Perl6 distributions from the Perl6 module ecosystem (modules.perl6.org) for testing. But hopefully soon we'll have an official Perl6 metacpan instance, separate from the Perl5 instance, that will track CPAN's Perl6 content as it should.
What we need next is:If anyone is interested in working on any of this stuff please stop by #perl6 on freenode. If nobody else is able to help you I'll (jdv79) do my best.
Thanks to those on Freenode IRC/perl6 for help.
Further corrections and expansions welcome either on iRC via pull request to https://github.com/stmuk/glr-html
| pre GLR | GLR |
|
| LIST IS NOW PARCEL |
> say (1,2,3).WHAT (Parcel) |
> say (1,2,3).WHAT (List) |
| LACK OF IMPLICIT LIST FLATTENING |
> my @array = 1,(2,3),4 1 2 3 4 > @array.elems 4 |
my @array = 1,(2,3),4 [1 (2 3) 4] > @array.elems 3 to flatten> my @list := 1, [2, 3], 4 (1 [2 3] 4) > dd @list.flat.list (1, 2, 3, 4) or> my @array = (1,(2,3),4).flat [1 2 3 4] or more complex structures (jnthn++)say gather [[[[["a", "b"], "c"], "a"], "d"], "e"].deepmap(*.take) |
| .lol METHOD REMOVED |
> dd (1,2,3).lol (1; 2; 3) |
|
| SINGLE ARG RULE |
> dd (1,) (1,) > dd [1,] $ = [1] > dd [[1,]] $ = [[1]] |
> dd (1,) (1) > dd [1,] [1] > dd [[1],] [[1],] |
| LIST NOW IMMUTABLE |
> my @array = 1,2,3 1 2 3 > @array.shift 1 > dd @array @array = [2, 3]<> |
> my @list := 1,2,3 (1 2 3) > @list.shift Method 'shift' not found for invocant of class 'List' > @list[0] 1 > dd @list (1, 2, 3) |
| ARRAY IS MUTABLE AND A SUBCLASS OF LIST |
> my @array = 1,2,3 [1 2 3] > @array[0]=0 0 > dd @array @array = [0, 2, 3] >say (Array).^mro ((Array) (List) (Cool) (Any) (Mu)) |
|
| SLIP SUBCLASS OF LIST |
> my @a = 1, (2, 3).Slip, 4 [1 2 3 4] > my $slip = slip(2,3) (2 3) > dd $slip Slip $slip = $(2, 3) > my @array = 1,$slip,4 [1 2 3 4] > (1,$(2,3),4) (1 (2 3) 4) > (1,|(2,3),4) (1 2 3 4) |
|
| SEQUENCE |
> my $grep = (1..4).grep(*>2); dd $grep>>.Int; (3, 4) > dd $grep>>.Int; This Seq has already been iterated, and its values consumed in block prevent consumption> my $grep = (1..4).grep(*>2); my $cache=$grep.cache (3 4) > say $cache>>.Int (3 4) > say $cache>>.Int (3 4) > my @array = 1,(2,3),4 [1 (2 3) 4] > dd @array.flat (1, $(2, 3), 4).Seq > dd @array.flat.list (1, $(2, 3), 4) |
So we are anticipating a long rollout cycle for PHP 6, and we did not want to take the same route that the Perl project did, with project contributors still working on Perl 6 I think six years later. People make fun of Microsoft, but take a look at Perl 6. . . .
Sure, PHP 6 may have a shorter release cycle than Perl 6 has, but at the end of it all, we'll have Perl 6, and you'll still have PHP.So how did those predictions work out? Well, after a little over six years of development, we discovered that we were never going to see a PHP 6 at all. Having seen how long Perl 6 had taken, and how long PHP 6 was taking, the number 6 is associated with failure. So they cancelled PHP 6 and voted to change the name to PHP 7. Problem solved! No, really, this is some of the actual reasoning given by people on the 6 to 7 RFC. (Someone should tell the ES6 folks before the curse strikes our browsers!)
Just sayin'.
xoxo,
Andy
print removed in favor of function print(), ostensibly to make a consistent API but really just to mess with people.At FOSDEM 2015, Larry announced that there will likely be a Perl 6 release candidate in 2015, possibly around the September timeframe. What we’re aiming for is concurrent publication of a language specification that has been implemented and tested in at least one usable compilation environment — i.e., Rakudo Perl 6.
So, for the rest of 2015, we can expect the Rakudo development team to be highly focused on doing only those things needed to prepare for the Perl 6 release later in the year. And, from previous planning and discussion, we know that there are three major areas that need work prior to release: the Great List Refactor (GLR), Native Shaped Arrays (NSA), and Normalization Form Grapheme (NFG).
…which brings us to Parrot. Each of the above items is made significantly more complicated by Rakudo’s ongoing support for Parrot, either because Parrot lacks key features needed for implementation (NSA, NFG) or because a lot of special-case code is being used to maintain adequate performance (lists and GLR).
At present most of the current userbase has switched over to MoarVM as the backend, for a multitude of reasons. And more importantly, there currently aren’t any Rakudo or NQP developers on hand that are eager to tackle these problems for Parrot.
In order to better focus our limited resources on the tasks needed for a Perl 6 language release later in the year, we’re expecting to suspend Rakudo’s support for the Parrot backend sometime shortly after the 2015.02 release.
Unfortunately the changes that need to be made, especially for the GLR, make it impractical to simply leave existing Parrot support in place and have it continue to work at a “degraded” level. Many of the underlying assumptions will be changing. It will instead be more effective to (re)build the new systems without Parrot support and then re-establish Parrot as if it is a new backend VM for Rakudo, following the techniques that were used to create JVM, MoarVM, and other backends for Rakudo.
NQP will continue to support Parrot as before; none of the Rakudo refactorings require any changes to NQP.
If there are people that want to work on refactoring Rakudo’s support for Parrot so that it’s more consistent with the other VMs, we can certainly point them in the right direction. For the GLR this will mainly consists of migrating parrot-specific code from Rakudo into NQP’s APIs. For the NSA and NFG work, it will involve developing a lot of new code and feature capabilities that Parrot doesn’t possess.
This past weekend I attended the 2014 Austrian Perl Workshop and Hackathon in Salzburg, which turned out to be an excellent way for me to catch up on recent changes to Perl 6 and Rakudo. I also wanted to participate directly in discussions about the Great List Refactor, which has been a longstanding topic in Rakudo development.
What exactly is the “Great List Refactor” (GLR)? For several years Rakudo developers and users have identified a number of problems with the existing implementation of list types — most notably performance. But we’ve also observed the need for user-facing changes in the design, especially in generating and flattening lists. So the term GLR now encompasses all of the list-related changes that seem to want to be made.
It’s a significant (“great”) refactor because our past experience has shown that small changes in the list implementation often have far-reaching effects. Almost any bit of rework of list fundamentals requires a fairly significant refactor throughout much of the codebase. This is because lists are so fundamental to how Perl 6 works internally, just like the object model. So, as the number of things that are desirable to fix or change has grown, so has the estimated size of the GLR effort, and the need to try to achieve it “all at once” rather than piecemeal.
The pressure to make progress on the GLR has been steadily increasing, and APW2014 was significant in that a lot of the key people needed for that would be in the same location. Everyone I’ve talked to agrees that APW2014 was a smashing success, and I believe that we’ve now resolved most of the remaining GLR design issues. The rest of this post will describe that.
This is an appropriate moment to recognize and thank the people behind the APW effort. The organizers did a great job. The Techno-Z and ncm.at venues were fantastic locations for our meetings and discussions, and I especially thank ncm.at, Techno-Z, yesterdigital, and vienna.pm for their generous support in providing venues and food at the event.
So, here’s my summary of GLR issues where we were able to reach significant progress and consensus.
(Be sure to visit our gift shop!)
Much of the GLR discussion at APW2014 concerned flattening list context in Perl 6. Over the past few months and years Perl 6 has slowly but steadily reduced the number of functions and operators that flatten by default. In fact, a very recent (and profound) change occurred within the last couple of months, when the .[] subscript operator for Parcels switched from flattening to non-flattening. To illustrate the difference, the expression
(10,(11,12,13),(14,15)).[2]
previously would flatten out the elements to return 12, but now no longer flattens and produces (14,15). As a related consequence, .elems no longer flattens either, changing from 6 to 3.
Unfortunately, this change created a inconsistency between Parcels and Lists, because .[] and .elems on Lists continued to flatten. Since programmers often don’t know (or care) when they’re working with a Parcel or a List, the inconsistency was becoming a significant pain point. Other inconsistencies were increasing as well: some methods like .sort, .pick, and .roll have become non-flattening, while other methods like .map, .grep, and .max continue to flatten. There’s been no really good guideline to know or decide which should do which.
Flattening behavior is great when you want it, which is a lot of the time. After all, that’s what Perl 5 does, and it’s a pretty popular language. But once a list is flattened it’s hard to get the original structure if you wanted that — flattening discards information.
So, after many animated discussions, review of lots of code snippets, and seeking some level of consistency, the consensus on Perl 6 flattening behavior seems to be:
[ ] array constructor are unchanged; they continue to flatten their input elements. (Arrays are naturally flat.)for @a,@b { ... } flattens @a,@b and applies the block to each element of @a followed by each element of @b. Note that flattening can easily be suppressed by itemization, thus for @a, $@b { ... } flattens @a but does all of @b in a single iteration..map, .grep, and .first… the programmer will have to use .flat.grep and .flat.first to flatten the list invocant. Notably, .map will no longer flatten its invocant — a significant change — but we’re introducing .for as a shortcut for .flat.map to preserve a direct isomorphism with the for statement.There’s ongoing conjecture of creating an operator or syntax for flattening, likely a postfix of some sort, so that something like .|grep would be a convenient alternative to .flat.grep, but it doesn’t appear that decision needs to be made as part of the GLR itself.((1,2), 3, (4,5)).map({...}) # iterates over three elements
map {...}, ((1,2),3,(4,5)) # iterates over five elements
(@a, @b, @c).pick(1) # picks one of three arrays
pick 1, @a, @b, @c # flatten arrays and pick one element
As a result of improvements in flattening consistency and behavior, it appears that we can eliminate the Parcel type altogether. There was almost unanimous agreement and enthusiasm at this notion, as having both the Parcel and List types is quite confusing.
Parcel was originally conceived for Perl 6 as a “hidden type” that programmers would rarely encounter, but it didn’t work out that way in practice. It’s nice that we may be able to hide it again — by eliminating it altogether. 
Thus infix:<,> will now create Lists directly. It’s likely that comma-Lists will be immutable, at least in the initial implementation. Later we may relax that restriction, although immutability also provides some optimization benefits, and Jonathan points out that may help to implement fixed-size Arrays.
Speaking of optimization, eliminating Parcel may be a big boost to performance, since Rakudo currently does a fair bit of converting Parcels to Lists and vice-versa, much of which goes away if everything is a List.
During a dinner discussion Jonathan reminded me that Synopsis 4 has all of the looping constructs as list generators, but Rakudo really only implements for at the moment. He also pointed out that if the loop generators are implemented, many functions that currently use gather/take could potentially use a loop instead, and this could be much more performant. After thinking on it a bit, I think Jonathan is on to something. For example, the code for IO::Handle.lines() currently does something like:
gather {
until not $!PIO.eof {
$!ins = $!ins + 1;
take self.get;
}
}
With a lazy while generator, it could be written as
(while not $!PIO.eof { $!ins++; self.get });
This is lazily processed, but doesn’t involve any of the exception or continuation handling that gather/take requires. And since while might choose to not be strictly lazy, but lines() definitely should be, we may also use the lazy statement prefix:
lazy while not $!PIO.eof { $!ins++; self.get };
The lazy prefix tells the list returned from the while that it’s to generate as lazily as it possibly can, only returning the minimum number of elements needed to satisfy each request.
So as part of the GLR, we’ll implement the lazy list forms of all of the looping constructs (for, while, until, repeat, loop). In the process I also plan to unify them under a single LoopIter type, which can avoid repetition and be heavily optimized.
This new loop iterator pattern should also make it possible to improve performance of for statements when performed in sink context. Currently for statements always generate calls to .map, passing the body of the loop as a closure. But in sink context the block of a for statement could potentially be inlined. This is the way blocks in most other loops are currently generated. Inlining the block of the body could greatly increase performance of for loops in sink context (which are quite common).
Many people are aware of the problem that constructs such as for and map aren’t “consuming” their input during processing. In other words, if you’re doing .map on a temporary list containing a million elements, the entire list stays around until all have been processed, which could eat up a lot of memory.
Naive solutions to this problem just don’t work — they carry lots of nasty side effects related to binding that led us to design immutable Iterators. We reviewed a few of them at the hackathon, and came back to the immutable Iterator we have now as the correct one. Part of the problem is that the current implementation is a little “leaky”, so that references to temporary objects hang around longer than we’d like and these keep the “processed” elements alive. The new implementation will plug some of the leaks, and then some judicious management of temporaries ought to take care of the rest.
In the past year much work has been done to improve sink context to Rakudo, but I’ve never felt the implementation we have now is what we really want. For one, the current approach bloats the codegen by adding a call to .sink after every sink-context statement (i.e., most of them). Also, this only handles sink for the object returned by a Routine — the Routine itself has no way of knowing it’s being called in sink context such that it could optimize what it produces (and not bother to calculate or return a result).
We’d really like each Routine to know when it’s being called in sink context. Perl 5 folks will instantly say “Hey, that’s wantarray!”, which we long ago determined isn’t generally feasible in Perl 6.
However, although a generalized wantarray is still out of reach, we can provide it for the limited case of detecting sink contexts that we’re generating now, since those are all statically determined. This means a Routine can check if it’s been called in sink context, and use that to select a different codepath or result. Jonathan speculates that the mechanism will be a flag in the callsite, and I further speculate the Routine will have a macro-like keyword to check that flag.
Even with detecting context, we still want any objects returned by a Routine to have .sink invoked on them. Instead of generating code for this after each sink-level statement, we can do it as part of the general return handler for Routines; a Routine in sink context invokes .sink on the object it would’ve otherwise returned to the caller. This directly leads to other potential optimizations: we can avoid .sink on some objects altogether by checking their type, and the return handler probably doesn’t need to do any decontainerizing on the return value.
As happy as I am to have discovered this way to pass sink context down into Routines, please don’t take this as opening an easy path to lots of other wantarray-like capabilities in Perl 6. There may be others, and we can look for them, but I believe sink context’s static nature (as well as the fact that a false negative generally isn’t harmful) makes it quite a special case.
One area that has always been ambiguous in the Synopses is determining when various contextualizing methods must return a copy or are allowed to return self. For example, if I invoke .values on a List object, can I just return self, or must I return a clone that can be modified without affecting the original? What about .list and .flat on an already-flattened list?
The ultra-safe answer here is probably to always return a copy… but that can leave us with a lot of (intermediate) copies being made and lying around. Always returning self leads to unwanted action-at-a-distance bugs.
After discussion with Larry and Jonathan, I’ve decided that true contextualizers like .list and .flat are allowed to return self, but other method are generally obligated to return an independent object. This seems to work well for all of the methods I’ve considered thus far, and may be a general pattern that extends to contextualizers outside of the GLR.
(small matter of programming and documentation)
The synopses — especially Synopsis 7 — have always been problematic in describing how lists work in Perl 6. The details given for lists have often been conjectural ideas that quickly prove to epic fail in practice. The last major list implementation was done in Summer 2010, and Synopsis 7 was supposed to be updated to reflect this design. However, the ongoing inconsistencies (that have led to the GLR) really precluded any meaningful update to the synopses.
With the progress recently made at APW2014, I’m really comfortable about where the Great List Refactor is leading us. It won’t be a trivial effort; there will be significant rewrite and refactor of the current Rakudo codebase, most of which will have to be done in a branch. And of course we’ll have to do a lot of testing, not only of the Perl 6 test suite but also the impact on the module ecosystem. But now that much of the hard decisions have been made, we have a roadmap that I hope will enable most of the GLR to be complete and documented in the synopses by Thanksgiving 2014.
Stay tuned.
"I'm just happy that the two of you liked my work." -- vanstynAlthough he was talking about DBIx, I think that captures the spirit of conference as a whole. All of us here -- from the n00bs to the pumpkings -- want to share our work and make something useful for others. It's not an organization where we wait for pronouncements from on high, but one where users create endless variations and share them. Not an organization so much as a family.
"We have faith, hope, and love, but the most awesome of these is love." -- Larry WallA line like this might seem a bit hokey out of context, but it was actually moving when I heard it. We have faith that we can use Perl to solve our problems. We have hope that Perl 5 and 6 will continue to get better. And we love Perl, unconditionally, despite all of her flaws. And as Wil Wheaton says about us geeks, we just want to love our special thing the best we can, and go the extra mile to share it with others.
[This is a response to the Russian Perl Podcast transcribed by Peter Rabbitson and discussed at blogs.perl.org.]
I found this translation and podcast to be interesting and useful, thanks to all who put it together.
Since there seems to have been some disappointment that Perl 6 developers didn’t join in the discussions about “Perl 7” earlier this year, and in the podcast I’m specifically mentioned by name, I thought I’d go ahead and comment now and try to improve the record a bit.
While I can’t speak for the other Perl 6 developers, in my case I didn’t contribute to the discussion because nearly all the things I would’ve said were already being said better by others such as Larry, rjbs, mst, chromatic, etc. I think a “Perl 7” rebrand is the wrong approach, for exactly the reasons they give.
A couple of statements in the podcast refer to “hurting the feelings of Perl 6 developers” as being a problem resulting from a rebrand to Perl 7. I greatly appreciate that people are concerned with the possible impact of a Perl 5 rebrand on Perl 6 developers and our progress. I believe that Perl 6’s success or failure at this point will have little to do with the fact that “6 is larger than 5”. I don’t find the basic notion of “Perl 7” offensive or directly threatening to Perl 6.
But I fully agree with mst that “you can’t … have two successive numbers in two brands and not expect people to be confused.” We already have problems explaining “5” and “6” — adding more small integers to the explanation would just make an existing problem even worse, and wouldn’t do anything to address the fundamental problems Perl 6 was intended to resolve.
Since respected voices in the community were already saying the things I thought about the name “Perl 7”, I felt that adding my voice to that chorus could only be more distracting than helpful to the discussion. My involvement would inject speculations on the motivations of Perl 6 developers into what is properly a discussion about how to promote progress with Perl 5. I suspect that other Perl 6 developers independently arrived at similar conclusions and kept silent as well (Larry being a notable exception).
I’d also like to remark on a couple of @sharifulin’s comments in the podcast (acknowledging that the transcribed comments may be imprecise in the translation from Russian):
First, I’m absolutely not the “sole developer” of Perl 6 (13:23 in the podcast), or even the sole developer of Rakudo Perl 6. Frankly I think it’s hugely disrespectful to so flippantly ignore the contributions of others in the Perl 6 development community. Let’s put some actual facts into this discussion… in the past twelve months there have been over 6,500 commits from over 70 committers to the various Perl 6 related repositories (excluding module repositories), less than 4% (218) of those commits are from me. Take a look at the author lists from the Perl 6 commit logs and you may be a little surprised at some of the people you find listed there.
Second, there is not any sense in which I think that clicking “Like” on a Facebook posting could be considered “admitting defeat” (13:39 in the podcast). For one, my “Like” was actually liking rjbs’ reply to mst’s proposal, as correctly noted in the footnotes (thanks Peter!).
But more importantly, I just don’t believe that Perl 5 and Perl 6 are in a battle that requires there to be a conquerer, a vanquished, or an admission of defeat.
Pm
$foo->WHAT can tell you if you have a Str, Int, or IO::Handle. $path =~ s/^([a-z]:)/\l$1/s;//server/share) that OS2.pm had only half-implemented. And so a huge block of code cruft bit the dust.sub _tmpdir {
my $self = shift;
my @dirlist = @_;
my $tmpdir;
foreach (@dirlist) {
next unless defined && -d && -w _;
$tmpdir = $_;
last;
}
return $self->canonpath($tmpdir);
}$_, @_, and shift.method !tmpdir( *@dirlist ) {
my $tmpdir = first { .defined && .IO.w && .IO.d }, @dirlist;
return self.canonpath($tmpdir);
}$tmpdir to the first defined writable directory in @dirlist." Less, easier to read code is easier to maintain.if( $foo ) to if $foo, etc.git, and make -- enough to commit to repositories and build a software package, anyway.git clone it to on your own machine.rakudo directory. There are a few setup things that you'll want to do. First of all, go ahead and build Rakudo, using the normal steps: perl ./Configure.pl --gen-parrot
make
make install$PATH environment variable. Which, if you don't know how to do it -- well here's Google. In particular, you'll need to add the full path to the rakudo/install/bin directory. make spectestt/spec before hitting ^C. You will need these tests later to make sure you didn't break anything. git remote add upstream git://github.com/rakudo/rakudo.git git clone git://github.com/tadzik/panda.git
cd panda
perl6 bootstrap.pl git checkout -b mynewbranchnamerakudo/src folder, so this is where you'll want to edit the contents.vm directory contains files specific to the virtual machines Rakudo runs under. At this time of this writing, there's only one thing in there, parrot, but very soon there will also be a jvm directory. Exciting! Most of the purpose of this code is to map functions to lower-level operations, in either Parrot or Java.Perl6 directory contains the grammar and actions used to build the language, as well as the object metamodel. The contents of this folder are written in NQP, or Not Quite Perl. This section determines how the language is parsed.core directory contains the files that will be built into the core setting. You'll find classes or subroutines in here for just about everything in Perl: strings, operators like eq, filehandles, sets, and more. Individual files look similar to modules, but these are "modules" that are available to every Perl 6 program.gen directory contains files that are created in the compliation process. The core setting lives here, creatively named CORE.setting. And if you look at it, it's just a concatenation of the files in core, put together in the order specified in rakudo/tools/build/Makefile.in. While these files can and do get overwritten in the build process, it's often a good idea to keep a copy of CORE.setting open so you can find what you're looking for faster -- and then go edit it in core.git bisect for problems later. And push your edits to Github as a free backup. If you get stuck, drop by #perl6 on irc.freenode.net and ask questions. git fetch upstream
git merge upstream/nom
perl Configure.pl
make
make spectest #?pugs 1 skip 'reason'
#?niecza 1 skip 'reason'rakudo/t/spectest.data. If your code fixes broken tests, then you'll want to *unfudge* by removing the #?rakudo skip lines above the relevant tests. perl6 panda/rebootstrap.plgit commit; git push will add it to the ticket. If there aren't any problems, someone will just merge it in a couple days.At YAPC::NA 2012 in Madison, WI I gave a lightning talk about basic improvements in Rakudo’s performance over the past couple of years. Earlier today the video of the lightning talks session appeared on YouTube; I’ve clipped out my talk from the session into a separate video below. Enjoy!
A couple of weeks ago I entered the Dallas Personal Robotics Group Roborama 2012a competition, and managed to come away with first place in the RoboColumbus event and Line Following event (Senior Level). For my robot I used one of the LEGO Mindstorms sets that we’ve been acquiring for use by our First Lego League team, along with various 3rd party sensors.
The goal of the RoboColumbus event was to build a robot that could navigate from a starting point to an ending point placed as far apart as possible; robots are scored on distance to the target when the robot stops. If multiple robots touch the finish marker (i.e., distance zero), then the time needed to complete the course determines the rankings. This year’s event was in a long hall with the target marked by an orange traffic cone.
HiTechnic IR ball and IRSeeker sensor
Contestants are allowed to make minor modifications to the course to aid navigation, so I equipped my robot with a HiTechnic IRSeeker sensor and put an infrared (IR) electronic ball on top of the traffic cone. The IRSeeker sensor reports the relative direction to the ball (in multiples of 30 degrees), so the robot simply traveled forward until the sensor picked up the IR signal, then used the IR to home in on the traffic cone. You can see the results of the winning run in the video below, especially around the 0:33 mark when the robot makes its first significant IR correction:
http://youtu.be/x1GvpYAArfY
My first two runs of RoboColumbus didn’t do nearly as well; the robot kept curving to the right for a variety of reasons, and so it never got a lock on the IR ball. Some quick program changes at the contest and adjustments to the starting direction finally made for the winning run.
For the Line Following contest, the course consisted of white vinyl tiles with electrical tape in various patterns, including line gaps and sharp angles. I used a LineLeader sensor from mindsensors.com for basic line following, with some heuristics for handling the gap conditions. The robot performed fine on my test tiles at home, but had difficulty with the “gap S curve” tiles used at the contest. However, my robot was the only one that successfully navigated the right angle turns, so I still ended up with first place.
Matthew and Anthony from our FLL robotics team also won other events in the contest, and there are more videos and photos available. The contest was a huge amount of fun and I’m already working on new robot designs for the next competition.
Many thanks to DPRG and the contest sponsors for putting on a great competition!