## dist_zef-p6steve-CLI-AWS-EC2-Simple.md
[![](https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg)](https://opensource.org/licenses/Artistic-2.0)

### *PLEASE EXERCISE CAUTION USING AWSCLI SINCE IT WILL CREATE BILLABLE AWS SERVICES IN YOUR ACCOUNT AND MAY NOT TERMINATE THEM AUTOMATICALLY*

# Raku CLI::AWS::EC2-Simple

This module provide a simple abstraction of the AWS command line interface, aka [awscli](https://aws.amazon.com/cli/), for Amazon's EC2 compute web service.

If you encounter a feature of EC2 you want that's not implemented by this module (and there are many), please consider sending a pull request.

## Getting Started

* apt-get update && apt-get install awscli [macOS brew update && brew install awscli]
* aws configure *[enter your config here]* (output format 'json')
* zef install CLI::AWS::EC2-Simple
* raws-ec2 *[enter your commands here]*

## Usage

```
./raws-ec2 [--id=<Str>] [--nsu] [--eip] [-y] <cmd>

    <cmd>         One of <list launch setup connect state stop start terminate nuke>
    --id=<Str>    Running InstanceId of form 'i-0785d8bd98b5f458b'
    --nsu         No setup (suppress launch from running setup)
    --eip         Allocates (if needed) and Associates Elastic IP
    -y            Silence confirmation <nuke> cmd only

```

Will make an (e.g.) `MyKeyPair1672164025.pem` from your credentials in your $\*HOME dir

## Config

`launch` reads `aws-ec2-launch.yaml` which is preloaded with the standard AWS Canonical, Ubuntu, 22.04 LTS, amd64 jammy image build on 2022-12-01.
Edit this yaml file to meet your needs...

* cat .raws-config/aws-ec2-launch.yaml

```
instance:
    image: ami-0f540e9f488cfa27d            # <== the standard, clean AWS Ubuntu
    #image: ami-0ebdbe39cf24185c1            # <== AWS Ubuntu plus raws-ec2 setup already applied (use --nsu flag)
    type: t2.micro                          # <== the basic, free tier eligible test machine
    #type: c6a.4xlarge                       # <== my choice of reasonably priced server class machine
    type: t2.micro
    storage: 30                             # <== EBS size for launch
    security-group:
        name: MySG
        rules:
            - inbound:
                port: 22
                cidr: 0.0.0.0/0
            - inbound:
                port: 80
                cidr: 0.0.0.0/0
            - inbound:
                port: 443
                cidr: 0.0.0.0/0
            - inbound:
                port: 8080
                cidr: 0.0.0.0/0
            - inbound:
                port: 8888
                cidr: 0.0.0.0/0

```

### *PLEASE REVIEW SECURITY GROUP RULES AND ADAPT TO YOUR NEEDS - SPECIFICALLY REMOVE THE PORT:22 RULE UNLESS YOU WANT ALL IPS TO HAVE ACCESS*

## Setup

`setup` deploys docker, docker-compose, raku and zef to the launchee...

* cat .raws-config/launch.pl

```
#!/usr/bin/perl
`sudo apt-get update -y`;

`sudo apt-get install rakudo -y`;
`sudo git clone https://github.com/ugexe/zef.git`;
`sudo raku -I./zef zef/bin/zef install ./zef --/test`;

`sudo apt-get install docker -y`;
`sudo apt-get install docker-compose -y`;

```

## Wordpress Deploy & Control

[This section will probably go into raku-CLI-WP-Simple]

viz. [digital ocean howto](https://www.digitalocean.com/community/tutorials/how-to-install-wordpress-with-docker-compose#step-3-defining-services-with-docker-compose)

* client script 'raku-wp --launch'

## NOTES

* unassigned Elastic IPs are chargeable ($5 per month ish), may be better to run one free tier instance
* rules about rules
  * will always open port 22 (SSH) inbound from this client IP
  * will re-use the existing named Security Group (or create if not present)
  * only inbound are supported for now
  * if you want to keep the name and change the rules, then delete via the aws console

### Copyright

copyright(c) 2022 Henley Cloud Consulting Ltd.


## dist_github-Raku-Blin.md
## Project Blin – Toasting Reinvented

Blin is a quality assurance tool for
[Rakudo](https://github.com/rakudo/rakudo/) releases. Blin is based on
[Whateverable](https://github.com/perl6/whateverable/).

Blin was inspired by
[Toaster](https://github.com/perl6-community-modules/perl6-Toaster). Here
are some advantages:

* Fetches archives from
  [whateverable](https://github.com/perl6/whateverable/wiki/Shareable#bot-usage-examples)
  instead of spending time to build rakudo
* Installs modules in proper order to avoid testing the same module more than once
* Deflaps modules that fail intermittently
* Automatically bisects regressed modules
* Avoids segfaults by producing no useful output instead of using DBIish

### Installation

Install required packages:

```
sudo apt install zstd lrzip graphviz

```

Install dependencies:

```
zef install --deps-only .

```

Many modules require native dependencies. See
[this page](https://github.com/perl6-community-modules/perl6-Toaster/wiki)
for the list of packages to install.

### Running

Currently it is supposed to run only on 64-bit linux systems.

If you want to test one or more modules:

```
RAKULIB=lib bin/blin.p6 SomeModuleHere AnotherModuleHere

```

Here is a more practical example:

```
time RAKULIB=lib bin/blin.p6 --old=2018.06 --new=2018.09 Foo::Regressed Foo::Regressed::Very Foo::Dependencies::B-on-A

```

You can also test arbitrary scripts. The code can depend on modules,
in which case they have to be listed on the command line (e.g. for a
script depending on WWW you should list WWW module, dependencies of
WWW will be resolved automatically).

Using this ticket as an example: <https://github.com/rakudo/rakudo/issues/2779>

Create file `foo.p6` with this content:

```
use WWW;
my @stations;
@stations = | jpost "https://www.perl6.org", :limit(42);

```

Then run Blin:

```
./bin/blin.p6 --old=2018.12 --new=HEAD --custom-script=foo.p6 WWW

```

Then check out the output folder to see the results. Essentially, it
is a local Bisectable.

If you want to test the whole ecosystem:

```
time RAKULIB=lib bin/blin.p6

```

Estimated time to test the whole ecosystem with 24 cores is ≈60 minutes.

**⚠☠ SECURITY NOTE: [issues mentioned in Toaster still
apply.](https://github.com/perl6-community-modules/perl6-Toaster#warning-dangerus-stuf-ahed)
Do not run this for the whole ecosystem on non-throwaway
installs. ☠⚠**

### Viewing

See `output/overview` file for a basic overview of results. More
details for specific modules can be found in `installed/`
directory. Betters ways to view the data should come soon (hopefully).

### Docker

For info about the Docker image, have a look at the
[Readme file](docker/README.md) in the docker directory.


## dist_zef-raku-community-modules-GD-Raw.md
[![Actions Status](https://github.com/raku-community-modules/GD-Raw/actions/workflows/linux.yml/badge.svg)](https://github.com/raku-community-modules/GD-Raw/actions) [![Actions Status](https://github.com/raku-community-modules/GD-Raw/actions/workflows/macos.yml/badge.svg)](https://github.com/raku-community-modules/GD-Raw/actions)

# NAME

GD::Raw - Low level language bindings to GD Graphics Library

# SYNOPSIS

```
use GD::Raw;

my $fh = fopen("my-image.png", "rb");
my $img = gdImageCreateFromPng($fh);
LEAVE gdImageDestroy($_) with $img;

say "Image resolution is ", gdImageSX($img), "x", gdImageSX($img);

```

# DESCRIPTION

`GD::Raw` is a low level language bindings to LibGD. It does not attempt to provide you with an rakuish interface, but tries to stay as close to its `C` origin as possible.

LibGD is large and this module far from covers it all. Feel free to add anything your missing and submit a pull request!

# AUTHORS

* Dagur Valberg Johannsson
* Raku Community

# COPYRIGHT AND LICENSE

Copyright 2013 - 2018 Dagur Valberg Johannsson

Copyright 2024 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_cpan-CTILMES-GPGME.md
# Raku GPGME - GNU Privacy Guard (GPG) Made Easy

## Introduction

From the [GPGME Manual](https://gnupg.org/documentation/manuals/gpgme/index.html):

```
‘GnuPG Made Easy’ (GPGME) is a C language library that allows to
add support for cryptography to a program. It is designed to make
access to public key crypto engines like GnuPG or GpgSM easier for
applications. GPGME provides a high-level crypto API for
encryption, decryption, signing, signature verification and key
management.

GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and
the Cryptographic Message Syntax (CMS).

```

So essentially, this is a Raku Module interfacing with a C library
interfacing with GnuPG and GpgSM command line programs.

Understanding how this module works will benefit from an understanding
of the [Gnu Privacy Guard](https://gnupg.org/documentation/manuals/gnupg/)
and [GnuPG Made Easy (GPGME)](https://gnupg.org/documentation/manuals/gpgme/).

**Note, this is still a work in progress, more features may or may not
be forthcoming!! Patches welcome!!**

# Basic Usage

```
use GPGME;
my $gpg = GPGME.new(:armor);                     # ASCII armor for key export
$gpg.create-key('joe@foo.bar');                  # Add key to key ring
my $joes-key = $gpg.get-key('joe@foo.bar');      # Retrieve a key
put $joes-key;                                   # Stringify key summary
put my $key = $gpg.export('joe@foo.bar');        # Export from key ring
$gpg.import($key);                               # Import key

my $cipher = $gpg.encrypt('message', 'joe@foo.bar');

my $plain = $gpg.decrypt($cipher);

$gpg.signers('joe@foo.bar');
my $signed = $gpg.sign('My message');

```

# Functionality

## Basic

```
use GPGME;
put GPGME.version;
put GPGME.dirinfo('gpg-name');
GPGME.set-locale('C');

```

## GPGME Object and Context

The main [GPGME](doc/GPGME.md) object holds a `context` with various
settings, and can be used to perform various functions.

```
use GPGME;
my $gpg = GPGME.new;
my $gpg = GPGME.new(:armor, :homedir</tmp/dir>);

```

See [GPGME](doc/GPGME.md) for more information.

## Results

After performing an operation, the result of the operation can be
retrieved from the context with the C method. As a
convenience, most methods from the result objects are passed through
to the result object.

For example, after a key generation operation, the
CGPGME::GenKeyResult object can be retrieved with the C
method. One of the attributes of that object is the fingerprint of
the generated key, which can be retrieved with its C method.

```
$gpg.create-key('joe@foo.bar');
my $result = $gpg.result;
my $fpr = $result.fpr;

```

This does the same thing, passing the I from the context to the
result:

```
my $fpr = $gpg.fpr;

```

Of course, for key generation, the result object is returned from
the I operation, so you can also just do:

```
my $fpr = $gpg.create-key('joe@foo.bar').fpr;

```

You can additionally retrieve the result object immediately following
the appropriate operation with these methods:

```
$gpg.genkey-result
$gpg.import-result
$gpg.sign-result
$gpg.encrypt-result
$gpg.decrypt-result
$gpg.verify-result

```

These are sometimes needed when an operation performs two actions
(e.g. decrypt and verify).

These are only valid immediately following the appropriate operation,
and all results must be used or copied prior to the next operation,
when the results are no longer available.

## Engine Information

```
.put for GPGME.engine-info;
GPGME.engine-info('openpgp', :homedir</tmp/dir>);

```

See [GPGME::EngineInfo](doc/GPGME/EngineInfo.md) for more information.

## Data Objects

A lot of data has to be exchanged between the user and the crypto
engine, like plaintext messages, ciphertext, signatures and
information about the keys. The technical details about exchanging the
data information are completely abstracted by GPGME. The user provides
and receives the data via `GPGME::Data` objects, regardless of the
communication protocol between GPGME and the crypto engine in use.

In general the API will construct the appropriate `GPGME::Data`
object for you.

For input objects, you can provide one of these types:

* `Blob` -- Actual data to use
* `Str` -- Actual data to use
* `IO::Path` -- Filename of file to use
* `IO::Handle` -- File with a `native-descriptor` to read from

For output objects, you can provide one of these types:

* `Str` -- Filename of file to write to
* `IO::Path` -- Filename to write to
* `IO::Handle` -- File with a C to write to

When an output object is omitted, a memory buffer will be used and
returned.

When a `GPGME::Data` object is returned, you can stringify it if and
only if the data are `utf8` encoded or ascii (usually produced when
the *:armor* option was specified during context creation).

The object can also be treated as an `IO::Handle` and read from as
usual.

## Key Management

An important fact to remember is that in addition to providing
mechanisms to manipulate keys, GPG also serves as a Key Store or 'Key
Ring'. Keys can generally be referred to by patterns and fingerprints
that map to actual keys stored in the key store.

## Key Generation

GPGME Supports two different interfaces to Key Generation --
`create-key` and `genkey`.

```
$gpg.create-key('joe@foo.bar');
my $key = $gpg.get-key('joe@foo.bar');
$gpg.create-subkey($key);
$gpg.adduid($key, 'another@email.address');
$gpg.set-uid-flag($key, 'another@email.address');  # Make new one primary
$gpg.revuid($key, 'joe@foo.bar');                  # Revoke a user ID

```

`genkey` takes a set of parameters, expressed either as a single
string, or a set of named parameters:

```
$gpg.genkey(q:to/END/)
Key-Type: default
Name-Email: joe@foo.bar
END

```

or

```
$gpg.genkey(:Name-Email<joe@foo.bar>);  # Key-Type defaults to 'default'

```

See [GPG Key Generation](https://gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html) and [CSR and Certificate Creation](https://www.gnupg.org/documentation/manuals/gnupg/CSR-and-certificate-creation.html) for information on all the parameters.

## Listing Keys

List keys in the key ring by specifying a list of patterns and
optionally specifying the *:secret* option to retrieve secret keys.

```
$key = $gpg.get-key('me@my.key');
$key = $gpg.get-key($fpr, :secret);
.put for $gpg.keylist('me@my.key', :secret);
.put for $gpg.keylist(<alice harry bob>);

```

Individual attributes from the keys can be queried.
See [GPGME::Key](doc/GPGME/Key.md) for more information.

## Deleting Keys

```
$gpg.delete-key($key, :secret, :force);

```

* *:secret* deletes secret keys
* *:force* overrides a user confirmation, but is only available after
  version 1.8.

## Signing Keys

Key signatures are a unique concept of the OpenPGP protocol. They can
be used to certify the validity of a key and are used to create the
Web-of-Trust (WoT).

```
$gpg.signers('alice@foo.bar');                     # select signers
$gpg.keysign($key);                                # Default sign all user IDs
$gpg.keysign($key, 'joe@foo.bar');                 # Specify a user ID
$gpg.keysign($key, :local);                        # Non exportable
$gpg.keysign($key, 'joe@foo.bar', expires => $DateTime);

```

## Exporting Keys

```
my $gpg = GPGME.new(:armor);                   # Use :armor to get ASCII export
put $gpg.export('joe@foo.bar');                # Stringify and print out
$gpg.export('joe@foo.bar', :out<outputfile>);  # Export to filename
$gpg.export('joe@foo.bar', out => $*OUT);      # Send to a file handle

```

## Importing Keys

```
$gpg.import($someexportedkeydata);

```

Stores the [ImportResult](doc/GPGME/ImportResult.md).

## Encrypting a Plaintext

```
$cipher = $gpg.encrypt("my message", $key);             # Encrypt for a key
$cipher = $gpg.encrypt("my message", 'joe@foo.bar');     # Encrypt for a pattern
$cipher = $gpg.encrypt("my message", 'joe@foo.bar', :sign);  # Encrypt and sign

```

Stores the [EncryptResult](doc/GPGME/EncryptResult.md).

If signed as well with the *:sign* option,
[SignResult](doc/GPGME/SignResult.md) can be examined as well.

## Decrypting

```
$plain = $gpg.decrypt($cipher);
$gpg.decrypt($cipher, out => 'filename');
$gpg.decrypt($cipher, out => $*OUT);
$gpg.decrypt($cipher, :verify);

```

Stores the [DecryptResult](doc/GPGME/DecryptResult.md).

If the signature was verified with the *:verify* option, the
[VerifyResult](doc/GPGME/VerifyResult.md) is also available.

## Signing

A signature can contain signatures by one or more keys. The set of
keys used to create a signatures is contained in a context, and is
applied to all following signing operations in this context (until the
set is changed).

They can be set either at `GPGME` creation with the *:signers* object,
or with the `.signers` method later.

```
$gpg.signers('joe@foo.bar');
my $signed = $gpg.sign('My message');
$gpg.sign($*IN, out => $*OUT);

my $signature = $gpg.sign('My message', :detach); # Detached signature

```

The [SignResult](doc/GPGME/SignResult.md) will be available after signing.

## Verifying Signature

```
$message = $gpg.verify($signed);
$gpg.verify('infile'.IO, :out<somefile>);

put $gpg.verify($signature, $message).status;      # Detached signature

```

The [VerifyResult](doc/GPGME/VerifyResult.md) will be available after
verification.

# Entropy

Some `GPGME` actions (particularly key generation with very long keys)
rely on the OS ability to generate a great deal of entropy. Things
may appear to hang on entropy starved hosts. Tools like
[haveged](https://www.issihosts.com/haveged/) can help the OS capture
entropy. Even doing something simple like running `sudo dd if=/dev/sda of=/dev/zero` in the background can help speed things up.

# INSTALL

You must install `libgpgme` which usually has the right dependencies
on GPG as well.

* For debian or ubuntu: `apt install libgpgme11`
* For alpine: `apk add gpgme`
* For CentOS: `yum install gpgme`

If you get locale errors on CentOS, you may need to run this:

```
yum install glibc-locale-source glibc-langpack-en
localedef -i en_US -f UTF-8 en_US.UTF-8

```

# License

This work is subject to the Artistic License 2.0.

See <LICENSE> for more information.


## dist_zef-lizmat-FINALIZER.md
[![Actions Status](https://github.com/lizmat/FINALIZER/actions/workflows/linux.yml/badge.svg)](https://github.com/lizmat/FINALIZER/actions) [![Actions Status](https://github.com/lizmat/FINALIZER/actions/workflows/macos.yml/badge.svg)](https://github.com/lizmat/FINALIZER/actions) [![Actions Status](https://github.com/lizmat/FINALIZER/actions/workflows/windows.yml/badge.svg)](https://github.com/lizmat/FINALIZER/actions)

# NAME

FINALIZER - dynamic finalizing for objects that need finalizing

# SYNOPSIS

```
{
    use FINALIZER;   # enable finalizing for this scope
    my $foo = Foo.new(...);
    # do stuff with $foo
}
# $foo has been finalized by exiting the above scope

# different file / module
use FINALIZER <role-only>;   # only get the Finalizable role
class Foo is Finalizable {
    method FINALIZE() {
        # do whatever we need to finalize, e.g. close db connection
    }
}

```

# DESCRIPTION

FINALIZER allows one to register finalization of objects in the scope that you want, rather than in the scope where objects were created (like one would otherwise do with `LEAVE` blocks or the `is leave` trait).

# AS A MODULE DEVELOPER

If you are a module developer, you need to use the Finalizable role in your code. Objects created with the `Finalizable` role applied may implement `FINALIZE` method to perform cleanup tasks after scope is completed.

```
use FINALIZER <role-only>;   # only get the Finalizable role
class Foo is Finalizable {
   method FINALIZE {
       # do whatever we need to finalize, e.g. close db connection
   }
}

```

It is also possible to use the `FINALIZER` class from `FINALIZE` module in your code. In any logic that returns an object (typically the `new` method) that you want finalized at the moment the client decides, you register a code block to be executed when the object should be finalized. Typically that looks something like:

```
use FINALIZER <class-only>;  # only get the FINALIZER class
class Foo {
    has &!unregister;

    submethod TWEAK() {
        &!unregister = FINALIZER.register: { .finalize with self }
    }
    method finalize() {
        &!unregister();  # make sure there's no registration anymore
        # do whatever we need to finalize, e.g. close db connection
    }
}

```

# AS A PROGRAM DEVELOPER

Just use the module in the scope you want to have objects finalized for when that scope is left. If you don't use the module at all, all objects that have been registered for finalization, will be finalized when the program exits. If you want to have finalization happen for some scope, just add `use FINALIZER` in that scope. This could e.g. be used inside `start` blocks, to make sure all registered resources of a job run in another thread, are finalized:

```
await start {
    use FINALIZER;
    # open database handles, shared memory, whatever
    my $foo = Foo.new(...);
}   # all finalized after the job is finished

```

# RELATION TO DESTROY METHOD

This module has **no** direct connection with the `.DESTROY` method functionality in Raku. However, if you, as a module developer, use this module, you do not need to supply a `DESTROY` method as well, as the finalization will have been done by the `FINALIZER` module. And as the finalizer code that you have registered, will keep the object otherwise alive until the program exits.

It therefore makes sense to reset the variable in the code doing the finalization. For instance, in the above class Foo:

```
method finalize(\SELF: --> Nil) {
    # do stuff with SELF
    SELF = Nil
}

```

The `\SELF:` is a way to get the invocant without it being decontainerized. This allows resetting the variable containing the object (by assigning `Nil` to it).

# AUTHOR

Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks)

Source can be located at: <https://github.com/lizmat/FINALIZER> . Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a [small sponsorship](https://github.com/sponsors/lizmat/) would mean a great deal to me!

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2021, 2024, 2025 Elizabeth Mattijsen

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_cpan-MARTIMM-Gnome-Gtk3.md
![gtk logo](https://martimm.github.io/gnome-gtk3/content-docs/images/gtk-perl6.png)

# Gnome Gtk3 - Widget toolkit for graphical interfaces

![artistic-2.0](http://martimm.github.io/label/License-label.svg)

Documentation at [this site](http://martimm.github.io/gnome-gtk3) has the ![GNU Free Documentation License](http://martimm.github.io/label/License-label-docs.svg).

# Description

The purpose of this project is to create an interface to the **GTK+** version 3 library.

# History

There is already a bit of history for this package. It started off building the `GTK::Glade` package which soon became too big. So a part was separated into `GTK::V3`. After some working with the library I felt that the class names were a bit too long and that the words `gtk` and `gdk` were repeated too many times in the class path. E.g. there was `GTK::V3::Gtk::GtkButton` and `GTK::V3::Gdk::GdkScreen` to name a few. So, finally it was split into several other packages named, `Gnome::N` for the native linkup on behalf of any other Gnome modules, `Gnome::Glib`, `Gnome::GObject`, `Gnome::Gdk3` and `Gnome::Gtk3` according to what is shown [on the developers page here](https://developer-old.gnome.org/references). The classes in these packages are now renamed into e.g. `Gnome::Gtk3::Button`, `Gnome::Gdk3::Screen`, `Gnome::GObject::Object` and `Gnome::Glib::List`.

Note that all modules are now in `:api<1>` (as of 2024/4/5). This is done to prevent clashes with future distributions having the same class names only differing in this api string. So, add this string to your import statements and dependency modules of these classes in META6.json. Furthermore add this api string also when installing with zef.

# Example

This example does the same as the example from `GTK::Simple` to show you the differences between the implementations. What immediately is clear is that this example is somewhat longer. To sum up;

### Pros

* The defaults of GTK+ are kept.
* No fancy stuff like tapping into channels to run signal handlers.
* Separation of callbacks from other code. Callbacks are always given to the routines as an object and a name. The name is the callback method which is defined in that object. Extra user data can be provided using named arguments to the callback setup.
* The most common use of callback routines is for responding to events resulting from signals like button clicks, keyboard input and mouse events. To set a callback to handle events is by calling the `register-signal()` method.

### Cons

* The code is larger because it is more low level, that is, closer to the GTK+ api.
* Code is somewhat slower. The setup of the example shown next is about 0.05 sec slower. That isn't much seen in the light that a user interface is mostly set up and drawn once.
* More worrying is the compile time of a sufficient large application.

|  |  |
| --- | --- |
| **A screenshot of the example** | **A screenshot of Gtk Simple** |

The code can be found down on the [Getting Started](https://martimm.github.io/gnome-gtk3/content-docs/tutorial/getting-started.html) page.

```
use v6.d;

use Gnome::Gtk3::Main:api<1>;
use Gnome::Gtk3::Window:api<1>;
use Gnome::Gtk3::Grid:api<1>;
use Gnome::Gtk3::Button:api<1>;

# Instantiate main module for UI control
my Gnome::Gtk3::Main $m .= new;

# Class to handle signals
class AppSignalHandlers {

  # Handle 'Hello World' button click
  method first-button-click ( :_widget($b1), :other-button($b2) ) {
    $b1.set-sensitive(False);
    $b2.set-sensitive(True);
  }

  # Handle 'Goodbye' button click
  method second-button-click ( ) {
    $m.gtk-main-quit;
 }

  # Handle window managers 'close app' button
  method exit-program ( ) {
    $m.gtk-main-quit;
  }
}

# Instantiate the event handler class and register signals
my AppSignalHandlers $ash .= new;

# Create buttons and disable the second one
with my Gnome::Gtk3::Button $second .= new(:label('Goodbye')) {
  .set-sensitive(False);
  .register-signal( $ash, 'second-button-click', 'clicked');
}

with my Gnome::Gtk3::Button $button .= new(:label('Hello World')) {
  .register-signal(
    $ash, 'first-button-click', 'clicked',  :other-button($second)
  );
}

# Create grid and add buttons to the grid
with my Gnome::Gtk3::Grid $grid .= new {
  .attach( $button, 0, 0, 1, 1);
  .attach( $second, 0, 1, 1, 1);
}

# Create a top level window and set a title among other things
with my Gnome::Gtk3::Window $top-window .= new {
  .set-title('Hello GTK!');
  .set-border-width(20);

  # Create a grid and add it to the window
  .add($grid);

  .register-signal( $ash, 'exit-program', 'destroy');

  # Show everything and activate all
  .show-all;
}

# Start the event loop
$m.gtk-main;

```

## Documentation

* [🔗 Website](http://martimm.github.io/gnome-gtk3)
* [ 🔗 Travis-ci run on master branch][travis-run]
* [ 🔗 Appveyor run on master branch][appveyor-run]
* [🔗 License document](http://www.perlfoundation.org/artistic_license_2_0)
* [🔗 Release notes](https://martimm.github.io/gnome-gtk3//content-docs/about/release-notes-gtk3.html)
* [🔗 Issues](https://github.com/MARTIMM/gnome-gtk3/issues)

# TODO

# Versions of involved software

* Program is tested against the latest version of **Raku** on **rakudo** en **moarvm**. It is also necessary to have the (almost) newest compiler, because there are some code changes which made e.g. variable argument lists to the native subs possible. Older compilers cannot handle that (before summer 2019 I believe). Bugs come and go again. There was one the software had a problem with, which was ironed away just before Raku version 2020.10.

  Some steps to follow if you want to be at the top of things (but try the easy way first!). You need `git` to get software from the github site.

  1. Make a directory to work in e.g. Raku
  2. Go in that directory and run `git clone https://github.com/rakudo/rakudo.git`
  3. Then go into the created rakudo directory and read README.md and INSTALL.md
  4. Run `perl Configure.pl --gen-moar --gen-nqp --backends=moar`
  5. Run `make test`
  6. And run `make install`

  Subsequent updates of the Raku compiler and moarvm can be installed with

  1. Go into the rakudo directory
  2. Run `git pull`
     then repeat steps 4 to 6 from above

  Your path must then be set to the program directories where `$Rakudo` is your `rakudo` directory;
  `${PATH}:$Rakudo/install/bin:$Rakudo/install/share/perl6/site/bin`

  After this, you will notice that the `raku` command is available next to `perl6` so it is also a move forward in the renaming of perl6.

  The rakudo star installation must be removed, because otherwise there will be two raku compilers wanting to be the captain on your ship. Also all modules must be reinstalled of course and are installed at `$Rakudo/install/share/perl6/site`.
* Gtk library used **Gtk 3.24**. The versioning of GTK+ is a bit different in that there is also a 3.90 and up. This is only meant as a prelude to version 4. So do not use those versions for the Raku packages.

# Installation

The version of Raku must be at least 2020.10, otherwise a few tests will not run!

There are several dependencies from one package to the other because it was one package in the past. To get all packages, just install the *Gnome::Gtk3* package and the rest will be installed with it.

```
zef install 'Gnome::Gtk3:api<1>'

```

# Issues

There are always some problems! If you find one, please help by filing an issue at [my github project](https://github.com/MARTIMM/gnome-gtk3/issues).

# Attribution

* The inventors of Raku, formerly known as Perl 6, of course and the writers of the documentation which helped me out every time again and again.
* The builders of the GTK+ library and the documentation.
* I would like to thank the developers of the `GTK::Simple` project because of the information I got while reading the code. Also because one of the files is copied unaltered for which I did not had to think about to get that right. The examples in that project are also useful to compare code with each other and to see what is or is not possible.
* Other helpful modules for their insight and use. E.g. the Cairo package of Timo.
* Documentation from [Wikibooks](https://en.wikibooks.org/wiki/GTK%2B_By_Example) and [Zetcode](http://zetcode.com/tutorials/gtktutorial/)
* Helpful hands are there when issues are raised, after requesting for help or developers returning ideas tips, etcetera for documentation; Pixlmixr, Hkdtam, JackKuhan, Alain Barbason, Clifton Wood, Rob Ransbottom, Håkon Hægland (some names are Github names).
* Icons used from [www.iconfinder.com](http://www.iconfinder.com), humility icons, Andy Fitzsimon, licensed GPL.
* Prof Stewart Weiss, [web address](http://www.compsci.hunter.cuny.edu/~sweiss/index.php). On his site are numerous documents under which many about GTK+. I have used parts from these to explain many aspects of the user interface system.

# Licenses

* Raku code and pod documentation: Artistic License 2.0
* Use of Gnome reference documentation: GNU Free Documentation License Version 1.3
* Documentation from other external sources used in tutorials: Creative Commons Attribution-ShareAlike 4.0 International Public License

# Author

Name: **Marcel Timmerman**
Github account name: **MARTIMM**

# Copyright

© 2019 - ∞ 😉. **Marcel Timmerman**


## dist_zef-raku-community-modules-Concurrent-Iterator.md
[![Actions Status](https://github.com/raku-community-modules/Concurrent-Iterator/actions/workflows/linux.yml/badge.svg)](https://github.com/raku-community-modules/Concurrent-Iterator/actions) [![Actions Status](https://github.com/raku-community-modules/Concurrent-Iterator/actions/workflows/macos.yml/badge.svg)](https://github.com/raku-community-modules/Concurrent-Iterator/actions) [![Actions Status](https://github.com/raku-community-modules/Concurrent-Iterator/actions/workflows/windows.yml/badge.svg)](https://github.com/raku-community-modules/Concurrent-Iterator/actions)

# NAME

Concurrent::Iterator - Enables safe concurrent consumption of Iterable values

# SYNOPSIS

```
use Concurrent::Iterator;

```

# DESCRIPTION

A standard Raku `Iterator` should only be consumed from one thread at a time. `Concurrent::Iterator` allows any `Iterable` to be iterated concurrently.

-head1 SYNOPSIS

```
use Concurrent::Iterator;

# Make a concurrent iterator over an infinite Range
# of ascending integers.
my $ids = concurrent-iterator(0..Inf);

# Many concurrent workers can use it to obtain the IDs,
# being confident of no duplication.
do await for ^10 {
    start {
        say "I got $ids.pull-one()";
    }
}

```

# Overview

The purpose of `Concurrent::Iterator` is to allow multiple threads to safely race to obtain values from a single iterable source of data. It:

* Uses locking to ensure that only one thread can be pulling a value from the underlying iterator at a time
* Will return `IterationEnd` to all future requests for values after it is returned by the underlying iterator (it is erroneous to call pull-one on a normal Iterator that has already produced `IterationEnd`)
* Will rethrow any exception thrown by the underlying iterator on all future requests

Together, these mean that it is possible to use a `Concurrent::Iterator` to have many workers compete for data items to process, and have them all terminate on end of sequence or exception. That might look something like this

```
my \to-process = concurrent-seq(@data);
my @results = flat await do for ^4 {
    start (compute-stuff($_) for to-process)
}

```

However, there's no reason to use `Concurrent:Iterator` for such a simple use case. It is far more simply expressed without this module as just:

```
my @results = @data.hyper.map(&compute-stuff);

```

Or, if you really wanted to enforce one-at-a-time and exactly 4 workers:

```
my @results = @data.hyper(:degree(4), :batch(1)).map(&compute-stuff);

```

# Concurrent::Iterator

The `Concurrent::Iterator` class is constructed with a single positional argument, which must be of type `Iterable:D`:

```
my $ci = Concurrent::Iterator.new(1..Inf);

```

It implements the Raku standard `Iterator` interface.

# Convenience subs

There is a convenience sub to form a `Concurrent::Iterator`:

```
my $ci = concurrent-iterator(1..Inf);

```

There is also one to have it wrapped in a `Seq`:

```
my $cs = concurrent-seq(1..Inf);

```

Which literally just passes the result of calling `concurrent-iteratorr` to `Seq.new`.

# AUTHOR

Jonathan Worthington

# COPYRIGHT AND LICENSE

Copyright 2016 - 2024 Jonathan Worthington

Copyright 2024 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## period.md
class Telemetry::Period

Performance data over a period

```raku
class Telemetry::Period is Telemetry { }

```

**Note:**  This class is a Rakudo-specific feature and not standard Raku.

```raku
# basic usage
use Telemetry;
my $t0 = Telemetry.new;
# execute some code
my $t1 = Telemetry.new;
my $period = $t1 - $t0;  # creates Telemetry::Period object
say "Code took $period<wallclock> microseconds to execute";

```

A `Telemetry::Period` object contains the difference between two [`Telemetry`](/type/Telemetry) objects. It is generally not created by calling .new, but it can be if needed. For all practical purposes, it is the same as the [`Telemetry`](/type/Telemetry) object, but the **meaning** of the values is different (and the values are generally much smaller, as they usually are the difference of two big values of the [`Telemetry`](/type/Telemetry) objects from which it was created).


## filename-extensions.md
Filename extensions

The extensions recommended for files with Raku content.

| File contents | Extension | Historic extensions |
| --- | --- | --- |
| Raku script | .raku | .pl, .p6 |
| Raku module | .rakumod | .pm, .pm6 |
| Raku documentation | .rakudoc | .pm, pm6, pod, pod6 |
| Test files in raku | .rakutest | .t |
| Not Quite Perl (NQP) | .nqp |  |

Note that in most cases, the historic extensions will still work.

# [Introduction](#Filename_extensions "go to top of document")[§](#Introduction "direct link")

An extension is the part of the filename after the final '.'; if no '.' is present, there is no extension.

Filename extensions can be used to associate behavior with the file content, such as opening a specialized reader or editor, running a program with the file content as input, etc. Even when it is not required by the operating system, filename extensions can provide a useful reminder about the contents of the file.

# [History](#Filename_extensions "go to top of document")[§](#History "direct link")

The Raku language was originally known as Perl 6, and this is reflected in the historic column above. Please use the current extensions whenever possible when generating new code.


## dist_zef-tbrowder-RakupodObject.md
[![Actions Status](https://github.com/tbrowder/RakupodObject/actions/workflows/linux.yml/badge.svg)](https://github.com/tbrowder/RakupodObject/actions) [![Actions Status](https://github.com/tbrowder/RakupodObject/actions/workflows/macos.yml/badge.svg)](https://github.com/tbrowder/RakupodObject/actions) [![Actions Status](https://github.com/tbrowder/RakupodObject/actions/workflows/windows.yml/badge.svg)](https://github.com/tbrowder/RakupodObject/actions)

# NAME

**RakupodObject** - An obsolete attempt to provide a routine to extract the '$=pod' object from an external Rakupod source (a file or a string)

**Please use Pod::Loader instead.**

# AUTHOR

Tom Browder [tbrowder@acm.org](mailto:tbrowder@acm.org)

# COPYRIGHT AND LICENSE

© 2022-2024 Tom Browder

This library is free software; you may redistribute it or modify it under the Artistic License 2.0.


## our.md
our

Combined from primary sources listed below.

# [In Variables](#___top "go to top of document")[§](#(Variables)_declarator_our "direct link")

See primary documentation
[in context](/language/variables#The_our_declarator)
for **The our declarator**.

`our` variables are created in the scope of the surrounding package. They also create an alias in the lexical scope, therefore they can be used like `my` variables as well.

```raku
module M {
    our $Var;
    # $Var available here
}

# Available as $M::Var here.
```

In order to create more than one variable with package scope, at the same time, surround the variables with parentheses:

```raku
our ( $foo, $bar );
```

see also [the section on declaring a list of variables with lexical or package scope](/language/variables#index-entry-declaring_a_list_of_variables).


## dist_zef-jonathanstowe-Manifesto.md
# Manifesto

Make a supply of the results of Promises

[![CI](https://github.com/jonathanstowe/Manifesto/actions/workflows/main.yml/badge.svg)](https://github.com/jonathanstowe/Manifesto/actions/workflows/main.yml)

## Synopsis

A different version of the old 'sleep sort'

```
use Manifesto;

my $manifesto = Manifesto.new;

for (^10).pick(*).map( -> $i { Promise.in($i + 0.5).then({ $i })}) -> $p {
    $manifesto.add-promise($p);
}

my $channel = Channel.new;

react {
    whenever $manifesto -> $v {
        $channel.send: $v;
    }
    whenever $manifesto.empty {
        $channel.close;
        done;
    }
}

say $channel.list;

```

## Description

This manages a collection of Promise objects and provides a Supply
of the result of the kept Promises.

This is useful to aggregate a number of Promises to a single stream
of results, which may then be used in, a *react* or *supply* block
or otherwise tapped.

## Installation

Assuming you have a working installation of Rakudo installed with *zef* you should be able to do either:

```
zef install Manifesto

# or from a local checkout

zef install .

```

Other equally capable installers may become available in the future.

## Support

This is so simple I'm not sure there is much scope for many bugs, but
if you have any questions, suggestions, patches or whatever please send
them via [GitHub](https://github.com/jonathanstowe/Manifesto/issues)

## Copyright and Licence

© Jonathan Stowe 2016 - 2021

This is free software, the terms are described in the <LICENCE> file in this repository.


## dist_github-Atrox-Haikunator.md
# Haikunator for Perl 6

[![Build Status](https://img.shields.io/travis/Atrox/haikunatorperl.svg?style=flat-square)](https://travis-ci.org/Atrox/haikunatorperl)

Generate Heroku-like random names to use in your **perl 6** applications.

## Installation

```
panda install Haikunator

```

or in your META.info:

```
"depends" : [ "Haikunator" ],

```

## Usage

Haikunator is pretty simple.

```
use Haikunator;

# default usage
haikunate() # => "wispy-dust-1337"

# custom length (default=4)
haikunate(:tokenLength(6)) # => "patient-king-887265"

# use hex instead of numbers
haikunate(:tokenHex(True)) # => "purple-breeze-98e1"

# use custom chars instead of numbers/hex
haikunate(:tokenChars("HAIKUNATE")) # => "summer-atom-IHEA"

# don't include a token
haikunate(:tokenLength(0))) # => "cold-wildflower"

# use a different delimiter
haikunate(:delimiter("."))) # => "restless.sea.7976"

# no token, space delimiter
haikunate(:tokenLength(0)), :delimiter(" ")) # => "delicate haze"

# no token, empty delimiter
haikunate(:tokenLength(0)), :delimiter("")) # => "billowingleaf"

```

## Options

The following options are available:

```
haikunate(
  :delimiter("-"),
  :tokenLength(4),
  :tokenHex(False),
  :tokenChars("0123456789")
)

```

*If `tokenHex` is true, it overrides any tokens specified in `tokenChars`*

## Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

* [Report bugs](https://github.com/atrox/haikunatorperl/issues)
* Fix bugs and [submit pull requests](https://github.com/atrox/haikunatorperl/pulls)
* Write, clarify, or fix documentation
* Suggest or add new features

## Other Languages

Haikunator is also available in other languages. Check them out:

* Node: <https://github.com/Atrox/haikunatorjs>
* .NET: <https://github.com/Atrox/haikunator.net>
* Python: <https://github.com/Atrox/haikunatorpy>
* PHP: <https://github.com/Atrox/haikunatorphp>
* Java: <https://github.com/Atrox/haikunatorjava>
* Go: <https://github.com/Atrox/haikunatorgo>
* Dart: <https://github.com/Atrox/haikunatordart>
* Ruby: <https://github.com/usmanbashir/haikunator>
* Rust: <https://github.com/nishanths/rust-haikunator>


## dist_cpan-ANDINUS-antlia.md
```
           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                 ANTLIA
            Antlia is a text based Rock paper scissors game

                                Andinus
           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents
─────────────────

Demo
Installation
Documentation
News

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Website
 Source
 GitHub (mirror)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Demo
════

  This was recorded with `asciinema'.

  [https://asciinema.org/a/410736.png]

  ⁃ Antlia v0.1.0:

[https://asciinema.org/a/410736.png]

Installation
════════════

  Antlia is released to CPAN, you can get it from there or install it
  from source. In any case, `zef' is required to install the
  distribution.

  You can run Antlia without `zef'. Just run `raku -Ilib bin/antlia'
  from within the source directory.

Release
───────

  1. Run `zef install antlia'.

  Antlia should be installed, try running `antlia --version' to confirm.

From Source
───────────

  You can either download the release archive generated by cgit/GitHub
  or clone the project if you have `git' installed.

Without `git'
╌╌╌╌╌╌╌╌╌╌╌╌╌

  1. Download the release:
     •
     •
  2. Extract the file.
  3. Run `zef install .' in source directory.

With `git'
╌╌╌╌╌╌╌╌╌╌

  All commits will be signed by my [PGP Key].

  ┌────
  │ # Clone the project.
  │ git clone https://git.tilde.institute/andinus/antlia
  │ cd antlia
  │
  │ # Install octans.
  │ zef install .
  └────

[PGP Key]

Documentation
═════════════

Implementation
──────────────

  Just enter the player names & it'll print each throw along with
  scores. Press enter to play another round.

Options
───────

players
╌╌╌╌╌╌╌

  Number of players. Default is 2, should be an integer equal to or
  greater than 2.

News
════

v0.1.1 - 2021-05-01
───────────────────

  ⁃ Added support for more than 2 players.
  ⁃ Prints a scorecard after the last round.

v0.1.0 - 2021-04-29
───────────────────

  Initial Implementation

```


## compilation.md
CompUnits and where to find them

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

# [Overview](#CompUnits_and_where_to_find_them "go to top of document")[§](#Overview "direct link")

Programs in Raku, as a member of the Perl language family, tend at the top level to be more at the interpreted end of the interpreted-compiled spectrum. In this tutorial, an 'interpreted' program means that the source code, namely the human-readable text such as `say 'hello world';`, is immediately processed by the `Raku` program into code that can be executed by the computer, with any intermediate stages being stored in memory.

A compiled program, by contrast, is one where the human readable source is first processed into machine-executable code and some form of this code is stored 'on disk'. In order to execute the program, the machine-readable version is loaded into memory and then run by the computer.

Both compiled and interpreted forms have advantages. Briefly, interpreted programs can be 'whipped up' quickly and the source changed quickly. Compiled programs can be complex and take a significant time to pre-process into machine-readable code, but then running them is much faster for a user, who only 'sees' the loading and running time, not the compilation time.

`Raku` has both paradigms. At the **top level** a Raku program is interpreted, but code that is separated out into a Module will be compiled and the preprocessed version is then loaded when necessary. In practice, Modules that have been written by the community will only need to be precompiled once by a user when they are 'installed', for example by a Module manager such as `zef`. Then they can be `use`d by a developer in her own program. The effect is to make `Raku` top level programs run quickly.

One of the great strengths of the `Perl` family of languages was the ability to integrate a whole ecosystem of modules written by competent programmers into a small program. This strength was widely copied and is now the norm for all languages. `Raku` takes integration even further, making it relatively easy for `Raku` programs to incorporate system libraries written in other languages into `Raku` programs, see [Native Call](/language/nativecall).

The experience from `Perl` and other languages is that the distributive nature of Modules generate several practical difficulties:

* a popular module may go through several iterations as the API gets improved, without a guarantee that there is backward compatibility. So, if a program relies on some specific function or return, then there has to be a way to specify the [`Version`](/type/Version).
* a module may have been written by Bob, a very competent programmer, who moves on in life, leaving the module unmaintained, so Alice takes over. This means that the same module, with the same name, and the same general API may have two versions in the wild. Alternatively, two developers (e.g., Alice and Bob) who initially cooperated on a module, then part company about its development. Consequently, it sometimes is necessary for there to be a way to define the **Auth** of the module.
* a module may be enhanced over time and the maintainer keeps two versions up to date, but with different APIs. So it is may be necessary to define the **API** required.
* when developing a new program a developer may want to have the modules written by both Alice and Bob installed locally. So it is not possible simply to have only one version of a module with a single name installed.

`Raku` enables all of these possibilities, allowing for multiple versions, multiple authorities, and multiple APIs to be present, installed, and available locally. The way classes and modules can be accessed with specific attributes is explained [elsewhere](/language/typesystem#Versioning,_authorship,_and_API_version.). This tutorial is about how `Raku` handles these possibilities.

# [Introduction](#CompUnits_and_where_to_find_them "go to top of document")[§](#Introduction "direct link")

Before considering the `Raku` framework, let's have a look at how languages like `Perl` or `Python` handle module installation and loading.

｢text｣ without highlighting

```

```

ACME::Foo::Bar -> ACME/Foo/Bar.pm
os.path -> os/path.py

```

```

In those languages, module names have a 1:1 relation with filesystem paths. We simply replace the double colons or periods with slashes and add a `.pm` or `.py`.

Note that these are relative paths. Both `Python` and `Perl` use a list of include paths, to complete these paths. In `Perl` they are available in the global `@INC` array.

｢text｣ without highlighting

```

```

@INC

/usr/lib/perl5/site_perl/5.22.1/x86_64-linux-thread-multi
/usr/lib/perl5/site_perl/5.22.1/
/usr/lib/perl5/vendor_perl/5.22.1/x86_64-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.22.1/
/usr/lib/perl5/5.22.1/x86_64-linux-thread-multi
/usr/lib/perl5/5.22.1/

```

```

Each of these include directories is checked for whether it contains a relative path determined from the module name. If the shoe fits, the file is loaded.

Of course that's a bit of a simplified version. Both languages support caching compiled versions of modules. So instead of just the `.pm` file `Perl` first looks for a `.pmc` file. And `Python` first looks for `.pyc` files.

Module installation in both cases means mostly copying files into locations determined by the same simple mapping. The system is easy to explain, easy to understand, simple and robust.

## [Why change?](#CompUnits_and_where_to_find_them "go to top of document")[§](#Why_change? "direct link")

Why would `Raku` need another framework? The reason is there are features that those languages lack, namely:

* Unicode module names
* Modules published under the same names by different authors
* Having multiple versions of a module installed

The set of 26 Latin characters is too restrictive for virtually all real modern languages, including English, which have diacritics for many commonly-used words.

With a 1:1 relation between module names and filesystem paths, you enter a world of pain once you try to support Unicode on multiple platforms and filesystems.

Then there's sharing module names between multiple authors. This one may or may not work out well in practice. I can imagine using it for example for publishing a module with some fix until the original author includes the fix in the "official" version.

Finally there's multiple versions. Usually people who need certain versions of modules reach for local::lib or containers or some home grown workarounds. They all have their own disadvantages. None of them would be necessary if applications could just say, hey I need good old, trusty version 2.9 or maybe a bug fix release of that branch.

If you had any hopes of continuing using the simple name mapping solution, you probably gave up at the versioning requirement. Because, how would you find version 3.2 of a module when looking for a 2.9 or higher?

Popular ideas included collecting information about installed modules in JSON files but when those turned out to be toe-nail growing slow, text files were replace by putting the metadata into SQLite databases. However, these ideas can be easily shot down by introducing another requirement: distribution packages.

Packages for Linux distributions are mostly just archives containing some files plus some metadata. Ideally the process of installing such a package means just unpacking the files and updating the central package database. Uninstalling means deleting the files installed this way and again updating the package database. Changing existing files on install and uninstall makes packagers' lives much harder, so we really want to avoid that. Also the names of the installed files may not depend on what was previously installed. We must know at the time of packaging what the names are going to be.

## [Long names](#CompUnits_and_where_to_find_them "go to top of document")[§](#Long_names "direct link")

｢text｣ without highlighting

```

```

Foo::Bar:auth<cpan:nine>:ver<0.3>:api<1>

```

```

Step 0 in getting us back out of this mess is to define a long name. A full module name in `Raku` consists of the short-name, auth, version and API

At the same time, the thing you install is usually not a single module but a distribution which probably contains one or more modules. Distribution names work just the same way as module names. Indeed, distributions often will just be called after their main module. An important property of distributions is that they are immutable. `Foo:auth<cpan:nine>:ver<0.3>:api<1>` will always be the name for exactly the same code.

## [$\*REPO](#CompUnits_and_where_to_find_them "go to top of document")[§](#$*REPO "direct link")

In `Perl` and `Python` you deal with include paths pointing to filesystem directories. In `Raku` we call such directories "repositories" and each of these repositories is governed by an object that does the [`CompUnit::Repository`](/type/CompUnit/Repository) role. Instead of an **`@INC`** array, there's the `$*REPO` variable. It contains a single repository object. This object has a **next-repo** attribute that may contain another repository. In other words: repositories are managed as a *linked list*. The important difference to the traditional array is, that when going through the list, each object has a say in whether to pass along a request to the next-repo or not. `Raku` sets up a standard set of repositories, "core", "vendor", and "site". In addition, there is a "home" repository for the current user.

Repositories must implement the `need` method. A `use` or `require` statement in `Raku` code is basically translated to a call to **`$*REPO`**'s `need` method. This method may in turn delegate the request to the next-repo.

```raku
role CompUnit::Repository {
    has CompUnit::Repository $.next-repo is rw;

    method need(CompUnit::DependencySpecification $spec,
                CompUnit::PrecompilationRepository $precomp,
                CompUnit::Store :@precomp-stores
                --> CompUnit:D
                )
        { ... }
    method loaded(
                --> Iterable
                )
        { ... }

    method id( --> Str )
        { ... }
}

```

## [Repositories](#CompUnits_and_where_to_find_them "go to top of document")[§](#Repositories "direct link")

Rakudo comes with several classes that can be used for repositories. The most important ones are [`CompUnit::Repository::FileSystem`](/type/CompUnit/Repository/FileSystem) and [`CompUnit::Repository::Installation`](/type/CompUnit/Repository/Installation). The FileSystem repo is meant to be used during module development and actually works just like `Perl` when looking for a module. It doesn't support versions or `auth`s and simply maps the short-name to a filesystem path.

The Installation repository is where the real smarts are. When requesting a module, you will usually either do it via its exact long name, or you say something along the lines of "give me a module that matches this filter." Such a filter is given by way of a `CompUnit::DependencySpecification` object which has fields for

* short-name,
* auth-matcher,
* version-matcher and
* api-matcher.

When looking through candidates, the Installation repository will smartmatch a module's long name against this DependencySpecification or rather the individual fields against the individual matchers. Thus a matcher may be some concrete value, a version range, or even a regex (though an arbitrary regex, such as `.*`, would not produce a useful result, but something like `3.20.1+` will only find candidates higher than 3.20.1).

Loading the metadata of all installed distributions would be prohibitively slow. The current implementation of the `Raku` framework uses the filesystem as a kind of database. However, another implementation may use another strategy. The following description shows how one implementation works and is included here to illustrate what is happening.

We store not only a distribution's files but also create indices for speeding up lookups. One of these indices comes in the form of directories named after the short-name of installed modules. However most of the filesystems in common use today cannot handle Unicode names, so we cannot just use module names directly. This is where the now infamous SHA-1 hashes enter the game. The directory names are the ASCII encoded SHA-1 hashes of the UTF-8 encoded module short-names.

In these directories we find one file per distribution that contains a module with a matching short name. These files again contain the ID of the dist and the other fields that make up the long name: auth, version, and api. So by reading these files we have a usually short list of auth-version-api triplets which we can match against our DependencySpecification. We end up with the winning distribution's ID, which we use to look up the metadata, stored in a JSON encoded file. This metadata contains the name of the file in the sources/ directory containing the requested module's code. This is what we can load.

Finding names for source files is again a bit tricky, as there's still the Unicode issue and in addition the same relative file names may be used by different installed distributions (think versions). So for now at least, we use SHA-1 hashes of the long-names.

## [Resources](#CompUnits_and_where_to_find_them "go to top of document")[§](#Resources "direct link")

｢text｣ without highlighting

```

```

%?RESOURCES
%?RESOURCES<libraries/p5helper>
%?RESOURCES<icons/foo.png>
%?RESOURCES<schema.sql>

Foo
|___ lib
|     |____ Foo.rakumod
|
|___ resources
      |___ schema.sql
      |
      |___ libraries
            |____ p5helper
            |        |___
            |___ icons
                     |___ foo.png

```

```

It's not only source files that are stored and found this way. Distributions may also contain arbitrary resource files. These could be images, language files or shared libraries that are compiled on installation. They can be accessed from within the module through the `%?RESOURCES` hash.

As long as you stick to the standard layout conventions for distributions, this even works during development without installing anything.

A nice result of this architecture is that it's fairly easy to create special purpose repositories.

## [Dependencies](#CompUnits_and_where_to_find_them "go to top of document")[§](#Dependencies "direct link")

Luckily precompilation at least works quite well in most cases. Yet it comes with its own set of challenges. Loading a single module is easy. The fun starts when a module has dependencies and those dependencies have again dependencies of their own.

When loading a precompiled file in `Raku` we need to load the precompiled files of all its dependencies, too. And those dependencies **must** be precompiled, we cannot load them from source files. Even worse, the precomp files of the dependencies **must** be exactly the same files we used for precompiling our module in the first place.

To top it off, precompiled files work only with the exact `Raku` binary, that was used for compilation.

All of that would still be quite manageable if it weren't for an additional requirement: as a user you expect a new version of a module you just installed to be actually used, don't you?

In other words: if you upgrade a dependency of a precompiled module, we have to detect this and precompile the module again with the new dependency.

## [Precomp stores](#CompUnits_and_where_to_find_them "go to top of document")[§](#Precomp_stores "direct link")

Now remember that while we have a standard repository chain, the user may prepend additional repositories by way of `-I` on the command line or "use lib" in the code.

These repositories may contain the dependencies of precompiled modules.

Our first solution to this riddle was that each repository gets its own precomp store where precompiled files are stored. We only ever load precomp files from the precomp store of the very first repository in the chain because this is the only repository that has direct or at least indirect access to all the candidates.

If this repository is a FileSystem repository, we create a precomp store in a `.precomp` directory.

While being the safe option, this has the consequence that whenever you use a new repository, we will start out without access to precompiled files.

Instead, we will precompile the modules used when they are first loaded.

## [Credit](#CompUnits_and_where_to_find_them "go to top of document")[§](#Credit "direct link")

This tutorial is based on a `niner` [talk](http://niner.name/talks/A%20look%20behind%20the%20curtains%20-%20module%20loading%20in%20Perl%206/).


## dist_cpan-ROBERTLE-CucumisSextus.md
# Cucumis Sextus

... a Cucumber-like Behavior-Driven Development (BDD) Test Framework for the
Raku language

## State

This is still in development, but already works for most basic cases. There are
bound to be many bugs, please let me know how you get along.

### Missing Features

* Harness improvements to allow parallel execution
* TAP integration
* Different types of reporting
* Neater printing of features/scenarios/steps as they are being executed

There is also a [ToDo List](TODO.md), and there are a lot of `XXX` fixmes in the
code.

## Usage

This is trying to be faithful and compatible to the "consensus" Cucumber
implementation, which also means that most of this documentation applies
and will also explain background and theory better than I possibly could:
<https://github.com/cucumber/cucumber/wiki/A-Table-Of-Content>

Please let me know if there are any surprising discrepancies.

### Basic Feature Files

By default, cucumis will search for feature files under `features/*.feature`, the
syntax of these is the same as in other cumumber implementations. Currently only
basic scenarios are supported, no tables or templates. An example:

```
Feature: Basic Calculator Functions
    In order to check I've written the Calculator class correctly
    As a developer I want to check some basic operations
    So that I can have confidence in my Calculator class.

Scenario: First Key Press on the Display
    Given a new Calculator object
    And having pressed 1
    Then the display should show 1

```

### Step Definitions

Cucumis will load all .pm6/.rakumod files under 'step\_definitions' in the same directory
that holds the feature file in question, e.g. "features/step\_definitions/StepDefs.rakumod":

```
unit module StepDefs;

use CucumisSextus::Glue;

Given /'a new Calculator object'/, sub () {
    # implement!
};

Step /'having pressed' \s* (\d+)/, sub ($num) {
    # implement!
};

```

Step definition modules are using semi-keywords from the CucumisSextus::Glue module
and a regular expression to define step definitions. The "Step" keywords matches any
type/verb in the scenario steps, and serves as a sort of wildcard.

When cucumis executes a feature file, it will find the appropriate step definition
for each step, and execute it. If there is no step definition or there is a problem
with it, it will report an error.

Note that the step definitions can have arguments that are taken from captures
within the regular expression, as in the "having pressed example above. You can
even use non-capturing groups in the regex and slurpy arguments (quite cool!):

```
Step /'having pressed' \s+ (\S+) [\s+ 'and' \s+ (\S+)]*/, sub (+@btns) {
    for @btns -> $b {
        # implement!
    }
}

```

Within your glue code, you can use any exception (except X::CucumisSextus::FeatureExecFailure,
which is to signal problems when trying to run the step, not *within* the step) to signal
a failure. The next steps of the scenario will be skipped, but the remaining scenarios of the
feature will be executed, as will be other features.

```
Then /'the display should be off'/, sub () {
    die "display should be off, but isn't";
}

```

### Execution

In order to execute the tests described in a feature file, the "cucumis6" tool can
be used:

```
cucumis6 features

```

Cucumis will execute your features, producing some more output, and then report the results:

```
14 scenarios executed, 4 skipped, 12 succeeded, 2 failed

```

The return code form the command will only be 0 if there are no problems executing cucumis,
and if there are no failed scenarios.

### Tags

You can tag your features and scenarios like this:

```
@calc @basic
Feature: Basic Calculator Functions
    In order to check I've written the Calculator class correctly
    As a developer I want to check some basic operations
    So that I can have confidence in my Calculator class.

@positive
Scenario: First Key Press on the Display
    Given a new Calculator object
    And having pressed 1
    Then the display should show 1

```

And then select only certain features and scenarios (the latter inherit all the
tags from the corresponding feature as well as have their own tags) when executing
cucumis:

```
cucumis6 --tags=@calc

```

You can negate the matches with a '~', and OR them together with commas:

```
cucumis6 --tags=@calc,@print
cucumis6 --tags=~@positive

```

And you can AND them together by repeatedly specifying --tags:

```
cucumis6 --tags=@calc --tags@basic

```

### Background Scenarios

You can define "background" scenarios:

```
Feature: Basic Calculator Functions
In order to check I've written the Calculator class correctly
As a developer I want to check some basic operations
So that I can have confidence in my Calculator class.

Background: Unboxing a new Calculator
    Given a freshly unboxed Calculator
    And having it switched on

Scenario: First Key Press on the Display
    Given a new Calculator object
    And having pressed 1
    Then the display should show 1

Scenario: Second Key Press on the Display
    Given a new Calculator object
    And having pressed 1
    And having pressed 2
    Then the display should show 12

```

These background scenarios will get executed before each of the other
scenarios of the feature. There can only be one background scenario and
it needs to be the first one in the feature.

### Tables

Your steps can contain tabular data:

```
Scenario: Separation of calculations
    Given a new Calculator object
    And having successfully performed the following calculations
        | first | operator | second | result |
        | 0.5   | +        | 0.1    | 0.6    |
        | 0.01  | /        | 0.01   | 1      |
        | 10    | *        | 1      | 10     |
    And having pressed 3
    Then the display should show 3

```

Your step definition code will get the table passed in as a array of
hashes, in the final parameter after the captures. The keys come from the
first line of the table in your feature file, and you get one entry per
following row:

```
Step /'having successfully performed the following calculations'/, sub (@table) {
    say @table.perl;
}

```

would yield:

```
[{:first("0.5"), :operator("+"), :result("0.6"), :second("0.1")},
 {:first("0.01"), :operator("/"), :result("1"), :second("0.01")},
 {:first("10"), :operator("*"), :result("10"), :second("1")}]

```

### Multiline Data

In a way similar to tables, you can add multiline verbatim data to your step
definitions by starting and ending such a section with three quotes:

```
Feature: Basic Calculator Functions
In order to check I've written the Calculator class correctly
As a developer I want to check some basic operations
So that I can have confidence in my Calculator class.

Scenario: Ticker Tape
    Given a new Calculator object
    And having entered the following sequence
    """
    1 + 2 + 3 + 4 + 5 + 6 -
    100
    * 13 \=\=\= + 2 =
    """
    Then the display should show -1025

```

Note that while the indentation of the three quotes themselves, like any other line
in a feature file, is not relevant, that indentation is removed from each line in the
multiline data. This also means that your indentation needs to be somewhat conistent
or cucumis will fail to do so.

The multiline data is passed to your step definition as a single argument after any
captures, just like with tables. Note that you can only use multiline data or tables
in a step, not both.

### Hooks

You can create "before" and "after" hooks in your glue code, these will be
executed before and after each scenario respectively. Before hooks will be
executed in the order they are registered, and after hooks in reverse order.
Note however that registration order is unpredicatble across multiple glue
code modules. These hooks get executed for *any* scenario, so you typically
want to inspect the feature and scenario passed in before doing anything:

```
Before sub ($feature, $scenario) {
    if $feature.tags.first(* ~~ 'hooked') {
        # implement!
    }
}

After sub ($feature, $scenario) {
    # implement!
}

```

### Outlines and Examples

You can write a single scenario and execute it multiple times for different
sets of input and output values using outlines and examples:

```
Scenario Outline: Basic arithmetic
    Given a new Calculator object
    And having keyed <first>
    And having keyed <operator>
    And having keyed <second>
    And having pressed =
    Then the display should show <result>
    Examples:
    | first | operator | second | result |
    | 5.0   | +        | 5.0    | 10     |
    | 6     | /        | 3      | 2      |
    | 10    | *        | 7.550  | 75.5   |
    | 3     | -        | 10     | -7     |

```

Note that the glue code regular expression has to match the substituted value,
not the original one from the step text.

### Other Languages

If you want to write your feature files in your native language rather than in
english, you can certianly do that by putting a language directive into the first
line of your feature file:

```
#language: hi
रूप लेख: मूलभूत गणक कार्य
    जाँच करने के लिए मैंने गणक वर्ग को सही ढंग से लिखा है
    एक विकासक के रूप में मैं कुछ बुनियादी कार्यों की जांच करना चाहता हूं
    ताकि मेरे गणक वर्ग में मुझे भरोसा हो।
परिदृश्य: प्रदर्शन पर प्रथम कुंजी दबाएं
    पूर्वानुमान एक नई गणक वस्तु
    और 1 दबाया हुआ
    अतः प्रदर्शन 1 दिखाना चाहिए

```

And then write the appropriate step definition code:

```
Then /'प्रदर्शन' \s+ (\d+) \s+ 'दिखाना चाहिए'/, sub ($num) {
    # XXX implement
}

```

Note that you could even use Hindi number literals like १ instead
of the arabic ones in the example above, the \d does detect them
correctly and $num.Int will convert to a number as well!

This should even work for right-to-left languages, but of course
you get the usual problems with shells, editors and the like:

```
#language: fa
ویژگی: عملیات ساده ماشین حساب
    جهت ارزیابی اینکه کلاس ماشین حساب را به درستی نوشته ام
    به عنوان یک برنامه نویس چند عملیات ساده ریاضی را ارزیابی می کنم
    تا از کلاس ماشین حسابم اطمینان حاصل کنم

سناریو: اولین دکمه فشرده شده در صفحه نمایش
    با فرض یک شی جدید ماشین حساب
    و فشرده شدن ۱۲۳
    آنگاه صفحه نمایش باید ۱۲۳ را نشان بدهد

```

## License

CucumisSextus is licensed under the [Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).

## Feedback and Contact

Please let me know what you think: Robert Lemmen [robertle@semistable.com](mailto:robertle@semistable.com)


## dist_zef-jforget-Date-Calendar-Bahai.md
# NAME

Date::Calendar::Bahai - Conversions from / to the Baháʼí calendar

# SYNOPSIS

```
use Date::Calendar::Bahai;
my Date $dt-greg;
my Date::Calendar::Bahai $dt-bahai;

$dt-greg  .= new(2021, 5, 17);
$dt-bahai .= new-from-date($dt-greg);

say $dt-bahai;
# --> 0178-04-01
say $dt-bahai.strftime("%A %d %B %Y");
# --> Kamál 1 ‘Aẓamat 178

```

Converting a Bahai date (e.g. 19 Jamál 178) into Gregorian

```
use Date::Calendar::Bahai;
my Date::Calendar::Bahai $dt-bahai;
my Date $dt-greg;

$dt-bahai .= new(year => 178, month => 3, day => 19);
$dt-greg   = $dt-bahai.to-date;

say $dt-greg;
# --> 2021-05-16

```

# DESCRIPTION

Date::Calendar::Bahai is a class representing dates in the Baháʼí
calendar. It allows you to convert a Baháʼí date into Gregorian or
into other implemented calendars, and it allows you to convert dates
from Gregorian or from other calendars into Baháʼí.

The Date::Calendar::Bahai class gives the early version of the Baháʼí
calendar, which is synchronised with the Gregorian calendar. The new
version, after the 2015 reform, is partially implemented in
Date::Calendar::Bahai::Astronomical, included in this distribution.

# INSTALLATION

```
zef install Date::Calendar::Bahai

```

or

```
git clone https://github.com/jforget/raku-Date-Calendar-Bahai.git
cd raku-Date-Calendar-Bahai
zef install .

```

# AUTHOR

Jean Forget

# COPYRIGHT AND LICENSE

Copyright 2021, 2024 Jean Forget

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_github-grondilu-Base58.md
![Sparky](https://sparky.sparrowhub.io/badge/grondilu-base58-raku?foo=bar)

# Base58

Satoshi Nakamoto's binary-to-text encoding in Raku. No checksum.

## Synopis

```
use Base58;

say Base58::encode "Hello World!";      # 2NEpo7TZRRrLZSi2U
say Base58::decode "2NEpo7TZRRrLZSi2U"; # Blob[uint8]:0x<48 65 6C 6C 6F 20 57 6F 72 6C 64 21>

say Base58::encode blob8.new: ^10; # 1kA3B2yGe2z4

```


## dist_zef-FRITH-Math-Libgsl-Series.md
[![Actions Status](https://github.com/frithnanth/raku-Math-Libgsl-Series/actions/workflows/test.yml/badge.svg)](https://github.com/frithnanth/raku-Math-Libgsl-Series/actions)

# NAME

Math::Libgsl::Series - An interface to libgsl, the Gnu Scientific Library - Series Acceleration

# SYNOPSIS

```
use Math::Libgsl::Series;

```

# SYNOPSIS

```
use Math::Libgsl::Series;

my Math::Libgsl::Series $s .= new: N;
constant \N = 20;
my @array := Array[Num].new;
(^N).map: -> $n { my $np1 = $n + 1e0; @array[$n] = 1e0 / ($np1 * $np1) }
my ($sum, $err) = $s.levin-accel: @array;
say "The series' sum is $sum, with an estimated error $err";

```

# DESCRIPTION

Math::Libgsl::Series is an interface to the Series Acceleration functions of libgsl, the Gnu Scientific Library.

### new(UInt:D() $size!, Bool $truncation? = False)

### new(UInt:D() :$size!, Bool :$truncation? = False)

The constructor accepts one or optionally two simple or named arguments: the mandatory series size and the optional error estimation type. This last argoment may have two values: propagation of rounding error or truncation error in the estrapolation. If the **Bool :$truncation** parameter is **True** then the error is estimated by means of the truncation error in the estrapolation. If the **Bool :$truncation** parameter is **False** then the error is estimated by means of the propagation of rounding errors.

### levin-accel(\*@array where \*.all > 0 --> List)

This method computes the extrapolated limit of the series using a Levin u-transform. It returns a **List**: the extrapolated **$sum**, the estimated **$error**, and the number of **$terms-used** during the computation.

# C Library Documentation

For more details on libgsl see <https://www.gnu.org/software/gsl/>. The excellent C Library manual is available here <https://www.gnu.org/software/gsl/doc/html/index.html>, or here <https://www.gnu.org/software/gsl/doc/latex/gsl-ref.pdf> in PDF format.

# Prerequisites

This module requires the libgsl library to be installed. Please follow the instructions below based on your platform:

## Debian Linux and Ubuntu 20.04+

```
sudo apt install libgsl23 libgsl-dev libgslcblas0

```

That command will install libgslcblas0 as well, since it's used by the GSL.

## Ubuntu 18.04

libgsl23 and libgslcblas0 have a missing symbol on Ubuntu 18.04. I solved the issue installing the Debian Buster version of those three libraries:

* <http://http.us.debian.org/debian/pool/main/g/gsl/libgslcblas0_2.5+dfsg-6_amd64.deb>
* <http://http.us.debian.org/debian/pool/main/g/gsl/libgsl23_2.5+dfsg-6_amd64.deb>
* <http://http.us.debian.org/debian/pool/main/g/gsl/libgsl-dev_2.5+dfsg-6_amd64.deb>

# Installation

To install it using zef (a module management tool):

```
$ zef install Math::Libgsl::Series

```

# AUTHOR

Fernando Santagata [nando.santagata@gmail.com](mailto:nando.santagata@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2022 Fernando Santagata

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-martimm-Gnome-Pango.md
![](https://martimm.github.io/gnome-gtk3/content-docs/images/gtk-perl6.png)

# Gnome Pango

![Artistic License 2.0](https://martimm.github.io/label/License-label.svg)

# Description

Pango is a library for layout and rendering of text, with an emphasis on internationalization. Pango can be used anywhere that text layout is needed; however, most of the work on Pango so far has been done using the GTK widget toolkit as a test platform. Pango forms the core of text and font handling for GTK.

## Documentation

* [🔗 Website, entry point for all documents and blogs](https://martimm.github.io/)
* [🔗 License document](https://www.perlfoundation.org/artistic_license_2_0)
* [🔗 Release notes of all the packages in `:api<2>`](https://github.com/MARTIMM/gnome-source-skim-tool/blob/main/CHANGES.md)
* [🔗 Issues of all the packages in `:api<2>`](https://github.com/MARTIMM/gnome-source-skim-tool/issues)

# Installation

Do not install this package on its own. Instead install `Gnome::Gtk4` newest api.

`zef install Gnome::Gtk4:api<2>`

# Author

Name: **Marcel Timmerman**
Github account name: **MARTIMM**

# Issues

There are always some problems! If you find one please help by filing an issue at [my github project](https://github.com/MARTIMM/gnome-source-skim-tool/issues).

# Attribution

* The inventors of Raku, formerly known as Perl 6, of course and the writers of the documentation which helped me out every time again and again.
* The builders of all the Gnome libraries and the documentation.
* Other helpful modules for their insight and use.


## dist_zef-raku-community-modules-Terminal-WCWidth.md
[![Actions Status](https://github.com/raku-community-modules/Terminal-WCWidth/actions/workflows/linux.yml/badge.svg)](https://github.com/raku-community-modules/Terminal-WCWidth/actions) [![Actions Status](https://github.com/raku-community-modules/Terminal-WCWidth/actions/workflows/macos.yml/badge.svg)](https://github.com/raku-community-modules/Terminal-WCWidth/actions) [![Actions Status](https://github.com/raku-community-modules/Terminal-WCWidth/actions/workflows/windows.yml/badge.svg)](https://github.com/raku-community-modules/Terminal-WCWidth/actions)

# NAME

Terminal::WCWidth - returns character width on a terminal

# SYNOPSIS

```
use Terminal::WCWidth;

sub print-right-aligned($s) {
    print " " x (80 - wcswidth($s));
    say $s;
}
print-right-aligned("this is right-aligned");
print-right-aligned("another right-aligned string")

```

# DESCRIPTION

A Raku port of a [Python module](https://github.com/jquast/wcwidth).

# SUBROUTINES

## `wcwidth`

Takes a single *codepoint* and outputs its width:

```
wcwidth(0x3042) # "あ" - returns 2

```

Returns:

* `-1` for a control character
* `0` for a character that does not advance the cursor (NULL or combining)
* `1` for most characters
* `2` for full width characters

## `wcswidth`

Takes a *string* and outputs its total width:

```
wcswidth("*ウルヰ*") # returns 8 = 2 + 6

```

Returns -1 if any control characters are found.

Unlike the Python version, this module does not support getting the width of only the first `n` characters of a string, as you can use the `.substr` method.

# ACKNOWLEDGEMENTS

Thanks to Jeff Quast (jquast), the author of the Python module, which in turn is based on the C library by Markus Kuhn.

# AUTHORS

* +merlan #flirora
* José Joaquín Atria
* Raku Community

# COPYRIGHT AND LICENSE

Copyright 2015 - 2017 +merlan #flirora

Copyright 2020, 2024 Raku Commuity

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## relative.md
relative

Combined from primary sources listed below.

# [In IO::Path](#___top "go to top of document")[§](#(IO::Path)_method_relative "direct link")

See primary documentation
[in context](/type/IO/Path#method_relative)
for **method relative**.

```raku
method relative(IO::Path:D: $base = $*CWD --> Str)
```

Returns a new [`Str`](/type/Str) object with the path relative to the `$base`. If `$base` is not provided, `$*CWD` is used in its place. If the invocant is not an absolute path, it's first made to be absolute using the `.CWD` attribute the object was created with, and then is made relative to `$base`.


## dist_github-yowcow-String-CamelCase.md
[![Build Status](https://travis-ci.org/yowcow/p6-String-CamelCase.svg?branch=master)](https://travis-ci.org/yowcow/p6-String-CamelCase)

# NAME

String::CamelCase - Camelizes and decamelizes given string

# SYNOPSIS

```
use String::CamelCase;

```

# DESCRIPTION

String::CamelCase is a module to camelize and decamelize a string.

# FUNCTIONS

Following functions are exported:

## camelize (Str) returns Str

```
camelize("hoge_fuga");
# => "HogeFuga"

camelize("hoge-fuga");
# => "HogeFuga"

```

## decamelize (Str, [Str $expr = '-']) returns Str

```
decamelize("HogeFuga");
# => hoge-fuga

decamelize("HogeFuga", "_");
# => hoge_fuga

```

## wordsplit (Str) returns List

```
wordsplit("HogeFuga");
# => ["Hoge", "Fuga"]

wordsplit("hoge-fuga");
# => ["hoge", "fuga"]

```

# SEE ALSO

[String::CamelCase](http://search.cpan.org/dist/String-CamelCase/lib/String/CamelCase.pm)

# AUTHOR

Yoko Ohyama [yowcow@cpan.org](mailto:yowcow@cpan.org)

# COPYRIGHT AND LICENSE

Copyright 2015 yowcow

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-raku-community-modules-Form.md
[![Actions Status](https://github.com/raku-community-modules/Form/workflows/test/badge.svg)](https://github.com/raku-community-modules/Form/actions)

# NAME

Form - A Raku implementation of Perl-style string formatting

# SYNOPSIS

```
use Form;

```

# DESCRIPTION

An implementation of Perl's Form module, as described by Exegesis 7 and Damian Conway's Perl6::Form module.

This is a WORK IN PROGRESS and most likely doesn't work at any given time.

# AUTHOR

Matthew Walton

Source can be located at: <https://github.com/raku-community-modules/Form> . Comments and Pull Requests are welcome.

# TODO

* DOCUMENTATION
* Data specified as lists
* Numeric fields with decimal separator and justification
* Numeric fields with thousands separators and justification
* Currencies
* Rendering of Complex numbers (currently restricted to Real)
* Everything else

# COPYRIGHT AND LICENSE

Copyright 2009 - 2012 Matthew Walton

Copyright 2013 - 2022 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-dwarring-PDF-Grammar.md
[[Raku PDF Project]](https://pdf-raku.github.io)
/ [PDF::Grammar](https://pdf-raku.github.io/PDF-Grammar-raku)

# PDF-Grammar

Although PDF documents do not lend themselves to an overall BNF style grammar
description; there are areas where these can be put to use, including:

* PDF file header and trailer/xref parsing
* Parsing of objects fetched via the xref index. Top level objects commomly include:
  dictionarys , streams, arrays or numbers.
* The overall file structure for FDF files (which are not indexed), or for
  full-scan recovery of PDF files (headers, objects, cross-reference tables
  and footers).
* Parsing the operands that make up content streams. These are used to markup text, forms,
  images and graphical elements.

PDF::Grammar is a set of Raku grammars for parsing and validation of real-world PDF examples. There are
four grammars:

`PDF::Grammar::Content` - describes the text and graphics operators that are used to produce page layout.

`PDF::Grammar::Content::Fast` - is an optimized version of PDF::Grammar::Content.

`PDF::Grammar::FDF` - this describes the file structure of FDF (Form Data) exchange files.

`PDF::Grammar::PDF` - this describes the file structure of PDF documents,
including headers, trailers, top-level objects and the cross-reference table.

`PDF::Grammar::Function` - a tokeniser for Postscript Calculator (type 4) functions.

PDF-Grammar has so far been tested against a number of sample of PDF documents and may still be subject to change.

I have been working off the [PDF 32000-1:2008 1.7](https://opensource.adobe.com/dc-acrobat-sdk-docs/standards/pdfstandards/pdf/PDF32000_2008.pdf) specification. I've relaxed rules, when needed, to handle real-world examples.

## Usage Notes

* PDF input files typically contain a mixture of ASCII directives and binary data, plus byte-orientated addressing. For this
  reason:

  * files should be read as binary (avoid encoding layers)
  * strings should be decoded as `latin1`

  `% rakudo -MPDF::Grammar::PDF -e"say PDF::Grammar::PDF.parse: slurp($f, :bin).decode('latin-1')"`
* This module is put to work by the down-stream [PDF](https://pdf-raku.github.io/PDF-raku) module. E.g.
  to uncompress a PDF, using the installed `pdf-rewriter` script:

  ```
  % pdf-rewriter.raku --uncompress flyer.pdf

  ```

## Examples

* parse some markup content:

  `% raku -M PDF::Grammar::Content -e"say PDF::Grammar::Content.parse('(Hello, world\041) Tj')"`
* parse a PDF file:

  `% rakudo -MPDF::Grammar::PDF -e"say PDF::Grammar::PDF.parsefile( $f )"`
* dump the contents of a PDF

  ```
  use v6;
  use PDF::Grammar::PDF;
  use PDF::Grammar::PDF::Actions;

  sub MAIN(Str $pdf-file) {
      my $actions = PDF::Grammar::PDF::Actions.new;

      if PDF::Grammar::PDF.parsefile( $pdf-file, :$actions ) {
          say $/.ast.raku;
      }
      else {
          say "failed to parse PDF: $pdf-file";
      }
  }

  ```

## AST Reference

The action methods in this module return AST trees. Each node in the
tree consists of a key, value pair, where the key is the AST Tag,
indicating the type of the AST node.

For example, here's the AST tree for the following parse:

```
use PDF::Grammar::PDF;
use PDF::Grammar::PDF::Actions;
my $actions = PDF::Grammar::PDF::Actions.new;

PDF::Grammar::PDF.parse( q:to"--END-DOC--", :rule<ind-obj>, :$actions);
3 0 obj <<
   /Type /Pages
   /Count 1
   /Kids [4 0 R]
>>
endobj
--END-DOC--

say '# ' ~ $/.ast.raku;
# :ind-obj($[3, 0, :dict({:Count(:int(1)), :Kids(:array([:ind-ref($[4, 0])])), :Type(:name("Pages"))})])

```

Note that there's also a `lite` mode which skips types `bool`, `int`, `real` and `null`:

```
$actions .= new: :lite;
PDF::Grammar::PDF.parse( q:to"--END-", :rule<ind-obj>, :$actions);
3 0 obj << /Count 1 >> endobj
--END--
say '# ' ~ $/.ast.raku;
# :ind-obj($[3, 0, :dict({:Count(1)})])

```

This is an indirect object (`ind-obj`), it contains a dictionary object (`dict`). Entries in the dictionary are:

* `Count` with integer value (`int`) of 1.
* `Kids`, and array (`array`) containing one indirect reference (`ind-ref`).
* `Type` with name (`name`) 'Pages'.

In most cases, the node type corresponds to the name of the rule or token that was used to construct the node.

This AST representation is used extensively throughout the PDF tool-chain. For example, as an intermediate format by `PDF::Writer` for reserialization.

For reference, here is a list of all AST node types:

| *AST Tag* | Raku Type | Description |
| --- | --- | --- |
| array | Array[Any] | Array object type, e.g. `[ 0 0 612 792 ]` |
| body | Array[Hash] | The FDF/PDF body consisting of `ind-obj` and `comment` entries. A PDF with revisions has multiple body segments |
| bool | Bool | Boolean object type, e.g. `true` [1] |
| comment | Str | (Write only) a comment string |
| cos | Hash | A PDF or FDF document, consisting of a `header` and `body` array |
| dict | Hash | Dictionary object type, e.g. `<< /Type /Catalog /Pages 3 0 R >>` |
| encoded | Str | Raw encoded stream data. This is returned as a latin-1 byte-string. |
| entries | Array[Hash] | A list of entries in a cross reference segment |
| decoded | Str | Uncompressed/unencrypted stream data |
| gen-num | UInt | Object generation number |
| header | Hash | PDF or FDF header, e.g. `%PDF1.4` |
| hex-string | Str | A hex-string, e.g. `<736e6f6f7079>` |
| ind-ref | Array[UInt] | An indirect reference, .e.g. `23 2 R` |
| ind-obj | Any | An indirect object. This is a three element array that contains an object number, generation number and the object |
| int | Int | Integer object type, e.g. `42` [1] |
| obj-count | UInt | object count/number of entries in a cross reference segment |
| obj-first-num | UInt | object first number in a cross reference segment |
| obj-num | UInt | Object number |
| offset | UInt | byte offset of an indirect object in the file. |
| literal | Str | A literal string, e.g. `(Hello, World!)` |
| name | Str | Name string, e.g. `/Fred` |
| null | Mu | Null object type, e.g. `null` [1] |
| real | Real | Real object type, e.g. `42.0` [1] |
| start | UInt | Start position of stream data (returned by `ind-obj-nibble` rule) |
| startxref | UInt | byte offset from the start of the file to the start of the trailer |
| stream | Hash | Stream object type. A dictionary indirect object followed by stream data |
| trailer | Hash | Trailer. This typically contains the trailer `dict` entry. |
| type | Str | Document type; 'pdf', or 'fdf' |
| version | Rat | The PDF / FDF version number, parsed from the header |

Note [1] Types `bool`, `int`, `real`, and `null` don't appear in `lite` mode.

## See also

* [PDF](https://pdf-raku.github.io/PDF-raku) - Raku module for PDF manipulation, including compression, encryption and reading and writing of PDF data.


## dist_github-azawawi-Odoo-Client.md
# Odoo::Client

[![Actions
Status](https://github.com/azawawi/raku-odoo-client/workflows/test/badge.svg)](https://github.com/azawawi/raku-odoo-client/actions)

A simple Odoo ERP client that uses JSON RPC.

## Example

```
use v6;
use Odoo::Client;

my $odoo = Odoo::Client.new(
    hostname => "localhost",
    port     => 8069
);

my $uid = $odoo.login(
    database => "<database>",
    username => '<email>',
    password => "<password>"
);
printf("Logged on with user id '%d'\n", $uid);

```

For more examples, please see the <examples> folder.

## Installation

To install it using zef (a module management tool bundled with Rakudo Star):

```
$ zef install Odoo::Client

```

## Testing

* To run tests:

```
$ prove --ext .rakutest -ve "raku -I."

```

* To run all tests including author tests (Please make sure
  [Test::Meta](https://github.com/jonathanstowe/Test-META) is installed):

```
$ zef install Test::META
$ AUTHOR_TESTING=1 prove --ext .rakutest -ve "raku -I."

```

## See Also

* [JSON::RPC](https://github.com/bbkr/jsonrpc)
* [Odoo ERP](http://odoo.com)
* [JSON-RPC Library](https://www.odoo.com/documentation/10.0/howtos/backend.html#json-rpc-library)

## Author

Ahmad M. Zawawi, [azawawi](https://github.com/azawawi/) on #raku

## License

MIT License


## dist_zef-ohmycloudy-SnowFlake.md
## NAME

SnowFlake - A tool for generating unique ID numbers.

## SYNOPSIS

```
use SnowFlake;

my $worker = SnowFlake.new(worker_id => 1, sequence => 2);
say $worker.get_id();

```

## DESCRIPTION

SnowFlake is a tool for generating unique ID numbers.

## LICENSE

[![](https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg)](https://opensource.org/licenses/Artistic-2.0)

## AUTHORS

* [ohmycloudy@gmail.com](mailto:ohmycloudy@gmail.com)


## dist_github-jaffa4-Log-D.md
# Log::D

The module provides support for logging. There are different type of logging: error, warning, debug, verbose, info and plain.

You create a log object, then you call methods e,w,d,v,i or p. Methods accept one argument, the logging message or two , section and message.
Sections can be allowed or banned. Logging types can be enebled or disabled.
The prefix of the log message can be given by a prefix function. Default output is $\*ERR.

## Usage

```
use Log::D;

my $f = Log::D.new(:w,:i); # create a new object , enable warning and infos

$f.prefix = sub { callframe(2).file~" "~callframe(2).line~" "~$*THREAD.id~" "~DateTime.now~" ";   }; #show line number of logging

$f.i("reached destructor");

$f.enable(:v); # let us enable verbose error messages too

$f.allow("engine func"); # if no allow is given, everything is allowed
$f.i("engine func", "engine starting");

$f.remove_allow("engine func"); # it is not longer allowed, if no allow left, all is turned on
$f.ban("low level func"); # or use ban, then it is not displayed for sure
$f.i("low level func", "print invoice");

$f.remove_ban("low level func"); # need to be able to remove it

$f.o = $*OUT; # change output of the log

use Log::Empty;
my $f = Log::Empty.new(:w,:i);   # all logging is off.. useful to replace Log::D with Log::Empty

$f.notify = True;  # show bans, allows..etc in the log as well to track their usages

```


## fail.md
fail

Combined from primary sources listed below.

# [In Failure](#___top "go to top of document")[§](#(Failure)_sub_fail "direct link")

See primary documentation
[in context](/type/Failure#sub_fail)
for **sub fail**.

```raku
multi fail(--> Nil)
multi fail(*@text)
multi fail(Exception:U $e  --> Nil )
multi fail($payload --> Nil)
multi fail(|cap (*@msg) --> Nil)
multi fail(Failure:U $f --> Nil)
multi fail(Failure:D $fail --> Nil)
```

Exits the calling [`Routine`](/type/Routine) and returns a `Failure` object wrapping the exception `$e` - or, for the `cap` or `$payload` form, an [`X::AdHoc`](/type/X/AdHoc) exception constructed from the concatenation of `@text`. If the caller activated fatal exceptions via the pragma `use fatal;`, the exception is thrown instead of being returned as a `Failure`.

```raku
# A custom exception defined
class ForbiddenDirectory is Exception {
    has Str $.name;

    method message { "This directory is forbidden: '$!name'" }
}

sub copy-directory-tree ($dir) {
    # We don't allow for non-directories to be copied
    fail "$dir is not a directory" if !$dir.IO.d;
    # We don't allow 'foo' directory to be copied too
    fail ForbiddenDirectory.new(:name($dir)) if $dir eq 'foo';
    # or above can be written in method form as:
    # ForbiddenDirectory.new(:name($dir)).fail if $dir eq 'foo';
    # Do some actual copying here
    ...
}

# A Failure with X::AdHoc exception object is returned and
# assigned, so no throwing Would be thrown without an assignment
my $result = copy-directory-tree("cat.jpg");
say $result.exception; # OUTPUT: «cat.jpg is not a directory␤»

# A Failure with a custom Exception object is returned
$result = copy-directory-tree('foo');
say $result.exception; # OUTPUT: «This directory is forbidden: 'foo'␤»
```

If it's called with a generic `Failure`, an ad-hoc undefined failure is thrown; if it's a defined `Failure`, it will be marked as unhandled.

```raku
sub re-fail {
    my $x = +"a";
    unless $x.defined {
        $x.handled = True;
        say "Something has failed in \$x ", $x.^name;
        # OUTPUT: «Something has failed in $x Failure␤»
        fail($x);
        return $x;
    }
}

my $x = re-fail;
say $x.handled; # OUTPUT: «False␤»

```

# [In Exception](#___top "go to top of document")[§](#(Exception)_routine_fail "direct link")

See primary documentation
[in context](/type/Exception#routine_fail)
for **routine fail**.

```raku
multi  fail(Exception $e)
method fail(Exception:D:)
```

Exits the calling [`Routine`](/type/Routine) and returns a [`Failure`](/type/Failure) object wrapping the exception.

```raku
# A custom exception defined
class ForbiddenWord is Exception {
    has Str $.word;
    method message { "This word is forbidden: «$!word»" }
}

sub say-word ( $word ) {
    ForbiddenWord.new(:word($word)).fail if $word eq 'foo';
    $word.say;
}

my $result = say-word("foo");
say $result.exception;

```

The routine form works in the same way, with an alternative syntax: `fail ForbiddenWord.new(:word($word))`.

# [In Channel](#___top "go to top of document")[§](#(Channel)_method_fail "direct link")

See primary documentation
[in context](/type/Channel#method_fail)
for **method fail**.

```raku
method fail(Channel:D: $error)
```

Closes the `Channel` (that is, makes subsequent `send` calls die), and enqueues the error to be thrown as the final element in the `Channel`. Method `receive` will throw that error as an exception. Does nothing if the `Channel` has already been closed or `.fail` has already been called on it.

```raku
my $c = Channel.new;
$c.fail("Bad error happens!");
$c.receive;
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::AdHoc: Bad error happens!␤»
```


## im.md
im

Combined from primary sources listed below.

# [In Complex](#___top "go to top of document")[§](#(Complex)_method_im "direct link")

See primary documentation
[in context](/type/Complex#method_im)
for **method im**.

```raku
method im(Complex:D: --> Real:D)
```

Returns the imaginary part of the complex number.

```raku
say (3+5i).im;    # OUTPUT: «5␤»
```