## dist_cpan-UZLUISF-Colorizable.md
# Colorizable

A Raku module for colorizing text using ANSI escape codes.

## Synopsis

```
use Colorizable;

my $string = "Hello" but Colorizable;

given $string {
    say .colorize: red;                            # red text
    say .colorize: :fg(red);                       # same as previous
    say .red;                                      # same as previous

    say .colorize: red, blue;                      # red text on blue background
    say .colorize: :fg(red), :bg(blue);            # same as previous
    say .red.on-blue;                              # same as previous

    say .colorize: red, blue, bold;                # bold red text on blue background
    say .colorize: :fg(red), :bg(blue), :mo(bold); # same as previous
    say .red.on-blue.bold;                         # same as previous
}

```

## Installation

From [Raku module ecosystem](https://modules.raku.org/) using `zef`:

```
$ zef install Colorizable

```

From source code:

```
$ git clone https://gitlab.com/uzluisf/raku-colorizable.git
$ cd raku-colorizable/
$ zef install .

```

## Description

The module allows to colorize text using ANSI escape code by composing the `Colorizable` role into a string. After doing this, the method `colorize` can be used to set the text color, background color and text effects (e.g., bold, italic, etc.):

```
use Colorizable;

my $planet = "Arrakis" but Colorizable;
say $planet.colorize(:fg(blue), :bg(red), :mo(bold));

```

If composed into a class, `Colorizable` assumes the class implements the appropriate `Str` method:

```
use Colorizable;

class A does Colorizable {
}

say A.new.colorize(blue); #=> A<94065101711120>, in blue

class B does Colorizable {
    method Str { 'Class B' }
}

say B.new.colorize(blue); #=> class B, in blue

```

Invocations to the `colorize` method are chainable:

```
use Colorizable;

my $text = "Bold red text on yellow background" but Colorizable;

say $text
.colorize(:fg(red))
.colorize(:bg(yellow))
.colorize(:mo(bold));

```

Colors and modes can be invoked as methods: `.color` for foreground, `.on-color` for background, and `.mode` for mode given `color` and `mode` respectively:

```
use Colorizable;

my $text = "Bold red text on yellow background" but Colorizable;

say $text.red.on-yellow.bold;

```

To get a list of available colors and modes, use the `colors` and `modes` methods respectively

Although this might not be advisable, you can make regular strings colorizable by augmenting the `Str` class:

```
use Colorizable;
use MONKEY-TYPING;

# making strings colorizable
augment class Str {
    also does Colorizable;
}

say "Bold red text on yellow background"
.colorize(:fg(red))
.colorize(:bg(yellow))
.colorize(:mo(bold));

```

Note the use of the pragma [`MONKEY-TYPING`](https://docs.raku.org/language/pragmas#index-entry-MONKEY-TYPING__pragma).

## Methods

# colorize

`method colorize($fg, $bg, $mo)`

Change color of string.

**Examples:**

```
my $str = "Hello" does Colorizable;
say $str.colorize(yellow);          # yellow text
say $str.colorize('yellow');        # yellow text
say $str.colorize(blue, red, bold); # bold blue text in red background

```

**Parameters:**

* `$fg` the string's foreground color
* `$bg` the string's background color
* `$mo` the string's mode

# colorize

`method colorize(:fg(:$foreground), :bg(:$background), :mo(:$mode))`

Change color of string.

**Examples:**

```
my $str = "Hello" does Colorizable;
say $str.colorize(:fg(yellow));           # yellow text
say $str.colorize(:foreground('yellow')); # yellow text
say $str.colorize(:fg(blue), :bg(red));   # blue text in red background

```

**Parameters:**

* `$fg` the string's foreground color
* `$bg` the string's background color
* `$mo` the string's mode

# colors

`method colors(--> List)`

Return list of available colors as allomorphs. By default, the `IntSt` values for the foreground are returned. To return the values for the background, pass the Boolean named argument `bg` (or `background`).

**Examples:**

```
my $str = "Hello" does Colorizable;
say $str.colors.head(3).join(' ');           #=> «black red green␤»
say $str.colors.head(3)».Int.join(' ');      #=> «30 31 32␤»
say $str.colors(:bg).head(3).join(' ');      #=> «black red green␤»
say $str.colors(:bg).head(3)».Int.join(' '); #=> «40 41 42␤»

```

# modes

`method modes( --> List )`

Return list of available modes as allomorphs.

**Examples:**

```
my $str = "Hello" does Colorizable;
say $str.modes.head(3).join(' ');      #=> «default-mode bold italic␤»
say $str.modes.head(3)».Int.join(' '); #=> «0 1 3␤»

```

# is-colorized

`method is-colorized( --> Bool )`

Return true if the string is colorized. Otherwise, false. A string is considered colorized if it has at least one element (foreground, background, or mode) set.

**Examples:**

```
my $str = "Hello" does Colorizable;
say $str.is-colorized;

```

# uncolorize

`method uncolorize( --> Str )`

Return uncolorized string.

**Examples:**

```
my $str = "Hello" does Colorizable;
say $str.uncolorize;

```

# color-samples

`method color-samples()`

Display color samples.

**Examples:**

```
my $str = "Hello" does Colorizable;
$str.color-samples; # display color samples

```

## More examples

### How to make rainbow-y strings?

An option is to create a subroutine that colorizes a string character by character:

```
sub rainbow( $str, :@only ) {
    sub rainbowize( @colors ) {
        $str.comb
        .batch(@colors.elems)
        .map({($_ Z @colors).map(-> ($ch, $fg) { ($ch does Colorizable).colorize($fg) }).join })
        .join
    }

    return rainbowize(@only) if @only;
    return rainbowize Color.enums.keys.list;
}

say rainbow "Hello, World!";
say rainbow "Hello, World!", :only[blue, red, yellow];

```

Another "I know what I'm doing" alternative is to implement a somewhat similar routine right into the `Str` class after composing `Colorizable` into it:

```
use MONKEY-TYPING;

augment class Str {
    also does Colorizable;

    method rainbow( $str : :@only ) {
        sub rainbowize( @colors ) {
            $str.comb
            .batch(@colors.elems)
            .map({($_ Z @colors).map(-> ($ch, $fg) { $ch.colorize($fg) }).join })
            .join
        }

        return rainbowize(@only) if @only;
        return rainbowize Color.enums.keys.list;
    }
}

say "Hello, World!".rainbow;
say "Hello, World!".rainbow: :only[blue, red, yellow];

```

## Acknowledgement

This module is inspired by [Michał Kalbarczyk](https://github.com/fazibear)'s Ruby gem [colorize](https://github.com/fazibear/colorize).

## Authors

Luis F. Uceta

## License

You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.

The META6.json file of this distribution may be distributed and modified without restrictions or attribution.


## dist_zef-librasteve-Physics-Constants.md
[![](https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg)](https://opensource.org/licenses/Artistic-2.0)
[![](https://github.com/librasteve/raku-Physics-Constants/actions/workflows/constants-weekly.yaml/badge.svg)](https://github.com/librasteve/raku-Physics-Constants/actions/workflows/constants-weekly.yaml)

Bridging physical constants into [Physics::Measure](https://github.com/librasteve/raku-Physics-Measure) objects

# SYNOPSIS

```
#!/usr/bin/env raku
use Physics::Constants;  #<== must use before Physics::Measure
use Physics::Measure :ALL;

say ~kg-amu;                        #6.02214076e+26 mol^-1  (avogadro number = Na)
say ~plancks-h;                     #6.626070015e-34 J.s
say ~faraday-constant;              #96485.33212 C/mol
say ~fine-structure-constant;       #0.0072973525693   (dimensionless)
say ~μ0;                            #1.25663706212e-06 H/m
say ~ℏ;                             #1.054571817e-34 J.s

my \λ = 2.5nm;
say "Wavelength of photon (λ) is " ~λ;

my \ν = c / λ;
say "Frequency of photon (ν) is " ~ν.in('petahertz');

my \Ep = ℎ * ν;
say "Energy of photon (Ep) is " ~Ep.in('attojoules');

#Wavelength of photon (λ) is 2.5 nm
#Frequency of photon (ν) is 119.9169832 petahertz
#Energy of photon (Ep) is 79.45783266707788 attojoules

This module is a wrapper on JJ Merelo Math::Constants
https://github.com/JJ/p6-math-constants
#say '----------------';
#say @physics-constants;
#say '----------------';
#say @physics-constants-names.sort;
#say '----------------';
#say @physics-constants-symbols.sort;

```

Copyright (c) Henley Cloud Consulting Ltd. 2021-2023


## tapbeforespawn.md
class X::Proc::Async::TapBeforeSpawn

Error due to tapping a Proc::Async stream after spawning its process

```raku
class X::Proc::Async::TapBeforeSpawn is Exception {}
```

If the `stdout` or `stderr` methods of [`Proc::Async`](/type/Proc/Async) are called after the program has been `start`ed, an exception of type `X::Proc::Async::TapBeforeSpawn` is thrown.

```raku
my $proc = Proc::Async.new("echo", "foo");
$proc.start;
$proc.stdout.tap(&print);
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Proc::Async::TapBeforeSpawn: To avoid data races, you must tap stdout before running the process␤»
```

The right way is the reverse order

```raku
my $proc = Proc::Async.new("echo", "foo");
$proc.stdout.tap(&print);
await $proc.start;
```

# [Methods](#class_X::Proc::Async::TapBeforeSpawn "go to top of document")[§](#Methods "direct link")

## [method handle](#class_X::Proc::Async::TapBeforeSpawn "go to top of document")[§](#method_handle "direct link")

```raku
method handle(X::Proc::Async::TapBeforeSpawn:D: --> Str:D)
```

Returns the name of the handle (`stdout` or `stderr`) that was accessed after the program started.


## dist_zef-deoac-App-APOTD.md
[![Actions Status](https://github.com/deoac/App-APOTD/actions/workflows/test.yml/badge.svg)](https://github.com/deoac/App-APOTD/actions)

### multi sub MAIN

```
multi sub MAIN(
    Bool :$pod!
) returns Mu

```

Run with '--pod' to see all of the POD6 objects

### multi sub MAIN

```
multi sub MAIN(
    Str :$doc!
) returns Mu

```

Run with '--doc' to generate a document from the POD6 It will be rendered in Text format unless specified with the --format option. e.g. --format=HTML

# TITLE

Astronomy Picture of the Day

# SUBTITLE

Download Today's Astronomy Picture of the Day

# VERSION

This documentation refers to `apotd` version 1.0.9

# USAGE

```
apotd [-v|-V|--version] [--verbose]
apotd [-d|--dir=<Str>] [-f|--filename=<Str>] [-a|--prepend-count]

  -d|--dir=<Str>         What directory should the image be saved to? [default: '$*HOME/Pictures/apotd']
  -f|--filename=<Str>    What filename should it be saved under? [default: the caption of the image]
  -a|--prepend-count     Add a count to the start of the filename. [default: False]

```

To downloand the image and save it using the default behavior, simply:

```
$ apotd

```

# DESCRIPTION

[Astronomy Picture of the Day](https://apod.nasa.gov/apod/astropix.html) is a website provided by NASA and Michigan Technological University which provides a different astronomy picture every day.

**Each day a different image or photograph of our fascinating universe is**

featured, along with a brief explanation written by a professional astronomer.

Set `apotd` as a cronjob (\*nux), launch agent (MacOS), or Task Scheduler (Windows) and you'll accumulate a beautiful collection of images for wallpaper, screen savers, etc.

# SYNOPSIS

By default, `apotd` will save to

```
~/Pictures/apotd/

```

with the filename taken from the caption of the photo e.g.

```
Dark Nebulae and Star Formation in Taurus.jpg

```

and will optionally prepend a number which increments with each new image, e.g.

```
2483-Dark Nebulae and Star Formation in Taurus.jpg

```

Macintosh allows a comment to be associated with each file. So on Macs, `apodt` will copy the `alt` text and the permalink for the image into the file's comment, e.g.

**A star field strewn with bunches of brown dust is pictured. In the center is a bright area of light brown dust, and in the center of that is a bright region of star formation.**

<https://apod.nasa.gov/apod/ap230321.html>

# OPTIONS

```
# Save to directory "foo"
$ apotd --dir=foo
$ apotd    -d=foo

# Save with the filename "bar"
# The image's extension, e.g. ".jpg", will be automatically added.
$ apotd --file=bar
$ apotd     -f=bar

# Prepend a count to the filename
$ apotd --prepend-count
$ apotd  -p

```

# DIAGNOSTICS

## General problems

Failed to get the directory contents of <*directory*>: Failed to open dir: No such file or directory

Failed to create directory <*directory*>: Failed to mkdir: No such file or directory

Failed to resolve host name 'apod.nasa.gov'

## Problems specific to `apotd`

Couldn't find an image on the site. It's probably a video today.

The image has already been saved as <*filename*>.

Couldn't write the alt-text to <*path*>.

## Success

Successfully wrote Pictures/apotd/ 2483-Dark Nebulae and Star Formation in Taurus.jpg

Successfully wrote the alt-text and permanent link as a comment to the file.

# DEPENDENCIES

```
LWP::Simple;
Filetype::Magic;
Digest::SHA1::Native;

```

# ASSUMPTIONS

`apotd` assumes that the caption of the photo is the first `<b> ... </b>` line in the HTML code.

And that the image is the first `<IMG SRC=` html tag.

And that tag has an `alt=` attribute.

# BUGS AND LIMITATIONS

There are no known bugs in this module.

# AUTHOR

Shimon Bollinger [deoac.shimon@gmail.com](mailto:deoac.shimon@gmail.com)

Source can be located at: <https://github.com/deoac/apotd.git>

Comments, suggestions, and pull requests are welcome.

# LICENSE AND COPYRIGHT

© 2023 Shimon Bollinger

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See [perlartistic](http://perldoc.perl.org/perlartistic.html).

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


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

# NAME

CLI::Version - add -V / --version parameters to your script

# SYNOPSIS

```
proto sub MAIN(|) {*}
use CLI::Version $?DISTRIBUTION, &MAIN;

# alternately:
use CLI::Version $?DISTRIBUTION, proto sub MAIN(|) {*}

# only allow --version
use CLI::Version $?DISTRIBUTION, proto sub MAIN(|) {*}, "long-only";

```

# DESCRIPTION

CLI::Version adds a `multi sub` candidate to the `&MAIN` function in your script, that will trigger if the script is called with `-V` or `--version` arguments **only**.

For instance, in the [App::Rak](https://raku.land/zef:lizmat/App::Rak) distribution, which provides a `rak` CLI, calling `rak -V` will result in something like:

```
$ rak --version
rak - provided by App::Rak 0.3.2, running Raku 6.d with Rakudo 2024.07.

```

If the candidate is triggered, it will exit with the default value for `exit` (which is usually **0**).

If you would also like to see the description of the module, you can add `--verbose` as an argument: then you get something like:

```
$ rak --version --verbose
rak - 21st century grep / find / ack / ag / rg on steroids.
Provided by App::Rak 0.3.2, running Raku 6.d with Rakudo 2024.07.

```

By specifying a true value as the 3rd argument in the `use` statement, will cause only `--version` to trigger the candidate.

# IMPLEMENTATION NOTES

Due to the fact that the `$?DISTRIBUTION` and `&MAIN` of the code that uses this module, can **not** be obtained by a public API, it is necessary to provide them in the `use` statement. This need may disappear in future versions of the Raku Programming Language.

# AUTHOR

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

Source can be located at: <https://github.com/lizmat/CLI-Version> . 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 2022, 2024 Elizabeth Mattijsen

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


## dist_zef-rawleyfowler-Humming-Bird.md
# Humming-Bird

![](https://user-images.githubusercontent.com/75388349/222969311-216081eb-fe47-4f97-bc49-d52fc8750a24.svg)

![Zef Badge](https://raku.land/zef:rawleyfowler/Humming-Bird/badges/version?)
[![SparrowCI](https://ci.sparrowhub.io/project/gh-rawleyfowler-Humming-Bird/badge)](https://ci.sparrowhub.io)

Humming-Bird is a simple, composable, and performant web-framework for Raku on MoarVM.
Humming-Bird was inspired mainly by [Sinatra](https://sinatrarb.com), and [Express](https://expressjs.com), and tries to keep
things minimal, allowing the user to pull in things like templating engines, and ORM's on their own terms.

## Features

Humming-Bird has 2 simple layers, at the lowest levels we have `Humming-Bird::Glue` which is a simple "glue-like" layer for interfacing with
`Humming-Bird::Backend`'s.
Then you have the actual application logic in `Humming-Bird::Core` that handles: routing, middleware, error handling, cookies, etc.

* Powerful function composition based routing and application logic

  * Routers
  * Groups
  * Middleware
  * Advice (end of stack middleware)
  * Simple global error handling
  * Plugin system
* Simple and helpful API

  * get, post, put, patch, delete, etc
  * Request content will be converted to the appropriate Raku data-type if possible
  * Static files served have their content type infered
  * Request/Response stash's for inter-layer route talking
* Swappable backends

**Note**: Humming-Bird is not meant to face the internet directly. Please use a reverse proxy such as Apache, Caddy or NGiNX.

## How to install

Make sure you have [zef](https://github.com/ugexe/zef) installed.

#### Install latest

```
zef -v install https://github.com/rawleyfowler/Humming-Bird.git

```

#### Install stable

```
zef install Humming-Bird

```

## Performance

See [this](https://github.com/rawleyfowler/Humming-Bird/issues/43#issuecomment-1454252501) for a more detailed performance preview
vs. Ruby's Sinatra using `Humming-Bird::Backend::HTTPServer`.

## Examples

#### Simple example:

```
use v6.d;

use Humming-Bird::Core;

get('/', -> $request, $response {
    $response.html('<h1>Hello World</h1>');
});

listen(8080);

# Navigate to localhost:8080!

```

#### Simple JSON CRUD example:

```
use v6.d;

use Humming-Bird::Core;
use JSON::Fast; # A dependency of Humming-Bird

my %users = Map.new('bob', %('name', 'bob'), 'joe', %('name', 'joe'));

get('/users/:user', -> $request, $response {
    my $user = $request.param('user');

    if %users{$user}:exists {
        $response.json(to-json %users{$user});
    } else {
        $response.status(404).html("Sorry, $user does not exist.");
    }
});

post('/users', -> $request, $response {
    my %user = $request.content; # Different from $request.body, $request.content will do its best to decode the data to a Map.
    if my-user-validation-logic(%user) { # Validate somehow, i'll leave that up to you.
        %users{%user<name>} = %user;
        $response.status(201); # 201 created
    } else {
        $response.status(400).html('Bad request');
    }
});

listen(8080);

```

#### Using plugins

```
use v6.d;

use Humming-Bird::Core;

plugin 'Logger'; # Corresponds to the pre-built Humming-Bird::Plugin::Logger plugin.
plugin 'Config'; # Corresponds to the pre-built Humming-Bird::Plugin::Config plugin.

get('/', sub ($request, $response) {
    my $database_url = $request.config<database_url>;
    $response.html("Here's my database url :D " ~ $database_url);
});

listen(8080);

```

#### Routers

```
use v6.d;

use Humming-Bird::Core;
use Humming-Bird::Middleware;

# NOTE: Declared routes persist through multiple 'use Humming-Bird::Core' statements
# allowing you to declare routing logic in multiple places if you want. This is true
# regardless of whether you're using the sub or Router process for defining routes.
my $router = Router.new(root => '/');

plugin 'Logger';

$router.get(-> $request, $response { # Register a GET route on the root of the router
    $response.html('<h1>Hello World</h1>');
});

$router.get('/foo', -> $request, $response { # Register a GET route on /foo
    $response.html('<span style="color: blue;">Bar</span>');
});

my $other-router = Router.new(root => '/bar');

$other-router.get('/baz', -> $request, $response { # Register a GET route on /bar/baz
    $response.file('hello-world.html'); # Will render hello-world.html and infer its content type
});

# No need to register routers, it's underlying routes are registered with Humming-Bird on creation.
listen(8080);

```

#### Middleware

```
use v6.d;

use Humming-Bird::Core;
use Humming-Bird::Middleware;

get('/logged', -> $request, $response {
    $response.html('This request has been logged!');
}, [ &middleware-logger ]); # &middleware-logger is provided by Humming-Bird::Middleware

# Custom middleware
sub block-firefox($request, $response, &next) {
    return $response.status(400) if $request.header('User-Agent').starts-with('Mozilla');
    $response.status(200);
}

get('/no-firefox', -> $request, $response {
    $response.html('You are not using Firefox!');
}, [ &middleware-logger, &block-firefox ]);

listen(8080);

```

Since Humming-Bird `3.0.4` it may be more favorable to use plugins to register global middlewares.

#### Swappable Backends

```
use v6.d;

use Humming-Bird::Core;

get('/', -> $request, $response {
    $response.html('This request has been logged!');
});

# Run on a different backend, assuming:
listen(:backend(Humming-Bird::Backend::MyBackend));

```

More examples can be found in the [examples](https://github.com/rawleyfowler/Humming-Bird/tree/main/examples) directory.

## Swappable backends

In Humming-Bird `3.0.0` and up you are able to write your own backend, please follow the API outlined by the `Humming-Bird::Backend` role,
and view `Humming-Bird::Backend::HTTPServer` for an example of how to implement a Humming-Bird backend.

## Plugin system

Humming-Bird `3.0.4` (`4.0.0` created a breaking change for plugins) and up features the Humming-Bird Plugin system, this is a straight forward way to extend Humming-Bird with desired functionality before the server
starts up. All you need to do is create a class that inherits from `Humming-Bird::Plugin`, for instance `Humming-Bird::Plugin::Config`, expose a single method `register` which
takes arguments that align with the arguments specified in `Humming-Bird::Plugin.register`, for more arguments, take a slurpy at the end of your register method.

If the return value of a `Humming-Bird::Plugin.register` is a `Hash`, Humming-Bird will assume that you
are returning helpers from your plugin, meaning the keys and values will be bound to `Humming-Bird::HTTPAction`.
This allows you to use functionality easily in your request/response life-cycles.

Here is an example of a plugin:

```
use JSON::Fast;
use Humming-Bird::Plugin;
use Humming-Bird::Core;

unit class Humming-Bird::Plugin::Config does Humming-Bird::Plugin;

method register($server, %routes, @middleware, @advice, **@args) {
    my $filename = @args[0] // '.humming-bird.json';
    my %config = from-json($filename.IO.slurp // '{}');

    # The key will become the name, and the value will become a method on Humming-Bird::Glue::HTTPAction,
    # allowing you to have helper methods available in your request/response life-cycle.
    return %(
        config => sub (Humming-Bird::Glue::HTTPAction $action) {
            %config;
        }
    );

    CATCH {
        default {
            warn 'Failed to find or parse your ".humming-bird.json" configuration. Ensure your file is well formed, and does exist.';
        }
    }
}

```

This plugin embeds a `.config` method on the base class for Humming-Bird's Request and Response classes, allowing your config to be accessed during the request/response lifecycle.

Then to register it in a Humming-Bird application:

```
use Humming-Bird::Core;

plugin 'Config', 'config/humming-bird.json'; # Second arg will be pushed to he **@args array in the register method.

get('/', sub ($request, $response) {
    $response.write($request.config<foo>); # Echo back the <foo> field in our JSON config.
});

listen(8080);

```

## Design

* Humming-Bird should be easy to pickup, and simple for developers new to Raku and/or web development.
* Humming-Bird is not designed to be exposed to the internet directly. You should hide Humming-Bird behind a reverse-proxy like NGiNX, Apache, or Caddy.
* Simple and composable via middlewares.

## Things to keep in mind

* This project is in active development, things will break.
* You may run into bugs.
* This project is largely maintained by one person.

## Contributing

All contributions are encouraged! I know the Raku community is amazing, so I hope to see
some people get involved :D

Please make sure you squash your branch, and name it accordingly before it gets merged!

#### Testing

Install App::Prove6

```
zef install --force-install App::Prove6

```

Ensure that the following passes:

```
cd Humming-Bird
zef install . --force-install --/test
prove6 -v -I. t/ it/

```

## License

Humming-Bird is available under the MIT, you can view the license in the `LICENSE` file
at the root of the project. For more information about the MIT, please click
[here](https://mit-license.org/).


## quoting.md
Quoting constructs

Writing strings and word lists, in Raku

# [The Q lang](#Quoting_constructs "go to top of document")[§](#The_Q_lang "direct link")

Strings are usually represented in Raku code using some form of quoting construct. The most minimalistic of these is `Q`, usable via the shortcut `｢…｣`, or via `Q` followed by any pair of delimiters surrounding your text, including many [Unicode pairs](https://github.com/Raku/roast/blob/aa4994a7f6b3f6b450a9d231bebd5fba172439b0/S02-literals/quoting-unicode.t#L49-L65). Most of the time, though, the most you'll need is `'…'` or `"…"`, described in more detail in the following sections.

For information about quoting as applied in regexes, see the [regular expression documentation](/language/regexes).

## [Literal strings: Q](#Quoting_constructs "go to top of document")[§](#Literal_strings:_Q "direct link")

```raku
Q[A literal string]
｢More plainly.｣
Q^Almost any non-word character can be a delimiter!^
Q｢｢Delimiters can be repeated/nested if they are adjacent.｣｣
Q｟Quoting with fancy unicode pairs｠

```

Delimiters can be nested, but in the plain `Q` form, backslash escapes aren't allowed. In other words, basic `Q` strings are as literal as possible.

Some delimiters are not allowed immediately after `Q`, `q`, or `qq`. Any characters that are allowed in [identifiers](/language/syntax#Identifiers) are not allowed to be used, since in such a case, the quoting construct together with such characters are interpreted as an identifier. In addition, `( )` is not allowed because that is interpreted as a function call. If you still wish to use those characters as delimiters, separate them from `Q`, `q`, or `qq` with a space. Please note that some natural languages use a left delimiting quote on the right side of a string. `Q` will not support those as it relies on unicode properties to tell left and right delimiters apart.

```raku
Q'this will not work!'
Q(this won't work either!)

```

The examples above will produce an error. However, this will work

```raku
Q (this is fine, because of space after Q)
Q 'and so is this'
Q<Make sure you <match> opening and closing delimiters>
Q{This is still a closing curly brace → \}

```

These examples produce:

```raku
this is fine, because of space after Q
and so is this
Make sure you <match> opening and closing delimiters
This is still a closing curly brace → \

```

The behavior of quoting constructs can be modified with adverbs, as explained in detail in later sections.

|  |  |  |
| --- | --- | --- |
| Short | Long | Meaning |
| :x | :exec | Execute as command and return results |
| :w | :words | Split result on words (no quote protection) |
| :ww | :quotewords | Split result on words (with quote protection) |
| :q | :single | Interpolate \\, \qq[...] and escaping the delimiter with \ |
| :qq | :double | Interpolate with :s, :a, :h, :f, :c, :b |
| :s | :scalar | Interpolate $ vars |
| :a | :array | Interpolate @ vars (when followed by postcircumfix) |
| :h | :hash | Interpolate % vars (when followed by postcircumfix) |
| :f | :function | Interpolate & calls |
| :c | :closure | Interpolate {...} expressions |
| :b | :backslash | Enable backslash escapes (\n, \qq, \$foo, etc) |
| :to | :heredoc | Parse result as heredoc terminator |
| :v | :val | Convert to allomorph if possible |

These adverbs can be used together with `Q`, so that it will interpolate even if the quoting operator does not:

```raku
my %þ = :is-mighty;
say Q "Þor %þ<>";                         # OUTPUT: «Þor %þ<>␤»
say Q:h"Þor %þ<>";                        # OUTPUT: «Þor is-mighty   True␤»
%þ = :42foo, :33bar;
say Q:h:c "Þor %þ<> →  { [+] %þ.values}"; # OUTPUT: «Þor bar 33␤foo  42 →  75␤»
my @þ= <33 44>; say Q:a "Array contains @þ[]"; # OUTPUT: «Array contains 33 44␤»
say Q:v<33> + 3;                          # OUTPUT: «36␤»

```

By default, and as shown, `Q` quotes directly without any kind of transformation of the quoted string. The adverbs will modify its behavior, converting, for instance, the string into an allomorph (with the `:v` adverb) or allowing interpolation of hashes (via `:h`) or `{}` code sections (via `:c`). Arrays and hashes must be *followed by a postcircumfix*; that is, the sigiled identifier will not interpolate, but followed by an indexing, decont operator or a method call with parentheses, it will:

```raku
my @þ= <33 44>;
say Q:a "Array contains @þ.elems()"; # OUTPUT: «Array contains 2␤»

```

The same code without the parentheses will simply not interpolate, absent the post-circumfix operator.

## [Escaping: q](#Quoting_constructs "go to top of document")[§](#Escaping:_q "direct link")

```raku
'Very plain';
q[This back\slash stays];
q[This back\\slash stays]; # Identical output
q{This is not a closing curly brace → \}, but this is → };
Q :q $There are no backslashes here, only lots of \$\$\$!$;
'(Just kidding. There\'s no money in that string)';
'No $interpolation {here}!';
Q:q!Just a literal "\n" here!;

```

The `q` form allows for escaping characters that would otherwise end the string using a backslash. The backslash itself can be escaped, too, as in the third example above. The usual form is `'…'` or `q` followed by a delimiter, but it's also available as an adverb on `Q`, as in the fifth and last example above.

These examples produce:

｢text｣ without highlighting

```

```

Very plain
This back\slash stays
This back\slash stays
This is not a closing curly brace → } but this is →
There are no backslashes here, only lots of $$$!
(Just kidding. There's no money in that string)
No $interpolation {here}!
Just a literal "\n" here

```

```

The `\qq[...]` escape sequence enables [`qq` interpolation](/language/quoting#Interpolation:_qq) for a portion of the string. Using this escape sequence is handy when you have HTML markup in your strings, to avoid interpretation of angle brackets as hash keys:

```raku
my $var = 'foo';
say '<code>$var</code> is <var>\qq[$var.uc()]</var>';
# OUTPUT: «<code>$var</code> is <var>FOO</var>␤»
```

## [Interpolation: qq](#Quoting_constructs "go to top of document")[§](#Interpolation:_qq "direct link")

```raku
my $color = 'blue';
say "My favorite color is $color!"; # OUTPUT: «My favorite color is blue!␤»

```

The `qq` form – usually written using double quotes – allows for interpolation of backslash escape sequences (like `q:backslash`), all sigiled variables (like `q:scalar:array:hash:function`), and any code inside `{...}` (like `q:closure`).

### [Interpolating variables](#Quoting_constructs "go to top of document")[§](#Interpolating_variables "direct link")

Inside a `qq`-quoted string, you can use variables with a sigil to trigger interpolation of the variable's value. Variables with the `$` sigil are interpolated whenever the occur (unless escaped); that's why, in the example above, `"$color"` became `blue`.

Variables with other sigils, however, only trigger interpolation when you follow the variable with the appropriate postfix (`[]` for Arrays, `<>`, for Hashes, `&` for Subs). This allows you to write expressions like `"[email protected]"` without interpolating the `@raku` variable.

To interpolate an Array (or other [`Positional`](/type/Positional) variable), append a `[]` to the variable name:

```raku
my @neighbors = "Felix", "Danielle", "Lucinda";
say "@neighbors[] and I try our best to coexist peacefully."
# OUTPUT: «Felix Danielle Lucinda and I try our best to coexist peacefully.␤»

```

Alternatively, rather than using `[]`, you can interpolate the Array by following it with a method call with parentheses after the method name. Thus the following code will work:

```raku
say "@neighbors.join(', ') and I try our best to coexist peacefully."
# OUTPUT: «Felix, Danielle, Lucinda and I try our best to coexist peacefully.␤»

```

However, `"@example.com"` produces `@example.com`.

To call a subroutine, use the `&`-sigil and follow the subroutine name with parentheses.

```raku
say "uc  'word'";  # OUTPUT: «uc  'word'»␤
say "&uc 'word'";  # OUTPUT: «&uc 'word'»␤
say "&uc('word')"; # OUTPUT: «WORD»␤
# OUTPUT: «abcDEFghi␤»
```

To interpolate a Hash (or other [`Associative`](/type/Associative) variable), use the `<>` postcircumfix operator.

```raku
my %h = :1st; say "abc%h<st>ghi";
# OUTPUT: «abc1ghi␤»
```

The way `qq` interpolates variables is the same as `q:scalar:array:hash:function`. You can use these adverbs (or their short forms, `q:s:a:h:f`) to interpolate variables without enabling other `qq` interpolations.

### [Interpolating closures](#Quoting_constructs "go to top of document")[§](#Interpolating_closures "direct link")

Another feature of `qq` is the ability to interpolate Raku code from within the string, using curly braces:

```raku
my ($x, $y, $z) = 4, 3.5, 3;
say "This room is {$x}m by {$y}m by {$z}m.";               # OUTPUT: «This room is 4m by 3.5m by 3m.␤»
say "Therefore its volume should be { $x * $y * $z }m³!";  # OUTPUT: «Therefore its volume should be 42m³!␤»

```

This provides the same functionality as the `q:closure`/`q:c` quoting form.

### [Interpolating escape codes](#Quoting_constructs "go to top of document")[§](#Interpolating_escape_codes "direct link")

The `qq` quoting form also interpolates backslash escape sequences. Several of these print invisible/whitespace ASCII control codes or whitespace characters:

|  |  |  |  |
| --- | --- | --- | --- |
| Sequence | Hex Value | Character | Reference URL |
| \0 | \x0000 | Nul | https://util.unicode.org/UnicodeJsps/character.jsp?a=0000 |
| \a | \x0007 | Bel | https://util.unicode.org/UnicodeJsps/character.jsp?a=0007 |
| \b | \x0008 | Backspace | https://util.unicode.org/UnicodeJsps/character.jsp?a=0008 |
| \e | \x001B | Esc | https://util.unicode.org/UnicodeJsps/character.jsp?a=001B |
| \f | \x000C | Form Feed | https://util.unicode.org/UnicodeJsps/character.jsp?a=000C |
| \n | \x000A | Newline | https://util.unicode.org/UnicodeJsps/character.jsp?a=000A |
| \r | \x000D | Carriage Return | https://util.unicode.org/UnicodeJsps/character.jsp?a=000D |
| \t | \x0009 | Tab | https://util.unicode.org/UnicodeJsps/character.jsp?a=0009 |

`qq` also supports two multi-character escape sequences: `\x` and `\c`. You can use `\x` or `\x[]` with the hex-code of a Unicode character or a list of characters:

```raku
my $s = "I \x2665 Raku!";
say $s;
# OUTPUT: «I ♥ Raku!␤»

$s = "I really \x[2661,2665,2764,1f495] Raku!";
say $s;
# OUTPUT: «I really ♡♥❤💕 Raku!␤»
```

You can also create a Unicode character with `\c` and that character's [unicode name](/language/unicode#Entering_unicode_codepoints_and_codepoint_sequences) , [named sequences](/language/unicode#Named_sequences) or [name alias](/language/unicode#Name_aliases):

```raku
my $s = "Camelia \c[BROKEN HEART] my \c[HEAVY BLACK HEART]!";
say $s;
# OUTPUT: «Camelia 💔 my ❤!␤»
```

See the description of [\c[]](/language/unicode#Entering_unicode_codepoints_and_codepoint_sequences) on the [Unicode](/language/unicode) documentation page for more details.

`qq` provides the same interpolation of escape sequences as that provided by `q:backslash`/`q:b`.

### [preventing interpolation and handling missing values](#Quoting_constructs "go to top of document")[§](#preventing_interpolation_and_handling_missing_values "direct link")

You can prevent any undesired interpolation in a `qq`-quoted string by escaping the sigil or other initial character:

```raku
say "The \$color variable contains the value '$color'"; # OUTPUT: «The $color variable contains the value 'blue'␤»

```

Interpolation of undefined values will raise a control exception that can be caught in the current block with [CONTROL](/language/phasers#CONTROL).

```raku
sub niler {Nil};
my Str $a = niler;
say("$a.html", "sometext");
say "alive"; # this line is dead code
CONTROL { .die };

```

## [Word quoting: qw](#Quoting_constructs "go to top of document")[§](#Word_quoting:_qw "direct link")

```raku
qw|! @ # $ % ^ & * \| < > | eqv '! @ # $ % ^ & * | < >'.words.list;
q:w { [ ] \{ \} }           eqv ('[', ']', '{', '}');
Q:w | [ ] { } |             eqv ('[', ']', '{', '}');

```

The `:w` form, usually written as `qw`, splits the string into "words". In this context, words are defined as sequences of non-whitespace characters separated by whitespace. The `q:w` and `qw` forms inherit the interpolation and escape semantics of the `q` and single quote string delimiters, whereas `Qw` and `Q:w` inherit the non-escaping semantics of the `Q` quoter.

This form is used in preference to using many quotation marks and commas for lists of strings. For example, where you could write:

```raku
my @directions = 'left', 'right,', 'up', 'down';
```

It's easier to write and to read this:

```raku
my @directions = qw|left right up down|;
```

## [Word quoting: `< >`](#Quoting_constructs "go to top of document") [§](#Word_quoting:_<_> "direct link")

```raku
say <a b c> eqv ('a', 'b', 'c');   # OUTPUT: «True␤»
say <a b 42> eqv ('a', 'b', '42'); # OUTPUT: «False␤», the 42 became an IntStr allomorph
say < 42 > ~~ Int; # OUTPUT: «True␤»
say < 42 > ~~ Str; # OUTPUT: «True␤»

```

The angle brackets quoting is like `qw`, but with extra feature that lets you construct [allomorphs](/language/glossary#Allomorph) or literals of certain numbers:

```raku
say <42 4/2 1e6 1+1i abc>.raku;
# OUTPUT: «(IntStr.new(42, "42"), RatStr.new(2.0, "4/2"), NumStr.new(1000000e0, "1e6"), ComplexStr.new(<1+1i>, "1+1i"), "abc")␤»
```

To construct a [`Rat`](/type/Rat) or [`Complex`](/type/Complex) literal, use angle brackets around the number, without any extra spaces:

```raku
say <42/10>.^name;   # OUTPUT: «Rat␤»
say <1+42i>.^name;   # OUTPUT: «Complex␤»
say < 42/10 >.^name; # OUTPUT: «RatStr␤»
say < 1+42i >.^name; # OUTPUT: «ComplexStr␤»
```

Compared to `42/10` and `1+42i`, there's no division (or addition) operation involved. This is useful for literals in routine signatures, for example:

```raku
sub close-enough-π (<355/113>) {
    say "Your π is close enough!"
}
close-enough-π 710/226; # OUTPUT: «Your π is close enough!␤»

```

```raku
# WRONG: can't do this, since it's a division operation
sub compilation-failure (355/113) {}

```

## [Word quoting with quote protection: qww](#Quoting_constructs "go to top of document")[§](#Word_quoting_with_quote_protection:_qww "direct link")

The `qw` form of word quoting will treat quote characters literally, leaving them in the resulting words:

```raku
say qw{"a b" c}.raku; # OUTPUT: «("\"a", "b\"", "c")␤»
```

Using the `qww` variant allows you to use quote characters for embedding strings in the word quoting structure:

```raku
say qww{"a b" c}.raku; # OUTPUT: «("a b", "c")␤»
```

Other kinds of quotes are also supported with their usual semantics:

```raku
my $one = 'here';
my $other = 'there';
say qww{ ’this and that’ “$one or $other” ｢infinity and beyond｣ }.raku;
# OUTPUT: «("this and that", "here or there", "infinity and beyond")␤»
```

The delimiters of embedded strings are always considered word splitters:

```raku
say qww{'alpha'beta'gamma' 'delta'"epsilon"}.raku; # OUTPUT: «("alpha", "beta", "gamma", "delta", "epsilon")␤»
```

## [Word quoting with interpolation: qqw](#Quoting_constructs "go to top of document")[§](#Word_quoting_with_interpolation:_qqw "direct link")

The `qw` form of word quoting doesn't interpolate variables:

```raku
my $a = 42; say qw{$a b c};  # OUTPUT: «$a b c␤»
```

Thus, if you wish for variables to be interpolated within the quoted string, you need to use the `qqw` variant:

```raku
my $a = 42;
my @list = qqw{$a b c};
say @list;                # OUTPUT: «[42 b c]␤»
```

Note that variable interpolation happens before word splitting:

```raku
my $a = "a b";
my @list = qqw{$a c};
.say for @list; # OUTPUT: «a␤b␤c␤»
```

## [Word quoting with interpolation and quote protection: qqww](#Quoting_constructs "go to top of document")[§](#Word_quoting_with_interpolation_and_quote_protection:_qqww "direct link")

The `qqw` form of word quoting will treat quote characters literally, leaving them in the resulting words:

```raku
my $a = 42; say qqw{"$a b" c}.raku;  # OUTPUT: «("\"42", "b\"", "c")␤»
```

Using the `qqww` variant allows you to use quote characters for embedding strings in the word quoting structure:

```raku
my $a = 42; say qqww{"$a b" c}.raku; # OUTPUT: «("42 b", "c")␤»
```

The delimiters of embedded strings are always considered word splitters:

```raku
say qqww{'alpha'beta'gamma' 'delta'"epsilon"}.raku; # OUTPUT: «("alpha", "beta", "gamma", "delta", "epsilon")␤»
```

Unlike the `qqw` form, interpolation also always splits (except for interpolation that takes place in an embedded string):

```raku
my $time = "now";
$_ = 'ni';
my @list = qqww<$time$time {6*7}{7*6} "$_$_">;
.say for @list; # OUTPUT: «now␤now␤42␤42␤nini␤»
```

Quote protection happens before interpolation, and interpolation happens before word splitting, so quotes coming from inside interpolated variables are just literal quote characters:

```raku
my $a = "1 2";
say qqww{"$a" $a}.raku; # OUTPUT: «("1 2", "1", "2")␤»
my $b = "1 \"2 3\"";
say qqww{"$b" $b}.raku; # OUTPUT: «("1 \"2 3\"", "1", "\"2", "3\"")␤»
```

## [Word quoting with interpolation and quote protection: « »](#Quoting_constructs "go to top of document")[§](#Word_quoting_with_interpolation_and_quote_protection:_«_» "direct link")

This style of quoting is like `qqww`, but with the added benefit of constructing [allomorphs](/language/glossary#Allomorph) (making it functionally equivalent to [qq:ww:v](#index-entry-:val_(quoting_adverb))). The ASCII equivalent to `« »` are double angle brackets `<< >>`.

```raku
# Allomorph Construction
my $a = 42; say «  $a b c    ».raku;  # OUTPUT: «(IntStr.new(42, "42"), "b", "c")␤»
my $a = 42; say << $a b c   >>.raku;  # OUTPUT: «(IntStr.new(42, "42"), "b", "c")␤»

# Quote Protection
my $a = 42; say «  "$a b" c  ».raku;  # OUTPUT: «("42 b", "c")␤»
my $a = 42; say << "$a b" c >>.raku;  # OUTPUT: «("42 b", "c")␤»
```

## [Shell quoting: qx](#Quoting_constructs "go to top of document")[§](#Shell_quoting:_qx "direct link")

To run a string as an external program, not only is it possible to pass the string to the `shell` or `run` functions but one can also perform shell quoting. There are some subtleties to consider, however. `qx` quotes *don't* interpolate variables. Thus

```raku
my $world = "there";
say qx{echo "hello $world"}
```

prints simply `hello`. Nevertheless, if you have declared an environment variable before calling `raku`, this will be available within `qx`, for instance

```raku
WORLD="there" raku
> say qx{echo "hello $WORLD"}

```

will now print `hello there`.

The result of calling `qx` is returned, so this information can be assigned to a variable for later use:

```raku
my $output = qx{echo "hello!"};
say $output;    # OUTPUT: «hello!␤»
```

See also [shell](/routine/shell), [run](/routine/run) and [`Proc::Async`](/type/Proc/Async) for other ways to execute external commands.

## [Shell quoting with interpolation: qqx](#Quoting_constructs "go to top of document")[§](#Shell_quoting_with_interpolation:_qqx "direct link")

If one wishes to use the content of a Raku variable within an external command, then the `qqx` shell quoting construct should be used:

```raku
my $world = "there";
say qqx{echo "hello $world"};  # OUTPUT: «hello there␤»
```

Again, the output of the external command can be kept in a variable:

```raku
my $word = "cool";
my $option = "-i";
my $file = "/usr/share/dict/words";
my $output = qqx{grep $option $word $file};
# runs the command: grep -i cool /usr/share/dict/words
say $output;      # OUTPUT: «Cooley␤Cooley's␤Coolidge␤Coolidge's␤cool␤...»
```

Be aware of the content of the Raku variable used within an external command; malicious content can be used to execute arbitrary code. See [`qqx` traps](/language/traps#Beware_of_variables_used_within_qqx)

See also [run](/routine/run) and [`Proc::Async`](/type/Proc/Async) for better ways to execute external commands.

## [Heredocs: :to](#Quoting_constructs "go to top of document")[§](#Heredocs:_:to "direct link")

A convenient way to write a multi-line string literal is by using a *heredoc*, which lets you choose the delimiter yourself:

```raku
say q:to/END/;
Here is
some multi-line
string
END

```

The contents of the *heredoc* always begin on the next line, so you can (and should) finish the line.

```raku
my $escaped = my-escaping-function(q:to/TERMINATOR/, language => 'html');
Here are the contents of the heredoc.
Potentially multiple lines.
TERMINATOR

```

If the terminator is indented, that amount of indention is removed from the string literals. Therefore this *heredoc*

```raku
say q:to/END/;
    Here is
    some multi line
        string
    END

```

produces this output:

｢text｣ without highlighting

```

```

Here is
some multi line
    string

```

```

*Heredocs* include the newline from before the terminator.

To allow interpolation of variables use the `qq` form, but you will then have to escape metacharacters `\{` as well as `$` if it is not the sigil for a defined variable. For example:

```raku
my $f = 'db.7.3.8';
my $s = qq:to/END/;
option \{
    file "$f";
};
END
say $s;
```

would produce:

｢text｣ without highlighting

```

```

option {
    file "db.7.3.8";
};

```

```

Some other situations to pay attention to are innocent-looking ones where the text looks like a Raku expression. For example, the following generates an error:

｢text｣ without highlighting

```

```

my $title = 'USAFA Class of 1965';
say qq:to/HERE/;
<a href='https://usafa-1965.org'>$title</a>
HERE
# Output:
Type Str does not support associative indexing.
  in block <unit> at here.raku line 2

```

```

The angle bracket to the right of '$title' makes it look like a hash index to Raku when it is actually a [`Str`](/type/Str) variable, hence the error message. One solution is to enclose the scalar with curly braces which is one way to enter an expression in any interpolating quoting construct:

｢text｣ without highlighting

```

```

say qq:to/HERE/;
<a href='https://usafa-1965.org'>{$title}</a>
HERE

```

```

Another option is to escape the `<` character to avoid it being parsed as the beginning of an indexing operator:

｢text｣ without highlighting

```

```

say qq:to/HERE/;
<a href='https://usafa-1965.org'>$title\</a>
HERE

```

```

Because a *heredoc* can be very long but is still interpreted by Raku as a single line, finding the source of an error can sometimes be difficult. One crude way to debug the error is by starting with the first visible line in the code and treating is as a *heredoc* with that line only. Then, until you get an error, add each line in turn. (Creating a Raku program to do that is left as an exercise for the reader.)

You can begin multiple Heredocs in the same line. If you do so, the second heredoc will not start until after the first heredoc has ended.

```raku
my ($first, $second) = qq:to/END1/, qq:to/END2/;
  FIRST
  MULTILINE
  STRING
  END1
   SECOND
   MULTILINE
   STRING
   END2
say $first;  # OUTPUT: «FIRST␤MULTILINE␤STRING␤»
say $second; # OUTPUT: «SECOND␤MULTILINE␤STRING␤»

```

## [Unquoting](#Quoting_constructs "go to top of document")[§](#Unquoting "direct link")

Literal strings permit interpolation of embedded quoting constructs by using the escape sequences such as these:

```raku
my $animal="quaggas";
say 'These animals look like \qq[$animal]'; # OUTPUT: «These animals look like quaggas␤»
say 'These animals are \qqw[$animal or zebras]'; # OUTPUT: «These animals are quaggas or zebras␤»
```

In this example, `\qq` will do double-quoting interpolation, and `\qqw` word quoting with interpolation. Escaping any other quoting construct as above will act in the same way, allowing interpolation in literal strings.


## whatever.md
class Whatever

Placeholder for the value of an unspecified argument

```raku
class Whatever { }
```

`Whatever` is a class whose objects don't have any explicit meaning; it gets its semantics from other routines that accept `Whatever`-objects as markers to do something special. Using the `*` literal as an operand creates a `Whatever` object.

Much of `*`'s charm comes from *Whatever-priming*. When `*` is used in term position, that is, as an operand, in combination with most operators, the compiler will transform the expression into a closure of type [`WhateverCode`](/type/WhateverCode), which is actually a [`Block`](/type/Block) that can be used wherever [`Callable`](/type/Callable)s are accepted.

```raku
my $c = * + 2;          # same as   -> $x { $x + 2 };
say $c(4);              # OUTPUT: «6␤»
```

Multiple `*` in one expression generate closures with as many arguments:

```raku
my $c = * + *;          # same as   -> $x, $y { $x + $y }
```

Using `*` in complex expressions will also generate closures:

```raku
my $c = 4 * * + 5;      # same as   -> $x { 4 * $x + 5 }
```

Calling a method on `*` also creates a closure:

```raku
<a b c>.map: *.uc;      # same as    <a b c>.map: -> $char { $char.uc }

```

As mentioned before, not all operators and syntactic constructs prime `*` (or `Whatever`-stars) to [`WhateverCode`](/type/WhateverCode). In the following cases, `*` will remain a `Whatever` object.

| Exception | Example | What it does |
| --- | --- | --- |
| comma | 1, \*, 2 | generates a List with a \* element |
| range operators | 1 .. \* | Range from 1 to Inf |
| series operator | 1 ... \* | infinite lazy Seq |
| assignment | $x = \* | assign \* to $x |
| binding | $x := \* | bind \* to $x |
| list repetition | 1 xx \* | generates an infinite list |

The range operators are handled specially. They do not prime with `Whatever`-stars, but they do prime with [`WhateverCode`](/type/WhateverCode)

```raku
say (1..*).^name;       # OUTPUT: «Range␤»
say ((1..*-1)).^name;   # OUTPUT: «WhateverCode␤»
```

This allows all these constructs to work:

```raku
.say for 1..*;          # infinite loop

```

and

```raku
my @a = 1..4;
say @a[0..*];           # OUTPUT: «(1 2 3 4)␤»
say @a[0..*-2];         # OUTPUT: «(1 2 3)␤»
```

Because *Whatever-priming* is a purely syntactic compiler transform, you will get no runtime priming of stored `Whatever`-stars into [`WhateverCode`](/type/WhateverCode)s.

```raku
my $x = *;
$x + 2;   # Not a closure, dies because it can't coerce $x to Numeric
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Multi::NoMatch: Cannot resolve caller Numeric(Whatever: );
# none of these signatures match:␤
# (Mu:U \v: *%_)»

```

The use cases for stored `Whatever`-stars involve those prime-exception cases mentioned above. For example, if you want an infinite series by default.

```raku
my $max    = potential-upper-limit() // *;
my $series = known-lower-limit() ... $max;

```

A stored `*` will also result in the generation of a [`WhateverCode`](/type/WhateverCode) in the specific case of smartmatch. Note that this is not actually the stored `*` which is being primed, but rather the `*` on the left-hand side.

```raku
my $constraint           = find-constraint() // *;
my $maybe-always-matcher = * ~~ $constraint;

```

If this hypothetical `find-constraint` were to have found no constraint, `$maybe-always-matcher` would evaluate to `True` for anything.

```raku
$maybe-always-matcher(555);      # True
$maybe-always-matcher(Any);      # True

```

[`HyperWhatever`](/type/HyperWhatever)'s functionality is similar to `Whatever`, except it refers to multiple values, instead of a single one.

# [Methods](#class_Whatever "go to top of document")[§](#Methods "direct link")

## [method ACCEPTS](#class_Whatever "go to top of document")[§](#method_ACCEPTS "direct link")

```raku
multi method ACCEPTS(Whatever:D: Mu $other)
multi method ACCEPTS(Whatever:U: Mu $other)
```

If the invocant is [an instance](/language/classtut#A_word_on_types), always returns `True`. If the invocant is a type object, performs a typecheck.

```raku
say 42 ~~ (*);       # OUTPUT: «True␤»
say 42 ~~ Whatever;  # OUTPUT: «False␤»
```

## [method Capture](#class_Whatever "go to top of document")[§](#method_Capture "direct link")

```raku
method Capture()
```

Throws `X::Cannot::Capture`.

# [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")

Type relations for `Whatever`

raku-type-graph

Whatever
Whatever

Any
Any

Whatever->Any

Mu
Mu

Any->Mu

[Expand chart above](/assets/typegraphs/Whatever.svg)


## round.md
round

Combined from primary sources listed below.

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

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

```raku
multi method round(Complex:D: --> Complex:D)
multi method round(Complex:D: Real() $scale --> Complex:D)
```

With no arguments, rounds both the real and imaginary parts to the nearest integer and returns a new `Complex` number. If `$scale` is given, rounds both parts of the invocant to the nearest multiple of `$scale`. Uses the same algorithm as [Real.round](/type/Real#method_round) on each part of the number.

```raku
say (1.2-3.8i).round;           # OUTPUT: «1-4i␤»
say (1.256-3.875i).round(0.1);  # OUTPUT: «1.3-3.9i␤»
```

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

See primary documentation
[in context](/type/Cool#routine_round)
for **routine round**.

```raku
multi        round(Numeric(Cool), $scale = 1)
multi method round(Cool:D: $scale = 1)
```

Coerces the invocant (or in sub form, its argument) to [`Numeric`](/type/Numeric), and rounds it to the unit of `$scale`. If `$scale` is 1, rounds to the nearest integer; an arbitrary scale will result in the closest multiple of that number.

```raku
say 1.7.round;          # OUTPUT: «2␤»
say 1.07.round(0.1);    # OUTPUT: «1.1␤»
say 21.round(10);       # OUTPUT: «20␤»
say round(1000, 23.01)  # OUTPUT: «989.43␤»
```

Always rounds **up** if the number is at mid-point:

```raku
say (−.5 ).round;       # OUTPUT: «0␤»
say ( .5 ).round;       # OUTPUT: «1␤»
say (−.55).round(.1);   # OUTPUT: «-0.5␤»
say ( .55).round(.1);   # OUTPUT: «0.6␤»
```

**Pay attention** to types when using this method, as ending up with the wrong type may affect the precision you seek to achieve. For [`Real`](/type/Real) types, the type of the result is the type of the argument ([`Complex`](/type/Complex) argument gets coerced to [`Real`](/type/Real), ending up a [`Num`](/type/Num)). If rounding a [`Complex`](/type/Complex), the result is [`Complex`](/type/Complex) as well, regardless of the type of the argument.

```raku
9930972392403501.round(1)      .raku.say; # OUTPUT: «9930972392403501␤»
9930972392403501.round(1e0)    .raku.say; # OUTPUT: «9.9309723924035e+15␤»
9930972392403501.round(1e0).Int.raku.say; # OUTPUT: «9930972392403500␤»
```

# [In role Real](#___top "go to top of document")[§](#(role_Real)_method_round "direct link")

See primary documentation
[in context](/type/Real#method_round)
for **method round**.

```raku
method round(Real:D: $scale = 1)
```

Rounds the number to scale `$scale`. If `$scale` is 1, rounds to an integer. If scale is `0.1`, rounds to one digit after the radix point (period or comma), etc.


## dist_zef-lizmat-Acme-Cow.md
[![Actions Status](https://github.com/lizmat/Acme-Cow/workflows/test/badge.svg)](https://github.com/lizmat/Acme-Cow/actions)

# NAME

Acme::Cow - Talking barnyard animals (or ASCII art in general)

# SYNOPSIS

```
  use Acme::Cow;

  my Acme::Cow $cow .= new;
  $cow.say("Moo!");
  $cow.print;

  my $sheep = Acme::Cow::Sheep.new;    # Derived from Acme::Cow
  $sheep.wrap(20);
  $sheep.think;
  $sheep.text("Yeah, but you're taking the universe out of context.");
  $sheep.print($*ERR);

  my $duck = Acme::Cow.new(File => "duck.cow");
  $duck.fill(0);
  $duck.say(`figlet quack`);
  $duck.print($socket);

```

# DESCRIPTION

Acme::Cow is the logical evolution of the old cowsay program. Cows are derived from a base class (Acme::Cow) or from external files.

Cows can be made to say or think many things, optionally filling and justifying their text out to a given margin.

Cows are nothing without the ability to print them, or sling them as strings, or what not.

# METHODS

## new

```
my $cow = Acme::Cow.new(
  over => 0,    # optional
  wrap => 40,   # optional
  fill => True, # optional

  text => "hello world",  # specify the text of the cow
  File => "/foo/bar",     # specify when loading cow from a file
);

```

Create a new `Acme::Cow` object. Optionally takes the following named parameters:

has Str $.el is rw = 'o'; has Str $.er is rw = 'o'; has Str $.U is rw = ' ';

## over

Specify (or retrieve) how far to the right (in spaces) the text balloon should be shoved.

## wrap

Specify (or retrieve) the column at which text inside the balloon should be wrapped. This number is relative to the balloon, not absolute screen position.

The number set here has no effect if you decline filling/adjusting of the balloon text.

## think

Tell the cow to think its text instead of saying it. Optionally takes the text to be thought.

## say

Tell the cow to say its text instead of thinking it. Optionally takes the text to the said.

## text

Set (or retrieve) the text that the cow will say or think.

Expects a list of lines of text (optionally terminated with newlines) to be displayed inside the balloon.

## print

Print a representation of the cow to the specified filehandle ($\*OUT by default).

## fill

Inform the cow to fill and adjust (or not) the text inside its balloon. By default, text inside the balloon is filled and adjusted.

## as\_string

Render the cow as a string.

# WRITING YOUR OWN COW FILES

{$balloon} is the text balloon; it should be on a line by itself, flush-left. {$tl} and {$tr} are what goes to the text balloon from the thinking/speaking part of the picture; {$tl} is a backslash ("") for speech, while {$tr} is a slash ("/"); both are a lowercase letter O ("o") for thought. {$el} is a left eye, and {$er} is a right eye; both are "o" by default. Finally {$U} is a tongue, because a capital U looks like a tongue. (Its default value is "U ".)

There are two methods to make your own cow file: the standalone file and the Perl module.

For the standalone file, take your piece of ASCII art and modify it according to the rules above. Note that the balloon must be flush-left in the template if you choose this method. If the balloon isn't meant to be flush-left in the final output, use its `over()` method.

For a Perl module, declare that your module is a subclass of `Acme::Cow`. You may do other modifications to the variables in the template, if you wish: many examples are provided with the `Acme::Cow` distribution.

# HISTORY

They're called "cows" because the original piece of ASCII art was a cow. Since then, many have been contributed (i.e. the author has stolen some) but they're still all cows.

# SEE ALSO

<perl>, <cowsay>, <figlet>, <fortune>, <cowpm>

# AUTHOR

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

# COPYRIGHT AND LICENSE

Original Perl version: Copyright 2002 Tony McEnroe, Raku adaptation: Copyright 2019, 2021 Elizabeth Mattijsen

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


## dist_github-tokuhirom-HTTP-Server-Tiny.md
[![Build Status](https://travis-ci.org/tokuhirom/p6-HTTP-Server-Tiny.svg?branch=master)](https://travis-ci.org/tokuhirom/p6-HTTP-Server-Tiny)

# NAME

HTTP::Server::Tiny - a simple HTTP server for Perl6

# SYNOPSIS

```
use HTTP::Server::Tiny;

my $port = 8080;

# Only listen for connections from the local host
# if you want this to be accessible from another
# host then change this to '0.0.0.0'
my $host = '127.0.0.1';

HTTP::Server::Tiny.new(:$host , :$port).run(sub ($env) {
    my $channel = Channel.new;
    start {
        for 1..100 {
            $channel.send(($_ ~ "\n").Str.encode('utf-8'));
        }
        $channel.close;
    };
    return 200, ['Content-Type' => 'text/plain'], $channel
});

```

# DESCRIPTION

HTTP::Server::Tiny is a standalone HTTP/1.1 web server for perl6.

# METHODS

* `HTTP::Server::Tiny.new($host, $port)`

Create new instance.

* `$server.run(Callable $app, Promise :$control-promise)`

Run http server with P6W app. The named parameter `control-promise` if provided, can be *kept* to quit the server loop, which may be useful if the server is run asynchronously to the main thread of execution in an application.

If the optional named parameter `control-promise` is provided with a `Promise` then the server loop will be quit when the promise is kept.

# VERSIONING RULE

This module respects [Semantic versioning](http://semver.org/)

# TODO

* Support timeout

# COPYRIGHT AND LICENSE

Copyright 2015, 2016 Tokuhiro Matsuno [tokuhirom@gmail.com](mailto:tokuhirom@gmail.com)

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


## dist_github-azawawi-Terminal-Caca.md
# Terminal::Caca

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

Terminal::Caca - Use libcaca (Colour AsCii Art library) API in Raku

**NOTE:** The library is currently **experimental**. You have been warned :)

Normally you would use the safer object-oriented API via `Terminal::Caca`. If
you need to access raw API for any reason, please use `Terminal::Caca::Raw`.

## Example

```
use v6;
use Terminal::Caca;

# Initialize library
given my $o = Terminal::Caca.new {
    # Set window title
    .title("Raku rocks");

    # Say hello world
    my $text = ' Hello world, from Raku! ';
    .color(white, blue);
    .text(10, 10, $text);

    # Draw an ASCII-art box around it
    .thin-box(9, 9, $text.chars + 2, 3);

    # Refresh display
    .refresh;

    # Wait for a key press event
    .wait-for-keypress;

    # Cleanup on scope exit
    LEAVE {
        .cleanup;
    }
}

```

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

## Installation

* On Debian-based linux distributions, please use the following command:

```
$ sudo apt-get install libcaca-dev

```

* On Mac OS X, please use the following command:

```
$ brew update
$ brew install libcaca

```

* Using zef (a module management tool bundled with Rakudo Star):

```
$ zef install Terminal::Caca

```

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

```

## Author

Ahmad M. Zawawi, azawawi on #raku, <https://github.com/azawawi/>

## License

MIT


## dist_cpan-SACOMO-Magento.md
# Magento [build status](https://travis-ci.org/scmorrison/perl6-Magento)

Perl 6 Magento 2 API client module.

* [Features](#features)
* [Getting started](#getting-started)
* [Module usage](#module-usage)
  * [Response format](#response-format)
  * [Error messages](#error-messages)
  * [Search critera](#search-criteria)
  * [Custom API endpoints](#custom-api-endpoints)
  * [Custom API endpoints](#custom-api-endpoints)
* [CLI usage](#cli-usage)
* [Config](#config)
  * [Config variables](#config-variables)
* [Installation](#installation)
* [Todo](#todo)
* [Requirements](#requirements)
* [Troubleshooting](#troubleshooting)
* [Authors](#authors)
* [License](#license)
* [See also](#see-also)

# Features

* **Magento 2 compatable**: Works with the latest Magento 2 API
* **Integration token support**: Can utilize Integration tokens for authentication
* **Admin & Customer token support**: Supports username / password authentication for access token generation
* **Use Perl 6 hash for search critera**: Write complex search criteria queries as Perl 6 Hash

# Getting started

For long-use Integration Access Token usage use the `6mag init` command:

```
6mag init

```

Enter your Magento installation base URL (e.g. <https://my.magento>), store identifier (e.g. default), and Integration Access Token (generated in Magento > System > Integrations).

By default this will generate the file `~/.6mag/config.yml`:

```
---
host: "https://my.magento"
store: default
access_token: ********************************

```

# Module Usage

All subroutines are documented in <docs/Subroutines.md>.

Using long-use Integration Access Token from `~/.6mag/config.yml`:

```
use Magento::Config;
use Magento::Customer;

my %config = Magento::Config::from-file;

#GET    /V1/customers/:customerId
say customers %config, id => 1;

```

Using pre-generated Access Token without `~/.6mag/config.yml`:

```
use Magento::Customer;

my $host   = 'https://my.magento';
my %config = %{
    host         => $host,
    access_token => '********************************',
    store        => 'default'
}

#GET    /V1/customers/:customerId
say customers %config, id => 1;

```

Using password authentication as Admin:

```
use Magento::Auth;
use Magento::Customer;

my $host   = 'https://my.magento';
my %config = %{
    host         => $host,
    access_token => request-access-token(username => 'admin', password => '****', :$host),
    store        => 'default'
}

#GET    /V1/customers/:customerId
say customers %config, id => 1;

```

Using password authentication as Customer:

```
use Magento::Auth;
use Magento::Customer;

my $host         = 'https://my.magento';
my $access_token =
    request-access-token(
        :$host,
        username  => 'customer@emailaddy.magento',
        password  => '****',
        user_type => 'customer');

my %config = %{:$host, :$access_key, store => 'default'};

#GET    /V1/customers/me
say customers-me %config;

```

### Response format

By default, all responses are returned as `Perl 6` variables. To return the raw `json` or `xml` body add the following to your config Hash:

```
my %config = %{
    host         => $host,
    access_token => '********************************',
    store        => 'default',
    format       => 'json',
    # or
    format       => 'xml'
}

```

### Error messages

For a successful request only the relevant data will be returned from the server response. For example, only the `cart_id` value will be returned when a new cart is successfully created on the server.

When an error occurs, the response will return a `Perl 6` Hash with a `message` and `status` pair, like this:

```
%{
    message => 'Cannot assign customer to the given cart. Customer already has active cart.',
    status  => 400
}

```

### Search criteria

Use a `Perl 6` Hash to define search criteria:

```
use Magento::Config;
use Magento::Customer;

my %config = Magento::Config::from-file;

my %customer_search_criteria = %{
    searchCriteria => %{
        filterGroups => [
            {
                filters => [
                    {
                        field => 'email',
                        value => 'customer@myemail.somewhere',
                        condition_type => 'eq'
                    },
                ]
            },
        ],
        current_page => 1,
        page_size    => 10
    }
}

# Do a customer search using the search criteria hash
say customers-search %config, search_criteria => %customer_search_criteria;

```

#### search-criteria Helper routine

In addition to the `Hash` approach above, you can also use the `search-critera` helper routine from `Magento::Utils`. This creates a search criteria `Hash` using more condensed notation.

Only the initial `Array` is required. The `conditions` named argument is optional.

```
use Magento::Utils;

# Single filter
my %critera = search-critera
    # field   value                      condition_type
    ['email', 'p6magento@fakeemail.com', 'eq'],
    conditions => %{
        current_page => 1,
        page_size    => 10
    }

# Logical AND filter
my %criteria = search-critera
    [
        ['email', 'p6magento@fakeemail.com', 'eq'],
        ['email', 'p6magento23@fakeemail.com', 'eq'],
    ],
    conditions => %{
        current_page => 1,
        page_size    => 10
    }

# Logical OR
my %criteria = search-critera
    [
        [
            ['email', 'p6magento@fakeemail.com', 'eq'],
            ['email', 'p6magento23@fakeemail.com', 'eq'],
        ],
        [
            ['email', 'fakeuser1@p6magento.com', 'eq'],
            ['email', 'fakeuser2@p6magehto.com', 'eq'],
        ],
    ],
    conditions => %{
        current_page => 1,
        page_size    => 10
    }

```

### Custom API endpoints

You can use the `request` subroutine directly to make requests against custom API endpoints:

```
use Magento::HTTP;
use JSON::Fast;

# GET
Magento::HTTP::request
    method  => 'GET',
    config  => %config,
    uri     => "myCustom/endpoint/123";

# POST/PUT/DELETE
Magento::HTTP::request
    method  => 'POST', # or PUT / DELETE
    config  => %config,
    uri     => "myCustom/endpoint",
    content => to-json %content-hash;

```

# CLI Usage

```
Usage:
  6mag init         - Generate Integration token based config
  6mag print-config - Print Integration token config
  6mag version      - Print 6mag version and exit

Optional arguments:

  --config=         - Specify a custom config file location
                      Default is `~/.6mag/config.yml`

  e.g. 6mag --config=path/to/config.yml init

```

# Config

Each project has its own `config.yml` which uses the following format:

```
---
host: "https://my.magento"
store: default
access_token: ********************************
format: json
version: V1

```

### Config variables

Config variables are defined in `config.yml`:

#### Required

* `host`: Magento base URL
* `access_token`: Magento access token. For long-use configurations, integrations, use an Integration Access Token.

#### Optional

* `format`: By default all results are returned as `Perl 6` variables. You can specify `json` or `xml` with this variable to return the raw response body in either format.
* `store`: Store identifier, defaults to `default`.
* `version`: Magento API version, defaults to `V1`.

# Installation

```
git clone https://github.com/scmorrison/perl6-Magento.git
cd perl6-Magento/
zef install .

```

Installation issue? See [Troubleshooting](#troubleshooting).

# Todo

* More tests
* More API endpoints

# Requirements

* [Perl 6](http://perl6.org/)

# Troubleshooting

* **Errors installing from previous version:**

  Remove the zef tmp / store perl6-Magento.git directories:

  ```
  # Delete these folders from your zef install
  # directory.
  rm -rf ~/.zef/store/perl6-Magento.git ~/.zef/tmp/perl6-Magento.git

  ```

  In some instances it might help to delete your local `~/.perl6/precomp` directory.

# Authors

* [Sam Morrison](@samcns)

# License

This Perl 6 Magento module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. (Note that, unlike the Artistic License 1.0, version 2.0 is GPL compatible by itself, hence there is no benefit to having an Artistic 2.0 / GPL disjunction.) See the file LICENSE for details.

# See also

* [Magento](https://magento.com/)


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

# NAME

Email::Simple - Simple email parsing module

# SYNOPSIS

```
use Email::Simple;

my $eml = Email::Simple.new($raw-mail-text);
say $eml.body;

my $new = Email::Simple.create(
  header => [
    ['To', 'mail@example.com'],
    ['From', 'me@example.com'],
    ['Subject', 'test']
  ],
  body => 'This is a test.',
);
say ~$new;

```

# DESCRIPTION

This is my attempt at porting Email::Simple from Perl to Raku (mostly just because I can)

# METHODS

## new(Str $text, :$header-class = Email::Simple::Header)

## new(Array $header, Str $body, :$header-class = Email::Simple::Header)

Alias of `.create` with positional arguments.

## create(Array :$header, Str :$body, :$header-class = Email::Simple::Header)

## header($name, :$multi)

Returns the email header with the name `$name`. If `:$multi` is not passed, then this will return the first header found. If `:$multi` is set, then this will return a list of all headers with the name `$name` (note the change from v1.0!)

## header-set($name, \*@lines)

Sets the header `$name`. Adds one `$name` header for each additional argument passed.

## header-names

Returns a list of header names in the email.

## headers

Alias of `header-names`

## header-pairs

Returns the full header data for an email.

```
$eml.header-pairs(); # --> [['Subject', 'test'], ['From', 'me@example.com']]

```

## body

Returns the mail body. Note that this module does not try to do any decoding, it just returns the body as-is.

## body-set($text)

Sets the mail body to `$text`. Note that this module does not try to properly encode the body.

## as-string, Str>

Returns the full raw email, suitable for piping into sendmail.

## crlf

## header-obj

## header-obj-set($obj)

# AUTHOR

Andrew Egeler

# COPYRIGHT AND LICENSE

Copyright 2012 - 2018 Andrew Egeler

Copyright 2019 - 2022 Raku Community

All files in this repository are licensed under the terms of Create Commons License; for details please see the LICENSE file


## dist_zef-CIAvash-Curry.md
# NAME

Curry - a [Raku](https://www.raku-lang.ir/en) module for currying functions.

# DESCRIPTION

Curry is a [Raku](https://www.raku-lang.ir/en) module for currying functions plus partially applying them.

# SYNOPSIS

```
use Curry:auth<zef:CIAvash> :all;

# Curried subs
sub f ($a, $b) is curry {
    $a × $b;
}
my &pf = f 2;
say pf 3;
=output 6␤

sub f2 ($a, $b, :$c = 1) is curry {
    [×] $a, $b, $c;
}
my &pf2 = f 2, :c(4);
say pf 3;
=output 24␤

sub f3 (*@a) is curry {
    [×] @a;
}
my &pf3 = f 2, 3;
say pf;
=output 6␤

say pf(4)();
=output 24␤

# Curried method and attribute
my class C {
    has &.f is curry is rw;

    method m (Int $a, Int $b) is curry {
        $a × $b;
    }
}
my C $c .= new;
# Method
say $c.m(2, 3)()
=output 6␤

my &pm = $c.m(2, 3);
say pm;
=output 6␤

say pm(4)();
=output 24␤

# Attribute
$c.f = * + *;
say $c.f.(1, 2);
=output 3␤

my &pa = $c.f.(1);
say pa 2;
=output 3␤

# Making Curry
my &f3 = Curry[* + *];
# Or
my &f4 = make_curry * + *;

my &cgrep = Curry[&grep];
# Or better
my &cgrep2 = new_curry &grep;

# Be careful with this
make_curry &grep;
# Or
make_curryable &grep; # This changes function's signature
# Original function (before being curried)
my &lost_grep = &grep.original_function;

```

# INSTALLATION

You need to have [Raku](https://www.raku-lang.ir/en) and [zef](https://github.com/ugexe/zef), then run:

```
zef install --/test "Curry:auth<zef:CIAvash>"

```

or if you have cloned the repo:

```
zef install .

```

# TESTING

```
prove -ve 'raku -I.' --ext rakutest

```

# ROLES

## role Curry [Code:D $function]

Curry role takes a function as parameter and does the `Callable` role

### method CALL-ME

```
method CALL-ME(
    |c
) returns Mu

```

Calls the function if all parameters are provided or returns a partially applied function

### method curry

```
method curry(
    |c
) returns Curry:D

```

Like `assuming` but returns a Curry. And tries to preserve the parameters of the partial function.

### method original\_function

```
method original_function() returns Code:D

```

Returns the original function, the function that was curried

## role Curry::CaptureAll

A role with a signature that captures all arguments

# SUBS

## multi sub make\_curry

```
multi sub make_curry(
    Code:D $f
) returns Curry:D is export(:all, :subs)

```

Takes a function, gives a cloned version of it to `Curry`, then adds the role to the function

## multi sub make\_curry

```
multi sub make_curry(
    *@f where { ... }
) returns Array[Curry:D] is export(:all, :subs)

```

Takes functions, gives a cloned version of each to `Curry`, then adds the role to each function

## multi sub new\_curry

```
multi sub new_curry(
    Code:D $f
) returns Curry:D is export(:all, :subs)

```

Takes a function, creates a copy of it with role `Curry` mixed in

## multi sub new\_curry

```
multi sub new_curry(
    *@f where { ... }
) returns Array[Curry:D] is export(:all, :subs)

```

Takes functions, creates a copy of each with role `Curry` mixed in

## multi sub make\_curryable

```
multi sub make_curryable(
    Code:D $f
) returns Curry:D is export(:all, :subs)

```

Takes a function and returns a curried function that does `Curry::CaptureAll`

## multi sub make\_curryable

```
multi sub make_curryable(
    *@f where { ... }
) returns Array[Curry:D] is export(:all, :subs)

```

Takes functions and returns an array of curried functions that does `Curry::CaptureAll`

## multi sub trait\_mod:

```
multi sub trait_mod:<is>(
    Sub:D $sub,
    :$curry!
) returns Mu is export(:all, :traits)

```

`is curry` trait for `Sub`; Makes the function a curried function that does `Curry::CaptureAll`

## multi sub trait\_mod:

```
multi sub trait_mod:<is>(
    Method:D $method,
    :$curry!
) returns Mu is export(:all, :traits)

```

`is curry` trait for `Method`; Makes the function a curried function that does `Curry::CaptureAll`

## multi sub trait\_mod:

```
multi sub trait_mod:<is>(
    Attribute:D $attribute,
    :$curry!
) returns Mu is export(:all, :traits)

```

`is curry` trait for `Attribute`; Makes the function a curried function that does `Curry::CaptureAll`.

If you want to be able to set the function from outside of the class, you need to make the attribute writable
with `is rw`. Setting the attribute with `new` doesn't work, only assignment works.

# REPOSITORY

<https://codeberg.org/CIAvash/Curry/>

# BUG

<https://codeberg.org/CIAvash/Curry/issues>

# AUTHOR

Siavash Askari Nasr - <https://siavash.askari-nasr.com>

# COPYRIGHT

Copyright © 2021 Siavash Askari Nasr

# LICENSE

Curry is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Curry is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with Curry. If not, see <http://www.gnu.org/licenses/>.


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

# NAME

YAMLish - a YAML parser/emitter written in pure raku

# DESCRIPTION

This is a YAML parser written in pure-raku. It aims at being feature complete (though there still a few features left to implement). Patches are welcome.

# INSTALLATION

```
$ zef install YAMLish

```

# EXPORTED SUBS

* `load-yaml(Str $input, ::Grammar:U :$schema = ::Schema::Core, :%tags)`
* `load-yamls(Str $input, ::Grammar:U :$schema = ::Schema::Core, :%tags)`
* `save-yaml($document, :$sorted = True)`
* `save-yamls(**@documents, :$sorted = True)`

# Example use for a configuration file

This configuration file begins with a comment followed by three lines of key/value:

```
# key: value
lang: en
lat: 46.12345
lon: -82.6231

```

Access the file in your code like this:

```
use YAMLish;
my $str = "config.yml".IO.slurp:
my %conf = load-yaml $str;
say %conf<lang>; # OUTPUT: «en␤»
say %conf<lat>;  # OUTPUT: «46.12345␤»
say %conf<lon>;  # OUTPUT: «-82.6231␤»

```

# TODO

Please have a look at <./TODO.md>

# AUTHOR

Leon Timmermans

# LICENSE

Artistic License 2.0


## dist_zef-jonathanstowe-Linux-Cpuinfo.md
# Linux::Cpuinfo

Obtain Linux CPU information.

![Build Status](https://github.com/jonathanstowe/Raku-Linux-Cpuinfo/workflows/CI/badge.svg)

## Synopsis

```
  use Linux::Cpuinfo;

  my $cpuinfo = Linux::Cpuinfo.new();

  my $cnt  = $cpuinfo.num-cpus();   # > 1 for an SMP system

  for $cpuinfo.cpus -> $cpu {
     say $cpu.bogomips;
  }

```

## Description

On Linux systems various information about the CPU ( or CPUs ) in the
computer can be gleaned from `/proc/cpuinfo`. This module provides an
object oriented interface to that information for relatively simple use
in Raku programs.

## Installation

Assuming you have a working Rakudo installation you should be able to
install this with *zef* :

```
# From the source directory

zef install .

# Remote installation

zef install Linux::Cpuinfo

```

## Support

Suggestions/patches are welcomed via github at <https://github.com/jonathanstowe/Raku-Linux-Cpuinfo/issues>

I'd be particularly interested in the /proc/cpuinfo from a variety of
architectures to test against, the ones that I already have can be seen
in t/proc

I'm not able to test on a wide variety of platforms so any help there
would be appreciated.

## Licence

Please see the <LICENCE> file in the distribution.

© Jonathan Stowe 2015, 2016, 2017, 2019


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

# NAME

Math::Libgsl::Random - An interface to libgsl, the Gnu Scientific Library - Random Number Generation.

# SYNOPSIS

```
use Math::Libgsl::Random;

my Math::Libgsl::Random $r .= new;
$r.get-uniform.say for ^10;

```

# DESCRIPTION

Math::Libgsl::Random is an interface to the Random Number Generation routines of libgsl, the Gnu Scientific Library.

### new(Int :$type?)

The constructor allows one optional parameter, the random number generator type. One can find an enum listing all the generator types in the Math::Libgsl::Constants module.

All the following methods *throw* on error if they return **self**, otherwise they *fail* on error.

### get(--> Int)

Returns the next random number as an Int.

### get-uniform(--> Num)

Returns the next random number as a Num in the interval [0, 1).

### get-uniform-pos(--> Num)

Returns the next random number as a Num in the interval (0, 1).

### get-uniform-int(Int $n --> Int)

This method returns an Int in the range [0, n - 1].

### seed(Int $seed)

This method initializes the random number generator. This method returns **self**, so it can be concatenated to the **.new()** method:

```
my $r = Math::Libgsl::Random.new.seed(42);
$r.get.say;

# or even

Math::Libgsl::Random.new.seed(42).get.say;

```

### name(--> Str)

This method returns the name of the current random number generator.

### min(--> Int)

This method returns the minimum value the current random number generator can generate.

### max(--> Int)

This method returns the maximum value the current random number generator can generate.

### copy(Math::Libgsl::Random $src)

This method copies the source generator **$src** into the current one and returns the current object, so it can be concatenated. The generator state is also copied, so the source and destination generators deliver the same values.

### clone(--> Math::Libgsl::Random)

This method clones the current object and returns a new object. The generator state is also cloned, so the source and destination generators deliver the same values.

```
my $r = Math::Libgsl::Random.new;
my $clone = $r.clone;

```

### write(Str $filename!)

Writes the generator to a file in binary form. This method can be chained.

### read(Str $filename!)

Reads the generator from a file in binary form. This method can be chained.

# 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::Random

```

# AUTHOR

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

# COPYRIGHT AND LICENSE

Copyright 2020 Fernando Santagata

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


## minpairs.md
minpairs

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Any#method_minpairs)
for **method minpairs**.

```raku
multi method minpairs(Any:D:)
```

Calls [`.pairs`](/routine/pairs) and returns a [`Seq`](/type/Seq) with all of the Pairs with minimum values, as judged by the [`cmp` operator](/routine/cmp):

```raku
<a b c a b c>.minpairs.raku.put; # OUTPUT: «(0 => "a", 3 => "a").Seq␤»
%(:42a, :75b).minpairs.raku.put; # OUTPUT: «(:a(42),).Seq␤»
```

# [In role Setty](#___top "go to top of document")[§](#(role_Setty)_method_minpairs "direct link")

See primary documentation
[in context](/type/Setty#method_minpairs)
for **method minpairs**.

```raku
multi method minpairs(Setty:D: --> Seq:D)
```

Returns the value of [`self.pairs`](/routine/pairs) (as all Pairs have minimum values). See also [`Any.minpairs`](/routine/minpairs)


## dist_cpan-AZAWAWI-Inline-Go.md
# Inline::Go

[![Build Status](https://travis-ci.org/azawawi/perl6-inline-go.svg?branch=master)](https://travis-ci.org/azawawi/perl6-inline-go) [![Build status](https://ci.appveyor.com/api/projects/status/github/azawawi/perl6-inline-go?svg=true)](https://ci.appveyor.com/project/azawawi/perl6-inline-go/branch/master)

Use inline [Go](https://golang.org/) code within your Perl 6 source code. The
project has the following ambitious goals to achieve:

* Parse Go code using Perl 6 grammars with test suite taking directly from Go
  language specification.
* Transform Go functions and classes to be usable within Perl 6.
* Provide a simple and robust way to take advantage of Go groutines in Perl 6.

**Note:** This currently a totally **experimental** module. Please do not use on
a production system.

The module is currently using simple regular expression to find exported go
functions signatures with a simple Go-to-Perl-6 type mapping. The Perl 6
NativeCall Go function wrapper is added via an evil `EVAL` into the current
object via a role (to support multiple objects).

## Example

```
use v6.c;

my $code = '
package main

import ("C"; "fmt")

//export Add_Int32
func Add_Int32(a int, b int) int { return a + b }

//export Hello
func Hello() { fmt.Println("Hello from Go!") }

func main() { }
';

my $go = Inline::Go.new( :code( $code ) );
$go.import-all;
$go.Hello;
say $go.Add_Int32(1, 2);

```

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

## Installation

* Please install the Go language toolchain from [here](https://golang.org/dl/). You
  need at least Go 1.5 or later.
* **On windows**, you need the gcc toolchain. Luckily you can have that easily
  by installing [Strawberry Perl](http://strawberryperl.com/).
* Install it using zef (a module management tool bundled with Rakudo Star):

```
$ zef install Inline::Go

```

## Testing

* To run tests:

```
$ prove -ve "perl6 -Ilib"

```

* 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 -e "perl6 -Ilib"

```

## See Also

* [Calling Go Functions from Other Languages](https://medium.com/learning-the-go-programming-language/calling-go-functions-from-other-languages-4c7d8bcc69bf).
* [The Go Programming Language Specification](https://golang.org/ref/spec) .
* [cgo Wiki](https://github.com/golang/go/wiki/cgo)

## Author

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

## License

MIT License


## dist_cpan-RBT-Test-Differences.md
# Test::Differences

Test complex data structures and output the differences between them in
diagnostics. This is helpful for spotting minor changes over a large dataset.

## SYNOPSIS

```
   use Test;
   use Test::Differences;

   eq_or_diff $got,  "a\nb\nc\n",   "testing strings";
   eq_or_diff @got, [{foo => <a b c>}, 1, Nil], "testing compex structure";

```

## DESCRIPTION

When the code you're testing returns multiple lines, records or data
structures and they're just plain wrong, an equivalent to the Unix
C utility may be just what's needed. Here's output from an
example test script that checks two text documents and then two
(trivial) data structures:

```
# Failed test 'Differences in text'
# +---+----------------+----------------+
# | Ln|Got             |Expected        |
# +---+----------------+----------------+
# |  0|this is line 1  |this is line 1  |
# *  1|this is line 2  |this is line b  *
# |  2|this is line 3  |this is line 3  |
# +---+----------------+----------------+
not ok 1 - Differences in text
#
# Failed test 'Differences in whitespace'
# +---+--------------+--------------+
# | Ln|Got           |Expected      |
# +---+--------------+--------------+
# |  0|    indented  |    indented  |
# *  1|indented      |indented      *
# |  2|    indented  |    indented  |
# +---+--------------+--------------+
not ok 2 - Differences in whitespace
#
# Failed test 'Differences in structure'
# +---+-----------------------------------+---+---------------------------+
# | Ln|Got                                | Ln|Expected                   |
# +---+-----------------------------------+---+---------------------------+
# *  0|{                                  *  0|[                          *
# *  1|ITEM => "Dry humourless message",  *  1|"ITEM",                    *
# *  2|}                                  *  2|"Dry humourless message",  *
# |   |                                   *  3|]                          *
# +---+-----------------------------------+---+---------------------------+
not ok 3 - Differences in structure
#
# You failed 3 tests of 3

```

eq\_or\_diff() compares two strings or (limited) data structures and
either emits an ok indication or a side-by-side diff. Test::Differences
is designed to be used with Test.

### eq-or-diff

```
eq_or_diff $got, $want, $test-title, OutputStyle :output-style = Table, :context-lines = 5, :dump-overrides => {};

```

* `output-style` may be any OutputStyle supported by [Text::Diff](https://github.com/rbt/raku-Text-Diff).
* `context-lines` is the number of lines above/below within the formatted output around
  the change to present.
* `dump-overrides` is a set of overrides to default [Data::Dump](https://github.com/tony-o/perl6-data-dump)
  styling.

## COPYRIGHT

Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.

Ported, with non-trivial restructuring, to Raku by Rod Taylor.

## LICENSE

You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.


## dist_zef-tbrowder-Modf.md
[![Actions Status](https://github.com/tbrowder/Modf/workflows/test/badge.svg)](https://github.com/tbrowder/Modf/actions)

# Modf

This module Provides a Raku version of routine 'modf' as used in other languages.

Note the `modf` routine is **not** currently available in the Raku core, but there is an open Rakudo Pull Request (#4434) to add it. Thus it is likely to be in the core by the 2021.07 release of Rakudo.

# SYNOPSIS

```
use Modf;
say modf(3.2);            # OUTPUT: «3 0.2␤»
say modf(-3.2);           # OUTPUT: «-3 -0.2␤»

```

# DESCRIPTION

## modf

```
sub modf($x is copy, $places? --> List) is export(:modf) {...}

```

The c routine (currently not available in the *Raku* core) is similar to those in other languages including *C*, *C++*, *Python*, and *Haskell*. It coerces its input into a base 10 number and returns the integral and fractional parts in a list as shown below. (Note the `modf` routine has been submitted as a PR for the Raku core and may be part of the language soon.)

```
say modf(3.24);  # OUTPUT: «3 0.24␤»
say modf(-2.7);  # OUTPUT: «-2 -0.7␤»
say modf(10);    # OUTPUT: «10 0␤»
say modf(0x10);  # OUTPUT: «16 0␤»
say modf(-0o10); # OUTPUT: «-8 0␤»

```

Note the sign of the input value is applied to both parts, unless the part is zero. As expected, the fractional part of an integer will be zero. If desired, the user may use the optional parameter `$places` (a positive integer) to specify the precision to be shown in the fractional part.

```
say modf(1.23456);    # OUTPUT: «1 0.23456␤»
say modf(1.23456, 3); # OUTPUT: «1 0.235␤»

```

# AUTHOR

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

# COPYRIGHT AND LICENSE

© 2021 Tom Browder

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


## prepost.md
class X::Phaser::PrePost

Error due to a false return value of a PRE/POST phaser

```raku
class X::Phaser::PrePost is Exception { }

```

Thrown when the condition inside a `PRE` or `POST` phaser evaluate to a false value.

For example

```raku
sub f($x) { PRE { $x ~~ Int } };
f "foo";
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: X::Phaser::PrePost: Precondition '{ $x ~~ Int }' failed«␤»
```

# [Methods](#class_X::Phaser::PrePost "go to top of document")[§](#Methods "direct link")

## [method phaser](#class_X::Phaser::PrePost "go to top of document")[§](#method_phaser "direct link")

```raku
method phaser(--> Str:D)
```

Returns the name of the failed phaser, `"PRE"` or `"POST"`.

## [method condition](#class_X::Phaser::PrePost "go to top of document")[§](#method_condition "direct link")

```raku
method condition(--> Str:D)
```

Returns the part of the source code that describes the phaser condition.


## binarymode.md
class X::IO::BinaryMode

Error while invoking methods on a handle in binary mode.

```raku
class X::IO::BinaryMode does X::IO is Exception { }

```

Thrown from certain [`IO::Handle`](/type/IO/Handle) methods if the handle is [in binary mode](/type/IO/Handle#method_encoding).

A typical error message is

｢text｣ without highlighting

```

```

Cannot do 'comb' on a handle in binary mode.

```

```

# [Methods](#class_X::IO::BinaryMode "go to top of document")[§](#Methods "direct link")

## [method trying](#class_X::IO::BinaryMode "go to top of document")[§](#method_trying "direct link")

Returns a string describing the failed operation; in this example, `comb`.