DEV Community: Fernando Correa de Oliveira

Crolite: filling the "Mojolicious::Lite" gap in the Cro ecosystem

Fernando Correa de Oliveira — Sun, 28 Sep 2025 00:28:31 +0000

Introduction

When I start something new in Raku with Cro, I almost always begin with a mental sketch: two or three routes, a response shape, maybe a typed segment. In the Perl world I leaned heavily on Mojolicious::Lite for that prototyping phase. In Cro—powerful and modular as it is—I missed an immediate “lite mode”: no manual wiring of server, pipeline, and router just to test a thought. Out of that friction came Crolite: a thin layer that re‑exports Cro's routing keywords and adds a multi MAIN with quick exploration commands.

What Crolite Is

Goal: Make minimal HTTP prototypes trivial while ideas mature.
Approach: Reuse Cro's router directly; no new DSL.
Deliverable: A collected RouteSet + a tiny embedded CLI.
Philosophy: “Start now; graduate later to a full Cro app.”

Installation

From a local checkout (inside the project directory):

zef install .

Once published:

zef install Crolite

First Example

File example.raku:

use Crolite;

get -> $any {
    content 'text/plain', "Hello: $any";
}

delete -> 'thing', Int $id {
    content 'application/json', %( :$id );
}

List derived routes:

raku example.raku routes

Run a development server:

raku example.raku --host=127.0.0.1 --port=3000 daemon

Test a route without a persistent daemon (ephemeral in‑memory request):

raku example.raku GET /thing/42

Suggested Workflow

Sketch routes and response formats.
Run raku app.raku routes to confirm patterns.
Fire single requests: raku app.raku GET /foo/123.
Iterate until it stabilizes.
Promote to a full Cro project if you need richer middleware, structured logging, TLS, etc.

CLI Options

Command	Purpose
`routes`	Print summary of registered endpoints
`[--host=0.0.0.0] [--port=10000] daemon`	Start simple Cro server
`GET <path>`	Single in‑memory GET
`POST <path>`	Single POST (no custom body)
`PUT <path>`	Single PUT
`DELETE <path>`	Single DELETE
`--method=<VERB> http <path>`	Generic form for any method

Stop the daemon with Ctrl+C (SIGINT is trapped for graceful shutdown).

Dynamic Segments & Typing

use Crolite;

get -> 'greet', Str $name {
    content 'text/plain', "Hi $name!";
}

post -> 'sum', Int $a, Int $b {
    content 'application/json', %( total => $a + $b );
}

Test:

raku app.raku GET /greet/Ana
raku app.raku POST /sum/2/5

Returning JSON

Just produce a Hash or Map:

get -> 'status' {
    content 'application/json', %( service => 'ok', ts => DateTime.now );
}

Hooks (Before / After)

If you manually add before or after handlers to the underlying RouteSet, Crolite includes them when composing the application for daemon:

use Crolite;

$*CRO-ROUTE-SET.before: {
    # Simple logging / auth stub
    proceed;
}

get -> 'ping' { content 'text/plain', 'pong' }

More Complete Example

use Crolite;

get -> 'health' {
    content 'application/json', %( ok => True );
}

put -> 'echo', Str $msg {
    content 'text/plain', $msg.uc;
}

post -> 'calc', Int $x, Int $y {
    content 'application/json', %( sum => $x + $y, prod => $x * $y );
}

delete -> 'soft', Int $id {
    content 'application/json', %( deleted => $id, soft => True );
}

Quick ping:

raku app.raku GET /health

Server:

raku app.raku --port=4000 daemon

Ergonomics While Prototyping

Rapid changes: Save & re‑run; no auto‑reloader (yet).
Inspection: routes surfaces path typos immediately.
Atomic requests: Avoids opening another terminal for curl just to see a body.

Current Limitations

No structured logging out of the box.
No built‑in TLS / websockets / streaming presets.
No hot reload.
Experimental API (may shift).

When to Migrate to a Full Cro App

You need chained middleware (auth, tracing, rate limiting).
You require richer body parsing / serialization customization.
You integrate multiple services or supervised components.
You need observability (metrics, distributed tracing, advanced logs).

Possible Future Roadmap

Optional reload in daemon mode.
Alternate tabular output for routes.
Lightweight latency / metrics helper.
Test skeleton generator for promotion phase.

Quick Testing Tips

Use the embedded CLI to validate the contract before formal tests.
When formalizing, reuse Cro::HTTP::Test (mirrors what the CLI verbs do).

Wrapping Up

Crolite does not compete with the full flexibility of a structured Cro project; it lowers the time to first useful response when exploring HTTP ideas in Raku. If you also miss the lightness of Mojolicious::Lite, try making the first step of each spike just:

use Crolite;

Then, once the shape hardens, graduate to something more robust.

Suggestions, issues, and PRs welcome.

Typed, Named Endpoints for Cro (with HTMX Helpers)

Fernando Correa de Oliveira — Sun, 21 Sep 2025 22:14:23 +0000

Cro’s HTTP router is great at declaring routes, but it doesn’t provide a first‑class way to reference those routes elsewhere in your app. Cro::HTTP::RouterUtils fills that gap: it lets you reference endpoints by name, build typed-safe paths, generate HTMX attributes, redirect to routes, and even call the underlying implementation.

Stable references to routes by name (or auto‑named fallback)
Typed path() builder validates parameter types
hx-attrs() renders HTMX attributes with the correct method and URL
redirect-to() returns a Cro redirect to the endpoint
call() invokes the route implementation directly (handy for tests)
Supports include with prefixes seamlessly

Repo: https://github.com/FCO/Cro-HTTP-RouterUtils

Install

zef install --depsonly .

Quick Start

use Cro::HTTP::RouterUtils;

my $app = route {
    # Name a route via a named sub
    get my sub greet-path('greet', $name) {
        content 'text/plain', "Hello, $name!"
    }

    # Use the endpoint by name
    get -> 'links' {
        my $ep = endpoints('greet-path');
        content 'text/html', qq:to/END/
            <a href="{ $ep.path(:name<alice>) }">alice</a>
            <a href="#" { $ep.hx-attrs(:name<bob>, :trigger<click>) }>bob</a>
        END
    }
}

Naming and Discovering Endpoints

Named endpoints: give your route a function name and reference it with endpoints('your-name').
Auto‑named endpoints: when no name is provided, keys are generated from method and path signature, e.g. get_greet.

# Auto-named
get -> 'greet', Str :$name { 200 }
endpoints('get_greet').path;  # => "/greet"

# Named
get my sub greet-path('greet', $name) { "Hello, $name!" }
endpoints('greet-path').path(:name<alice>);  # => "/greet/alice"

Includes with prefixes are supported transparently:

include external => other-routes;   # /external prefix applied

endpoints('external-ep1').method;   # "GET"
endpoints('external-ep1').path;     # "/external/returns-ok"

Typed Path Building

path(*%values) enforces your route’s typed parameters; missing or invalid values throw.

get my sub sum('sum', Int $a, Int $b) { $a + $b }

my $ep = endpoints('sum');
$ep.path(:a(1), :b(2));          # "/sum/1/2"
$ep.path(:a("x"), :b(2));        # throws (type mismatch)
$ep.path(:a(1));                 # throws (missing parameter)

HTMX Helpers

hx-attrs(:args…) returns a space-separated string of HTMX attributes. It uses the endpoint’s HTTP method by default (e.g., hx-get) and the built URL.

<a href="#"
   { endpoints('greet-path').hx-attrs(
       :name<alice>,
       :trigger<click>,
       :target<#out>,
       :swap<'outerHTML settle:200ms'>,
       :push-url<true>,
       :on{ click => "console.log(\"clicked\")" }
     )
   }>
  Load Alice
</a>

Highlights supported:

Request URL/method: method override; parameters via :name<...> etc.
Core: trigger, target, confirm, indicator, swap, oob (as hx-swap-oob), boost
Navigation: push-url (Bool|Str), replace-url (Bool|Str)
Selection: select, select-oob
JSON: vals, headers, request
Flags: disable, validate
Misc: disabled-elt, disinherit, encoding, ext, history, history-elt, include, inherit, params, prompt, sync, vars (deprecated)
Events: :on{ event => "code" } emits hx-on:event='code'

Example minimal output:

hx-get='/greet/alice' hx-trigger='click' hx-target='#out'

Redirects

get -> 'redir' {
    endpoints('greet-path').redirect-to: :name<ok>
}

Calling the Implementation

call(|args) invokes the underlying route implementation. Literal path segments are auto-injected; you pass only the non-literal parameters.

get my sub ret('ret') { 42 }
get my sub sum('sum', Int $a, Int $b) { $a + $b }

endpoints('ret').call;        # 42
endpoints('sum').call(2, 3);  # 5

Great for unit tests of pure route logic. If you depend on Cro’s pipeline, prefer Cro::HTTP::Test.

Full Example

See examples/example.raku and examples/ExampleRoute.rakumod in the repo. Run:

raku examples/example.raku

Then visit:

/form for a classic form
/links for <a href> links built from endpoints
/links-htmx for HTMX-driven links

Errors and Guarantees

Unknown endpoint name: throws.
Missing/invalid path params: throws with a clear message.
call() auto-injects literal path segments; you provide the rest.

Why This Isn’t in Cro

Cro focuses on routing and request handling. This utility adds “endpoint as a value” ergonomics—stable references, typed path building, HTMX helpers, and redirect/call helpers—while staying a thin layer on top of Cro::HTTP::Router.

Appendix: Include With Prefix Example

# examples/ExampleRoute.rakumod
use Cro::HTTP::RouterUtils;

sub other-routes is export {
  route {
    get  my sub external-ep1("returns-ok")  { content "text/plain", "OK" }
    post my sub external-ep2("using-post")  { content "text/plain", "OK" }
  }
}

# elsewhere
include external => other-routes;
endpoints('external-ep1').path;  # "/external/returns-ok"
endpoints('external-ep2').path;  # "/external/using-post"

—
Made with Cro::HTTP::RouterUtils (Raku).

From ASTs to RakuAST to ASTQuery

Fernando Correa de Oliveira — Sun, 14 Sep 2025 00:39:59 +0000

Precise code search and transformation for Raku

Raku’s RakuAST opens up a powerful way to analyze and transform code by working directly with its Abstract Syntax Tree (AST). ASTQuery builds on that by offering a compact, expressive query language to find the nodes you care about,
capture them, and even drive compile-time rewrites.

This guide explains:

What ASTs are and why they matter
What RakuAST provides
How to search ASTs and build macro-like passes
How ASTQuery’s selector language works
Practical examples: queries, captures, attribute filters, and rewrites

ASTs, Briefly

What: An AST is a structured, typed tree that represents your code after parsing (e.g., “call”, “operator application”, “variable”).
Why: Compilers, linters, and refactoring tools operate on ASTs because they capture code semantics, not just text. This enables robust search and safe transformations.

What Is RakuAST?

Raku’s AST: RakuAST is the new, structured representation of Raku code. It exposes node types like RakuAST::Call, RakuAST::ApplyInfix, RakuAST::Var, and more.
Access: my $ast = $code.AST; for strings, or $*CU for the current compilation unit in a CHECK phaser.
Status: RakuAST is still experimental. Some node fields may not be rw on your Rakudo; rebuild/replace enclosing nodes when needed.

Why Search ASTs?

Beyond grep: Find “function calls with an Int somewhere under args”, not just text matches.
Safer refactors: Target particular node shapes and attributes to avoid false positives.
Automated upgrades: Write codemods that transform legacy patterns into new APIs.

Macro-Like Passes (Compiler-Time Rewrites)

Use a CHECK phaser with use experimental :rakuast; to inspect/modify $*CU before runtime.
Typical flow: 1) Fetch $*CU 2) Query nodes with ASTQuery 3) Mutate nodes (or rebuild if fields aren’t rw) (How mutable RakuAST needs to be is still being discussed)

Example: Add '!!!' at the end of every say call.

use experimental :rakuast;
use ASTQuery;

CHECK {
    my $ast = $*CU;
    for $ast.&ast-query(Q|.call#say|).list {
        .args.push: RakuAST::StrLiteral.new: "!!!";
    }
}
say "some text"; # prints "some text!!!"

ASTQuery, at a Glance

• Query language: Describe node kinds, relationships (child/descendant/ancestor), and attributes succinctly.
• Captures: Name nodes you want to retrieve with $name.
• Functions: Reusable predicates referenced with &name.
• Programmatic API: ast-query and ast-matcher.
• CLI: Query files and print results in a readable form.

Quickstart

use ASTQuery;

my $code = q:to/CODE/;
    sub f($x) { }
    f 42;
    say 1 * 3;
CODE

my $ast = $code.AST;

# Find Apply operator nodes where left=1 and right=3
my $ops = $ast.&ast-query('.apply-operator[left=1, right=3]');
say $ops.list;

# Find calls that have an Int somewhere under args
my $calls = $ast.&ast-query('&is-call[args=>>>.int]');
say $calls.list;

Selector Language

Node description format:

RakuAST::Class::Name.group#id[attr1, attr2=attrvalue]$name&function

Components:

• RakuAST::Class::Name: Optional full class name.
• .group: Optional node group (alias to multiple classes).
• #id: Optional id value compared against the node’s id field (per-type mapping).
• [attributes]: Optional attribute matchers (see below).
• $name: Optional capture name (one per node part).
• &function: Optional function matcher (compose with AND when multiple).

Relationship operators:

• >: Left has right as a child.
• >>: Left has right as a descendant, skipping only ignorable nodes.
• >>>: Left has right as a descendant (any nodes allowed between).
• <: Right is the parent of left.
• <<: Right is an ancestor of left, skipping only ignorable nodes.
• <<<: Right is an ancestor of left (any nodes allowed between).
• Note: The space operator is no longer used.

Ignorable nodes (skipped by >>/<<):

• RakuAST::Block, RakuAST::Blockoid, RakuAST::StatementList,
RakuAST::Statement::Expression, RakuAST::ArgList

Attribute relation operators (start traversal from attribute value when it is a RakuAST node):

• [attr=>MATCH] child
• [attr=>>MATCH] descendant via ignorable nodes
• [attr=>>>MATCH] descendant (any nodes)

Attribute value operators (compare against a literal, identifier, or regex literal):

• [attr~=value] contains (substring) or regex match
• [attr^=value] starts-with
• [attr$=value] ends-with
• [attr*=/regex/] regex literal

Notes:
• When an attribute holds a RakuAST node, the matcher walks nested nodes via configured id fields to reach a comparable
leaf (e.g., .call[name] → Name’s identifier).
• Non-existent attributes never match.

Captures:

• Append $name to capture the current node part, e.g., .call#say$call then access with $match<call>.

Functions:

• Use &name to apply reusable predicates; multiple functions compose with AND.

Built-in Groups and Functions

Common groups:

• .call → RakuAST::Call
• .apply-operator → RakuAST::ApplyInfix|ApplyListInfix|ApplyPostfix|Ternary
• .operator → RakuAST::Infixish|Prefixish|Postfixish
• .conditional → RakuAST::Statement::IfWith|Unless|Without
• .variable, .variable-usage, .variable-declaration
• .statement, .expression, .int, .str, .ignorable

Built-in &functions:

• &is-call, &is-operator, &is-apply-operator
• &is-assignment, &is-conditional
• &has-var, &has-call, &has-int

See REFERENCE.md for the full, authoritative list of groups, functions, and id fields.

ID Fields (#id) and How Matching Works

• Each RakuAST type maps to an “id field” used for #id comparisons (e.g., RakuAST::Call uses name, RakuAST::Infix uses
operator, literals use value).
• When comparing attributes whose value is a RakuAST node, ASTQuery walks down by id fields until reaching a leaf value
to compare.
• For variable declarations, bare ids strip sigils for comparison:
• .variable-declaration#x matches my $x, even though the declaration’s name includes the sigil internally (if needed, you can always use [name="$x"]).

Examples

Find specific infix applications (left=1, right=3):

my $code = q{
    for ^10 {
        if $_ %% 2 {
            say 1 * 3;
        }
    }
};
my $ast = $code.AST;

my $result = $ast.&ast-query: Q|.apply-operator[left=1, right=3]|;

# ast-query returns a ASTQuery::Match object
say $result.list;

If you print the object itself, instead of getting the list of matched nodes, it will print something like this:

Use ancestor operator <<< with captures:

my $result = $ast.&ast-query('RakuAST::Infix <<< .conditional$cond .int#2$int');
say $result.list;  # infix nodes
say $result.hash;  # captured 'cond' and 'int'

Parent operator < and capturing:

my $result = $ast.&ast-query('RakuAST::Infix < .apply-operator[right=2]$op');
say $result<op>;   # ApplyInfix nodes with right=2

Descendant operator >>> and capturing a variable:

my $result = $ast.&ast-query('.call >>> RakuAST::Var$var');
say $result.list;  # call nodes
say $result.hash;  # captured 'var'

Attribute relation traversal (from attribute node):

# Calls that have an Int somewhere under args:
my $calls = $ast.&ast-query('&is-call[args=>>>.int]');

Attribute value operators:

# Calls whose name contains "sa" (e.g., say)
my $q1 = $ast.&ast-query('.call[name~= "sa"]');

# Calls whose name starts with "s"
my $q2 = $ast.&ast-query('.call[name^= "s"]');

# Calls whose name ends with "y"
my $q3 = $ast.&ast-query('.call[name$= "y"]');

# Calls whose name matches /sa.*/
my $q4 = $ast.&ast-query('.call[name*=/sa.*/]');

Capturing and retrieving nodes:

my $m = $ast.&ast-query('.call#say$call');
my $call-node = $m<call>;
my @matched = $m.list;

Reusable Function Matchers

• From a compiled matcher:

my $m = ast-matcher('.call#f');
new-function('&f-call', $m);
$ast.&ast-query('&f-call');

• From a callable:

new-function('&single-argument-call' => -> $n {
    $n.^name.starts-with('RakuAST::Call')
    && $n.args.defined
    && $n.args.args.defined
    && $n.args.args.elems == 1
});
$ast.&ast-query('&single-argument-call');

• From a selector string:

new-function('&var-decl' => '.variable-declaration');
$ast.&ast-query('&var-decl');

Programmatic API

• ast-query($ast, Str $selector) / ast-query($ast, $matcher): Run a query and get an ASTQuery::Match (acts like
Positional + Associative).
• ast-matcher(Str $selector): Compile a selector once and reuse it.
• new-function($name, $callable|$matcher|$selector): Register &name.
• add-ast-group($name, @classes) / add-to-ast-group($name, *@classes): Define/extend group aliases.
• set-ast-id($class, $id-method): Configure which attribute is used as the id for #id and nested value matching.

CLI Usage

• Run against a directory or single file:
• ast-query.raku 'SELECTOR' [path]
• If path is omitted, it scans the current directory recursively.
• Extensions scanned: raku, rakumod, rakutest, rakuconfig, p6, pl6, pm6.
• Example:
• ast-query.raku '.call#say >>> .int' lib/

Debugging Selectors

• Set ASTQUERY_DEBUG=1 to print a colored tree of matcher decisions, including deparsed node snippets and pass/fail per
validator step. This helps understand why a node matched—or didn’t.

Notes and Caveats

• RakuAST is experimental. It's still being discussed how mutable it will be.
• Regex flags in /.../ literals aren’t supported in attribute value operators yet.
• The old “space operator” for relationships is deprecated; use the explicit operators (>, >>, >>>, <, <<, <<<).

Conclusion

ASTQuery lets you describe meaningful shapes in RakuAST—calls, operators, variables, and more—compose those
descriptions, capture the nodes you want, and apply them to everything from precise code search to automated
compiler-time refactorings. It’s a compact tool for robust code understanding and transformation.

• Repo: https://github.com/FCO/ASTQuery
• See REFERENCE.md for the complete catalog of groups, built-in functions, and id fields.

🎮 ECS in Raku: A Toy Framework for Entities, Components, and Systems

Fernando Correa de Oliveira — Sun, 27 Jul 2025 19:36:03 +0000

⚠️ Note: This is a personal experiment. I’m not experienced in game development or ECS, and I’ve only recently learned about these concepts. This framework is not production-ready, and the API is still in flux. But I’d love your feedback! 🙏

🧠 What is ECS?

ECS stands for Entity-Component-System, a popular architecture pattern in game development.

Entities are just unique identifiers.
Components are data — like position, velocity, health, etc.
Systems are the logic that runs on entities with certain components.

Instead of having objects with both data and behavior (like in OOP), ECS separates those concerns cleanly. It encourages data-driven design and enables powerful querying and parallelism (though we’re far from that in this toy project).

🧱 What’s an Archetype?

This ECS implementation uses the concept of archetypes, which means:

Entities are grouped by the exact combination of components (and optionally tags) they have.

This means the world knows: "All entities with position and velocity, but not health are in this group."

This makes querying more efficient and predictable — we only iterate over relevant entities per system.

Archetypes are typically used in high-performance ECS engines (like Unity’s DOTS or Bevy in Rust), but here it also simplifies reasoning about how entities are grouped.

Why?

Recently, I came across the idea of Entity Component System (ECS) architectures, and it instantly clicked with my love for declarative APIs and composable logic.

So I decided to implement a minimal ECS framework in Raku — not for performance or production use, but just to explore the paradigm and learn from it. And who knows? Maybe others in the Raku community will enjoy hacking on it too.

The Demo 🎬

Here’s a simple bouncing animation built with this ECS framework and Raylib::Bindings:

The Code 🧩

Here’s the full example:

use Raylib::Bindings;
use ECS;

constant $screen-width  = 1024;
constant $screen-height = 450;
my $white               = init-white;
my $background          = init-skyblue;
init-window($screen-width, $screen-height, "Bouncing Camelias");

my $string         = "./camelia.png";
my $camelia        = load-image($string);
my $camelia-height = $camelia.height;
my $camelia-width  = $camelia.width;
my $camelia-pos    = Vector2.init: $camelia-width/2e0, $camelia-height/2e0;
my $texture        = load-texture-from-image($camelia);
unload-image($camelia);

set-target-fps(60);
END {
    unload-texture($texture);
    close-window;
}

# We define a few basic vector operators to help with math:
sub term:<vector2-zero> { Vector2.init: 0e0, 0e0 }

multi infix:<+>(Vector2 $a, Vector2 $b) { Vector2.init: $a.x + $b.x, $a.y + $b.y }
multi infix:<->(Vector2 $a, Vector2 $b) { Vector2.init: $a.x - $b.x, $a.y - $b.y }
multi infix:<*>(Vector2 $a, Numeric $i) { Vector2.init: $a.x * $i, $a.y * $i }
multi infix:</>(Vector2 $a, Numeric $i) { Vector2.init: $a.x / $i, $a.y / $i }

# Then comes the fun part: defining the ECS world.

my $world = world {
    component position => Vector2;
    component velocity => Vector2;

    entity "camelia";

    # Input system: spawn a new “camelia” on mouse click
    system "click", :when{is-mouse-button-pressed MOUSE_BUTTON_LEFT}, -> {
        world-self.new-camelia:
            :position(get-mouse-position - $camelia-pos),
            :velocity(vector2-zero),
        ;
    }

    system-group "input", <click>;

    # Movement, gravity and bounce logic
    system "move", -> :$position! is rw, :$velocity! {
        using-params -> Num $delta {
            $position += $velocity * $delta
        }
    }

    system "bounce", -> :$position! where *.y >= $screen-height - $camelia-height.Num, :$velocity! where *.y > 0 {
        $velocity.y *= -.8
    }

    system "gravity", -> :$velocity! {
        using-params -> Num $delta {
            $velocity.y += 100 * $delta;
        }
    }

    system-group "physics", <move gravity bounce>;

    # Draw each camelia
    system "draw", -> :$position! {
        draw-texture-v $texture, $position, $white;
    }
}

    system "draw", -> :$position! {

# And finally the game loop:
until window-should-close {
    $world.input;
    $world.physics: get-frame-time;
    begin-drawing;
    clear-background $background;
    $world.draw;
    draw-fps 10, 10;
    end-drawing;
}

Understanding the ECS Framework API

`world`

The world function is the entry point to define your ECS universe. Inside it, you declare your components, entity types, systems, and system groups. It returns an object that you will use to create entities and run your systems.

`component`

The component function defines a component that entities can have. You can call it in two ways:

component position => Vector2;

Or more concisely

component Color;

In the second case, the name of the component will be automatically derived from the type by converting it to kebab-case (e.g., Color becomes "color"). This helps reduce repetition when the type name already describes the data well.

entity

The entity function defines a named entity type. This name becomes a tag automatically added to all instances of that entity. For example:

entity "ball";

After this, you can create new entities with $world.new-ball(...), and those entities will be tagged with "ball".

system

The system keyword defines a system — a unit of logic that processes entities. By default, a system automatically performs a query based on its parameters: it runs once per entity that has all the required components and tags.

For example:

system "gravity", -> :$velocity! { ... }

This system runs once per frame for each entity with the velocity component.

However, if you pass a :condition or :when parameter, the system behaves differently: it no longer queries entities, and runs only once per frame (or tick), executing only when the condition is true. This is ideal for global events like input, timers, or other non-entity-specific logic.

Example:

system "click", :when { is-mouse-button-pressed MOUSE_BUTTON_LEFT }, -> {
    ...
}

This system executes once per frame only if the left mouse button is pressed.

system-group

The system-group function defines a reusable group of systems. This allows you to bundle related systems and execute them together. You can call the group like a method, optionally passing arguments that will be forwarded to any using-params blocks inside the systems.

Example:

system-group "physics", <move gravity bounce>;
...
$world.physics: get-frame-time;

using-params

The using-params function allows a system to access parameters passed when the system or system group is invoked. This is useful for values like frame delta time or external input.

Example:

system "gravity", -> :$velocity! {
    using-params -> Num $delta {
        $velocity.y += 100 * $delta;
    }
}

Here, the system needs a time delta value to apply acceleration due to gravity. It gets the value passed to the system group (e.g., physics: get-frame-time).

current-entity

Inside a system or query, you can call current-entity to get the entity object currently being processed. This is useful for adding or removing tags or other manipulations.

Example:

if some-condition {
    current-entity.add-tag: "jumping";
}

This gives you fine-grained control over the entity’s state and behavior beyond component data.

world-self

Inside a system or query, world-self gives you access to the current world instance. You can use it to create or modify entities, trigger systems, or manage state globally.

Example:

world-self.new-ball: :position(...), :velocity(...);

This allows a system to spawn new entities as part of its logic.

About the Framework 🛠️

Here are some things you should know:

It’s written entirely in Raku.
The world is declared with world { ... }.
Components are just names mapped to types.
Systems are defined using system with a name and a sub signature.
The system’s parameters are automatically injected from matching entities.
The using-params block lets you access runtime values (like delta time).
Tag filtering, conditions, and entity creation are built-in.
It’s not optimized in any way — it’s designed to be fun and expressive.

What’s next? 🚧

Nothing is fixed. The API might change. This is just the beginning of a small experiment. If you’re curious about ECS, or if you have experience with game development and want to help shape a more solid design, please get in touch!

You can find the project here:

👉 https://github.com/FCO/ECS

Feel free to open issues, create examples, or criticize design decisions.

⸻

Thanks for reading!

🚀 Bringing Structural Protocols to Raku

Fernando Correa de Oliveira — Sat, 19 Jul 2025 01:24:56 +0000

Recently on IRC someone asked how to add methods to basic types, which reminded me of an old experimental project of mine: Protocol. Its goal is to explore a structural style of interface in Raku—distinct from Raku’s nominal roles—echoing how Go’s interfaces work by method shape rather than explicit declaration.

🧩 Structural vs. Nominal (Go Inspiration vs. Raku Today)

Raku roles are nominal: you explicitly compose (does) a role to promise a bundle of behavior; roles package partial behavior for reuse and are mixed in at compile- or run-time.
Go interfaces are structural: any type whose method set matches the interface implicitly satisfies it—no prior annotation—providing “if it quacks…” flexibility with static checking.
Structural typing differs from duck typing: structural typing is verified statically (at compile/analyze time), while duck typing relies on runtime method availability.

📘 What Protocol Originally Did

Originally, declaring a protocol like:

use Protocol;

protocol Nameable {
    method name { ... }
}

created a subset of Any that type-checks values by verifying the presence of a name method (the ... yada marks a required placeholder).
Subsets in Raku re-dispatch to their base type but enforce constraints at assignment / parameter binding; Protocol leveraged that to express a structural “has-method(s)” check without nominal composition.
At first, providing concrete method bodies inside a protocol (i.e. anything other than yada) was disallowed—protocols were strictly about requirements.

🔄 Why Evolve Beyond Pure Subsets?

In practice you often want lightweight structural acceptance plus helper / default methods that build upon the required minimal surface (a pattern familiar from roles’ default methods or convenience wrappers around Go interface method sets).

🛠️ The New Behavior: Class Generation When Helpers Exist

If a protocol now includes any concrete method bodies, Protocol generates a class (instead of only a subset) so those methods can be mixed in via coercion when needed.

use Protocol;

protocol Nameable {
    method name { ... }  # required
    method description {
        [
            "Type: { $.^name }",
            "Name: { $.name }"
        ].join: "\n"
    }
}

This Nameable now packages both a structural requirement (name) and a concrete helper (description) that becomes available after coercion/mix-in.

🎯 Pure Structural Checking Only? Use `ProtocolSubset`

Need only to assert “this value has method name” (no helper methods)? Parameterize with ProtocolSubset:

my Nameable[ProtocolSubset] $with-name = Person.new: :name<Fernando>;

This uses subset semantics: compile/runtime binding checks ensure the method’s existence, while the underlying object remains unchanged and un-augmented.

✨ Need the Helper Methods? Use `ProtocolCoerce`

To use helpers like .description, request coercion:

sub print-description(Nameable[ProtocolCoerce] $_) {
    say .description;
}

ProtocolCoerce mixes in the generated class so its concrete methods become callable—conceptually similar to mixing a role into an instance on demand.

🧪 About the Mixed Value vs. Original Object

Raku’s mixin mechanism produces a new (reblessed) object when adding roles/mixins; the coerced value your function receives may differ in identity from the original variable, though it forwards behavior/state as defined by Raku’s mixin metaobject and caching rules.

🧠 Design Trade-Offs (Why This Split Helps)

Ergonomics: Structural checking (ProtocolSubset) validates method presence without retrofitting roles into legacy or 3rd-party types.
Extensibility: Helper methods embedded directly reduce boilerplate vs. writing separate wrapper roles or utility subs.
Clarity & Safety: Explicit choice between mere validation (ProtocolSubset) and augmentation (ProtocolCoerce) avoids hidden behavior changes.
Leverage Existing Semantics: Builds atop Raku subsets, mixins, and role composition models rather than inventing a wholly foreign mechanism.
Parametric Pattern: Parameterization mirrors broader parametric / mixin patterns in the ecosystem, easing conceptual load.

🆚 Quick Comparison Snapshot

Goal	Raku Role (Nominal)	Go Interface (Structural)	Protocol
Require methods	Consumer `does` role; nominal link	Any type with matching method set	Subset check: structural (`ProtocolSubset`)
Add helper methods	Role can define defaults	Helpers usually on concrete type	Concrete methods in protocol ⇒ coercible class
Retroactively apply w/out editing source	Mix role (instance/class)	Implicit satisfaction	Structural subset + optional coercion
Avoid nominal coupling	No (explicit name)	Yes (implicit)	Yes (shape-based check)
Opt-in behavior augmentation	Role mixin	Not via interface itself	ProtocolCoerce parameter

Each cell reflects documented capabilities of roles, subsets, mixins, and structural interfaces.

💬 Structural Interfaces in Go (Deeper Dive)

A Go value satisfies an interface automatically if it implements the interface’s method set—no implements clause—enabling decoupled design and interface-oriented APIs; this is a compile-time structural check distinct from dynamic duck typing.
Community discussions and educational material reiterate the static structural nature (and its contrast with duck typing) emphasizing that interface satisfaction is derived from shape not explicit declarations.

🧪 Example Recap (Putting It Together)

Define structural requirements (and optionally helpers) in a protocol.
Use Nameable[ProtocolSubset] where you just need a guarantee the argument responds to .name.
Use Nameable[ProtocolCoerce] when you also want .description (or other helper methods) to exist via a safe mixin/coercion process. These steps leverage Raku’s subset validation and mixin metaobject to approximate Go-like structural acceptance with optional augmentation.

🏁 Conclusion 🎉

Protocol aims to blend Go-style structural typing’s flexibility with Raku’s powerful role, subset, and mixin machinery—cleanly separating validation (ProtocolSubset) from augmentation (ProtocolCoerce) so you can retrofit interfaces onto existing code while progressively layering reusable helper behavior.

Cromponent new features

Fernando Correa de Oliveira — Fri, 11 Jul 2025 22:17:32 +0000

Cromponent 🎉 now lets your components bind cookies, query-string params, headers and HTTP-auth credentials directly in the method signature 🍪❓📑🔐 and push live HTML over WebSockets with two tiny hooks 🔌🛰️.
Paired with HTMX on the client, that means real-time Raku apps with zero JavaScript 🚀. Below you’ll find the new API plus a complete “live poll” example. Dive in! 🏊‍♂️

⸻

Why Cromponent? 🤔✨

Cromponent glues together Cro’s reactive HTTP / WebSocket server and Cro Templates to give Raku developers a component abstraction à la modern SPA frameworks – but rendered on the server and streamed as HTML fragments.
The latest release focuses on state & interaction: declarative request-context binding and built-in WebSocket wiring. ❤️‍🔥

⸻

Prerequisites at a Glance 📚🔎

Layer	Role	1-Liner
HTMX ⚡	Enriches plain HTML with AJAX, SSE & WebSockets via attributes.	`hx-put, hx-target, hx-ext="ws"`, …
Cro 🧩	Reactive HTTP/WebSocket server & router for Raku.	`route { … }`
Cro Templates 🖋️	HTML-centric templating DSL compiled on first use.	`template 'view.crotmp', %data`
Red ORM 🗄️	DB-agnostic ORM with migrations & relationships.	`model Foo { has Int $.id is serial … }`
Dynamic vars 🌐	`$*foo` passes per-request context through deep calls.	`$*user` in our example

New API: Context Traits 🍪❓📑🔐

Any method tagged is accessible becomes an endpoint and auto-binds request data:

method profile(
    Str :$uuid   is cookie,
    Str :$q      is query,
    Str :$accept is header,
    Str :$creds  is auth
) is accessible { ... }

Zero plumbing 🛠️
Type-safe input 🛡️
Self-documenting signatures 📜

Route pattern:

/ComponentName/<ids…>/profile

New API: Automatic WebSockets 🔌🛰️
1. Channel key – method IDS { $!id } groups browsers in the same room.
2. Re-render hook – method REDRAW(:$*user is cookie) { $.Str } returns fresh HTML when you redraw $component.
3. <|WebSocket> cromponent adds hx-ext="ws" ws-connect="/ws" and the htmx-ws extension swaps fragments for you.

No manual frames, pings or reconnect loops – Cro & HTMX handle all that jazz. 🎷

⸻

Building a Live Poll 🗳️⚡

5.1. Router & DB Setup 🛣️

my $routes = route {
    red-defaults "SQLite";
    PollItem.^add-cromponent-routes;   # auto REST 🆓
    WebSocket.^add-cromponent-routes;  # auto WS  🆓

    get -> 'polls', Str :$*user is cookie = UUID.new.Str {
        response.set-cookie: :name<user>, :value($*user);
        template 'polls.crotmp', { :$*user, :@polls = Poll.^all }
    }
}
Cro::HTTP::Server.new(:host<0.0.0.0>, :port(2000), :$routes).start;

First visit ➡️ generates UUID ➡️ saves in 🍪 ➡️ available as $*user.

5.2. Poll Component 📊

model Poll does Cromponent {
    has UInt $.id    is serial;
    has Str  $.descr is column;
    has      @.items is relationship(*.poll-id, :model<PollItem>);
    has      @.votes is relationship(*.poll-id, :model<PollVote>);

    method LOAD($id)       { Poll.^load: $id }  # rebuild
    method IDS             { $!id }             # WS room
    method REDRAW(:$*user) { $.Str }            # push update

    method did-user-vote($who = $*user) {
        ?@.votes.first: *.user eq $who
    }

    method RENDER { … }   # the template
}

5.3. PollItem Component ✅

method vote(Str :$*user is cookie)
      is accessible { :http-method<PUT>, :returns-cromponent } {
    red-do :transaction, {
        $!votes++;
        self.^save;
        $!poll.votes.create: :$*user;
        redraw $!poll;      # broadcast 🌍
        $!poll
    }
}

HTMX button:

<button
  hx-put="/poll-item/42/vote"
  hx-target="closest .poll"
  hx-swap="outerHTML">🗳️ Vote</button>

5.4. WebSocket-Enabled Page 🖥️

<|Boilerplate(:title('Polls 🗳️'), :htmx, :style-sheets('/css'))>
  <|WebSocket>
    <h6>Logged in as <.user> 🙋‍♂️</h6>
    <@.polls><&HTML($_)></@>
    <a href="/polls">All polls 📋</a>
  </|>
</|>

Generated Endpoints Recap 🛤️

Method	Path	Source
GET	`/polls`	manual route	❌
GET	`/polls/<id>`	manual route	❌
PUT	`/poll-item/<id>/vote`	PollItem.vote	✅
GET	`/cromponent-ws`	WebSocket	✅

One call to .^add-cromponent-routes ➡️ endpoints galore! 🎊

⸻

Key Take-aways 💡
Context traits (is cookie 🍪, is query ❓, is header 📑, is auth 🔐) shred boilerplate.
IDS + REDRAW inject WebSocket magic with two methods. ✨
Everything lives in one file: model + template + behaviour – still plain Raku, still testable. 🧪

Result: back-end-driven UX with instant updates and zero JavaScript. 🚀

⸻

Further Reading 📚
🌟 Cromponent → https://github.com/FCO/Cromponent
📜 Cro docs → https://cro.services
🗄️ Red ORM → https://github.com/FCO/Red
⚡ HTMX → https://htmx.org
🔌 htmx-ws extension → https://htmx.org/extensions/ws/
🧠 Dynamic vars in Raku → https://docs.raku.org/language/variables#Dynamic_variables

Happy hacking – and may your components stay Crom-pact! 🦀🎈

Deps

Fernando Correa de Oliveira — Sat, 07 Jun 2025 03:08:13 +0000

Summary

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.

1. Motivation and Background

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.

2. Overview of Deps

Deps exposes:

Low‑level API: Manually register and retrieve dependencies by type or name.
Block‑scoped DSL: Use deps { ... } to create nested containers and perform inline registrations or imports.
Trait‑based injection: Apply is injected to functions/subroutines to have parameters auto‑provided.
Automatic instantiation: Construct classes by matching attributes to registered values.

3. Core Features

3.1 Low‑Level API

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

3.2 Block‑Scoped DSL

deps {
   injectable C.new: :13attr;
   injected my C $obj;
   # $obj == C.new(attr => 13)
}

3.3 Function‑Level Injection

sub handle-request(UInt $id) is injected {
  injectable UserIdStorage.new: :$id;
  process-request
}

Parameters typed as registered types are injected at call time.

3.4 Automatic Instantiation

class Example { has Int $.x; has Str $.y }
deps {
  injectable 7;
  injectable "hello", :name<y>;
  instantiate(Example);    # Example.new(x => 7, y => "hello")
}

4. Resolution Lifecycles

Deps supports three built‑in lifecycles:

New (transient): the default; each call to .get creates a fresh instance.
Store (singleton): one instance per container; reused on every .get.
Scope (scoped): one instance per 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>;

5. Priority

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

6. Combined Example

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
}

7. Conclusion and Future Directions

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.

Testing Raku Applications with Cro, Red, and RedFactory

Fernando Correa de Oliveira — Sun, 27 Apr 2025 03:02:09 +0000

Introduction

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.

Cro is a set of libraries for building reactive services (such as web applications and HTTP APIs) in Raku.
Red is an Object-Relational Mapper (ORM) for Raku. Red allows you to interact with relational databases using Raku objects instead of writing raw SQL, bringing several advantages like type safety, consistency, and easier schema evolution.
RedFactory is a helper library designed to work with Red, making it easy to generate consistent test data.

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.

Setting Up the Environment

To set up a basic project using Cro, Red, and RedFactory:

Install Raku and dependencies: Ensure you have Raku installed. Then install Cro, Red, and RedFactory using zef:

zef install cro Red RedFactory

Create a new Cro project: Cro provides a CLI tool to generate project skeletons:

cro stub http MyApp myapp

This creates a project under myapp/ with initial files and structure.

Add Red to the project: Import Red into your main script or modules:

use Red:api<2>;

Configure the database connection:

red-defaults "SQLite", database => "myapp.db";

Install and configure RedFactory: You already installed RedFactory in step 1. Create a file like lib/Factories.rakumod where you will define factories for your models.

Now your environment is ready: a basic Cro project running, Red handling database interaction, and RedFactory set up to create test data easily.

Creating Models with Red

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.

Creating Factories with RedFactory

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.

Introduction to Cro::HTTP::Test

Testing HTTP routes without running a real server is made easy by Cro::HTTP::Test.

This module allows you to:

Execute your routes in-memory.
Send simulated HTTP requests.
Check responses declaratively.

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.

Writing Tests

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;

factory-run sets up a fresh SQLite in-memory database.
We create 10 children from the UK.
Then we test that the /children/count/UK route correctly returns 10.

This shows how Cro, Red, and RedFactory work together cleanly.

Full Integration Example

Suppose our API has:

GET /children — list all children.
POST /children — create a new child.

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:

Start with an empty list.
Add a child via POST.
Confirm the list now contains the new child.

Simple, clean, and fully automated.

Best Practices

Isolated Database for Tests: Always use a test database, ideally in-memory. factory-run with RedFactory makes this easy.
Use Factories: Define clear factories for your models to make tests readable.
Separate Unit and Integration Tests: Keep logic-only tests separate from HTTP integration tests.
Check Only Necessary Parts: Use partial JSON assertions with *%_ to avoid fragile tests.
Organize Code: Keep routes modular and tests structured.

Good practices help you keep tests maintainable, readable, and fast.

Conclusion

In this article, we showed how to test Raku applications using Cro, Red, and RedFactory:

Set up a project environment.
Define database models.
Create factories to generate test data.
Use Cro::HTTP::Test to simulate HTTP requests and verify responses.

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!

Introducing MCP: A Protocol for Modular AI Assistants and Raku's Potential

Fernando Correa de Oliveira — Fri, 18 Apr 2025 18:59:01 +0000

🤖 What is MCP?

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:

🛠️ Tools – callable actions or APIs, defined with input/output schemas
📦 Resources – contextual data or runtime configuration for the assistant
✉️ Prompts – snippets of guiding instructions, either static or code-generated

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.

💡 Why Raku?

Raku is well-suited to building MCP tooling due to its:

🧠 Expressive multi-paradigm syntax
🧰 Built-in meta-object protocol (MOP)
🔍 Introspection and trait support
🛡️ Strong type system with gradual typing
📁 Support for resource embedding via %?RESOURCES

These features allow developers to:

🧾 Derive schemas from code automatically
✔️ Perform advanced validation using traits
📝 Annotate and document APIs inline
📚 Embed metadata and logic in clean, declarative structures

🧱 Overview of the Raku Framework

The goal is to provide an ergonomic, modular Raku framework to define and serve MCP-compatible components. The core elements are:

🔧 Tools can be simple exported subs or classes that does MCP::Tool
📦 Resources can be classes, files (via %?RESOURCES), or environment variables
✨ Prompts can be strings or code-defined classes
📄 A mcp.json file describes each group’s capabilities
🌐 A CLI manages scaffolding, execution, and bundling

Execution is powered by servers (e.g. STDIO or HTTP), and applications can load multiple groups at once.

🔨 Defining Tools

As Functions

#| 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.

As Classes

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().

Via Module + Exported Function

To support legacy or utility modules:

{
  "type": "function",
  "module": "Math::Utils",
  "function": "add"
}

📚 Resources

Resources provide configuration, secrets, or contextual data to the assistant. You can define them as:

Embedded Class

"resources": [ "My::Class::Name" ]

File (referenced from `%?RESOURCES`)

{
  "name": "city-list",
  "type": "resource",
  "value": "data/cities.json"
}

Environment Variable

{
  "name": "api-key",
  "type": "env",
  "value": "API_KEY"
}

🧠 Prompts

Prompts can be:

A Code Class

class GreetingPrompt {
  method run() {
    "Hello! How can I assist you today?"
  }
}

A Static String

{
  "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?"

🧩 Group Structure and `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:

🛠️ Tools
📦 Resources
✉️ Prompts

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.

🛠️ CLI and Example Workflow

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

🤝 Want to Help?

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!

A Raku Cromponent to Render Highlighted Code — Powered by RakuAST

Fernando Correa de Oliveira — Mon, 14 Apr 2025 04:10:15 +0000

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.

🧩 The Goal

This Cromponent renders Raku code inside your app (like Codeboard), but instead of:

blindly printing text
or adding basic syntax coloring

…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.

🛠️ How It Works

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.

🧪 Limitations

This is very early. Some known issues:

It doesn’t yet support everything in the Raku language
Some edge cases might fail to parse
Error messages can be improved

But it works well for basic expressions, function definitions, variable usage, and more.

Even this small feature opens the door to things like:

Properly formatted code snippets
Static analysis tools
Teaching tools for understanding the structure of Raku

🤝 Want to Help?

RakuCode is open-source and very early. If you like where this is going, contributions are welcome — whether you:

Want to extend the renderer
Help parse new AST node types
Fix bugs or improve error handling
Write docs or tests

Check out the repo and feel free to open issues or PRs.

🔚 Wrap-up

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!

Building Raku Codeboard: A Simple Full-Stack App with Red, Cromponent, and HTMX

Fernando Correa de Oliveira — Tue, 08 Apr 2025 02:37:03 +0000

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

💡 What is Raku Codeboard?

Raku Codeboard is a lightweight app where users can:

Create topics
Post messages under each topic (text or code)
See a list of all people who participated

The stack:

Red for ORM/database mapping
Cromponent for reusable web components
HTMX for declarative interactivity

🧱 app.raku

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;
    }
}

🧩 index.crotmp

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>
</|>

📦 Cromponents and Models

Topics.rakumod

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 }

Topic.rakumod

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 }

Topic::Card.rakumod

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
}

Message.rakumod

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;

People.rakumod

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 }

🔁 HTMX + Cromponent + Red

Everything works together like this:

Forms use hx-post to Cromponent route methods (e.g., CREATE, message)
Cromponent methods use Red to insert into the database
They return a Cromponent that gets rendered to HTML
HTMX places that HTML back into the DOM (e.g., .main or .topics)

All routes are declared using .^add-cromponent-routes, so you don’t need to write routing logic by hand.

✅ Summary

This app is fully functional and real — and it’s all in Raku. It combines:

Red for database modeling
Cromponent for reusable UI
HTMX for user interactivity
Cro for the HTTP layer

🔗 https://github.com/FCO/Discuss

Let me know what you’d like to add!

The Evolution of Web Component Modules in Raku: A Journey of Diverse Approaches

Fernando Correa de Oliveira — Sun, 30 Mar 2025 02:39:02 +0000

Over the past several years, the Raku community has explored a variety of approaches to building web interfaces. Each module represents a distinct set of design choices and trade-offs, reflecting different philosophies and priorities. In this post, we’ll review key milestones in the evolution of web component modules in Raku and provide code examples that illustrate how each solution works in practice.

2017 – p6-react

p6-react was one of the earliest experiments in bringing a component-based approach to Raku web development. Inspired by modern front-end frameworks, p6-react enables developers to write server-side components with a declarative syntax. The following example demonstrates how to create reusable components using the p6-react style:

use Component;
use Slang;

component Item {
    has Str $.data;
    method render {
        <li>
            {{$.data}}
        </li>
    }
}

component UlList {
    has Str @.items;
    method render {
        <ul>
            {{
                do for @.items -> $item {
                    <Item data={{$item}} />
                }
            }}
        </ul>
    }
}

say UlList.new(:items<bla ble bli>).render.render

In this example, the Item component renders a list item (<li>) using its data, while UlList composes a set of Item components into an unordered list (<ul>). This approach leverages a clear, nested component structure that promotes code reuse and declarative UI construction.

2018 – MemoizedDOM

MemoizedDOM emerged in 2018 with a fresh perspective by focusing on a functional approach to HTML generation. Borrowing ideas from memoization techniques, MemoizedDOM emphasizes the declarative construction of web interfaces. It leverages tools like rakudo.js and integrates optionally with platforms such as webperl6 and 6pad.

The example below demonstrates a more advanced application—a dynamic todo list—with interactive form handling and live updates:

# App.rakumod
use MemoizedDOM;
use Todo;

class App does Tag {
    has @.todos;
    has Str $.new-title = "";

    method render {
        form(
            :event{
                :submit{
                    .preventDefault;
                    @!todos.push: {
                        :title($!new-title),
                        :!done
                    };
                    $!new-title = "";
                    self.call-render
                }
            },
            ul({ do for @!todos -> (Str :$title!, Bool :$done! is rw) {
                Todo(:$title, :$done, :toggle{ $done = !$done; self.call-render })
            }}),
            input(
                :type<text>,
                :event{
                    :keyup{ $!new-title = .<target><value> }
                },
                :value{ $!new-title }
            ),
            input(
                :type<submit>,
                :value<OK>,
            )
        )
    }
}


# Todo.rakumod
use MemoizedDOM;

class Todo does Tag {
    has Str  $.title;
    has Bool $.done is rw;
    has      &.toggle is required;

    method render {
        li(
            :style{
                $!done
                ?? { :textDecoration<line-through>, :opacity<0.3> }
                !! { :textDecoration<none>        , :opacity<1>   }
            },
            :event{
                :click( &!toggle )
            },
            input(
                :type<checkbox>,
                :checked{ $!done },
            ),
            $!title
        )
    }
}


# todo.raku
use App;

EVAL :lang<JavaScript>, 'HTMLElement.prototype.defined = function() { return true }';
EVAL :lang<JavaScript>, 'document.defined = function() { return true }';

my \document = EVAL :lang<JavaScript>, 'return document';

my $app = App(:todos[
    {:title<bla>, :!done},
    {:title<ble>, :done },
    {:title<bli>, :!done},
]);

$app.mount-on: document.getElementById: 'todoapp';

This example shows how MemoizedDOM can be used to build an interactive todo list. It demonstrates declarative UI rendering, event handling, and live updates through memoization. The functional style emphasizes a clear separation between data and view, though it may require a shift in mindset compared to traditional object-oriented approaches.

2023 – HTML::Component

HTML::Component took a different turn by embracing an object-oriented design to build HTML structures. Instead of relying solely on functions, this module uses methods and role composition to generate HTML elements. This approach harnesses Raku’s strengths in object composition and method chaining, offering a distinct set of trade-offs.

The following example demonstrates a complete todo list application using HTML::Component. It is divided across multiple modules to showcase component loading, dynamic updates, and integration with HTMX for seamless interactivity.

# examples/todo/Todo.rakumod
use HTML::Component;
use HTML::Component::Endpoint;

unit class Todo does HTML::Component;

my @todos;

has UInt   $.id = ++$;
has Str()  $.description is required;
has Bool() $.done = False;

submethod TWEAK(|) {
  @todos[$!id - 1] := self;
}

method LOAD(UInt() :$id) {
  @todos[$id - 1]
}

multi method new($description) { self.new: :$description, |%_ }

method RENDER($_) {
  .li:
    :htmx-endpoint(self.toggle),
    :hx-swap<outerHTML>,
    :class<todo>,
    {
      .input-checkbox:
        :checked($!done),
      ;
      if $!done {
        .del: $!description
      } else {
        .add-child: $!description
      }
    }
  ;
}

method toggle is endpoint{ :return-component } {
  $!done .= not
}



# examples/todo/TodoList.rakumod
use HTML::Component::Endpoint;
use HTML::Component;
use HTML::Component::Boilerplate;
use HTML::Component::Traits;
use Todo;

unit class TodoList does HTML::Component;

method new(|)  { $ //= self.bless }
method LOAD(|) { self.new }

has UInt $.id = ++$;
has Todo @.todos;

method RENDER($_) {
  .ol: {
    .add-children: @!todos;
  }
  .form: self.new-todo;
}

method new-todo(
  Str :$description! is no-label, #= What should be done?
) is endpoint{ :verb<POST>, :redirect</> } {
  @!todos.push: Todo.new: :$description;
}



# examples/todo/App.rakumod
use TodoList;
use HTML::Component;
use HTML::Component::Boilerplate;
unit class App does HTML::Component;

method RENDER($) {
  boilerplate
    :title("My TODO list"),
    :body{
      .script: :src<https://unpkg.com/htmx.org@1.9.10>;
      .add-child: TodoList.new;
    }
  ;
}



# examples/todo/cro-todo.raku
use Cro::HTTP::Log::File;
use Cro::HTTP::Server;
use Cro::HTTP::Router;
use HTML::Component::CroRouter;
use Cro::HTTP::Log::File;
use lib "examples";
use App;

my $route = route {
    root-component App.new
}

my $app = Cro::HTTP::Server.new(
    host => '127.0.0.1',
    port => 10000,
    application => $route,
    after => [
        Cro::HTTP::Log::File.new(logs => $*OUT, errors => $*ERR)
    ],
  );

$app.start;
say "Listening at http://127.0.0.1:10000";

react whenever signal(SIGINT) {
    $app.stop;
    exit;
}

This HTML::Component example is more elaborate, demonstrating how to split a todo list application into multiple components. It showcases dynamic component registration and loading, interactive endpoints using HTMX, and the integration of boilerplate templates to create a robust web application.

2024 – Cromponent

Cromponent offers a flexible way to create web components using Cro templates. It stands out by supporting three complementary modes of integration:

Template-Only Usage: Use a Cromponent as a “fancy substitute for cro-template sub/macro.”
Data Embedding: Pass a Cromponent as a value to a template so that printing it yields its rendered HTML.
Auto-Generated Routes: Automatically create Cro endpoints for your components, enabling dynamic, REST-like interactions.

Below is the simplest example taken directly from Cromponent’s README, demonstrating the template-only approach:

use Cromponent;
class AComponent does Cromponent {
    has $.data;

    method RENDER {
        Q:to/END/
        <h1><.data></h1>
        END
    }
}

sub EXPORT { AComponent.^exports }

In this example, AComponent is defined as a Cromponent that renders an <h1> tag with its data. This concise setup highlights Cromponent’s elegance: by simply defining a RENDER method using a Cro template, you can quickly build components that are reusable within your Cro applications. Moreover, Cromponent’s versatility allows its use in embedding within templates or even auto-generating HTTP routes for dynamic web interfaces.

2025 – Air

Air represents a fresh direction in the evolution of Raku’s web component ecosystem. Air merges automatic routing and functional HTML generation, aiming for a clear, declarative approach to building web pages. Below is an example demonstrating how you can use Air to define a full web page that dynamically renders content:

#!/usr/bin/env raku

use Air::Functional :BASE;
use Air::Base;

my &index = &page.assuming( #:REFRESH(1),
    title       => 'hÅrc',
    description => 'HTMX, Air, Red, Cro',
    footer      => footer p ['Aloft on ', b safe '&Aring;ir'],
);

my &planets = &table.assuming(
    :thead[["Planet", "Diameter (km)",
            "Distance to Sun (AU)", "Orbit (days)"],],
    :tbody[["Mercury",  "4,880", "0.39",  "88"],
           ["Venus"  , "12,104", "0.72", "225"],
           ["Earth"  , "12,742", "1.00", "365"],
           ["Mars"   ,  "6,779", "1.52", "687"],],
    :tfoot[["Average",  "9,126", "0.91", "341"],],
);

sub SITE is export {
    site #:bold-color<blue>,
        index
            main
                div [
                    h3 'Planetary Table';
                    planets;
                ]
}

In this Air example, the code demonstrates:

Declarative Page Composition: Using &page.assuming to create a page with a title, description, and footer.
Data-Driven Tables: Constructing an HTML table via &table.assuming with structured data for headers, body, and footers.
Functional Composition: The SITE subroutine assembles the complete page layout by combining various components, resulting in a dynamic page rendered in a functional style.

Air’s approach illustrates the potential for combining HTMX-enhanced interactivity with a concise, functional programming model, adding another valuable tool to the diverse landscape of Raku web component modules.

Other Noteworthy Projects

The evolution of web component modules in Raku is further enriched by additional projects that explore diverse integrations and methodologies:

Cro-WebSocket-WebComponents-test: Investigates the integration of Cro with WebSockets to enable live, reactive updates within web components.
Proact: Introduces reactive programming paradigms into web development, offering a creative approach to managing dynamic interfaces.

Each of these projects reflects different priorities—whether it’s seamless interactivity, modularity, or declarative design—allowing developers to select the tool that best fits their specific needs and preferences.

Conclusion

The history of web component modules in Raku is a testament to the community’s commitment to experimentation and innovation. From p6-react’s declarative, component-based structure to MemoizedDOM’s functional approach, from HTML::Component’s object-oriented, HTMX-powered applications to Cromponent’s versatile Cro template integration, and finally to Air’s functional, data-driven page composition—each module brings its own set of trade-offs and benefits. Rather than comparing these solutions as better or worse, it is more productive to view them as complementary approaches addressing different design goals and use cases.

I probably have not found all modules related to web components in Raku. If you remember any other module that should be cited here, please let me know—I’d love to hear your suggestions and will create a new post to cover them!

As the ecosystem continues to evolve, Raku developers have a rich set of tools at their disposal, each contributing to a diverse and dynamic web development landscape.

DEV Community: Fernando Correa de Oliveira

Crolite: filling the "Mojolicious::Lite" gap in the Cro ecosystem

Introduction

What Crolite Is

Installation

First Example

Suggested Workflow

CLI Options

Dynamic Segments & Typing

Returning JSON

Hooks (Before / After)

More Complete Example

Ergonomics While Prototyping

Current Limitations

When to Migrate to a Full Cro App

Possible Future Roadmap

Quick Testing Tips

Wrapping Up

Typed, Named Endpoints for Cro (with HTMX Helpers)

Install

Quick Start

Naming and Discovering Endpoints

Typed Path Building

HTMX Helpers

Redirects

Calling the Implementation

Full Example

Errors and Guarantees

Why This Isn’t in Cro

Appendix: Include With Prefix Example

From ASTs to RakuAST to ASTQuery

ASTs, Briefly

What Is RakuAST?

Why Search ASTs?

Macro-Like Passes (Compiler-Time Rewrites)

ASTQuery, at a Glance

Quickstart

Selector Language

Built-in Groups and Functions

ID Fields (#id) and How Matching Works

Examples

Reusable Function Matchers

Programmatic API

CLI Usage

Debugging Selectors

Notes and Caveats

Conclusion

🎮 ECS in Raku: A Toy Framework for Entities, Components, and Systems

🧠 What is ECS?

🧱 What’s an Archetype?

Why?

The Demo 🎬

The Code 🧩

Understanding the ECS Framework API

world

component

entity

system

system-group

using-params

current-entity

About the Framework 🛠️

What’s next? 🚧

🚀 Bringing Structural Protocols to Raku

🧩 Structural vs. Nominal (Go Inspiration vs. Raku Today)

📘 What Protocol Originally Did

🔄 Why Evolve Beyond Pure Subsets?

🛠️ The New Behavior: Class Generation When Helpers Exist

🎯 Pure Structural Checking Only? Use ProtocolSubset

✨ Need the Helper Methods? Use ProtocolCoerce

🧪 About the Mixed Value vs. Original Object

🧠 Design Trade-Offs (Why This Split Helps)

🆚 Quick Comparison Snapshot

💬 Structural Interfaces in Go (Deeper Dive)

🧪 Example Recap (Putting It Together)

🏁 Conclusion 🎉

Cromponent new features

Deps

Summary

1. Motivation and Background

`world`

`component`

🎯 Pure Structural Checking Only? Use `ProtocolSubset`

✨ Need the Helper Methods? Use `ProtocolCoerce`

File (referenced from `%?RESOURCES`)

🧩 Group Structure and `mcp.json`