## exceptions.md
Exceptions

Using exceptions in Raku

Exceptions in Raku are objects that hold information about errors. An error can be, for example, the unexpected receiving of data or a network connection no longer available, or a missing file. The information that an exception object stores is, for instance, a human-readable message about the error condition, the backtrace of the raising of the error, and so on.

All built-in exceptions inherit from [`Exception`](/type/Exception), which provides some basic behavior, including the storage of a backtrace and an interface for the backtrace printer.

# [*Ad hoc* exceptions](#Exceptions "go to top of document")[§](#Ad_hoc_exceptions "direct link")

Ad hoc exceptions can be used by calling [die](/routine/die) with a description of the error:

```raku
die "oops, something went wrong";
# OUTPUT: «oops, something went wrong in block <unit> at my-script.raku:1␤»
```

It is worth noting that `die` prints the error message to the standard error `$*ERR`.

# [Typed exceptions](#Exceptions "go to top of document")[§](#Typed_exceptions "direct link")

Typed exceptions provide more information about the error stored within an exception object.

For example, if while executing `.frobnicate` on an object, a needed path `foo/bar` becomes unavailable, then an [`X::IO::DoesNotExist`](/type/X/IO/DoesNotExist) exception can be thrown:

```raku
method frobnicate($path) {
    X::IO::DoesNotExist.new(:$path, :trying("frobnicate")).throw
      unless $path.IO.e;
    # do the actual frobnication
}

```

```raku
frobnicate("foo/bar");
# OUTPUT: «Failed to find 'foo/bar' while trying to do '.frobnicate'
#          in block <unit> at my-script.raku:1»

```

Note how the object has provided the backtrace with information about what went wrong. A user of the code can now more easily find and correct the problem.

Instead of calling the `.throw` method on the [`X::IO::DoesNotExist`](/type/X/IO/DoesNotExist) object, one can also use that object as a parameter to `die`:

```raku
die X::IO::DoesNotExist.new(:$path, :trying("frobnicate"));

```

# [Catching exceptions](#Exceptions "go to top of document")[§](#Catching_exceptions "direct link")

It's possible to handle exceptional circumstances by supplying a `CATCH` block:

```raku
CATCH {
    when X::IO { $*ERR.say: "some kind of IO exception was caught!" }
}
X::IO::DoesNotExist.new(:$path, :trying("frobnicate")).throw

# OUTPUT: «some kind of IO exception was caught!»

```

Here, we are saying that if any exception of type [`X::IO`](/type/X/IO) occurs, then the message `some kind of IO exception was caught!` will be sent to *stderr*, which is what `$*ERR.say` does, getting displayed on whatever constitutes the standard error device in that moment, which will probably be the console by default.

A `CATCH` block uses smartmatching similar to how `given/when` smartmatches on options, thus it's possible to catch and handle various categories of exceptions inside a `when` block. And it does so because, within the block, `$_` is set to the exception that has been raised.

To handle all exceptions, use a `default` statement. This example prints out almost the same information as the normal backtrace printer; the *dot* methods apply to `$_`, which holds the [`Exception`](/type/Exception) within the `CATCH` block.

```raku
CATCH {
     default {
         $*ERR.say: .message;
         for .backtrace.reverse {
             next if .file.starts-with('SETTING::');
             next unless .subname;
             $*ERR.say: "  in block {.subname} at {.file} line {.line}";
         }
     }
}
```

Note that the match target is a role. To allow user defined exceptions to match in the same manner, they must implement the given role. Just existing in the same namespace will look alike but won't match in a `CATCH` block.

Note that the `CATCH` block semantics apply to the **entire** lexical scope in which it is defined, **regardless** of where it is defined inside that lexical scope. It is therefore advised to put any `CATCH` block at the start of the lexical scope to which they apply so that the casual reader of the code can immediately see that there is something special going on.

## [Exception handlers and enclosing blocks](#Exceptions "go to top of document")[§](#Exception_handlers_and_enclosing_blocks "direct link")

After a CATCH has handled the exception, the block enclosing the `CATCH` block is exited.

In other words, even when the exception is handled successfully, the *rest of the code* in the enclosing block will never be executed.

```raku
die "something went wrong ...";

CATCH {
    # will definitely catch all the exception
    default { .Str.say; }
}

say "This won't be said.";   # but this line will be never reached since
                             # the enclosing block will be exited immediately
# OUTPUT: «something went wrong ...␤»
```

Compare with this:

```raku
CATCH {

  CATCH {
      default { .Str.say; }
  }

  die "something went wrong ...";

}

say "Hi! I am at the outer block!"; # OUTPUT: «Hi! I am at the outer block!␤»
```

See [Resuming of exceptions](/language/exceptions#Resuming_of_exceptions), for how to return control back to where the exception originated.

# [`try` blocks](#Exceptions "go to top of document")[§](#try_blocks "direct link")

A `try` block is a normal block which implicitly turns on the [`use fatal` pragma](/language/pragmas#fatal) and includes an implicit `CATCH` block that drops the exception, which means you can use it to contain them. Caught exceptions are stored inside the `$!` variable, which holds a value of type [`Exception`](/type/Exception).

A normal block like this one will simply fail:

```raku
{
    my $x = +"a";
    say $x.^name;
} # OUTPUT: «Failure␤»

```

However, a `try` block will contain the exception and put it into the `$!` variable:

```raku
try {
    my $x = +"a";
    say $x.^name;
}

if $! { say "Something failed!" } # OUTPUT: «Something failed!␤»
say $!.^name;                     # OUTPUT: «X::Str::Numeric␤»

```

Any exception that is thrown in such a block will be caught by a `CATCH` block, either implicit or provided by the user. In the latter case, any unhandled exception will be rethrown. If you choose not to handle the exception, they will be contained by the block.

```raku
try {
    die "Tough luck";
    say "Not gonna happen";
}

try {
    fail "FUBAR";
}

```

In both `try` blocks above, exceptions will be contained within the block, but the `say` statement will not be run. We can handle them, though:

```raku
class E is Exception { method message() { "Just stop already!" } }

try {
    E.new.throw; # this will be local

    say "This won't be said.";
}

say "I'm alive!";

try {
    CATCH {
        when X::AdHoc { .Str.say; .resume }
    }

    die "No, I expect you to DIE Mr. Bond!";

    say "I'm immortal.";

    E.new.throw;

    say "No, you don't!";
}
```

Which would output:

｢text｣ without highlighting

```

```

I'm alive!
No, I expect you to DIE Mr. Bond!
I'm immortal.
Just stop already!
  in block <unit> at exception.raku line 21

```

```

Since the `CATCH` block is handling just the [`X::AdHoc`](/type/X/AdHoc) exception thrown by the `die` statement, but not the `E` exception. In the absence of a `CATCH` block, all exceptions will be contained and dropped, as indicated above. `resume` will resume execution right after the exception has been thrown; in this case, in the `die` statement. Please consult the section on [resuming of exceptions](/language/exceptions#Resuming_of_exceptions) for more information on this.

A `try`-block is a normal block and as such treats its last statement as the return value of itself. We can therefore use it as a right-hand side.

```raku
say try { +"99999" } // "oh no"; # OUTPUT: «99999␤»
say try { +"hello" } // "oh no"; # OUTPUT: «oh no␤»

```

Try blocks support `else` blocks indirectly by returning the return value of the expression or [`Nil`](/type/Nil) if an exception was thrown.

```raku
with try +"♥" {
    say "this is my number: $_"
} else {
    say "not my number!"
}
# OUTPUT: «not my number!␤»
```

`try` can also be used with a statement instead of a block, that is, as a [statement prefix](/language/statement-prefixes#try):

```raku
say try "some-filename.txt".IO.slurp // "sane default";
# OUTPUT: «sane default␤»

```

What `try` actually causes is, via the `use fatal` pragma, an immediate throw of the exceptions that happen within its scope, but by doing so the `CATCH` block is invoked from the point where the exception is thrown, which defines its scope.

```raku
my $error-code = "333";
sub bad-sub {
    die "Something bad happened";
}
try {
    my $error-code = "111";
    bad-sub;

    CATCH {
        default {
            say "Error $error-code ", .^name, ': ',.Str
        }
    }
}
# OUTPUT: «Error 111 X::AdHoc: Something bad happened␤»

```

# [Throwing exceptions](#Exceptions "go to top of document")[§](#Throwing_exceptions "direct link")

Exceptions can be thrown explicitly with the `.throw` method of an [`Exception`](/type/Exception) object.

This example throws an [`X::AdHoc`](/type/X/AdHoc) exception, catches it and allows the code to continue from the point of the exception by calling the `.resume` method.

```raku
{
    X::AdHoc.new(:payload<foo>).throw;
    "OHAI".say;
    CATCH {
        when X::AdHoc { .resume }
    }
}

"OBAI".say;

# OUTPUT: «OHAI␤OBAI␤»
```

If the `CATCH` block doesn't match the exception thrown, then the exception's payload is passed on to the backtrace printing mechanism.

```raku
{
    X::AdHoc.new(:payload<foo>).throw;
    "OHAI".say;
    CATCH {  }
}

"OBAI".say;

# OUTPUT: «foo
#          in block <unit> at my-script.raku:1»
```

This next example doesn't resume from the point of the exception. Instead, it continues after the enclosing block, since the exception is caught, and then control continues after the `CATCH` block.

```raku
{
    X::AdHoc.new(:payload<foo>).throw;
    "OHAI".say;
    CATCH {
        when X::AdHoc { }
    }
}

"OBAI".say;

# OUTPUT: «OBAI␤»
```

`throw` can be viewed as the method form of `die`, just that in this particular case, the sub and method forms of the routine have different names.

# [Resuming of exceptions](#Exceptions "go to top of document")[§](#Resuming_of_exceptions "direct link")

Exceptions interrupt control flow and divert it away from the statement following the statement that threw it. Any exception handled by the user can be resumed and control flow will continue with the statement following the statement that threw the exception. To do so, call the method `.resume` on the exception object.

```raku
CATCH { when X::AdHoc { .resume } }         # this is step 2

die "We leave control after this.";         # this is step 1

say "We have continued with control flow."; # this is step 3
```

Resuming will occur right after the statement that has caused the exception, and in the innermost call frame:

```raku
sub bad-sub {
    die "Something bad happened";
    return "not returning";
}

{
    my $return = bad-sub;
    say "Returned $return";
    CATCH {
        default {
            say "Error ", .^name, ': ',.Str;
            $return = '0';
            .resume;

        }
    }
}
# OUTPUT:
# Error X::AdHoc: Something bad happened
# Returned not returning

```

In this case, `.resume` is getting to the `return` statement that happens right after the `die` statement. Please note that the assignment to `$return` is taking no effect, since the `CATCH` statement is happening *inside* the call to `bad-sub`, which, via the `return` statement, assigns the `not returning` value to it.

# [Uncaught exceptions](#Exceptions "go to top of document")[§](#Uncaught_exceptions "direct link")

If an exception is thrown and not caught, it causes the program to exit with a non-zero status code, and typically prints a message to the standard error stream of the program. This message is obtained by calling the `gist` method on the exception object. You can use this to suppress the default behavior of printing a backtrace along with the message:

```raku
class X::WithoutLineNumber is X::AdHoc {
    multi method gist(X::WithoutLineNumber:D:) {
        $.payload
    }
}
die X::WithoutLineNumber.new(payload => "message")

# prints "message\n" to $*ERR and exits, no backtrace
```

# [Control exceptions](#Exceptions "go to top of document")[§](#Control_exceptions "direct link")

Control exceptions are raised when throwing an Exception which does the [`X::Control`](/type/X/Control) role (since Rakudo 2019.03). They are usually thrown by certain [keywords](/language/phasers#CONTROL) and are handled either automatically or by the appropriate [phaser](/language/phasers#Loop_phasers). Any unhandled control exception is converted to a normal exception.

```raku
{ return; CATCH { default { $*ERR.say: .^name, ': ', .Str } } }
# OUTPUT: «X::ControlFlow::Return: Attempt to return outside of any Routine␤»
# was CX::Return

```


## dist_zef-melezhik-SparrowCI-20--20super-20fun-20and-20flexible-20CI-20system-20with-20many-20programming-20languages-20support.md
[![SparrowCI](https://ci.sparrowhub.io/project/gh-melezhik-SparrowCI/badge)](https://ci.sparrowhub.io)

# SparrowCI

SparrowCI - super fun and flexible CI system with many programming languages support.

## Why yet another pipeline DSL?

Read [why?](docs/why.md) manifest.

## Quick start

See [quickstart.md](docs/quickstart.md) document.

## DAG of tasks

See [dag.md](docs/dag.md) document to understand the main idea of SparrowCI flow.

## Deep dive

See [dsl.md](docs/dsl.md) document for a full SparrowCI pipelines tutorial.

## Environment variables

See [variables.md](docs/variables.md) document.

## Self-hosted deployment

See [selfhosted.md](docs/selfhosted.md) document.

## Development

See [development.md](docs/development.md) document.

## External systems integration

See [reporters.md](docs/reporters.md) document.

# Thanks to

God and Jesus Christ who inspires me


## dist_github-jaldhar-Algorithm-DawkinsWeasel.md
# NAME

Algorithm::DawkinsWeasel - An Illustration of Cumulative Selection

# SYNOPSIS

```
  use Algorithm::DawkinsWeasel;

  my $weasel = Algorithm::DawkinsWeasel.new(
    target-phrase      => 'METHINKS IT IS LIKE A WEASEL',
    mutation-threshold => 0.05,
    copies             => 100,
  );

  for $weasel.evolution {
    say .count.fmt('%04d '), .current-phrase, ' [', .hi-score, ']';
  }

```

# DESCRIPTION

Algorithm::DawkinsWeasel is a simple model illustrating the idea of cumulative
selection in evolution.

The original form of it looked like this:

1. Start with a random string of 28 characters.
2. Make 100 copies of this string, with a 5% chance per character of that
   character being replaced with a random character.
3. Compare each new string with "METHINKS IT IS LIKE A WEASEL", and give
   each a score (the number of letters in the string that are correct and
   in the correct position).
4. If any of the new strings has a perfect score (== 28), halt.
5. Otherwise, take the highest scoring string, and go to step 2

This module parametrizes the target string, mutation threshold, and number of
copies per round.

# INSTALLATION

With a normal rakudo installation, you should have available one or
both of the installer tools:

* `zef`
* `panda`

`zef` is becoming the preferred tool because of more features
(including an uninstall function) and more active development, but
either tool should work fine for a first installation of a desired
module. We'll use `zef` for the rest of the examples.

```
zef install Algorithm::DawkinsWeasel

```

If the attempt shows that the module isn't found or available, ensure
your installer is current:

```
zef update

```

If you want to use the latest version in the git repository (or it's
not available in the Perl 6 ecosystem), clone it and then install it
from its local directory. Here we assume the module is on Github in
location "https://github.com/jaldhar/Algorithm-DawkinsWeasel", but use
the Github clone instructions for the desired module. (Note the
repository name is usually not the exact name of the module as used in
Perl 6.)

```
git clone https://github.com/jaldhar/Algorithm-DawkinsWeasel.git
cd /path/to/cloned/repository/directory
zef install .

```

# AUTHOR

Jaldhar H. Vyas [jaldhar@braincells.com](mailto:jaldhar@braincells.com)

# COPYRIGHT AND LICENSE

Copyright (C) 2017, Consolidated Braincells Inc. All rights reserved.

This distribution is free software; you can redistribute it and/or modify it
under the terms of either:

a) the GNU General Public License as published by the Free Software
Foundation; either version 2, or (at your option) any later version, or

b) the Artistic License version 2.0.

The full text of the license can be found in the LICENSE file included
with this distribution.


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

# NAME

`Geo::Location` - Provides location data for astronomical and other programs

# SYNOPSIS

Use the default location:

```
$ raku
> use Geo::Location;
> my $loc = Location.new; # note no arguments entered here
> say $loc.name;
Gulf Breeze, FL, USA
> say $loc.location;
lat: 30.485092, lon: -86.4376157
say $loc.lat;
30.485092
say $loc.lon;
-86.4376157

```

# DESCRIPTION

**Geo::Location** Allows the user to define a geographical location for easy use either by manual entry, from a JSON description, or an environment variable (`GEO_LOCATION`).

For now one must enter latitude and longitude using signed decimal numbers. One easy way to find those for a location is to use Google Maps (on a PC) and drop a location pin with its point at the place of interest. Then select the pin, right-click, and see the lat/lon on the first line of data. (I have had some success also with doing that on an iPad, but it's a bit trickier for my tastes, hence my use of a PC for real mapping uses.)

Note the object has only two required parameters ($lat, $lon), but there are nine other attributes available. See them listed below.

### Class construction

Use the manual entry:

```
my $loc = Geo::Location.new: :lat(-36.23), :lon(+12);

```

Use a JSON description:

```
my $json = q:to/HERE/;
{
    "name" : "Foo Town",
    "lat"  : 35.267,
    "lon"  : -42.3
}
HERE
my $loc = Geo::Location.new: :$json;

```

Use an environment variable:

Define desired attributes just like a manual entry but without the colons. Use double quotes on the entire value and single quotes inside, or the reverse, as desired. Note also strings without spaces do not require quotes inside the parentheses. Note also this is only used when (1) no manual or json methods are used and (2) a valid `GEO_LOCATION` environment variable is defined in the using environment.

```
$ export GEO_LOCATION="lat(42.4),lon(13.6),name('Baz Beach')";

```

### Class attributes

There are eleven total public attributes in the class.

* city
* country

  typically a two-character ISO code
* county
* id

  use as unique reference in a collection
* lat
* lon
* name

  a convenient display name
* notes
* region

  **EU**, etc., multi-country area with DST rules
* state

  typically a two-letter ISO code, for example, a US state
* timezone

  use as a reference time zone abbreviation for use with module **DateTime::US**

### Class methods

In addition to the methods provided for the public attributes listed above, the following added methods provide some other ways of showing object data.

* **lat-dms**(--> Str) {...}

  Returns the latitude in DMS format
* **lon-dms**(--> Str) {...}

  Returns the longitude in DMS format
* **riseset-format**(:bare --> Str) {...}

  Returns the format required by the Perl programs accompanying CPAN Perl module **Astro::Montenbruck** (in this module the format will also be referred to as '**RST**'):

  ```
  ./script/riseset.pl --place=30N29 86W26 --twilight=civil

  ```

  Note that Perl module's convention for the sign of East longitude is negative instead of positive for decimal entries, so it is important to use the provided RST format to avoid longitude errors.
* **lat-rst**(--> Str) {...}

  Returns the latitude in RST format
* **lon-rst**(--> Str) {...}

  Returns the longitude in RST format
* **location**(:$format = 'decimal', :bare --> Str) {

  Returns the location in a single string in the specified format. For example:

  In default decimal:

  ```
  say $loc.location;
  lat: 30.485092, lon: -86.4376157
  say $loc.location(:bare);
  30.485092 -86.4376157

  ```

  Or in DMS:

  ```
  say $loc.location(:format('dms'));
  lat: N30d29m6s, lon: W86d26m15s
  say $loc.location(:format('dms'), :bare);
  N30d29m6s W86d26m15s

  ```

  Or in RST:

  ```
  say $loc.location(:format('rst'));
  lat: 30N29, lon: 86W26
  say $loc.location(:format('rst'), :bare);
  30N29 86W26

  ```

# To Do

* Allow other forms of lat/lon entry besides decimal
* Provide more methods for astronomical use
* Prove enums for use with argument entry

# AUTHOR

Tom Browder `tbrowder@acm.org`

# COPYRIGHT AND LICENSE

© 2021-2024 Tom Browder

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


## dist_cpan-JNTHN-Cro-HTTP.md
# Cro::HTTP Build Status

This is part of the Cro libraries for implementing services and distributed
systems in Raku. See the [Cro website](http://cro.services/) for further
information and documentation.


## dist_zef-akiym-JSON-Hjson.md
[![Actions Status](https://github.com/akiym/JSON-Hjson/actions/workflows/test.yml/badge.svg)](https://github.com/akiym/JSON-Hjson/actions)

# NAME

JSON::Hjson - Human JSON (Hjson) deserializer

# SYNOPSIS

```
use JSON::Hjson;

my $text = q:to'...';
{
  // specify delay in
  // seconds
  delay: 1
  message: wake up!
}
...
say from-hjson($text).raku;

```

# DESCRIPTION

JSON::Hjson implements Human JSON (Hjson) in Raku grammar.

# SEE ALSO

JSON::Tiny

<https://hjson.org/rfc.html>

# AUTHOR

Takumi Akiyama [t.akiym@gmail.com](mailto:t.akiym@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2016 Takumi Akiyama

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


## dist_github-ugexe-CompUnit-Repository-Github.md
## CompUnit::Repository::Github

Load modules directly from the Github API over http. Fuck it.

## Synopsis

```
BEGIN %*ENV<GITHUB_ACCESS_TOKEN> = "..."; # optional, but useful due to api rate limiting

use CompUnit::Repository::Github;
use lib "CompUnit::Repository::Github#user<ugexe>#repo<Raku-PathTools>#branch<main>#/";

require ::("PathTools") <&ls>;
say &ls($*CWD);

```

See: [tests](https://github.com/ugexe/Raku-CompUnit--Repository--Github/blob/main/t)


## dist_cpan-JMERELO-Perl6-Ecosystem.md
[![Build Status](https://travis-ci.org/JJ/p6-river.svg?branch=master)](https://travis-ci.org/JJ/p6-river)

# NAME

Perl6::Ecosystem - Obtains information from Perl6 modules in the ecosystem

# SYNOPSIS

```
use Perl::Ecosystem;
my $eco = Perl6::Ecosystem.new;

say $eco.modules;
say $eco.depended;
say $eco.depends-on;

```

# DESCRIPTION

A tool to analyze the Perl 6 ecosystem by downloading all modules and finding out how they depend on each other.

# METHODS

## method new( )

Creates the object, downloading and filling it with information. Error output goes to `/tmp/perl6-eco-err.txt`

## method modules

Returns a `hash` with module names, dependencies and URLs.

## method depended

Returns a `hash` with module names and the number of other modules it depends on.

## method depends-on

Returns a `hash` with module names and its dependencies.

## method river-scores --> Hash

Computes the "river-score" by looking at all dependency chains and giving a score according to the position. That is, if there's this dependenci chain

```
Foo → Bar → Baz

```

Foo will have a 0 score for appearing in the first position, up to Baz which will have score equal to 2. The total score of every module is computed by adding all scores.

# SEE ALSO

[Perl6 module ecosystem](https://modules.perl6.org).

# KNOWN BUGS

It chokes on circular references. Right now they are blacklisted.

# AUTHOR

Alex Daniel, JJ Merelo [jjmerelo@gmail.com](mailto:jjmerelo@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2018 Alex Daniel, JJ Merelo

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


## dist_zef-dwarring-CSS-Module.md
[[Raku CSS Project]](https://css-raku.github.io)
/ [[CSS-Module]](https://css-raku.github.io/CSS-Module-raku)

# CSS::Module

```
# Parse a sample stylesheet as CSS 2.1. Dump the AST.
use v6;
use CSS::Module::CSS21;
my $css = 'h1 { color: orange; text-align: center }';
my $module = CSS::Module::CSS21.module;
my $actions = $module.actions.new;
$module.grammar.parse( $css, :$actions);
say $/.ast.raku;

```

CSS::Module is a set of Raku classes for parsing and manipulation of CSS Levels 1, 2.1 and 3, and SVG.

It contains modules `CSS::Module::CSS1`, `CSS::Module::CSS21` and `CSS::Module::CSS3` for CSS levels 1.0, 2.1 and 3.0, along with `CSS::Module::SVG`, which is a CSS3 extension for [styling SVG](https://www.w3.org/TR/SVG2/styling.html).

Each of these classes has a `module` method which produces an object that encapsulates grammars, actions
and property metadata. It has a`property-metadata` method that can be used to introspect properties. For example

```
% raku -M CSS::Module::CSS3 -e'say CSS::Module::CSS3.module.property-metadata<azimuth>.raku'
{:default("center"), :inherit, :synopsis("<angle> | [[ left-side | far-left | left | center-left | center | center-right | right | far-right | right-side ] || behind ] | leftwards | rightwards")}

```

Note: `CSS::Module::CSS3.module` is composed from the following grammars.

* `CSS::Module::CSS3::Colors` - CSS 3.0 Colors (@color-profile)
* `CSS::Module::CSS3::Fonts` - CSS 3.0 Fonts (@font-face)
* `CSS::Module::CSS3::Selectors` - CSS 3.0 Selectors
* `CSS::Module::CSS3::Namespaces` - CSS 3.0 Namespace (@namespace)
* `CSS::Module::CSS3::Media` - CSS 3.0 Media (@media)
* `CSS::Module::CSS3::PagedMedia` - CSS 3.0 Paged Media (@page)
* `CSS::ModuleX::CSS21` - the full set of CSS21 properties

This corresponds to the sub-modules described in [CSS Snapshot 2010](http://www.w3.org/TR/2011/NOTE-css-2010-20110512/).

## Installation

You can use the Raku `zef` module installer to test and install `CSS::Module`:

```
% zef install CSS::Module

```

## Examples

* parse a stylesheet using the CSS2.1 grammar:

  % raku -MCSS::Module::CSS21 -e"say CSS::Module::CSS21.parse('h1 {margin:2pt; color: blue}')"
* compile a CSS2.1 stylesheet to an AST, using the module interface:

```
use v6;
use CSS::Module::CSS21;

my $css = 'H1 { color: blue; foo: bar; background-color: zzz }';
my $module  = CSS::Module::CSS21.module;
my $grammar = $module.grammar;
my $actions = $module.actions.new;
my $p = $grammar.parse($css, :$actions);
note $_ for $actions.warnings;
say "declaration: " ~ $p.ast[0]<ruleset><declarations>.raku;
# output:
# unknown property: foo - declaration dropped
# usage background-color: <color> | transparent | inherit
# declaration: {"color" => {"expr" => [{"rgb" => [{"num" => 0}, {"num" => 0}, {"num" => 255}]}]}

```

* parse an individual `azimuth` property expression via the module interface:

```
    use v6;
    use CSS::Module::CSS21;
    my $ast = CSS::Module::CSS21.module.parse-property('azimuth', 'center-left behind');

```

* Composition: A secondary aim is mixin style module composition. For example to create a module MyCSS3Subset::CSS3 comprising CSS2.1 properties + CSS3 Selectors + CSS3 Colors:

  ```
  use v6;

  use CSS::Module;
  use CSS::Module::CSS21::Actions;
  use CSS::Module::CSS21;

  use CSS::Module::CSS3::Selectors;
  use CSS::Module::CSS3::Colors;
  use CSS::Module::CSS3::_Base;

  class MyCSS3Subset::Actions
      is CSS::Module::CSS3::Selectors::Actions
      is CSS::Module::CSS3::Colors::Actions
      is CSS::ModuleX::CSS21::Actions
      is CSS::Module::CSS3::_Base::Actions {
  };
  grammar MyCSS3Subset::CSS3
      is CSS::Module::CSS3::Selectors
      is CSS::Module::CSS3::Colors
      is CSS::ModuleX::CSS21
      is CSS::Module::CSS3::_Base {

      #| a minimal module definition: grammar + actions
      method module {
    state $this //= CSS::Module.new(
            :name<my-css3-subset>,
            :grammar($?CLASS),
            :actions(MyCSS3Subset::Actions) );
      }
  };

  ```

## Property Definitions

Property definitions are built from the sources in the `src` directory using the CSS::Specification tools. These implement the [W3C Property Definition Syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax).

Generated modules are written under the `gen/lib` directory.

For example [CSS::Module:CSS1::Spec::Grammar](gen/lib/CSS/Module/CSS1/Spec/Grammar.pm), [CSS::Module:CSS1::Spec::Actions](gen/lib/CSS/Module/CSS1/Spec/Actions.pm) and [CSS::Module:CSS1::Spec::Interface](gen/lib/CSS/Module/CSS1/Spec/Interface.pm) are generated from <etc/css1-properties.txt>.

See `make-modules.pl`.

## Actions Options

* **`:lax`** Don't warn about, or discard, unknown properties, sub-rules. Pass back the elements with a classification
  of unknown. E.g.

```
    my $module  = CSS::Module::CSS21.module;
    my $grammar = $module.grammar;
    my $actions = $module.actions.new( :lax );

    say $grammar.parse('{bad-prop: 12mm}', :$actions, :rule<declarations>).ast.raku;
    # output {"property:unknown" => {:expr[{ :mm(12) }], :ident<bad-prop>}}

    say $grammar.parse('{ @guff {color:red} }', :$actions, :rule<declarations>).ast.raku;
    # output: {"margin-rule:unknown" =>  { :declarations[ { :ident<color>,
                                                          :expr[ { :rgb[ { :num(255) }, { :num(0) }, { :num(0) } ] } ] } ],
                                         :at-keyw<guff> } }

```

`lax` mode likewise returns quantities with unknown dimensions:

```
    say $grammar.parse('{margin: 12mm .1furlongs}', :$actions, :rule<declarations>).ast.raku;
    # output {"property" => {:expr[{ :mm(12) }, { :num(0.12), "units:unknown" => <furlongs>}], :ident<margin>}}

```

## Custom Properties

Properties may be added, or overriden via an `:%extensions` option to the `new()` method.

```
subset MyAlignment of Str where 'left'|'middle'|'right';
sub coerce(MyAlignment:D $keyw --> Pair) { :$keyw }

my %extensions =  %(
    '-my-align' => %(:synopsis("left | middle | right"), :default<middle>, :&coerce),
    '-my-misc' => %(), # can hold any value
);

my $module = CSS::Module::CSS3.module: :%extensions;
say $module.property-metadata<-my-align>.raku;

```

## See Also

* [CSS::Properties](https://css-raku.github.io/CSS-Properties-raku) - property-set manipulation module
* [CSS::Specification](https://css-raku.github.io/CSS-Specification-raku) - property definition syntax
* [CSS::Grammar](https://css-raku.github.io/CSS-Grammar-raku) - base grammars
* [CSS::Writer](https://css-raku.github.io/CSS-Writer-raku) - AST reserializer

## References

* CSS Snapshot 2010 - <http://www.w3.org/TR/2011/NOTE-css-2010-20110512/>
* CSS1 - <http://www.w3.org/TR/2008/REC-CSS1-20080411/#css1-properties>
* CSS21 - <http://www.w3.org/TR/2011/REC-CSS2-20110607/propidx.html>
* CSS3
  * CSS Color Module Level 3 - <http://www.w3.org/TR/2011/REC-css3-color-20110607/>
  * CSS Fonts Module Level 3 - <http://www.w3.org/TR/2013/WD-css3-fonts-20130212/>
  * CSS3 Namespaces Module - <http://www.w3.org/TR/2011/REC-css3-namespace-20110929/>
  * CSS3 Media Query Extensions - <http://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/>
  * CSS3 Module: Paged Media - <http://www.w3.org/TR/2006/WD-css3-page-20061010/>
  * CSS Selectors Module Level 3 - <http://www.w3.org/TR/2011/REC-css3-selectors-20110929/>
* SVG - <https://www.w3.org/TR/SVG2/styling.html> <https://www.w3.org/TR/SVG/propidx.html>


## dist_github-grondilu-PBKDF2.md
[![SparkyCI](https://sparky.sparrowhub.io/badge/gh-grondilu-pbkdf2-raku?foo=bar)](https://sparky.sparrowhub.io)

# pbkdf2-raku

PBKDF2 in pure raku. Speed will mostly depend on the pseudo-random function used.

## Synopsis

```
use PBKDF2;
use Digest::MD5;

say pbkdf2 "password",
  :salt("salt"),
  :prf(&md5 ∘ &[~]),
  :c(10),
  :dkLen(32);

```


## dist_zef-ingy-YAMLScript.md
# YAMLScript

Program in YAML — Code is Data

## Synopsis

```
#!/usr/bin/env ys-0

defn main(name='world'):
  say: "Hello, $name!"

```

## Description

YAMLScript is a functional programming language with a stylized YAML syntax.

YAMLScript can be used for:

* Writing new programs and applications
  * Run with `ys file.ys`
  * Or compile to binary executable with `ys -C file.ys`
* Enhancing ordinary YAML files with new functional magics
  * Import parts of other YAML files to any node
  * String interpolation including function calls
  * Any other functionality you can dream up!
* Writing reusable shared libraries
  * High level code instead of C
  * Bindable to almost any programming language

YAMLScript should be a drop-in replacement for your YAML loader!

Most existing YAML files are already valid YAMLScript files.
This means that YAMLScript works as a normal YAML loader, but can also evaluate
functional expressions if asked to.

Under the hood, YAMLScript code compiles to the Clojure programming language.
This makes YAMLScript a complete functional programming language right out of
the box.

Even though YAMLScript compiles to Clojure, and Clojure compiles to Java, there
is no dependency on Java or the JVM.
YAMLScript is compiled to a native shared library (`libyamlscript.so`) that can
be used by any programming language that can load shared libraries.

To see the Clojure code that YAMLScript compiles to, you can use the YAMLScript
command line utility, `ys`, to run:

```
$ ys --compile file.ys

```

## Raku Usage

File `prog.raku`:

```
use YAMLScript;
my $program = slurp 'file.ys';
my YAMLScript $ys .= new;
say $ys.load($program);

```

File `file.ys`:

```
!YS-v0:

name =: "World"

foo: [1, 2, ! inc(41)]
bar:: load("other.yaml")
baz:: "Hello, $name!"

```

File `other.yaml`:

```
oh: Hello

```

Run:

```
$ raku prog.raku
{bar => {oh => Hello}, baz => Hello, World!, foo => [1 2 42]}

```

## Installation

You can install this module like any other Raku module:

```
zef install YAMLScript

```

but you will need to have a system install of `libyamlscript.so`.

One simple way to do that is with:

```
curl https://yamlscript.org/install | bash

```

> Note: The above command will install the latest version of the YAMLScript
> command line utility, `ys`, and the shared library, `libyamlscript.so`, into
> `~/local/bin` and `~/.local/lib` respectively.

See <https://github.com/yaml/yamlscript?#installing-yamlscript> for more info.

## See Also

* [The YAMLScript Web Site](https://yamlscript.org)
* [The YAMLScript Blog](https://yamlscript.org/blog)
* [The YAMLScript Source Code](https://github.com/yaml/yamlscript)
* [YAML](https://yaml.org)
* [Clojure](https://clojure.org)

## Authors

* [Ingy döt Net](https://github.com/ingydotnet)
* [tony-o](https://github.com/tony-o)

## License & Copyright

Copyright 2022-2025 Ingy döt Net [ingy@ingy.net](mailto:ingy@ingy.net)

This project is licensed under the terms of the `MIT` license.
See [LICENSE](https://github.com/yaml/yamlscript/blob/main/License) for
more details.


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

# NAME

String::Color - map strings to a color code

# SYNOPSIS

```
use String::Color;
use Randomcolor;  # some module for randomly generating colors

my $sc = String::Color.new(
  generator => { Randomcolor.new.list.head },
  cleaner   => { .lc },         # optionally provide own cleaning logic
  colors    => %colors-so-far,  # optionally start with given set
);

my @added = $sc.add(@nicks);    # add mapping for strings in @nicks

my %colors := $sc.Map;          # set up Map with color mappings so far

say "$color is already used"
  if $sc.known($color);        # check if a color is used already

```

# DESCRIPTION

String::Color provides a class and logic to map strings to a (random) color code. It does so by matching the cleaned version of a string.

The way a color is generated, is determined by the required `generator` named argument: it should provice a `Callable` that will take a cleaned string, and return a color for it.

The way a string is cleaned, can be specified with the optional `cleaner` named argument: it should provide a `Callable` that will take the string, and return a cleaned version of it. By default, the cleaning logic will remove any non-alpha characters, and lowercase the resulting string.

Strings can be continuously added by calling the `add` method. The current state can be obtained with the `Map` method. The `known` method can be used to see whether a color is already being used or not.

Note that colors are described as strings. In whichever format you would like. Technically, this module could be used to match strings to other strings that would not necessarily correspond to colors. But that's entirely up to the fantasy of the user of this module.

Also note that by e.g. writing out the `Map` of a `String::Color` object as e.g. **JSON** to disk, and then later use that in the `colors` argument to `new`, would effectively make the mapping persistent.

Finally, even though this may look like a normal hash, but all operations are thread safe (although results may be out of date).

# CLASS METHODS

## new

```
my $sc = String::Color.new(
  generator => -> $string {
      $string eq 'liz'
        ?? "ff0000"
        !! RandomColor.new.list.head
  },
  cleaner => { .lc },         # optionally provide own cleaning logic
  colors  => %colors-so-far,  # optionally start with given set
);

```

The `new` class method takes two named arguments.

### :cleaner

The `cleaner` named argument allows one to specify a `Callable` which is supposed to take a string, and return a cleaned version of the string. By default, a cleaner that will remove all non-alpha characters and return the resulting string in lowercase, will be used.

### :colors

The `colors` named argument allows one to specify a `Hash` / `Map` with colors that have been assigned to strings so far. Only the empty string mapping to the empty string will be assumed, if not specified.

### :generator

The `generator` named argument specifies a `Callable` that will be called to generate a colors for the associated string (which gets passed to the `Callable`). It **must** be specified.

# INSTANCE METHODS

## add

```
my @added = $sc.add(@strings);

```

The `add` instance method allows adding of strings to the colors mapping. It takes a list of strings as the positional argument. It returns a list of strings that were actually added (in the order they were added).

## aliases

```
my @aliases = $sc.aliases($string);

```

The `aliases` instance method returns a sorted list of strings that are considered aliases of the given string, because they share the same cleaned string.

## cleaned

```
.say for $sc.cleaned;

```

The `cleaned` instance method returns the cleaned strings in the same order as `strings`.

## colors

```
say "colors assigned:";
.say for $sc.colors.unique;

```

The `colors` instance method returns the colors in the same order as `strings`.

## elems

```
say "$sc.elems() mappings so far";

```

The `elems` instance method returns the number of mappings.

## known

```
say "$color is already used"
  if $sc.known($color);            # check if a color is used already

```

The `known` instance method takes a single string for color, and returns whether that color is already in use or not.

## Map

```
my %colors := $sc.Map;            # create simple Associative interface

```

The `Map` instance method returns the state of the mapping as a `Map` object, which can be bound to create an `Associative` interface. Or it can be used to create a persistent version of the mapping.

## strings

```
say "strings mapped:";
.say for $sc.strings;

```

The `strings` instance method returns the strings.

# AUTHOR

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

Source can be located at: <https://github.com/lizmat/String-Color> . 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 2021, 2024, 2025 Elizabeth Mattijsen

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


## dist_zef-antononcube-UML-Translators.md
# Raku UML::Translators

## In brief

This repository is for a Raku package for the translations of code into
[Unified Modeling Language (UML)](https://en.wikipedia.org/wiki/Unified_Modeling_Language)
specifications and vice versa.

Currently, the package only translates Object-Oriented Programming (OOP) Raku code into:

* The Domain Specific Language (DSL) of [Mermaid-JS](https://mermaid-js.github.io/mermaid/)
* The DSL of [PlantUML](https://plantuml.com)
* Argument specification of the UML class diagram function [`UMLClassGraph`](https://github.com/antononcube/MathematicaForPrediction/blob/master/Misc/UMLDiagramGeneration.m)
  of the Mathematica / Wolfram Language (WL) package [AAp1]

See [AA2] for usage examples of both PlantUML and `UMLClassGraph` in Mathematica.

**Remark:** The package provides Command Line Interface (CLI) script.

**Remark:** (Currently) the development of PlantUML is more robust and complete than that of Mermaid-JS.
Hence, workflow-wise, using this package to generate PlantUML specs would produce (on average) best results.

### Future plans

A fully fledged version of this package would translate:

* C++, Java, Kotlin, or Raku code into UML specs
* UML specs into C++, Java, Kotlin, or Raku code

Currently, only UML specs are generated to PlantUML's DSL and a much poorer WL DSL.
Ideally, subsequent versions of this package would be able to use UML specifications
encoded in XML and JSON.

---

## Installation

### From zef's ecosystem

```
zef install UML::Translators

```

### From GitHub

```
zef install https://github.com/antononcube/Raku-UML-Translators.git

```

---

## Command Line Interface

The package provides the CLI script `to-uml-spec`. Here is its usage message:

```
to-uml-spec --help

```

```
# Usage:
#   to-uml-spec <packageName> [--type=<Str>] [-I=<Str>] [--attributes] [--methods] [--concise-grammar-classes] [--format=<Str>] [--plot] [--jar=<Str>] [--viewer=<Str>] -- Make a UML diagram for a specified package.
#
#     <packageName>                Package name.
#     --type=<Str>                 Type of the UML diagram. [default: 'class']
#     -I=<Str>                     Using include path to find libraries. [default: '']
#     --attributes                 Should the class attributes be included in the UML diagrams or not? [default: True]
#     --methods                    Should the class methods be included in the UML diagrams or not? [default: True]
#     --concise-grammar-classes    Should grammar classes be shortened or not? [default: True]
#     --format=<Str>               Format of the output, one of 'Mermaid', 'MermaidJS', 'Plant', 'PlantUML', 'WL', 'WLUML', or 'Whatever'. [default: 'PlantUML']
#     --plot                       Should the result be plotted or not? [default: False]
#     --jar=<Str>                  JAR file to use if --plot. If --jar is an empty string then PLANTUMLJAR and PLANTUML_JAR are attempted. [default: '']
#     --viewer=<Str>               Image viewer program to use if --plot. If --viewer is an empty string then open is used on macOS and xdg-open on Linux. [default: '']

```

### Usage examples

Generate PlantUML spec for the Raku package
["ML::Clustering"](https://raku.land/zef:antononcube/ML::Clustering):

```
to-uml-spec --/methods --/attributes "ML::Clustering"

```

```
# @startuml
# class "find-clusters" <<routine>> {
# }
# "find-clusters" --|> Routine
# "find-clusters" --|> Block
# "find-clusters" --|> Code
# "find-clusters" --|> Callable
#
#
# class "k-means" <<routine>> {
# }
# "k-means" --|> Routine
# "k-means" --|> Block
# "k-means" --|> Code
# "k-means" --|> Callable
#
#
# class ML::Clustering::KMeans  {
# }
# ML::Clustering::KMeans --|> ML::Clustering::DistanceFunctions
#
#
# class ML::Clustering::DistanceFunctions <<role>> {
# }
#
#
# @enduml

```

With this shell command we generate a Plant UML spec for the package
["Chemistry::Stoichiometry"](https://raku.land/cpan:ANTONOV/Chemistry::Stoichiometry)
and create the UML diagram image with a local PlantUML JAR file (downloaded from [PUML1]):

```
to-uml-spec --/methods --/attributes 'Chemistry::Stoichiometry' | java -jar ~/Downloads/plantuml-1.2022.5.jar -pipe -tjpg > /tmp/myuml.jpg

```

---

## Raku session

### UML for ad hoc classes

Here we generate a PlantUML spec:

```
use UML::Translators;
module MyPackageClass {
  role A { method a1 {} }
  role B { method b1 {} }
  class C does A { has $!c-var; method c1 {} }
  class D does B is C { has $!d-var; method d1 {} }
}
to-uml-spec('MyPackageClass')

```

```
# @startuml
# class MyPackageClass::C  {
#   {field} $!c-var
#   {method} BUILDALL
#   {method} a1
#   {method} c1
# }
# MyPackageClass::C --|> MyPackageClass::A
#
#
# class MyPackageClass::D  {
#   {field} $!c-var
#   {field} $!d-var
#   {method} BUILDALL
#   {method} b1
#   {method} d1
# }
# MyPackageClass::D --|> MyPackageClass::C
# MyPackageClass::D --|> MyPackageClass::A
# MyPackageClass::D --|> MyPackageClass::B
#
#
# class MyPackageClass::B <<role>> {
#   {method} b1
# }
#
#
# class MyPackageClass::A <<role>> {
#   {method} a1
# }
#
#
# @enduml

```

Here we generate a MermaidJS spec:

```
to-uml-spec('MyPackageClass', format => 'mermaid')

```

```
classDiagram
class MyPackageClass_C {
  +$!c-var
  +BUILDALL()
  +a1()
  +c1()
}
MyPackageClass_C --|> MyPackageClass_A

class MyPackageClass_D {
  +$!c-var
  +$!d-var
  +BUILDALL()
  +b1()
  +d1()
}
MyPackageClass_D --|> MyPackageClass_C
MyPackageClass_D --|> MyPackageClass_A
MyPackageClass_D --|> MyPackageClass_B

class MyPackageClass_B {
  <<role>>
  +b1()
}

class MyPackageClass_A {
  <<role>>
  +a1()
}

```

### UML for packages

Get PlantUML code for the package
['Chemistry::Stoichiometry'](https://raku.land/cpan:ANTONOV/Chemistry::Stoichiometry):

```
say to-uml-spec('Chemistry::Stoichiometry'):!methods:!attributes

```

```
# @startuml
# class Chemistry::Stoichiometry::ResourceAccess  {
# }
#
#
# class Chemistry::Stoichiometry::Grammar <<grammar>> {
# }
# Chemistry::Stoichiometry::Grammar --|> Grammar
# Chemistry::Stoichiometry::Grammar --|> Match
# Chemistry::Stoichiometry::Grammar --|> Capture
# Chemistry::Stoichiometry::Grammar --|> Chemistry::Stoichiometry::Grammar::ChemicalElement
# Chemistry::Stoichiometry::Grammar --|> Chemistry::Stoichiometry::Grammar::ChemicalEquation
# Chemistry::Stoichiometry::Grammar --|> NQPMatchRole
#
#
# class Chemistry::Stoichiometry::Grammar::ChemicalEquation <<role>> {
# }
#
#
# class Chemistry::Stoichiometry::Grammar::ChemicalElement <<role>> {
# }
#
#
# class Chemistry::Stoichiometry::Actions::EquationBalance  {
# }
# Chemistry::Stoichiometry::Actions::EquationBalance --|> Chemistry::Stoichiometry::Actions::EquationMatrix
#
#
# class Chemistry::Stoichiometry::Actions::MolecularMass  {
# }
#
#
# class Chemistry::Stoichiometry::Actions::EquationMatrix  {
# }
#
#
# class Chemistry::Stoichiometry::Actions::WL::System  {
# }
#
#
# @enduml

```

Get WL UML graph spec for the package [AAp1]:

```
say to-uml-spec('Chemistry::Stoichiometry', format => 'wluml'):!methods:!attributes

```

```
# UMLClassGraph[
# "Parents" -> Flatten[{"Chemistry::Stoichiometry::Grammar" \[DirectedEdge] "Grammar", "Chemistry::Stoichiometry::Grammar" \[DirectedEdge] "Match", "Chemistry::Stoichiometry::Grammar" \[DirectedEdge] "Capture", "Chemistry::Stoichiometry::Grammar" \[DirectedEdge] "Chemistry::Stoichiometry::Grammar::ChemicalElement", "Chemistry::Stoichiometry::Grammar" \[DirectedEdge] "Chemistry::Stoichiometry::Grammar::ChemicalEquation", "Chemistry::Stoichiometry::Grammar" \[DirectedEdge] "NQPMatchRole", "Chemistry::Stoichiometry::Actions::EquationBalance" \[DirectedEdge] "Chemistry::Stoichiometry::Actions::EquationMatrix"}],
# "RegularMethods" -> Flatten[{}],
# "Abstract" -> Flatten[{"Chemistry::Stoichiometry::Grammar::ChemicalElement", "Chemistry::Stoichiometry::Grammar::ChemicalEquation", "NQPMatchRole"}],
# "EntityColumn" -> False, VertexLabelStyle -> "Text", ImageSize -> Large, GraphLayout -> Automatic]

```

### Classes in a name space

Get the classes, roles, subs, and constants of a namespace:

```
.say for namespace-types('ML::TriesWithFrequencies', :how-pairs).sort(*.key)

```

```
# ML::TriesWithFrequencies::LeafProbabilitiesGatherer => Perl6::Metamodel::ClassHOW
# ML::TriesWithFrequencies::ParetoBasedRemover => Perl6::Metamodel::ClassHOW
# ML::TriesWithFrequencies::PathsGatherer => Perl6::Metamodel::ClassHOW
# ML::TriesWithFrequencies::RegexBasedRemover => Perl6::Metamodel::ClassHOW
# ML::TriesWithFrequencies::ThresholdBasedRemover => Perl6::Metamodel::ClassHOW
# ML::TriesWithFrequencies::Trie => Perl6::Metamodel::ClassHOW
# ML::TriesWithFrequencies::TrieTraverse => Perl6::Metamodel::ParametricRoleGroupHOW
# ML::TriesWithFrequencies::Trieish => Perl6::Metamodel::ParametricRoleGroupHOW
# TRIEROOT => Str
# TRIEVALUE => Str

```

---

## Potential problems

### Mermaid JS

The package can export class diagrams in the
[Mermaid-JS format](https://mermaid-js.github.io/mermaid/#/classDiagram).
Unfortunately, currently (November 2022) Mermaid-JS does not support colon characters in class names.
Hence, colons are replaced with underscores.

Also, currently (November 2022) class specs in Mermaid-JS cannot be empty. I.e. the Mermaid JS code
generated here ***will not*** produce a diagram:

```
to-uml-spec --/methods --/attributes "ML::Clustering" --format=mermaid

```

```
# classDiagram
# class ML_Clustering_KMeans {
# }
# ML_Clustering_KMeans --|> ML_Clustering_DistanceFunctions
#
#
# class k_means {
#   <<routine>>
# }
# k_means --|> Routine
# k_means --|> Block
# k_means --|> Code
# k_means --|> Callable
#
#
# class ML_Clustering_DistanceFunctions {
#   <<role>>
# }
#
#
# class find_clusters {
#   <<routine>>
# }
# find_clusters --|> Routine
# find_clusters --|> Block
# find_clusters --|> Code
# find_clusters --|> Callable

```

(Because of the empty definition `ML_Clustering_KMeans { }`.)

This command should produce Mermaid JS code that will produce diagram:

```
to-uml-spec --/methods --/attributes "ML::Clustering" --format=mermaid

```

---

## References

[AA1] Anton Antonov, et al.,
["Find programmatically all classes, grammars, and roles in a Raku package"](https://stackoverflow.com/q/68622047/14163984),
(2021),
[StackOverflow](https://stackoverflow.com).

[AA2] Anton Antonov,
["Generating UML diagrams for Raku namespaces"](https://community.wolfram.com/groups/-/m/t/2549055),
(2022),
[community.wolfram.com](https://community.wolfram.com).

[AAp1] Anton Antonov,
["UML Diagram Generation Mathematica package"](https://github.com/antononcube/MathematicaForPrediction/blob/master/Misc/UMLDiagramGeneration.m),
(2016),
[MathematicaForPrediction at GitHub/antononcube](https://github.com/antononcube).

[ES1] Eugene Steinberg and Vojtech Krasa,
[PlantUML integration IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/7017-plantuml-integration),
[JetBrains Plugins Marketplace](https://plugins.jetbrains.com).

[GV1] [graphviz.org](https://graphviz.org).

[PUML1] [plantuml.com](https://plantuml.com).

[PUML2] [PlantUML online demo server](http://www.plantuml.com/plantuml).

[UMLD1] [uml-diagrams.org](https://www.uml-diagrams.org).

[WK1] Wikipedia entry, ["Graphviz"](https://en.wikipedia.org/wiki/Graphviz).

[WK2] Wikipedia entry, ["PlantUML"](https://en.wikipedia.org/wiki/PlantUML).

[WK3] Wikipedia entry, ["Unified Modeling Language"](https://en.wikipedia.org/wiki/Unified_Modeling_Language).


## make.md
make

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Match#routine_make)
for **routine make**.

```raku
method make(Match:D: Mu $payload)
sub make(Mu $payload)
```

Sets the `.ast` attribute, which will be retrieved using `.made`.

```raku
$/.make("your payload here");
```

That is, it stores an arbitrary payload into the `Match` object that can later be retrieved via [`.made`](/routine/made) method. Since the sub form operates, by default, on `$/`, that example is equivalent to:

```raku
make("your payload here");
```

This is typically used in a [grammar](/language/grammars)'s actions class methods, where a piece of data is stored by one method and then later retrieved by another. It's up to you what data you store. It could be a tree node, [result of a calculation](/language/grammars#Proto_regexes), a type object, or a list of values.

The sub form operates on the current Match `$/`, which can be a convenient shortcut:

```raku
method my-action ($/) {
    make "foo: $/";
}
```


## dist_zef-melezhik-Sparrowdo.md
# Sparrowdo

Run Sparrow tasks remotely (and not only)

# Build status

![SparkyCI](https://sparky.sparrowhub.io/badge/gh-melezhik-Sparrowdo?foo=bar)

# Install

```
zef install Sparrowdo

```

# Usage

```
sparrowdo --host=remote-host [options]

```

For example:

```
# ssh host, bootstrap first, use of local repository
sparrowdo --host=13.84.166.232  --repo=file:///home/melezhik/repo --verbose  --bootstrap

# docker host, don't add sudo
sparrowdo --docker=SparrowBird --image=alpine:latest --no_sudo

# localhost, with sudo
sparrowdo --localhost

# read hosts from file
sparrowdo --host=hosts.raku

```

# DSL

Sparrow6 DSL provides high level functions to manage configurations.

Just create a file named `sparrowdo` in current working directory and add few functions:

```
$ cat sparrowfile

user 'zookeeper';

group 'birds';

directory '/var/data/avifauna/greetings/', %( owner => 'zookeeper' );

file-create '/var/data/avifauna/greetings/sparrow.txt', %(
  owner => 'zookeeper',
  group => 'birds',
  mode  => '0644',
  content => 'I am little but I am smart'
);

service-start 'nginx';

package-install ('nano', 'ncdu', 'mc' );

```

The full list of function is available at [Sparrow6 DSL](https://github.com/melezhik/Sparrow6/blob/master/documentation/dsl.md)
documentation.

If DSL is not enough you can call any Sparrow6 plugin using `task-run` function:

```
task-run "show me your secrets", "azure-kv-show", %(
  kv      => "Stash" # key vault name
  secret  => ( "password", "login" ) # secret names
)

```

## DSL vs `task-run` function

DSL is high level adapter with addition of some "syntax sugar" to make a code concise and readable.

DSL functions are Raku functions, you take advantage of input parameters validation.

However DSL is limited. Not every Sparrow6 plugin has related DSL function.

Once we've found some Sparrow6 plugin common enough we add a proper DSL wrapper for it.

In case you need more DSL wrappers let us know!

# Sparrowdo workflow

```
  ====================                                   ====================
  |                  |  --- [ Bootstrap ]                |                  | LocalHost
  |    MasterHost    |  --- [ Sparrowdo Scenario ] --->  |    TargetHost    | Docker
  |                  |               *                   |                  | Ssh
  ====================               |                   ====================
   {Sparrow6 Module}                 |                    {Sparrow6 Client}
                                      \    parameters
                                       \-----------------> [ tasks ]
                                                            ^  ^  ^
                                                           /  /  /
                                ------------              /  /  /
                               { Repository } ------------------
                                ------------          [ plugins ]
                             -------------------
                            /      |       |     \
                           /       |       |      \
                          /        |       |       \
                         /         |       |        \
                      [CPAN]   [RubyGems] [PyPi]  [raku.land]

```

## Master host

Master host is where Sparrow6 tasks "pushed" from totarget hosts.

Sparrowdo should be installed on master host:

```
$ zef install Sparrowdo

```

## Sparrowdo scenario

Sparrowdo scenario is a collection of Sparrow6 tasks executed on target host.

## Target hosts

Target hosts are configured by Sparrow6 which should be installed there as well:

```
$ zef install Sparrow6

```

## Bootstrap

Bootstrap is process of automation of Sparrow6 installation on target host:

```
$ sparrowdo --host=192.168.0.1 --bootstrap

```

Bootstrap runs under `sudo` and requires sudo privileges on target host.

## Sudo

Execution of Sparrow6 tasks on target host is made under `sudo` by default, to disable this use `no_sudo` flag:

```
$ sparrowdo --docker=brave_cat --no_sudo # We don't need sudo on docker

```

## Various types of target hosts

Once sparrowfile is created it could be run on target host.

Ssh host:

```
$ sparrowdo --host=192.168.0.1

```

Docker container:

```
$ sparrowdo --docker=old_dog

```

Localhost:

```
$ sparrowdo --localhost

```

## Repositories

Sparrowdo use Sparrow6 repository to download tasks that are executed on target hosts.

During scenario execution Sparrowdo pulls plugins from repository and runs it *with parameters*.

Plugin that gets run with parameters is a Sparrow6 task.

* Detailed explanation of Sparrow6 tasks is available at [Sparrow6 development](https://github.com/melezhik/Sparrow6/blob/master/documentation/development.md) documentation.
* Detailed explanation of Sparrow6 plugins [Sparrow6 plugins](https://github.com/melezhik/Sparrow6/blob/master/documentation/plugins.md) documentation
* Detailed explanation of Sparrow6 repositories is available at [Sparrow6 repositories](https://github.com/melezhik/Sparrow6/blob/master/documentation/repository.md) documentation.

By default local repository located at `~/repo` is used:

```
$ sparrowdo --host=192.168.0.1 #  using repo ~/repo

```

Use `--repo` flag to set repository URI. For example:

```
$ sparrowdo --repo=file:///tmp/repo --localhost # use /tmp/repo repository for local mode

$ docker run --name --name=fox -d sh -v /tmp/repo:/var/data

$ sparrowdo --repo=/var/data --docker=fox --repo=file://var/data # mount /tmp/repo to /var/data within docker instance

$ sparrowdo --repo=http://sparrow.repo # use http repository

```

Ssh mode supports synchronizing local file repositories with master and target host using scp.
It extremely useful if for some reason you can't use http based repositories:

```
# scp local repository /tmp/repo to target host
# and use it within target host

$ sparrowdo --sync=/tmp/repo --host=192.168.0.1

```

Read [Sparrow6 documentation](https://github.com/melezhik/Sparrow6/blob/master/documentation/repository.md)
to know more about Sparrow6 repositories.

# Sparrowdo files anatomy

When Sparrowdo scenario executed there are might be *related* that get *copied* to a target host,
for convenience, so that one can reliably refer to those files inside Sparrowdo scenario.

Thus Sparrowdo *project* might consists of various files and folders:

```
.
├── conf
│   └── alternative.pl6
├── config.raku
├── data
│   └── list.dat
├── files
│   └── baz.txt
├── sparrowfile
└── templates
    └── animals.tmpl

```

* `sparrowfile`

The minimal setup is just `sparrowfile` placed in the current working directory.

That file contains Sparrowdo scenario to be executed.

One may optionally define other data that make up the whole set up:

* `conf`

Directory to hold configuration files

* `config.raku`

Default configuration file, if placed in current working directory will define Sparrowdo configuration, see
also [scenarios configuration](#scenario-configuration) section, alternatively one may place configuration file to `conf` directory and
choose to run with that file:

```
$ sparrowdo --conf=conf/alternative.pl6

```

* `files`

Directory containing files, so one could write such a scenario:

```
file "/foo/bar/baz.txt", %( source => "files/baz.txt" )

```

* `templates`

The same as `files` directory, but for templates, technically `templates` and `files` as equivalent, but
named separately for logical reasons. Obviously one can populate templates using that directory:

```
template-create '/var/data/animals.txt', %(
  source => ( slurp 'templates/animals.tmpl' ),
  owner => 'zookeeper',
  group => 'animals' ,
  mode => '644',
  variables => %(
    name => 'red fox',
    language => 'English'
  ),
);

```

* `data`

The same as `files` and `templates` folder but to keep "data" files, just another folder
to separate logically different pieces of data:

```
file "/data/list.txt", %( source => "data/list.dat" )

```

# Scenario configuration

If `config.raku` file exists at the current working directory it *will be
loaded* via Raku [EVALFILE](https://docs.raku.org/routine/EVALFILE) at the *beginning* of scenario.

For example:

```
$ cat config.raku

{
  user         => 'foo',
  install-base => '/opt/foo/bar'
}

```

Later on in the scenario you may access config data via `config` function, that returns
configuration as Raku Hash object:

```
$ cat sparrowfile

my $user         = config<user>;
my $install-base = config<install-base>;

```

To refer configuration files at arbitrary location use `--conf` parameter:

```
$ sparrowdo --conf=conf/alternative.conf

```

See also [Sparrowdo files anatomy](#sparrowdo-files-anatomy) section.

# Including other Sparrowdo scenarios

Because Sparrowdo scenarios are Raku code files, you're free to include other scenarios into
"main" one using via Raku [EVALFILE](https://docs.raku.org/routine/EVALFILE) mechanism:

```
$ cat sparrowfile

EVALFILE "another-sparrowfile";

```

Including another scenario does not include related files (`data`, `files`, `templates`) into main one,
so you can only reuse Sparrowdo scenario itself, but not it's *related* files.

# Bootstrap and manual install

To ensure that target hosts has all required Sparrow6 dependencies one may choose bootstrap mechanism that
installs those dependencies on target host. This operation is carried out under `sudo`.

Bootstrap is disabled by default and should be enabled by `--bootstrap` option:

```
$ sparrowdo --host=192.168.0.1 --bootstrap

```

Be aware that all dependencies will be installed *system wide* rather then user account, because `sudo` is used.

if you don't want bootstrap target host, you can always choose to install Sparrow6 zef module
on target host, which is enough to start using Sparrowdo to manage target host:

```
$ zef install Sparrow6

```

# Run Sparrowdo on docker

Sparrowdo supports docker as target host, just refer to running docker container by name to
run Sparrowdo scenario on it:

```
$ sparrowdo --docker=running-horse

```

If you need to pull an image first and then run docker container
for this image, choose `--image` option:

```
$ sparrowdo --docker=running-horse --image=alpine:latest --bootstrap --no_sudo

```

# Run Sparrowdo on ssh hosts

This is probably one the most common use case for Sparrowdo - configuring servers by ssh:

```
$ sparrowdo --host=192.168.0.1

```

# Run Sparrowdo in local mode

In case you need to run sparrowdo on localhost use `--localhost` flag:

```
$ sparrowdo --localhost

```

# Sparrowdo cli

`sparrowdo` is Sparrowdo cli to run Sparrowdo scenarios, it accepts following arguments:

* `--host`

One of two things:

Ssh host to run Sparrowdo scenario on. Default value is `127.0.0.1`. For example:

```
  --host=192.168.0.1

```

Path to raku file with hosts configuration. For example:

```
  --host=hosts.raku

```

This will effectively runs Sparrowdo in asynchronous mode through Sparky backend.

See [Sparky integration](https://github.com/melezhik/sparrowdo/blob/master/doc/sparky-integration.md) doc.

* `--workers`

Number of asynchronous workers when run in asynchronous mode through Sparky backend

See [Sparky integration](https://github.com/melezhik/sparrowdo/blob/master/doc/sparky-integration.md) doc.

* `--watch`

Runs watcher job

See [Sparky integration](https://github.com/melezhik/sparrowdo/blob/master/doc/sparky-integration.md#watcher-jobs) doc.

* `--docker`

Name of docker container to run sparrowdo scenario on, to run docker container first
after pulling an image use `--image` option

* `--localhost`

If set, runs Sparrowdo in localhost, in that case Sparrow6 tasks get run directly without launching ssh.

* `--with_sparky`

If set, run in asynchronous mode through Sparky backend.

See [Sparky integration](https://github.com/melezhik/sparrowdo/blob/master/doc/sparky-integration.md#watcher-jobs) doc.

* `--desc`

Set a descriptive name to a build, only works when run in asynchronous mode through Sparky backend

* `--ssh_user`

If set defines ssh user when run Sparrowdo scenario over ssh, none required.

* `--ssh_port`

If set defines ssh port to use when run Sparrowdo scenario over ssh. Default value is 22.

If set, run Sparrowdo scenario on localhost, don't confuse with `--host=127.0.0.1` which
runs scenario on the machine but using ssh.

* `--repo`

Defines Sparrow6 repository `URI`, for example:

```
--repo=https://192.168.0.1 # Remote http repository

--repo=file:///var/data/repo # Local file system repository

```

If `--repo` is not set, Sparrowdo uses default local repository located at `~/repo` path.

Sparrowdo uses repository to pull plugins from, see also [Sparrowdo workflow](#sparrowdo-workflow) section.

See also [Sparrow6 Repositories](https://github.com/melezhik/Sparrow6/blob/master/documentation/repository.md)
documentation.

* `--sync`

If set synchronize local file system repository with target hosts using `scp`, it's useful if for some reasons
remote http repositories are not available or disable, so one can *automatically copy* repository from master host
to target. `--sync` parameter value should file path pointing repository directory at master host:

```
--sync=/var/data/repository

```

* `--no_index_update`

If set, don't request Sparrow6 repository update. Useful when in limited internet and using http based remote repositories.

* `--dry_run`

Runs in dry run mode. Only applies when run in asynchronous mode through a Sparky backend.

See [Sparky integration](https://github.com/melezhik/sparrowdo/blob/master/doc/sparky-integration.md) doc.

* `--tags`

Set host(s) tags, see [Sparky integration](https://github.com/melezhik/sparrowdo/blob/master/doc/sparky-integration.md) doc.

* `--color`

Enable color output. Disabled by default.

* `--verbose`

If set print additional information during Sparrowdo scenario execution.

* `--debug`

If set, runs Sparrow6 tasks in `debug` mode, giving even more information, during scenario execution.

* `--prefix`

If set, define path to be appending to local cache directory on target host, used predominantly
when running concurrent Sparrowdo scenario on one target host, for example in Sparky CI server.
None required, no default value.

# Advanced topics

[Run Sparrowdo scenarios in asynchronous mode, using Sparky backend](https://github.com/melezhik/sparrowdo/blob/master/doc/sparky-integration.md)

# Author

Alexey Melezhik

# See also

* [Sparrow6](https://github.com/melezhik/Sparrow6)

# Thanks

To God as the One Who inspires me to do my job!


## dist_zef-tony-o-Uxmal.md
# Uxmal

Analyses the an array of META6.json-ish hashes to determine the required build order and also provides a control mechanism for building as efficiently as possible.

## `depends-tree(@meta)`

Really only needs an array of `{ :name, :depends([]) }` of all of the dependencies required

## `depends-channel(%tree, $concurrency = 3)`

Returns a `Channel` you can use for flow control for whatever you're doing.

Example:

```
my %tree = depends-tree(@list-of-metas);
my $flow = depends-channel(%tree);

loop {
  if $flow.poll -> $key {
    # do something with %tree{$k}
    %tree{$k}<promise>.keep; # this is important so the controller
                             # knows it can send the next item to be
                             # built
  }
  if $flow.closed { last }
  sleep .5;
};

```

Check out `t/build-order.t:32` for a more complex example.

## `generate-dot(%tree)`

Returns a very simply graphviz dot format string that you can use to write to a file and generate a chart.

## `attempt-full-dot-gen(%tree, :$force = False)`

Will `die` if `$force ~~ False` or if `which dot` does not return the path to graphviz's `dot`.

This method attempts to generate the dot file, runs `dot -T png -o <tmp-file.png> <tmp-file.dot>` and returns the string path to the png file.


## dist_github-Mouq-TOML.md
## TOML.pm6

A WIP ~250 line TOML parser and serializer written in Perl 6.

### Synopsis

```
use TOML;

say from-toml q:/.../;
    [TOML]
    format = "simple"

    [TOML.types]
    bool = true
    strings = "true"
    dates = 1996-08-28T21:11:00Z
    arrays = [ "yep", "got 'em too" ]
    ...

```

### Testing

Tests are currently done via [toml-test](https://github.com/BurntSushi/toml-test).
To test TOML.pm6, Go must be installed. Then, install toml-test via:

```
cd
export GOPATH=$HOME/go
go get github.com/BurntSushi/toml-test

```

And then test TOML.pm6 with:

```
cd -1
$HOME/go/bin/toml-test bin/toml2json

```

### TODO

* TOML encoding
* Perl 6 test harness
* Better errors


## dist_cpan-JFORGET-Date-Calendar-Bahai.md
# NAME

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

# SYNOPSIS

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

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

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

```

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

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

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

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

```

# DESCRIPTION

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

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

# INSTALLATION

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

```

or

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

```

# AUTHOR

Jean Forget [JFORGET@cpan.org](mailto:JFORGET@cpan.org)

# COPYRIGHT AND LICENSE

Copyright 2021 Jean Forget

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


## dist_github-sylvarant-Avro.md
# perl6 Avro support

[![Build Status](https://travis-ci.org/sylvarant/Avro.svg?branch=master)](https://travis-ci.org/sylvarant/Avro) [![artistic](https://img.shields.io/badge/license-Artistic%202.0-blue.svg?style=flat)](https://opensource.org/licenses/Artistic-2.0)

Provides a native perl6 implementation of the [Avro specification](https://avro.apache.org/docs/current/spec.html).

## TODO

This is a work in progress.
Still to implement:

* : Reader schemas and resolution
* : JSON output (OPTIONAL)

## Example

The official [python example](https://avro.apache.org/docs/current/gettingstartedpython.html) can be rewritten in perl6 as follows.

```
use Avro;

my $path = "testfile";
my $avro_ex = Q<<{ "namespace": "example.avro",
 "type": "record",
 "name": "User",
 "fields": [
     {"name": "name", "type": "string"},
     {"name": "favorite_number",  "type": ["int", "null"]},
     {"name": "favorite_color", "type": ["string", "null"]}]}>>;

my $schema = parse-schema($avro_ex);
my $writer =  Avro::DataFileWriter.new(:handle($path.IO.open(:w)),:schema($schema));
$writer.append({"name" => "Alyssa","favorite_number" => 256,});
$writer.append({"name" => "Ben", "favorite_number" => 7, "favorite_color" => "red"});
$writer.close();

my $reader = Avro::DataFileReader.new(:handle($path.IO.open(:r)));
repeat {
 say $reader.read();
} until $reader.eof;
$reader.close()

```

## License

[Artistic License 2.0](http://www.perlfoundation.org/artistic_license_2_0)


## dist_zef-guifa-UserTimezone.md
# User::Timezone

**Important notice:** This module was previously known as `Intl::UserTimezone`. Its name was changed to align with similar modules. It will still be usable as `Intl::UserTimezone` until the end of 2024 to give ample time for the change to happen.

A simple Raku module for determining the user's timezone as an Olson (IANA or tz) identifier, particularly useful when formatting dates.

To use:

```
use User::Timezone;

say user-timezone;  # 'America/New_York'
                    # 'Africa/Malabo'
                    # 'Asia/Tokyo'
                    # 'Etc/GMT'

```

The returned string does *not* apply a metazone.
If you wish to show a user-facing string like, e.g., "Central European Time", you should use the appropriate functions from `Intl::DateTime` (NYI, might go into `DateTime::*`, haven't decided yet ^\_^).

## Options

The default fallback (in case detection fails) is **Etc/GMT**.
If for some reason you wish to use a different one, pass it as a positional argument in the use statement.
Note that this has *global* effects:

```
use User::Timezone 'Asia/Qyzylorda'

```

Similarly, you can *force* a certain timezone which is useful when testing out aspects of your program that may be sensitive to timezones.
To do that, include the override option.

```
use User::Timezone :override;

```

This will import two additional subroutines into your scope:

```
override-user-timezone(Str $olson-id)
clear-user-timezone-override

```

These do exactly what their names imply.
Again, be aware that their effects are global.

## Compatibility / Implementation Notes

For Mac OS and most \*nix systems, the region is accurately grabbed from `/etc/localtime` if it exists.
Currently timezones indicated by the `$TZ` environmental variable are ignored, but will eventually be supported.

For Windows, the ID should be acceptable and better than a GMT offset, but may occasionally be suboptimal.
This is because Windows uses its own custom timezone identifiers that do not have a one-to-one relationship with Olsen IDs.
The Windows timezone ID is combined with the Windows GeoID to provide a best-guess that should generally be accurate.
For example, if your Windows timezone is "Central Standard Time", and your GeoID is 244 (United States), then it will be reported as **America/Chicago** (others are possible, but there is not enough information to differentiate with **America/Indiana/Knox**, so the broadest is used).
But if your GeoID is 39 (Canada), then it will be reported as **America/Winnipeg**.

## What if it doesn't work

If there is a problem determining the timezone, the default will be `Etc/GMT`, being the most generic, although that's not really an acceptable alternative.
If it's clear that `User::Timezone` cannot determine things for your operating system, or is in some other way not returning the correct results, please file an issue on Github and let's figure out how to make it work on your system.

# Version history

* **v0.3.1**
  * Updated Windows zones data files
* **v0.3.0**
  * Changed name to `User::Timezone` and added a fallback message for older uses
  * Adjusted Mac OS detection for improved accuracy
* **v0.2**
  * Added option for a custom fallback (in case detection fails)
  * Added ability for overriding the timezone (mainly for testing purposes)
* **v0.1.1**
  * Removed test code that prevented correct Windows detection.
  * Chomped output to facilitate use in other modules.
* **v0.1**
  * Initial release with support for macOS, most \*nix machines and beta support Windows

# License

Except as indicated, this module and all its files is provided under the Artistic License 2.0.

## Except as indicated

The file `windowsZones.xml` is Copyright 2020 The Unicode Consortium, and distributed without modification in accordance with its [license/terms of use](https://www.unicode.org/copyright.html).


## dist_cpan-MATIASL-Matrix-Client.md
# Matrix::Client

A [Raku](https://raku.org) library for [Matrix](https://matrix.org).

## Installation

```
zef install Matrix::Client

```

## Usage

```
use Matrix::Client;

my $client = Matrix::Client.new(
    :home-server<https://matrix.org>,
    :device-id<matrix-client>
);

$client.login(:username<myuser>, :password<s3cr3t>);

# Check my user
say $client.whoami;  # @myuser:matrix.org

# Send a message to a random room that I'm in
my $room = $client.joined-rooms.pick;
say "Sending a message to {$room.name}";
$room.send("Hello from Raku!");

```

## Description

Matrix is an open network for secure, decentralized communication.

This module provides an interface to interact with a Matrix homeserver through
the *Client-Server API*. It's currenlty on active development but it's mostly
stable for day to day use.

Here's a not complete list of things that can be done:

* Login/logout
* Registration
* Synchronization of events/messages
* Send events
* Send messages
* Upload files to a home-server

There are many missing endpoints (you can check a complete checklist
[here](https://github.com/matiaslina/perl6-matrix-client/blob/master/endpoints.md)).
If you want to contribute with some endpoint check the
<CONTRIBUTING.md> file.

## Documentation

There's a couple of pages of documentation on the `docs/` directory. This
includes API documentation, basic usage, examples, etc.

## Author

Matías Linares [matias@deprecated.org](mailto:matias@deprecated.org) | Matrix ID: `@matias:chat.deprecated.org`


## dist_zef-antononcube-DSL-Entity-MachineLearning.md
# DSL::Entity::MachineLearning (Raku package)

Raku grammar classes for Machine Learning (ML) entities (names.)

The package does entity name recognition using regexes over a set of
hashes (dictionaries) that map entity name phrases into entity Identifiers (IDs).
The hashes are obtained from [the resource files](./resources).

In short, we say that the package has grammar-resource-based architecture.
The same architecture is used in the Domain Specific Language (DSL) entity packages [AAr3-AAr6].

**Remark:** It is assumed that the associations between entity name phrases and entity IDs
placed in the resource files are going to be changed in the future, because of classifier
systems updates, or usage feedback. This is one of the main reasons to use grammar-resource-based
architecture: subsequent package versions would have better, fuller associations.

---

## Installation

```
zef install https://github.com/antononcube/Raku-DSL-Entity-MachineLearning.git

```

---

## Usage examples

```
use DSL::Entity::MachineLearning;
use DSL::Entity::MachineLearning::ResourceAccess;

my $pCOMMAND = DSL::Entity::MachineLearning::Grammar;
$pCOMMAND.set-resources(DSL::Entity::MachineLearning::resource-access-object());

say $pCOMMAND.parse('DecisionTree', rule => 'machine-learning-entity-command');
say $pCOMMAND.parse('gradient boosted trees', rule => 'machine-learning-entity-command');
say $pCOMMAND.parse('roc curve', rule => 'machine-learning-entity-command');

```

```
# ｢DecisionTree｣
#  classifier-entity-command => ｢DecisionTree｣
#   entity-classifier-name => ｢DecisionTree｣
#    0 => ｢DecisionTree｣
#     word-value => ｢DecisionTree｣
# ｢gradient boosted trees｣
#  classifier-entity-command => ｢gradient boosted trees｣
#   entity-classifier-name => ｢gradient boosted trees｣
#    0 => ｢gradient boosted trees｣
#     word-value => ｢gradient｣
#     word-value => ｢boosted｣
#     word-value => ｢trees｣
# ｢roc curve｣
#  classifier-measurement-entity-command => ｢roc curve｣
#   entity-classifier-measurement-name => ｢roc curve｣
#    0 => ｢roc curve｣
#     word-value => ｢roc｣
#     word-value => ｢curve｣

```

---

## Command line interface

The package provide as Command Line Interface (CLI) to its functionalities:

```
> ToMachineLearningEntityCode --help
# Usage:
#   ToMachineLearningEntityCode <command> [--target=<Str>] [--user=<Str>] -- Conversion of (natural) DSL machine learning entity name into code.
#   ToMachineLearningEntityCode <target> <command> [--user=<Str>] -- Both target and command as arguments.
#
#     <command>         natural language command (DSL commands)
#     --target=<Str>    target language/system/package (defaults to 'WL-System') [default: 'WL-System']
#     --user=<Str>      user identifier (defaults to '') [default: '']
#     <target>          Programming language.

```

**Remark:** (Currently) the CLI script always returns results in JSON format.

---

## Resource files

The resource file:

1. ["ClassifierNameToEntityID\_EN.csv"](./resources/ClassifierNameToEntityID_EN.csv),
   was derived from the Mathematica function page for
   [`Classify`](https://reference.wolfram.com/language/ref/Classify.html), [WRI1].
2. ["ClassifierMeasurementNameToEntityID\_EN.csv"](./resources/ClassifierMeasurementNameToEntityID_EN.csv)
   was derived using Mathematica's built-in function
   [`ClassifierMeasurements`](https://reference.wolfram.com/language/ref/ClassifierMeasurements.html), [WRI3].
   Some additional associations were put in following [WK1].
3. ["ClassifierPropertyNameToEntityID\_EN.csv"](./resources/ClassifierPropertyNameToEntityID_EN.csv),
   was derived using Mathematica's built-in function
   [`Information`](https://reference.wolfram.com/language/ref/Information.html), [WRI4].
4. ["ROCFunctionNameToEntityID\_EN.csv"](./resources/ROCFunctionNameToEntityID_EN.csv)
   uses the names and mappings in [WK1]. (See also the related package [AAr7].)

The initial versions Bulgarian versions of the resource files with name suffix "\_BG.csv" were
derived by automatic translations of the corresponding English content.
Afterwards the Bulgarian mappings were reviewed and manually modified.

---

## References

### Articles

[WK1] Wikipedia entry, ["Receiver operating characteristic"](https://en.wikipedia.org/wiki/Receiver_operating_characteristic).

### Wolfram Language (WL) articles and functions

[WRI1] Wolfram Research (2014),
[Classify](https://reference.wolfram.com/language/ref/Classify.html),
Wolfram Language function, <https://reference.wolfram.com/language/ref/Classify.html> (updated 2021).

[WRI2] Wolfram Research, Inc.,
[Machine Learning Methods](https://reference.wolfram.com/language/guide/MachineLearningMethods.html).

[WRI3] Wolfram Research (2014),
[ClassifierMeasurements](https://reference.wolfram.com/language/ref/ClassifierMeasurements.html),
Wolfram Language function, <https://reference.wolfram.com/language/ref/ClassifierMeasurements.html> (updated 2021).

[WRI4] Wolfram Research (1988),
[Information](https://reference.wolfram.com/language/ref/Information.html),
Wolfram Language function, <https://reference.wolfram.com/language/ref/Information.html> (updated 2021).

### Repositories

[AAr1] Anton Antonov,
[DSL::English::ClassificationWorkflows Raku package](https://github.com/antononcube/Raku-DSL-English-ClassificationWorkflows),
(2020-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAr2] Anton Antonov,
[DSL::Shared Raku package](https://github.com/antononcube/Raku-DSL-Shared),
(2020),
[GitHub/antononcube](https://github.com/antononcube).

[AAr3] Anton Antonov,
[DSL::Entity::Geographics Raku package](https://github.com/antononcube/Raku-DSL-Entity-Geographics),
(2021),
[GitHub/antononcube](https://github.com/antononcube).

[AAr4] Anton Antonov,
[DSL::Entity::Jobs Raku package](https://github.com/antononcube/Raku-DSL-Entity-Jobs),
(2021),
[GitHub/antononcube](https://github.com/antononcube).

[AAr5] Anton Antonov,
[DSL::Entity::Foods Raku package](https://github.com/antononcube/Raku-DSL-Entity-Foods),
(2021),
[GitHub/antononcube](https://github.com/antononcube).

[AAr6] Anton Antonov,
[DSL::Entity::Metadata Raku package](https://github.com/antononcube/Raku-DSL-Entity-Metadata),
(2021),
[GitHub/antononcube](https://github.com/antononcube).

[AAr7] Anton Antonov,
[ML::ROCFunctions Raku package](https://github.com/antononcube/Raku-ML-ROCFunctions),
(2022),
[GitHub/antononcube](https://github.com/antononcube).