## dist_zef-averna-Shodan.md
# NAME

Shodan

# DESCRIPTION

A [raku-lang](https://raku.org/) client for [Shodan](https://www.shodan.io/), a search engine for Internet-connected devices. This client provides an interface for the [Shodan API](https://developer.shodan.io).

# SYNOPSIS

```
use Shodan;

my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

my $api-info = $shodan.api-info();

my $host = $shodan.host(ip => '8.8.8.8');

my $scan = $shodan.scan(
                           ips     => '8.8.8.8,1.1.1.1',
                           service => [[53, 'dns-udp'], [443, 'https']]
                       );

my $alert = $shodan.alert-create(
                                    name    => 'test',
                                    filters => {
                                                   ip => ['1.1.1.1', '8.8.8.8']
                                               },
                                    expires => 60
                                );

my $notifiers = $shodan.notifiers();

my $queries = $shodan.queries();

my $dns = $shodan.dns-domain(
                                domain  => 'google.com',
                                history => True,
                                type    => 'A',
                                page    => 1
                            );

my $headers = $shodan.tools-http-headers();

my $exploit = $shodan.exploit-count(query => '2011-0349');

$shodan.stream-alerts(callback => {say $_; done;});

```

## REST API METHODS

Interface for the [Shodan REST API](https://developer.shodan.io/api).

### Search Methods

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Returns all services that have been found on the given host IP.
# Params:
# ip: [Str] Host IP address.
# history (optional): [Bool] Show all history (default: False).
# minify (optional): [Bool] Only return list of ports & host info (default: False).
$shodan.host(ip => '8.8.8.8');
$shodan.host(ip => '8.8.8.8', history => True, minify => True);

# Same as .host method except only returns the total number of results.
# Params:
# query: [Str] Shodan search query.
# facets (optional): [Str] Comma-separated list of properties to get info on.
$shodan.host-count(query => 'port:22');
$shodan.host-count(query => 'port:22', facets => 'org,os');

# Search Shodan, same query syntax as website. Use facets to get summary info.
# Params:
# query: [Str] Shodan search query.
# facets (optional): [Str] Comma-separated list of properties to get info on.
# page (optional): [UInt] Page num to page through results 100 per page (default: 1).
# minify (optional): [Bool] Whether or not to truncate larger fields (default: True).
$shodan.host-search(query => 'port:22');
$shodan.host-search(query => 'port:22', facets => 'org,os', page => 2, minify => True);

# Returns a list of facets to get a breakdown of the top values for a property.
$shodan.host-search-facets();

# Returns a list of search filters that can be used in the search query.
$shodan.host-search-filters();

# Shows which filters are used by query str & what params were provided to filters.
$shodan.search-tokens(query => 'Raspbian port:22');

```

### On-Demand Scanning

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Returns a list of port numbers that the crawlers are looking for.
$shodan.ports();

# List protocols that can be used with on-demand Internet scans via Shodan.
$shodan.protocols();

# Request Shodan to crawl a network.
# Params:
# ips: [Str] A comma-separated list of IPs or netblocks (CIDR) to get crawled.
# service (optional): [Array] List services to be scanned.
$shodan.scan(ips => '8.8.8.8,1.1.1.1');
$shodan.scan(ips => '8.8.8.8,1.1.1.1', service => [[53, 'dns-udp'], [443, 'https']]);

# Request Shodan to crawl the Internet for a specific port.
# Requires enterprise account.
# Params:
# port: [UInt] Port that Shodan should crawl the Internet for.
# protocol: [Str] Name of protocol to be used to interrogate the port.
$shodan.scan-internet(port => 80, protocol => 'http');

# Returns a list of all the scans that are currently active on the account.
$shodan.scans();

# Check the progress of a previously submitted scan request.
# Possible values for the status are: SUBMITTING, QUEUE, PROCESSING, DONE
# Params:
# id: [Str] The unique scan ID that was returned by /shodan/scan.
$shodan.scan-status(id => $scan-id);

```

### Network Alerts

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Create an alert to monitor a network range.
# Params:
# name: [Str] The name to describe the network alert.
# filters: [Hash] Specifying the criteria that an alert should trigger.
# filters{ip}: [Array] List of IPs or CIDR.
# expires (optional): [UInt] Number of seconds that the alert should be active.
my $alert = $shodan.alert-create(
                                    name    => 'test',
                                    filters => {
                                                   ip => ['1.1.1.1', '8.8.8.8']
                                               },
                                    expires => 60
                                );

# Get the details for a network alert.
# Params:
# id: [Str] Alert ID.
$shodan.alert-info(id => $alert{'id'});

# Update the networks monitored in an alert.
# Params:
# id: [Str] Alert ID.
# filters: [Hash] Specifying the criteria that an alert should trigger.
# filters{ip}: [Array] List of IPs or CIDR.
$alert{'filters'}{'ip'}[0] = '8.8.4.4';
$shodan.alert-update(id => $alert{'id'}, filters => $alert{'filters'});

# Enable a trigger to get notifications when the specified trigger is met.
# Params:
# id: [Str] Alert ID.
# trigger: [Str] Comma-separated list of trigger names.
$shodan.alert-trigger-create(id => $alert{'id'}, trigger => 'new_service,vulnerable');

# Ignore the specified service when it is matched for the trigger.
# Params:
# id: [Str] Alert ID.
# trigger: [Str] Trigger name.
# service: [Str] Service specified in the format "ip:port" (ex. "1.1.1.1:80").
$shodan.alert-trigger-service-ignore(
                                        id      => $alert{'id'},
                                        trigger => 'vulnerable',
                                        service => '1.1.1.1:80'
                                    );

# Start getting notifications again for the specified trigger.
# Params:
# id: [Str] Alert ID.
# trigger: [Str] Trigger name.
# service: [Str] Service specified in the format "ip:port" (ex. "1.1.1.1:80").
$shodan.alert-trigger-service-notify(
                                        id      => $alert{'id'},
                                        trigger => 'vulnerable',
                                        service => '1.1.1.1:80'
                                    );
# Add the notifier to the alert.
# Params:
# id: [Str] Alert ID.
# notifier-id: [Str] Notifier ID.
$shodan.alert-notifier-create(id => $alert{'id'}, notifier-id => 'default');

# Remove the notifier from the alert
# Params:
# id: [Str] Alert ID.
# notifier-id: [Str] Notifier ID.
$shodan.alert-notifier-delete(id => $alert{'id'}, notifier-id => 'default');

# Disable a trigger to stop getting notifications for the specified trigger.
# Params:
# trigger: [Str] Trigger name.
# service: [Str] Service specified in the format "ip:port" (ex. "1.1.1.1:80").
$shodan.alert-trigger-delete(id => $alert{'id'}, trigger => 'new_service,vulnerable');

# Delete an alert.
# Params:
# id: [Str] Alert ID.
$shodan.alert-delete(id => $alert{'id'});

# Returns a list of all the network alerts that are active on the account.
$shodan.alerts();

# Returns a list of all the triggers that can be enabled on network alerts.
$shodan.alert-triggers();

```

### Notifiers

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Get a list of all the notifiers that the user has created.
$shodan.notifiers();

# List of available notification providers.
$shodan.notifier-providers();

# Create a new notification service for the user.
# Params:
# provider: [Str] Provider name as returned by notifier-providers.
# description: [Str] Description of the notifier.
# args: [Hash] Arguments required by the provider.
my $notifier = $shodan.notifier-create(
                                          provider    => 'email',
                                          description => 'Email notifier',
                                          args        => {to => 'jmath@shodan.io'}
                                      );
# Get information about a notifier.
# Params:
# id: [Str] Notifier ID.
$shodan.notifier(id => $notifier{'id'});

# Update the parameters of a notifier.
# Params:
# id: [Str] Notifier ID.
# args: [Hash] Arguments required by the provider.
$shodan.notifier-update(id => $notifier{'id'}, args => {to => 'e@shodan.io'});

# Remove the notification service created for the user.
# Params:
# id: [Str] Notifier ID.
$shodan.notifier-delete(id => $notifier{'id'});

```

### Directory Methods

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# List the saved search queries.
# Params:
# page (optional): [UInt] Page number to iterate over results (10 per page).
# sort (optional): [Str] Sort the list based on a property. Possible values are: votes, timestamp.
# order (optional): [Str] Whether to sort the list in ascending or descending order. Possible values are: asc, desc.
$shodan.queries();
$shodan.queries(page => 1, sort => 'timestamp', order => 'asc');

# Search the directory of saved search queries.
# Params:
# query: [Str] What to search for in the directory of saved search queries.
# page (optional): [UInt] Page number to iterate over results (10 per page).
$shodan.query-search(query => 'webcam');
$shodan.query-search(query => 'webcam', page => 1);

# List the most popular tags.
# Params:
# size (optional): [UInt] The number of tags to return (default: 10).
$shodan.query-tags();
$shodan.query-tags(size => 10);

```

### Bulk Data

Requires enterprise account.

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Get a list of available datasets.
$shodan.data();

# List the files for a dataset.
# Params:
# dataset: [Str] Name of the dataset.
$shodan.data-dataset();

```

### Manage Organization

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Get information about your organization.
$shodan.org();

# Add a Shodan user to the organization.
# Params:
# user: [Str] Username or email of the Shodan user.
# notify (optional): [Bool] Whether or not to send an email notification.
$shodan.org-member-create(user => 'averna');

# Remove a member.
# Params:
user: [Str] Username or email of the Shodan user.
$shodan.org-member-delete(user => 'averna');

```

### Account Methods

```
# Returns information about the Shodan account linked to this API key.
$shodan.account-profile();

```

### DNS Methods

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Get all the subdomains and other DNS entries for the given domain.
# Params:
# domain: [Str] Domain name to lookup; example "cnn.com".
# history (optional): [Bool] Show historical DNS data (default: False).
# type (optional): [Str] DNS type, possible values are: A, AAAA, CNAME, NS, SOA, MX, TXT.
# page (optional): [UInt] The page number to page through results 100 at a time (default: 1).
$shodan.dns-domain(domain => 'google.com');
$shodan.dns-domain(domain => 'google.com', history => True, type => 'A', page => 1);

# Look up the IP address for the provided list of hostnames.
# Params:
# hostnames: [Str] Comma-separated list of hostnames; example "google.com,bing.com".
$shodan.dns-resolve(hostnames => 'google.com');

# Look up the hostnames that have been defined for the given list of IP addresses.
# Params:
# ips: [Str] Comma-separated list of IP addresses; example "74.125.227.230,204.79.197.200".
$shodan.dns-reverse(ips => '8.8.8.8');

```

### Utility Methods

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Shows the HTTP headers that your client sends when connecting to a webserver.
$shodan.tools-http-headers();

# Get your current IP address as seen from the Internet.
$shodan.tools-myip();

```

### API Status Methods

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Returns information about the API plan belonging to the given API key.
$shodan.api-info();

```

See [Shodan::API::REST](https://github.com/averna-syd/Shodan/blob/main/README_REST_API.md) readme for more information.

## EXPLOIT API METHODS

Interface for the [Shodan Exploit API](https://developer.shodan.io/api/exploits/rest).

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Search across a variety of data sources for exploits and use facets to get summary information.
# Params:
# query: [Str] Search the database of known exploits. See https://developer.shodan.io/api/exploits/rest for list.
# facets (optional): [Str] A comma-separated list of properties to get summary info on. See https://developer.shodan.io/api/exploits/rest for list.
# page (optional): [UInt] The page number to page through results 100 at a time.
$shodan.exploit-search(query => '2011-0349');

# Search for Exploits without Results.
# Params:
# query: [Str] Search the database of known exploits. See https://developer.shodan.io/api/exploits/rest for list.
# facets (optional): [Str] A comma-separated list of properties to get summary info on. See https://developer.shodan.io/api/exploits/rest for list.
# page (optional): [UInt] The page number to page through results 100 at a time.
$shodan.exploit-count(query => '2011-0349');

```

See [Shodan::API::Exploit](https://github.com/averna-syd/Shodan/blob/main/README_EXPLOIT_API.md) readme for more information.

## STREAM API METHODS

Interface for the [Shodan Streaming API](https://developer.shodan.io/api/stream).

### Data Streams

Requires enterprise account.

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# This stream provides ALL of the data that Shodan collects.
# Params:
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-banners(callback => {say $_; done;});

# Filtered by ASN.
# Params:
# asn: [Str] Comma-separated list of ASNs; example "3303,32475".
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-asn(asn => '3303,32475', callback => {say $_; done;});

# Filtered by Country.
# Params:
# countries: [Str] Comma-separated list of countries indicated by their 2 letter code; example "DE,US".
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-countries(countries => 'DE,US', callback => {say $_; done;});

# Filtered by Ports.
# Params:
# ports: [Str] Comma-separated list of ports; example "22,443".
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-ports(ports => '22,443', callback => {say $_; done;});

# Filtered by Vulnerabilities.
# Params:
# vulns: [Str] Comma-separated list of case-insensitive vulns; example: "CVE-2017-7679,CVE-2018-15919".
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-vulns(vulns => 'CVE-2017-7679,CVE-2018-15919', callback => {say $_; done;});

# Filtered by Query
# Params:
# query: [Str] Space-separated list of key:value filters examplei: "port:22 SSH-2.0-OpenSSH_6.4"
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-custom(query => 'port:22 SSH-2.0-OpenSSH_6.4', callback => {say $_; done;});

```

### Network Alerts

```
my $shodan = Shodan.new(api-key => %*ENV{'SHODAN_API_KEY'});

# Subscribe to banners discovered on all IP ranges described in the network alerts.
# Params:
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-alerts(callback => {my $alert = $_; done;});

# Subscribe to banners discovered on the IP range defined in a specific network alert.
# Params:
# id: [Str] The unique ID of the network alert; example "OYPRB8IR9Z35AZPR".
# callback: [code] Code that's run within stream & passed stream data.
$shodan.stream-alert(id => 'ZLN92ZK9IHS22SDX', callback => {my $alert = $_; done;});

```

See [Shodan::API::Stream](https://github.com/averna-syd/Shodan/blob/main/README_STREAM_API.md) readme for more information.

## DISCLAIMER

This is an early version thus methods maybe subject to change. The author does not have access to an enterprise account. Therefore while ever effort was made to ensure enterprise method calls are correct, without adequate testing of enterprise calls the author can not be as confident when compared to method calls which can be adequately tested.

# AUTHOR

"Sarah Fuller", `<"sarah at averna . id . au">`

# COPYRIGHT AND LICENSE

Copyright 2022 Sarah Fuller

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


## dist_zef-bbkr-Metropolis.md
# Metropolis generator for [Raku](https://www.raku.org) language

[![.github/workflows/test.yml](https://github.com/bbkr/Metropolis/actions/workflows/test.yml/badge.svg)](https://github.com/bbkr/Metropolis/actions/workflows/test.yml)

[Metropolis–Hastings algorithm](https://en.wikipedia.org/wiki/Metropolis%E2%80%93Hastings_algorithm) is Markov chain Monte Carlo (MCMC) method for generating sequence of random samples from probability distribution function.

It can be used to generate naturally looking data for applications testing and presentation. For example let's assume that you have software for online marketing campaigns. And you have to generate fake traffic (100 000 site visits) that occurred after campaign started 10 days ago to record tutorial for users. It's obvious that such traffic is not constant. After campaign start traffic is low, then it quickly gains momentum, reaches interest peak and slowly fades away like this:

![Campaign traffic](/images/1.png)

`f( x ) = 2x / ( x^3 + 0.5 ), { x > 0 }` generated using awesome [Desmos calculator](https://www.desmos.com/calculator).

With this module you will be able to generate such random samples with any probability distribution function within given domain.

**Note:** This is raw and fast implementation of Metropolis–Hastings algorithm. You may need to turn few dials to get best results for your cases. If you get bad results or timeouts be sure to read [TWEAKS](#tweaks) section.

# TABLE OF CONTENTS

* [SYNOPSIS](#synopsis)
* [METHODS](#methods)
  * [new](#new)
  * [sample](#sample)
  * [graph](#graph)
* [TWEAKS](#tweaks)
* [CONTACT](#contact)

# SYNOPSIS

```
use Metropolis;

my $m = Metropolis.new(
    function => -> $x { 2* $x / ( $x ** 3 + 0.5 ) },
    domain => 0 .. 10
);

say $m.sample( ) for ^42;

```

# METHODS

## new

Params:

* `function` (mandatory) - probability distribution function, must accept exactly one positional argument.
* `domain` (mandatory) - range within which samples should be generated.
* `jumper` (optional) - function that will return new sample from given jumping distribution. Check [TWEAKS](#tweaks) section for more info.

## sample

Params:

* `timeout` (optional) - how long can algorithm look for next sample, no timeout by default.

Get next sample value of `Num` type. `Nil` will be returned in case of timeout.

## graph

Params:

* `samples` (mandatory) - how many samples should be gathered.
* `scale` (optional) - how high `y` axis should be, `100` characters by default.

Crude plotting to quickly visualize requested distribution. With **swapped** axis (x is vertical, turn your monitor). All values are rounded to nearest integer. All bars are rounded to nearest 1/8. For example to display distribution from [SYNOPSIS](#synopsis):

```
my $m = Metropolis.new(
    function => -> $x { 2 * $x / ( $x ** 3 + 0.5 ) },
    domain => 0 .. 10
);

$m.graph( samples => 10000, scale => 10 );

```

```
 0 ███▋ (1622)
 1 ██████████  (4545)
 2 ████ (1800)
 3 █▊ (803)
 4 ▉ (417)
 5 ▌ (251)
 6 ▌ (208)
 7 ▎ (135)
 8 ▎ (106)
 9 ▎ (91)
10 ▏ (22)

```

Potato-grade but useful :)

# TWEAKS

**Common issues:**

* Some places have accumulation of samples way too high for requested probability distribution there.
* Algorithm is not reaching every part of the domain. Some zero probability gaps (like in `f( x ) = sin x` function) are not crossed by algorithm at all, places beyond them do not generate samples.
* Sampling is realy, really slow.

**Solutions:**

* Don't go crazy with domain width. By default algorithm is tuned to work with domain of total width `<= 10`. Remember that you get `Num` values and you can project them to bigger domain (like for example 864\_000 timestamps from the last 10 days) if needed.
* Avoid functions with zero probability gaps within domain. This algorithm can handle them to some extend. But you will get best results if probability is always positive across whole domain. Sometimes it is better to generate samples for each positive probability area separately.
* Burn samples to forget initial state. This algorithm is based on Markov chain Monte Carlo method which needs warmup to eventually converge to the desired distribution. For example throw away first 1000 samples.

**Expert:**

You can provide your own jump function with desired distribution. By default [normal distribution](https://en.wikipedia.org/wiki/Normal_distribution) with `standard-deviation = 2` is used. [Uniform distribution](https://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29) is also provided with default `delta = 3`.

To use prebuilt and/or change its default:

```
my $m = Metropolis.new(
    ...,

    # let's jump bigger zero probability gaps!
    jumper => &uniform-distribution.assuming( delta => 15 )
);

```

To provide own:

```
my $m = Metropolis.new(
    ...,

    # discrete decrease of longer jump distance probability
    jumper => sub ( :$mean ) { # mean is current sample position

        # roll jump distance within 0..1 range
        my $jump = rand;

        # make small jumps less probable by randomly re-rolling
        $jump max= rand if $jump < 0.5;

        # return new sampling point
        # remember output must have equal chance to go both ways!
        return $mean + (1, -1).pick * $jump;
    }
);

```


## dist_zef-patrickb-BuildToolchainRepo.md
```
=begin pod

=NAME BuildToolchainRepo

A repository of compiler build toolchains

=head1 Synopsis

use BuildToolchainRepo::Lang::CRepo;
my $c-file = "hello.c";
my $o-file = "hello.o";
my $e-name = "hello";
my $t = BuildToolchainRepo::Lang::CRepo::get-toolchain().new;

my $cexit = $t.compile($c-file, $o-file);
my ($lexit, $e-file) = $t.link-executable(@$o-file, $dir, $e-name);

my $p = run $e-file;

=head1 Description

This module aims to provide a lightweight interface to build toolchains or in
other words: provide an easy way to build your C (or some other lang) code.

=head1 Compiling

Compilers can be searched automatically via C.
To directly use a specific compiler, just instanciate a C
class directly.

Such C toolchain objects provide a set of variables to modify their behavior
and a few methods to do the actual compiling.

=begin item
C Int>

Compile a single C file to an O file. Returns the compiler exit code.
=end item

=begin item
C List>

Link one or more O files to a shared object file. C<$out-path> is the folder
where the library should be placed in. C<$lib-name> is the name (not filename)
of the library.

Returns a list with two elements: The exit code of the compiler and a full path
of the generated library. The filename will differ from the given name, as it
will have the platform specific prefix and suffix added.
=end item

=begin item
C List)>

Link one or more O files to a shared object file. C<$out-path> is the folder
where the library should be placed in. C<$lib-name> is the name (not filename)
of the library.

Returns a list with two elements: The exit code of the compiler and a full path
of the generated library. The filename will differ from the given name, as it
will have the platform specific prefix and suffix added.
=end item

=begin item
C Bool)>

Is the toolchain at hand is available on the system?
=end item

=head1 Probes

Some tooling is provided, to simplify working with feature probes.
C provides two subs:

=item C Int)>
=item C Int)>

Both take a piece of C code and a toolchain and return the exit code of the
program or compiler respectively.

To write a probe, implement a function returning an object of type C.
Probes can then be added to toolchains via C<$t.probes.push: your-probe()>.

This causes a respective preprocessor define C with value 1 to
be set for all successful probes;

=head1 Environment Variables

=head2 C_TOOLCHAIN

Set this to the name of a C toolchain, to force using that specific toolchain.

=head GCC_PATH

When using the GCC toolchain, sets the path to look for the C executable.

=AUTHOR  Patrick Böker

=head1 License

This module is distributed under the terms of the Artistic License 2.0.

=end pod

```


## dist_cpan-LEONT-Getopt-Long.md
[![Build Status](https://travis-ci.org/Leont/getopt-long6.svg?branch=master)](https://travis-ci.org/Leont/getopt-long6)

# NAME

Getopt::Long

# SYNOPSIS

```
use Getopt::Long;
get-options("length=i" => my $length, # numeric
            "file=s"   => my $file,   # string
            "verbose"  => my $verbose); # flag

use Getopt::Long;
my $options = get-options("length=i", # numeric
                          "file=s",   # string
                          "verbose"); # flag

```

or

```
use Getopt::Long;
sub MAIN(Int :$length, Str :$file, Bool :$verbose) { ... }

```

# DESCRIPTION

The Getopt::Long module implements extended getopt functions called `get-options()` and `get-options-from`, as well as automatic argument parsing for a `MAIN` sub.

This function adheres to the POSIX syntax for command line options, with GNU extensions. In general, this means that options have long names instead of single letters, and are introduced with a double dash "--". Support for bundling of command line options, as was the case with the more traditional single-letter approach, is also provided.

# Command Line Options, an Introduction

Command line operated programs traditionally take their arguments from the command line, for example filenames or other information that the program needs to know. Besides arguments, these programs often take command line *options* as well. Options are not necessary for the program to work, hence the name 'option', but are used to modify its default behaviour. For example, a program could do its job quietly, but with a suitable option it could provide verbose information about what it did.

Command line options come in several flavours. Historically, they are preceded by a single dash `-`, and consist of a single letter.

```
-l -a -c

```

Usually, these single-character options can be bundled:

```
-lac

```

Options can have values, the value is placed after the option character. Sometimes with whitespace in between, sometimes not:

```
-s 24 -s24

```

Due to the very cryptic nature of these options, another style was developed that used long names. So instead of a cryptic `-l` one could use the more descriptive `--long`. To distinguish between a bundle of single-character options and a long one, two dashes are used to precede the option name. Also, option values could be specified either like

```
--size=24

```

or

```
--size 24

```

# Getting Started with Getopt::Long

To use Getopt::Long from a Raku program, you must include the following line in your program:

```
use Getopt::Long;

```

This will load the core of the Getopt::Long module and prepare your program for using it.

## Getopt::Long as a MAIN wrapper

Getopt::Long can be used as a argument parsing MAIN wrapper, replacing the builtin argument parsing. It will by default offer a Unix-typical command line interface, but various options allow it to be more similar to Raku's ideosyncratic parsing.

It supports the following types for named and positional arguments:

* Bool
* Any
* Str
* Int
* Rat
* Num
* Real
* Numeric
* Complex
* IO::Path
* DateTime
* Date
* Version

It also supports any enum type, and any coercion type that uses any of the aforementioned types as its contraint type (e.g. `Foo(Str)`).

An explicit converter can also be set using an `is option` trait, e.g.

```
sub MAIN(Foo :$foo is option(&foo-converter)) { ... }

```

## Simple options

The most simple options are the ones that take no values. Their mere presence on the command line enables the option. Popular examples are:

```
--all --verbose --quiet --debug

```

Handling simple options is straightforward:

```
sub MAIN(Bool :$verbose, Bool :$all) { ... }

```

or:

```
get-options('verbose' => my $verbose, 'all' => my $all);

```

The call to `get-options()` parses the command line arguments that are present in `@*ARGS` and sets the option variable to the value `True` if the option did occur on the command line. Otherwise, the option variable is not touched. Setting the option value to true is often called *enabling* the option.

The option name as specified to the `get-options()` function is called the option *specification*. Later we'll see that this specification can contain more than just the option name.

`get-options()` will return a `Capture` if the command line could be processed successfully. Otherwise, it will throw an error using die().

## A little bit less simple options

Getopt::Long supports two useful variants of simple options: *negatable* options and *incremental* options.

A negatable option is specified with an exclamation mark `!` after the option name or a default value for `MAIN` argument:

```
sub MAIN(Bool :$verbose = False) { ... }

```

or:

```
get-options('verbose!' => my $verbose);

```

or:

```
my $options = get-options('verbose!');

```

Now, using `--verbose` on the command line will enable `$verbose`, as expected. But it is also allowed to use `--noverbose` or `--no-verbose`, which will disable `$verbose` by setting its value to `False`.

An incremental option is specified with a plus `+` after the option name:

```
sub MAIN(Int :$verbose is option('+')) { ... }

```

or:

```
get-options('verbose+' => my $verbose);

```

or

```
my $options = get-options('verbose+');

```

Using `--verbose` on the command line will increment the value of `$verbose`. This way the program can keep track of how many times the option occurred on the command line. For example, each occurrence of `--verbose` could increase the verbosity level of the program.

## Mixing command line option with other arguments

Usually programs take command line options as well as other arguments, for example, file names. It is good practice to always specify the options first, and the other arguments last. Getopt::Long will, however, allow the options and arguments to be mixed and 'filter out' all the options before passing the rest of the arguments to the program. To stop Getopt::Long from processing further arguments, insert a double dash `--` on the command line:

```
--size 24 -- --all

```

In this example, `--all` will *not* be treated as an option, but passed to the program unharmed, in `@*ARGS`.

## Options with values

For options that take values it must be specified whether the option value is required or not, and what kind of value the option expects.

Three kinds of values are supported: integer numbers, floating point numbers, and strings.

If the option value is required, Getopt::Long will take the command line argument that follows the option and assign this to the option variable. If, however, the option value is specified as optional, this will only be done if that value does not look like a valid command line option itself.

```
sub MAIN(Str :$tag) { ... }

```

or

```
get-options('tag=s' => my $tag);

```

or my %options = get-options('tag=s');

In the option specification, the option name is followed by an equals sign `=` and the letter `s`. The equals sign indicates that this option requires a value. The letter `s` indicates that this value is an arbitrary string. Other possible value types are `i` for integer values, and `f` for floating point values. Using a colon `:` instead of the equals sign indicates that the option value is optional. In this case, if no suitable value is supplied, string valued options get an empty string `''` assigned, while numeric options are set to `0`.

## Options with multiple values

Options sometimes take several values. For example, a program could use multiple directories to search for library files:

```
--library lib/stdlib --library lib/extlib

```

You can specify that the option can have multiple values by adding a "@" to the format, or declare the argument as positional:

```
sub MAIN(Str :@library) { ... }

```

or

```
get-options('library=s@' => my @libraries);

```

or

```
my $options = get-options('library=s@');

```

Used with the example above, `@libraries`/`$options<library>` would contain two strings upon completion: `"lib/stdlib"` and `"lib/extlib"`, in that order. It is also possible to specify that only integer or floating point numbers are acceptable values.

Warning: What follows is an experimental feature.

Options can take multiple values at once, for example

```
--coordinates 52.2 16.4 --rgbcolor 255 255 149

```

This can be accomplished by adding a repeat specifier to the option specification. Repeat specifiers are very similar to the `{...}` repeat specifiers that can be used with regular expression patterns. For example, the above command line would be handled as follows:

```
my $options = get-options('coordinates=f{2}', 'rgbcolor=i{3}');

```

or

```
sub MAIN(Rat :@coordinates is option('f{2}'),
  Int :@rgbcolor is option('i{3}'))

get-options('coordinates=f{2}' => my @coordinates,
  'rgbcolor=i{3}' => my @rgbcolor);

```

It is also possible to specify the minimal and maximal number of arguments an option takes. `foo=s{2,4}` indicates an option that takes at least two and at most 4 arguments. `foo=s{1,}` indicates one or more values; `foo:s{,}` indicates zero or more option values.

## Options with hash values

If you specify that the option can have multiple named values by adding a "%":

```
sub MAIN(Str :%define) { ... }

```

or

```
get-options("define=s%" => my %define);

```

or

```
my $options = get-options("define=s%");

```

When used with command line options:

```
--define os=linux --define vendor=redhat

```

the hash `%defines` or `$options<define>` will contain two keys, `"os"` with value `"linux"` and `"vendor"` with value `"redhat"`. It is also possible to specify that only integer or floating point numbers are acceptable values. The keys are always taken to be strings.

## Options with multiple names

Often it is user friendly to supply alternate mnemonic names for options. For example `--height` could be an alternate name for `--length`. Alternate names can be included in the option specification, separated by vertical bar `|` characters. To implement the above example:

```
sub MAIN(:height(:$length)) { ... }

```

or

```
get-options('length|height=f' => my $length);

```

or

```
$options = get-options('length|height=f');

```

The first name is called the *primary* name, the other names are called *aliases*. When using a hash to store options, the key will always be the primary name.

Multiple alternate names are possible.

## Summary of Option Specifications

Each option specifier consists of two parts: the name specification and the argument specification.

The name specification contains the name of the option, optionally followed by a list of alternative names separated by vertical bar characters.

```
length            option name is "length"
length|size|l     name is "length", aliases are "size" and "l"

```

The argument specification is optional. If omitted, the option is considered boolean, a value of `True` will be assigned when the option is used on the command line.

The argument specification can be

* !

  The option does not take an argument and may be negated by prefixing it with "no" or "no-". E.g. `"foo!"` will allow `--foo` (a value of 1 will be assigned) as well as `--nofoo` and `--no-foo` (a value of 0 will be assigned). If the option has aliases, this applies to the aliases as well.

```
The option does not take an argument and will be incremented by 1 every time it appears on the command line. E.g. `"more+"`, when used with `--more --more --more`, will increment the value three times, resulting in a value of 3 (provided it was 0 or undefined at firs).

The `+` specifier is ignored if the option destination is not a scalar.

```

* = *type* [ *desttype* ] [ *repeat* ]

  The option requires an argument of the given type. Supported types are:

  ```
  * s

    String(`Str`). An arbitrary sequence of characters. It is valid for the argument to start with `-` or `--`.

  * i

    Integer (`Int`). This can be either an optional leading plus or minus sign, followed by a sequence of digits, or an octal string (`0o`, optionally followed by '0', '1', .. '7'), or a hexadecimal string (`0x` followed by '0' .. '9', 'a' .. 'f', case insensitive), or a binary string (`0b` followed by a series of '0' and '1').

  * r

    Rational number (`Rat`). For example `3.14`.

  * f

    Floating-pointer number (`Num`). For example `3.14`, `-6.23E24` and so on.

  * c

    Complex number (`Complex`). For example `1+2i`.

  * p

    Path (`IO::Path`). For example `foo/bar.txt`.

  * d

    An ISO-8601 formatted date and time (`DateTime`). For example `2019-12-30T01:23:45-0700`.

  * a

    A ISO-8601 formatted date (`Date`). For example `2019-12-30`.

  * v

    A Version (`Version`). For example `1.2.3`.

  ```

  The *desttype* can be `@` or `%` to specify that the option is list or a hash valued.

  The *repeat* specifies the number of values this option takes per occurrence on the command line. It has the format `{` [ *min* ] [ `,` [ *max* ] ] `}`.

  *min* denotes the minimal number of arguments. It defaults to `0`.

  *max* denotes the maximum number of arguments. It must be at least *min*. If *max* is omitted, *but the comma is not*, there is no upper bound to the number of argument values taken.
* : *type* [ *desttype* ]

  Like `=`, but designates the argument as optional. If omitted, an empty string will be assigned to string values options, and the value zero to numeric options.

  Note that if a string argument starts with `-` or `--`, it will be considered an option on itself.
* : *number* [ *desttype* ]

  Like `:i`, but if the value is omitted, the *number* will be assigned.
* : + [ *desttype* ]

  Like `:i`, but if the value is omitted, the current value for the option will be incremented.

# Advanced Possibilities

## Object oriented interface

Getopt::Long can be used in an object oriented way as well:

```
use Getopt::Long;
my $p = Getopt::Long.new-from-patterns(@options);
my $o = $p.get-options(@args) ...

```

Configuration options can be passed to the constructor as named arguments:

```
$p = Getopt::Long.new-from-patterns(@options, :!permute);

```

## Parsing options from an arbitrary array

By default, get-options parses the options that are present in the global array `@*ARGS`. A special entry `get-options-from` can be used to parse options from an arbitrary array.

```
use Getopt::Long;
$ret = get-options-from(@myargs, ...);

```

The following two calls behave identically:

```
$ret = get-options( ... );
$ret = get-options-from(@*ARGS, :overwrite, ... );

```

# Configuring Getopt::Long

`get-options` and `get-options-from` take the following named options to configure. When using Getopt::Long as a `MAIN` wrapper, you can set them using the `%*SUB-MAIN-OPTS` variable:

* auto-abbreviate (default: `False`)

  Enabling this allows option names to be abbreviated to uniqueness (e.g. `--foo` can be written as `--f` if no other option starts with an `f`).
* compat-builtin (default: `False`)

  Enable all compatibility options that make argument parsing more like the builtin argument parsing. Currently that means disabling `bundling` and `permute`, and enabling `compat-singles`, `compat-negation`, `compat-positional` and `auto-help`)
* bundling (default: `!$compat-builtin`)

  Enabling this option will allow single-character options to be bundled. To distinguish bundles from long option names, long options *must* be introduced with `--` and bundles with `-`.

  Note that, if you have options `a`, `l` and `all`, possible arguments and option settings are:

  ```
  using argument   sets option(s)
  -------------------------------
  -a, --a          a
  -l, --l          l
  -all             a, l
  --all            all

  ```
* permute (default: `!$compat-builtin`)

  Whether command line arguments are allowed to be mixed with options. Default is enabled unless `$compat-builtin` is set.

  If `permute` is enabled, this means that

  ```
  --foo arg1 --bar arg2 arg3

  ```

  is equivalent to

  ```
  --foo --bar arg1 arg2 arg3

  ```
* compat-singles (default: `$compat-builtin`)

  Enabling this will allow single letter arguments with an `=` between the letter and its argument. E.g. `-j=2` instead of `-j2`. This is for compatibility with raku's built-in argument parsing.
* compat-negation (default: `$compat-builtin`)

  Enabling this will allow one to one to use `--/foo` as an alias for `--no-foo`, for compatibility with raku's built-in argument parsing. Note that this still requires the presence of a `--no-foo` handler, typically by using the `!` modifier.
* compat-positional (default: `$compat-builtin`)

  Enabling this will turn all positional arguments into allomorphs, if possible.
* compat-space (default: `$compat-builtin`)

  By default, an option with an optional argument will take that as a separate argument unless that argument starts with `--`; e.g. `--foo bar`. If this option is enabled, no such separate arguments are allowed, and the only way to express such an argument is in the same argument: `--foo=bar`.
* auto-help (default: `$compat-builtin`)

  This adds an extra --help option, that can hook into Raku's built-in usage message generator.

# Return values and Errors

`get-options` returns a capture to indicate success, or throws an `Getopt::Long::Exception` otherwise.

# Troubleshooting

## `get-options` does not fail when an option is not supplied

That's why they're called 'options'.

## `get-options` does not split the command line correctly

The command line is not split by get-options, but by the command line interpreter (CLI). On Unix, this is the shell. On Windows, it is CMD.EXE. Other operating systems have other CLIs.

It is important to know that these CLIs may behave different when the command line contains special characters, in particular quotes or backslashes. For example, with Unix shells you can use single quotes (`'`) and double quotes (`"`) to group words together. The following alternatives are equivalent on Unix:

```
"two words"
'two words'
two\ words

```

In case of doubt, insert the following statement in front of your Perl program:

```
note @*ARGS.join('|');

```

to verify how your CLI passes the arguments to the program.

# AUTHOR

Leon Timmermans [fawaka@gmail.com](mailto:fawaka@gmail.com)


## cygwin.md
class IO::Spec::Cygwin

Platform specific operations on file and directory paths for Cygwin

```raku
class IO::Spec::Cygwin is IO::Spec::Unix { }
```

An object of this type is available via the variable `$*SPEC` if the Raku interpreter is running on `Cygwin`.

About this class and its related classes also see [`IO::Spec`](/type/IO/Spec).

# [Methods](#class_IO::Spec::Cygwin "go to top of document")[§](#Methods "direct link")

## [method abs2rel](#class_IO::Spec::Cygwin "go to top of document")[§](#method_abs2rel "direct link")

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

Returns a string that represents `$path`, but relative to `$base` path. Both `$path` and `$base` may be relative paths. `$base` defaults to `$*CWD`. Uses [`IO::Spec::Win32`](/type/IO/Spec/Win32)'s semantics.

## [method canonpath](#class_IO::Spec::Cygwin "go to top of document")[§](#method_canonpath "direct link")

```raku
method canonpath(Str() $path, :$parent --> Str:D)
```

Returns a string that is a canonical representation of `$path`. If `:$parent` is set to true, will also clean up references to parent directories. **NOTE:** the routine does not access the filesystem.

```raku
IO::Spec::Cygwin.canonpath(｢C:\foo\\..\bar\..\ber｣).say;
# OUTPUT: «C:/foo/../bar/../ber␤»

IO::Spec::Cygwin.canonpath("foo///./../bar/../ber").say;
# OUTPUT: «foo/../bar/../ber␤»

IO::Spec::Cygwin.canonpath("foo///./../bar/../ber", :parent).say;
# OUTPUT: «ber␤»
```

## [method catdir](#class_IO::Spec::Cygwin "go to top of document")[§](#method_catdir "direct link")

```raku
method catdir (*@parts --> Str:D)
```

Concatenates multiple path fragments and returns the canonical representation of the resultant path as a string. The `@parts` are [`Str`](/type/Str) objects and are allowed to contain path separators.

```raku
IO::Spec::Cygwin.catdir(<foo/bar ber raku>).say;
# OUTPUT: «foo/bar/ber/raku␤»
```

## [method catpath](#class_IO::Spec::Cygwin "go to top of document")[§](#method_catpath "direct link")

```raku
method catpath (Str:D $volume, Str:D $dir, Str:D $file --> Str:D)
```

Same as [`IO::Spec::Win32.catpath`](/type/IO/Spec/Win32#method_catpath), except will also change all backslashes to slashes at the end:

```raku
IO::Spec::Cygwin.catpath('C:', '/some/dir', 'foo.txt').say;
# OUTPUT: «C:/some/dir/foo.txt␤»

IO::Spec::Cygwin.catpath('C:', '/some/dir', '').say;
# OUTPUT: «C:/some/dir␤»

IO::Spec::Cygwin.catpath('', '/some/dir', 'foo.txt').say;
# OUTPUT: «/some/dir/foo.txt␤»

IO::Spec::Cygwin.catpath('E:', '', 'foo.txt').say;
# OUTPUT: «E:foo.txt␤»
```

## [method is-absolute](#class_IO::Spec::Cygwin "go to top of document")[§](#method_is-absolute "direct link")

```raku
method is-absolute(Str:D $path --> Bool:D)
```

Returns `True` if the `$path` starts with a slash (`"/"`) or backslash (`"\"`), even if they have combining character on them, optionally preceded by a volume:

```raku
say IO::Spec::Cygwin.is-absolute: "/foo";        # OUTPUT: «True␤»
say IO::Spec::Cygwin.is-absolute: "/\x[308]foo"; # OUTPUT: «True␤»
say IO::Spec::Cygwin.is-absolute: ｢C:\foo｣;      # OUTPUT: «True␤»
say IO::Spec::Cygwin.is-absolute: "bar";         # OUTPUT: «False␤»
```

## [method join](#class_IO::Spec::Cygwin "go to top of document")[§](#method_join "direct link")

```raku
method join(|c)
```

Same as [`IO::Spec::Win32.join`](/type/IO/Spec/Win32#method_join), except replaces backslashes with slashes in the final result.

## [method rel2abs](#class_IO::Spec::Cygwin "go to top of document")[§](#method_rel2abs "direct link")

```raku
method rel2abs(|c --> List:D)
```

Same as [`IO::Spec::Win32.rel2abs`](/type/IO/Spec/Win32#method_rel2abs), except replaces backslashes with slashes in the final result.

## [method split](#class_IO::Spec::Cygwin "go to top of document")[§](#method_split "direct link")

```raku
method split(IO::Spec::Cygwin: Cool:D $path)
```

Same as [`IO::Spec::Win32.split`](/type/IO/Spec/Win32#method_split), except it replaces backslashes with slashes in all the values of the final result.

## [method splitpath](#class_IO::Spec::Cygwin "go to top of document")[§](#method_splitpath "direct link")

```raku
method splitpath(|c --> List:D)
```

Same as [`IO::Spec::Win32.splitpath`](/type/IO/Spec/Win32#method_splitpath), except replaces backslashes with slashes in all the values of the final result.

## [method tmpdir](#class_IO::Spec::Cygwin "go to top of document")[§](#method_tmpdir "direct link")

```raku
method tmpdir(--> IO::Path:D)
```

Attempts to locate a system's temporary directory by checking several typical directories and environment variables. Uses current directory if no suitable directories are found.


## dist_zef-cro-Cro-TLS.md
# Cro::TLS 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.


## hardware.md
hardware

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Kernel#method_hardware)
for **method hardware**.

```raku
method hardware
```

Instance method returning the hardware information of the Kernel object. Dies if the hardware information could not be established.

```raku
say $*KERNEL.hardware; # OUTPUT: «x86_64␤»
```


## dist_zef-librasteve-Math-Vector.md
```
[![License: Artistic-2.0](https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg)](https://opensource.org/licenses/Artistic-2.0)

#Math::Vector

This is a fork of https://github.com/colomon/Math-Vector from v0.6.0

# SYNOPSIS

```raku
#!/usr/bin/env raku
use Math::Vector;

my $v1 = Math::Vector.new(1, 2, 3);
my $v2 = Math::Vector.new(3, 4, 0);

say "My vector $v1 has {$v1.dim} dimensions";     #^(1, 2, 3)

say ~ ($v1 + $v2);         #^(4, 6, 3)
say ~ ($v1 * 2);           #^(2, 4, 6)
say ~ ($v1 ⋅ $v2);         #11
say ~ ($v1 × $v2);         #^(-12, 9, -2)
say ~ (⎡$v1⎤);             #3.7416573867739413
say ~ (-$v1);              #^(-1, -2, -3)
say ~ ($v1 cmp $v2);       #Less
```

```


## dist_zef-jonathanstowe-Printing-Jdf.md
# Printing::Jdf

This is a module for parsing Adobe Job Definition Format files that use Kodak's
SSi extensions.

![Build Status](https://github.com/jonathanstowe/raku-jdf/workflows/CI/badge.svg)

## Example

```
my $xml = slurp('/path/to/file.jdf');
my $jdf = Printing::Jdf.new($xml);

```

See the [imposition](examples/imposition) script for an example of using
this module to list the templates, adjustments and page details from a
JDF file.

## Documentation

### Printing::Jdf

#### .Auditpool

Returns a Printing::Jdf::AuditPool object for the provided JDF file

#### .ResourcePool

Returns a Printing::Jdf::ResourcePool object for the provided JDF file

#### ::mm (Str, Int, Rat) --> Int

Converts Pts to Millimetres, rounded to the closest millimetre

### Printing::Jdf::AuditPool

#### .Created

Returns a Hash with the following keys:

```
<Str>   AgentName => the name of the generator used to create the JDF file
<Str>   AgentVersion => the version of the generator
<DateTime> TimeStamp => object representing the date the file was created

```

### Printing::Jdf::ResourcePool

#### .ColorantOrder

Returns a List of Strings of the names of the colours in the document

#### .Layout

Returns a Hash with the following keys:

```
<Int> Bleed => the amount of bleed used in the document, in millimetres
PageAdjustments => a Hash representing the page offsets
    Odd => odd page offsets
        <Int> X => horizontal offset
        <Int> Y => vertical offset
    Even => even page offsets
        <Int> X => horizontal offset
        <Int> Y => vertical offset
Signatures => an array of the Signatures in the document
    Each Signature is a Hash containing the following keys:
        <Str> Name => the name of the signature
        <Int> PressRun => the number of the press run
        <IO::Path> Template => an IO::Path object of the template file

```

#### .Runlist

Returns an Array of Hashes representing each page in the runlist

```
<Int> Run => the run number of the page
<Int> Page => the page number
<IO::Path> Url => a IO::Path object for the file
<Bool> Centered => a Bool that is True if the page is centered
CenterOffset => a Hash of the page offsets of a centered page
    see Layout<PageAdjustments>
Offsets => a Hash of the page offsets in millimetres
    see Layout<PageAdjustments>
Scaling => a Hash with the keys <X> and <Y> representing the scaling percentage of the page
<Bool> IsBlank => a Bool that is True if the page is blank

```

## License

This module is licensed under the terms of the ISC License.

Adobe, Kodak, Preps and Creo are trademarks of their respective owners.


## dist_zef-avuserow-Audio-TagLib.md
[![Actions Status](https://github.com/avuserow/raku-audio-taglib/workflows/test/badge.svg)](https://github.com/avuserow/raku-audio-taglib/actions)

# NAME

Audio::TagLib - Read ID3 and other audio metadata with TagLib

# SYNOPSIS

```
use Audio::TagLib;

my $taglib = Audio::TagLib.new($path);

# Abstract API - aliases for simple fields
say $taglib.title ~ " by " ~ $taglib.artist;
say "$path has no album field set" unless $taglib.album.defined;

# Raw access to all tags in the file (as a list of pairs)
.say for $taglib.propertymap.grep(*.key eq 'ALBUMARTIST' | 'ALBUM ARTIST');

```

# DESCRIPTION

Audio::TagLib provides Raku bindings to the TagLib audio metadata library, providing a fast way to read metadata from many audio file formats: mp3, m4a, ogg, flac, opus, and more. See <https://taglib.org> for more details.

# Audio::TagLib vs Audio::Taglib::Simple

This module uses the C++ interface to TagLib rather than the C bindings. This means installation requires a C++ compiler, but provides the full API rather than the "abstract only" API.

This module is newer than Simple and does not yet provide tag writing functions.

This module does not keep a taglib object open and reads everything into memory initially, meaning there is no `free` method needed (unlike Simple).

`Audio::Taglib::Simple` has a lowercase 'l' in its name, where this module uses `TagLib` (as does the official website). I thought adjusting the case was a good idea at the time.

## Audio::TagLib

### new($path, :$load-raw-id3v2)

Loads the metadata from the given file. All metadata is read at this point.

The optional `:load-raw-id3v2` flag determines whether the `raw-id3v2` list is populated. This is false by default, since the `propertymap` provides similiar information for more types of files, and it's faster to not generate this mapping.

If any errors are encountered while reading the file or parsing the tags, a Failure is returned which contains an Exception explaining the error.

### Abstract API

TagLib provides what is known as the "abstract API", which provides an easy interface to common tags without having to know the format-specific identifier for a given tag. This module provides these as attributes of `Audio::TagLib`. The following fields are available as strings (Str):

* title
* artist
* album
* comment
* genre

The following are provided as integers (Int):

* year
* track
* length - length of the file, in seconds

These attributes will be undefined if they are not present in the file.

### @.propertymap

This is a List of Pairs of all the recognized tags within the file. The exact list of recognized tags differs from file to file, but the names are largely consistent between file types. For example, this allows the ID3v2 tag `TPE2` and the MP4 tag `aART` to be recognized as `ALBUMARTIST`.

If you are looking for a tag not found in the above abstract interface, you should be able to find it here.

### Bool has-id3v2

True if the file has an ID3v2 tag. This value is defined whether or not `:load-raw-id3v2` is specified.

### @.raw-id3v2

Similar to propertymap, this is a list of native ID3v2 tags, by their short identifier (e.g. `TPE2` instead of `ALBUMARTIST`). This list is empty if there are no ID3v2 Tag, and will return a `Failure` if the `:load-raw-id3v2` flag was not provided to the constructor.

## Album Art

Album art can be extracted from most types of audio files. This module provides access to the first picture data in the file. Most files only have a single picture attached, so this is usually the album art.

* album-art-size - the size of the album art in bytes
* album-art-mime - the mime type of the album art, such as 'image/png'

The data can be retrieved by calling one of the following methods:

* get-album-art - returns the data as a Blob[uint8]
* get-album-art-raw - returns the data as a CArray (call .elems to get the size)

The raw variant is much faster if you are passing the data to another function that uses a CArray. If speed is important, consider using NativeHelpers::Blob to convert the raw variant.

Note that the mime type is stored in the file, and not determined from the image, so it may be inaccurate.

# SEE ALSO

Audio::Taglib::Simple

<https://taglib.org>

# AUTHOR

Adrian Kreher [avuserow@gmail.com](mailto:avuserow@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2021-2023 Adrian Kreher

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


## dist_zef-antononcube-Data-Translators.md
# Data::Translators

Raku package for translation of JSON specs or JSON-like data structures into other formats.

It is envisioned this package to have translators to multiple formats. For example:

* DONE HTML
* DONE JSON
* DONE R
* DONE WL
* TODO Plain text
* TODO Python
* TODO Mermaid-JS
* TODO Julia
* TODO SQL

The main motivation for making the package is to have convenient way of making tables while doing
[Literate programming](https://en.wikipedia.org/wiki/Literate_programming)
with Raku using:

* Computational Markdown documents, [AAp4]
* Jupyter notebooks, [BDp1]
* Mathematica notebooks, [AAp4]

The use of JSON came to focus, since when working Large Language Model (LLM) functions, [AAp3],
very often it is requested from LLMs to produce output in JSON format, [AA1, AA2].

The package "Data::Reshapers", [AAp1], would complement nicely "Data::Translators" and vice versa.
The package "Data::TypeSystem", [AAp2], is used for "translation decisions" and for conversions into more regular datasets.

The package "Mathematica::Serializer", [AAp5], has very similar mission --
it is for translating Raku data structures into Mathematica (aka Wolfram Language or WL) code.

In order to utilize "Data::Translators" while doing Literate programming with:

* Computational Markdown files, then use the code chunk argument `results=asis`.
* Jupyter notebooks, then use the code cell magic spec `%%html` or `%% > html`.

One can find concrete examples for:

* Computational Markdown files, in the [raw source code of this README](https://raw.githubusercontent.com/antononcube/Raku-Data-Translators/main/README.md)
* Jupyter notebooks, in the [magics examples notebook](https://github.com/bduggan/raku-jupyter-kernel/blob/master/eg/magics.ipynb) at [BDp1]

**Remark:** The provided converters are made for communication purposes, so they might not be
very performant. I have used or tested them with datasets that have less than 5000 rows.

---

## Installation

Package installations from both sources use [zef installer](https://github.com/ugexe/zef)
(which should be bundled with the "standard" Rakudo installation file.)

To install the package from [Zef ecosystem](https://raku.land/) use the shell command:

```
zef install Data::Translators

```

To install the package from the GitHub repository use the shell command:

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

```

---

## Basic usage

### Main use case

Here is a "main use case" example:

1. Get a dataset that is an array of hashes
2. Filter or sample the records
3. Make an HTML table with those records

The HTML table outputs can be used to present datasets nicely in:

* Markdown documents
* Jupyter notebooks

Here we get the Titanic dataset and sample it:

```
use Data::Reshapers;
use Data::TypeSystem;
use Data::Translators;

my $tbl = get-titanic-dataset.pick(3);

```

```
# ({id => 258, passengerAge => 40, passengerClass => 1st, passengerSex => female, passengerSurvival => survived} {id => 1211, passengerAge => 40, passengerClass => 3rd, passengerSex => male, passengerSurvival => died} {id => 1227, passengerAge => 20, passengerClass => 3rd, passengerSex => male, passengerSurvival => died})

```

Here is the corresponding dataset type:

```
deduce-type($tbl);

```

```
# Vector(Assoc(Atom((Str)), Atom((Str)), 5), 3)

```

Here is the corresponding HTML table:

```
$tbl ==> data-translation

```

| passengerClass | passengerSurvival | id | passengerAge | passengerSex |
| --- | --- | --- | --- | --- |
| 1st | survived | 258 | 40 | female |
| 3rd | died | 1211 | 40 | male |
| 3rd | died | 1227 | 20 | male |

We can specify field names and HTML table attributes:

```
$tbl ==> data-translation(field-names => <id passengerSurvival>, table-attributes => 'id="info-table" class="table table-bordered table-hover" text-align="center"');

```

| id | passengerSurvival |
| --- | --- |
| 258 | survived |
| 1211 | died |
| 1227 | died |

Here is how the transposed dataset is tabulated:

```
$tbl ==> transpose() ==> data-translation;

```

|  |  |
| --- | --- |
| id | * 258 * 1211 * 1227 |
| passengerSurvival | * survived * died * died |
| passengerClass | * 1st * 3rd * 3rd |
| passengerSex | * female * male * male |
| passengerAge | * 40 * 40 * 20 |

### From JSON strings

Here is a JSON string translation to HTML:

```
my $json1 = q:to/END/;
{
    "sample": [
        {"name": "json2html", "desc": "coverts json 2 html table format", "lang": "python"},
        {"name": "testing", "desc": "clubbing same keys of array of objects", "lang": "python"}
    ]
}
END

data-translation($json1);

```

|  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| sample | | lang | name | desc | | --- | --- | --- | | python | json2html | coverts json 2 html table format | | python | testing | clubbing same keys of array of objects | |

### Cross-tabulated data

Here is a more involved data example:

```
data-translation(cross-tabulate(get-titanic-dataset, 'passengerSex', 'passengerSurvival'))

```

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| male | |  |  | | --- | --- | | died | 682 | | survived | 161 | |
| female | |  |  | | --- | --- | | died | 127 | | survived | 339 | |

Compare the HTML table above with the following plain text table:

```
to-pretty-table(cross-tabulate(get-titanic-dataset, 'passengerSex', 'passengerSurvival'))

```

```
# +--------+----------+------+
# |        | survived | died |
# +--------+----------+------+
# | female |   339    | 127  |
# | male   |   161    | 682  |
# +--------+----------+------+

```

### Generation of R and WL code

Here is the R code version of the Titanic data sample:

```
$tbl ==> data-translation(target => 'R', field-names => <id passengerClass passengerSex passengerAge passengerSurvival>)

```

```
data.frame(`passengerClass` = c("1st", "3rd", "3rd"),
`passengerSurvival` = c("survived", "died", "died"),
`id` = c("258", "1211", "1227"),
`passengerAge` = c("40", "40", "20"),
`passengerSex` = c("female", "male", "male"))

```

Here is the R code version of the contingency table:

```
data-translation(cross-tabulate(get-titanic-dataset, 'passengerSex', 'passengerSurvival'), target => 'R')

```

```
list("male"=list("died"=682, "survived"=161), "female"=list("survived"=339, "died"=127))

```

Here is the WL code version of the contingency table:

```
data-translation(cross-tabulate(get-titanic-dataset, 'passengerSex', 'passengerSurvival'), target => 'WL')

```

```
Association["female"->Association["survived"->339, "died"->127], "male"->Association["survived"->161, "died"->682]]

```

### Nicer datasets

In order to obtain datasets or more regular datasets the function `to-dataset` can be used.
Here a rugged dataset is made regular and converted to an HTML table:

```
my @tbl2 = get-titanic-dataset.pick(6);
@tbl2 = @tbl2.map({ $_.pick((1..5).pick).Hash });
@tbl2 ==> to-dataset(missing-value=>'・') ==> data-translation

```

| passengerClass | passengerAge | passengerSurvival | passengerSex | id |
| --- | --- | --- | --- | --- |
| 3rd | 30 | survived | ・ | 881 |
| 3rd | 10 | survived | female | 1258 |
| 2nd | ・ | ・ | ・ | ・ |
| 3rd | 10 | died | female | 808 |
| ・ | ・ | ・ | male | ・ |
| 1st | 20 | survived | female | ・ |

Here a hash is transformed into dataset with columns `<Key Value>` and then converted into an HTML table:

```
{ 4 => 'a', 5 => 'b', 8 => 'c'} ==> to-dataset() ==> data-translation

```

| Value | Key |
| --- | --- |
| c | 8 |
| b | 5 |
| a | 4 |

---

## Implementation notes

* The "need" for this package became evident while working on the notebooks/articles [AA1, AA2].
* Initially, I translated plain text tables into HTML.
  * Using LLMs or `md-interpret` provided by "Markdown::Grammar".
* I considered re-using the code behind `to-pretty-table` provided by "Data::Reshapers", [AAp1].
  * This is "too much work" and I wanted a lighter weight package.
* Having a solution for the more general problem ***translating JSON to HTML*** seemed a much better and easier option.
  * For example, I hoped that someone has already solved that problem for Raku.
* Since I did not find Raku packages for the translation I wanted, I looked for solutions into the Python ecosystem.
  * ... And found ["json2html"](https://github.com/softvar/json2html).
* Using ChatGPT-4.0 I translated the only class of that package from Python into Raku.
* The obtained translation could be executed with relatively minor changes.
  * I further refactored and enhanced the HTML translator to fit my most frequent Raku workflows.
* The ingestion of JSON strings is done with the package ["JSON::Fast"](https://raku.land/cpan:TIMOTIMO/JSON::Fast).
  * Hence the conversion *to* JSON "comes for free" using `to-json` from that package.
* The initial versions of the package did not have the "umbrella" function `data-translation`.
  * Only the "lower level" functions `json-to-html` and `json-to-r` were provided.
* The "lower level" functions, or shortcuts, can be used: `to-html`, `to-r`, `to-wl`.

---

## CLI

The package provides a Command Line Interface (CLI) script. Here is its usage message:

```
data-translation --help

```

```
# Usage:
#   data-translation <data> [-t|--target=<Str>] [--encode] [--escape] [--field-names=<Str>] -- Convert data into another format.
#
#     <data>                 Data to convert.
#     -t|--target=<Str>      Target to convert to, one of <JSON HTML R>. [default: 'HTML']
#     --encode               Whether to encode or not. [default: False]
#     --escape               Whether to escape or not. [default: False]
#     --field-names=<Str>    Field names to use for Map objects, separated with ';'. [default: '']

```

Here is an example application (to [this file](./resources/professionals.json)):

```
data-translation ./resources/professionals.json --field-names='data;id;name;age;profession'

```

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| data | | id | name | age | profession | | --- | --- | --- | --- | | 1 | Alice | 25 | Engineer | | 2 | Bob | 30 | Doctor | | 3 | Charlie | 28 | Artist | | 4 | Diana | 32 | Teacher | |

---

## References

### Articles

[AA1] Anton Antonov,
["Workflows with LLM functions"](https://rakuforprediction.wordpress.com/2023/08/01/workflows-with-llm-functions/),
(2023),
[RakuForPrediction at WordPress](https://rakuforprediction.wordpress.com).

[AA2] Anton Antonov,
["TLDR LLM solutions for software manuals"](https://rakuforprediction.wordpress.com/2023/08/15/tldr-llm-solutions-for-software-manuals/),
(2023),
[RakuForPrediction at WordPress](https://rakuforprediction.wordpress.com).

### Packages

[AAp1] Anton Antonov,
[Data::Reshapers Raku package](https://github.com/antononcube/Raku-Data-Reshapers),
(2021-2023),
[GitHub/antononcube](https://github.com/antononcube).

[AAp2] Anton Antonov,
[Data::TypeSystem Raku package](https://github.com/antononcube/Raku-Data-TypeSystem),
(2023),
[GitHub/antononcube](https://github.com/antononcube).

[AAp3] Anton Antonov,
[LLM::Functions Raku package](https://github.com/antononcube/Raku-LLM-Functions),
(2023),
[GitHub/antononcube](https://github.com/antononcube).

[AAp4] Anton Antonov,
[Text::CodeProcessing Raku package](https://github.com/antononcube/Raku-Text-CodeProcessing),
(2021-2023),
[GitHub/antononcube](https://github.com/antononcube).

[AAp5] Anton Antonov,
[Mathematica::Serializer Raku package](https://github.com/antononcube/Raku-Mathematica-Serializer),
(2021-2022),
[GitHub/antononcube](https://github.com/antononcube).

[BDp1] Brian Duggan,
[Jupyter:Kernel Raku package](https://github.com/bduggan/raku-jupyter-kernel),
(2017-2023),
[GitHub/bduggan](https://github.com/bduggan).

[VMp1] Varun Malhotra,
[json2html Python package](https://github.com/softvar/json2html),
(2013-2021),
[GitHub/softvar](https://github.com/softvar).


## dist_zef-jonathanstowe-Kivuli.md
# Kivuli

Get AWS IAM role credentials in EC2

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

## Synopsis

```

# In some application running on EC2

use Kivuli;
use WebService::AWS::S3;

my $k = Kivuli.new(role-name => 'my-iam-role');
my $s3 = WebService::AWS::S3.new(secret-access-key => $k.secret-access-key, access-key-id => $k.access-key-id, security-token => $k.token, region => 'eu-west-2');

# Do something with the S3

```

## Description

This module enables access to AWS IAM role credentials from within an EC2 instance as [described here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html).

The credentials supplied ( `AWS_ACCES_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) can be used to authenticate with another AWS service that the role has been granted access to.

Because the credentials are supplied in a way that is private to the EC2 instance this is a more secure method of obtaining the credentials than, for example, putting them in a configuration file.

The `token` **must** be supplied in the headers (or as a query parameter,) for requests to the service, however some services differ as to whether it should or shouldn't be part of the
signed headers in the request - please see the documentation for the service you are implementing for details.

## Installation

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

```
 zef install Kivuli

```

Bear in mind that this will pass its tests and install outside an EC2 instance, which may be useful for example to build a Docker image to upload to AWS, but it will only work correctly on EC2.

## Support

This has some fairly specific environmental dependencies, so before raising an issue please check:

* You are running your application in an AWS EC2 instance
* That you have created the [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/WorkingWithRoles.html), given it the required permissions and associated it your EC2 instance.

Any suggestions/issues/etc can be posted to [github](https://github.com/jonathanstowe/Kivuli/issues) and I'll see what I can do.

# Licence and Copyright

This is free software please see the <LICENCE> in the distribution files.

© Jonathan Stowe 2021


## dist_zef-Altai-man-Test-NoTabs.md
# Test::NoTabs

[![Build Status](https://travis-ci.org/Altai-man/perl6-Test-NoTabs.svg?branch=master)](https://travis-ci.org/Altai-man/perl6-Test-NoTabs)

This is a port of Test::NoTabs in Perl 6. It checks your Perl 6 files that can contain tabs. If it's so, test will be failed.

# Functions

`notabs-ok` takes path as a string to the file and check it for tabs absence.

`all-perl-files-ok` takes path to the directory and checks all files with extensions: `pl`, `pm`, `pl6`, `pm6`, `p6`.

# Usage example

```
use Test::NoTabs;
# Very simple.
notabs-ok("test-without-tabs");

```


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

# NAME

Math::Quaternion - Hyper-complex numbers as objects with operators

# SYNOPSIS

```
use Math::Quaternion;

```

# DESCRIPTION

This distribution implements an OO class for Quaternions, which are the simplest of the hyper-complex numbers. It adds the operators needed for basic math on the Qs, and should be a good base class for future modules to support the other hyper-complex numbers.

# RECOMMENDATIONS

I intend this module to be a high-quality example of Raku numeric OO, usable as a reference for future module authors.

# WARNINGS

This module is a mostly-from-scratch re-implementation of Quaternions; its API differs from the excellent Perl Math::Quaternion module.

# GLOSSARY

| Wikipedia | Raku | Boost | dwh | RAW |
| --- | --- | --- | --- | --- |
| a | $.r | R\_component\_1 | real | Real\_\_\_\_\_\_\_\_\_\_\_\_ part of a Q (as accessor) |
| b | $.i | R\_component\_2 | imag\_i | First\_ imaginary part of a Q (as accessor) |
| c | $.j | R\_component\_3 | imag\_j | Second imaginary part of a Q (as accessor) |
| d | $.k | R\_component\_4 | imag\_k | Third\_ imaginary part of a Q (as accessor) |
|  | .coeffs |  |  | (r, i, j, k) # List, not arrayref nor vector |
|  | .v |  |  | (i, j, k) # List, not arrayref nor vector |
|  |  |  |  | . |
| norm |  | abs | abs | sum\_of\_squares( r,i,j,k ).sqrt |
|  |  | norm | norm | sum\_of\_squares( r,i,j,k ) |
|  |  | abs(unreal) | abs\_imag | sum\_of\_squares( i,j,k ).sqrt |
|  |  | norm(unreal) | norm\_imag | sum\_of\_squares( i,j,k ) |
|  |  |  | arg | atan2( sum\_of\_squares( i,j,k ).sqrt, r ); |
| distance |  |  |  | . |
|  |  |  |  | . |
|  |  | unreal | imag | self.( 0.0, i, j, k ); |
|  |  |  | conj | self.( r, -i, -j, -k ); |
|  |  |  | operator \* | self.( r, -i, -j, -k ); |
|  |  |  | signum | absq = sum\_of\_squares( r,i,j,k ).sqrt; return ( absq == 0.0 ) ?? self !! self.new( r/absq, i/absq, j/absq, k/absq ); |
|  |  |  | sqr | self.( r\*r - i\*i - j\*j - k\*k, 2\*r\*i, 2\*r\*j, 2\*r\*k ); |
|  |  |  | inverse | self.new: (r,-i,-j,-k) / sum\_of\_squares( r,i,j,k ) |
| versor |  |  |  | self / sum\_of\_squares( r,i,j,k ).sqrt |
|  |  |  |  | . |
|  |  |  | is\_nan | r != r or i != i or j != j or k != k; |
|  |  |  | is\_inf | any(r,i,j,k) == any(PosInf,NegInf) |
|  |  |  | is\_neg\_inf | all(\_,i,j,k) == 0 and r == NEG\_INF; |
|  |  |  | is\_pos\_inf | all(\_,i,j,k) == 0 and r == POS\_INF; |
|  |  |  | is\_real\_inf | all(\_,i,j,k) == 0 and r == any(POS\_INF,NEG\_INF); |
|  | is\_real |  | is\_real | all(\_,i,j,k) == 0 |
|  | is\_zero |  | is\_zero | all(r,i,j,k) == 0 |
|  | is\_complex |  |  | all(\_,\_,j,k) == 0 |
|  | is\_imaginary |  | is\_imaginary | r == 0 |
|  |  |  |  | . |
|  |  |  | rotate | When |q| == 1 |
|  |  |  | sqrt | . |

# ACKNOWLEDGEMENTS

Thanks to:

* Jonathan Chin for the original Perl Math::Quaternion module.
* Solomon "colomon" Foster for encouraging this module's release.
* Will "Coke" Coleda for fixes to match changes in Rakudo.
* RosettaCode for the [challenge that provoked the initial code](https://rosettacode.org/wiki/Quaternion_type#Raku).

# SEE ALSO

* <http://en.wikipedia.org/wiki/Quaternion>
* <http://en.wikipedia.org/wiki/Hypercomplex_number>

# AUTHOR

Bruce Gray

# COPYRIGHT AND LICENSE

Copyright 2010 - 2017 Bruce Gray

Copyright 2024 Raku Community

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


## phasers.md
Phasers

Combined from primary sources listed below.

# [In Control flow](#___top "go to top of document")[§](#(Control_flow)_Phasers_Phasers "direct link")

See primary documentation
[in context](/language/control#Phasers)
for **Phasers**.

Blocks may have *phasers*: special labeled blocks that break their execution into phases that run in particular phases. See the page [phasers](/language/phasers) for the details.


## dist_zef-skaji-Acme-Test-Module-Zef.md
[![Actions Status](https://github.com/skaji/raku-Acme-Test-Module-Zef/workflows/test/badge.svg)](https://github.com/skaji/raku-Acme-Test-Module-Zef/actions)

# NAME

Acme::Test::Module::Zef - blah blah blah

# SYNOPSIS

```
use Acme::Test::Module::Zef;

```

# DESCRIPTION

Acme::Test::Module::Zef is ...

# AUTHOR

Shoichi Kaji [skaji@cpan.org](mailto:skaji@cpan.org)

# COPYRIGHT AND LICENSE

Copyright 2021 Shoichi Kaji

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


## dist_zef-jonathanstowe-CheckSocket.md
# CheckSocket

![Build Status](https://github.com/jonathanstowe/CheckSocket/workflows/CI/badge.svg)

A very simple Raku function to test if a TCP socket is listening on a given address or
a UNIX domain socket on the specified path

## Description

This module provides a very simple mechanism to determine whether
something is listening on a TCP socket at the given port and address,
or UNIX domain socket at a specified path. This is primarly for the
convenience of testing where there may be a dependency on an external
network service. For example:

```
 use Test;
 use CheckSocket;

 if not check-socket(80, "localhost") {
      skip-all "no web server";
     exit;
 }

# or

use Test;
use CheckSocket;

# Start some socket server concurrently
if wait-socket(80, "localhost") {
	# do some tests
}
else {
	skip-all "server didn't start in time";
}

```

## Installation

You can install directly with *zef*:

```
# From the source directory

zef install .

# Remote installation

zef install CheckSocket

```

## Support

Suggestions/patches are welcomed via github at

<https://github.com/jonathanstowe/CheckSocket/issues>

## Licence

Please see the LICENCE file in the distribution

© Jonathan Stowe 2015 - 2021


## fff-circumflex-accent.md
fff^

Combined from primary sources listed below.

# [In Operators](#___top "go to top of document")[§](#(Operators)_infix_fff^ "direct link")

See primary documentation
[in context](/language/operators#infix_fff^)
for **infix fff^**.

```raku
sub infix:<fff^>(Mu $a, Mu $b)
```

Like [fff](/routine/fff), except it does not return true for matches to the right argument.

```raku
my @list = <X A B C Y>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ fff^ /C/ for @list;  # OUTPUT: «A␤B␤»
```

For the non-sed version, see [ff^](/routine/ff$CIRCUMFLEX_ACCENT).

This operator cannot be overloaded, as it's handled specially by the compiler.


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

# NAME

Hash::Sorted - customizable role for sorted Hashes

# SYNOPSIS

```
use Hash::Sorted;

my %m is Hash::Sorted = a => 42, b => 666;  # [str,Any]

my %n is Hash::Sorted[int,str] = 42 => "a", 666 => "b";

```

# DESCRIPTION

This module provides the `Hash::Sorted` role, that allows you to create a Hash that always keeps its keys in sorted order. It also allows you to customize exactly how you would like to type your keys and/or your values.

Internally, this implementation works off two arrays that are being kept in sync, so any standard constraints available to arrays, can be applied as types for the keys or values.

Since `Hash::Sorted` is a role, you can also use it as a base for creating your own custom implementations of hashes.

# AUTHOR

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

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

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


## dist_github-ugexe-Net-HTTP.md
## Net::HTTP

Interfaces and default implementations for rolling your own http client and/or components

## Synopsis

```
use Net::HTTP::GET;
my %header   = :Connection<keep-alive>;
my $response = Net::HTTP::GET("http://httpbin.org/ip", :%header);
say $response.content;

use Net::HTTP::POST;
my $body     = Buf.new("a=b&c=d&f=".ords);
my $response = Net::HTTP::POST("http://httpbin.org/post", :$body);
say $response.content;

```

## How do I...?

#### Use a proxy

Simply add a proxy method to your client or transport object. For instance, to simply return a url
from a string you could do:

```
my $transport = Net::HTTP::Transport.new;
$transport does role {
    method proxy { ::('Net::HTTP::URL').new("http://proxy-lord.org") }
}

```

But you could also implement rotating proxies, proxy from `$*ENV`, etc

## Client Implementations

#### Net::HTTP::GET

```
my $response = Net::HTTP::GET("http://httpbin.org/ip");

```

Simple access to the http `GET` client api.

#### Net::HTTP::POST

```
my $body = Buf.new("a=1&b=2".ords);
my $response = Net::HTTP::POST("http://httpbin.org/post", :$body);

```

Simple access to the http `POST` client api (Still lacking anything beyond basic functionality)

#### Net::HTTP::Transport

```
    my $url = Net::HTTP::URL.new($abs-url);
    my $req = Net::HTTP::Request.new(:$url, :method<GET>, :User-Agent<raku-net-http>);
    my $transport = Net::HTTP::Transport.new;
    my $response  = $transport.round-trip($req);

```

A high level round-robin implementation that attempts connection caching and is thread safe.
For a user-agent level implementation that handles cookies, redirects, auth, etc then use
a `Net::HTTP::Client`. Can provide an alternative `Response` object as an argument.

```
> use HTTP::SomethingElse::Response;
> my \ALTRESPONSE = HTTP::SomethingElse::Response;
> my $response    = $transport.round-trip($req, ALTRESPONSE);

```

#### Net::HTTP::Client

```
# NYI

```

Highest level of http client implementation.

## Interface Default Implementations

Most `Net::HTTP` components can be swapped out for generic alternatives. `Net::HTTP` provides a set of interfaces (see: [Net::HTTP::Interfaces](https://github.com/ugexe/Raku-Net--HTTP/blob/main/lib/Net/HTTP/Interfaces.rakumod) and the other included classes in `Net::HTTP` can be viewed as `default` implementations.

#### Net::HTTP::URL

```
my $url = Net::HTTP::URL.new("http://google.com/");

```

Create a `url` object to provide an api to the url parts, such as *scheme*, *host*, and *port*.

```
> say ~$url
http://google.com/
> say $url.host;
google.com

```

#### Net::HTTP::Request

```
my $url     = Net::HTTP::URL.new("http://google.com/");
my $request = Net::HTTP::Request.new(:$url, :method<GET>, header => :Host<google.com>);

```

Create a `Request` object which provides an api to generating an over-the-wire or human readable representation
of an http request. `.raw` gives a binary representation, and `.Str` gives a utf8 encoded version.

```
> my $socket = IO::Socket::INET.new(:host<google.com>, :port(80));
> $socket.write($request.raw)

```

#### Net::HTTP::Response

```
my $response-from-args = Net::HTTP::Response.new(:$status-line, :%header, :$body);
my $response-from-buf  = Net::HTTP::Response.new($response-as-buf);

```

Creates a `Response` object that provides an api to parsing an http response. It can be created with named arguments
representing the http message parts, or it can be given a raw `Blob`.

```
> my $data = buf8.new andthen while $socket.recv(:bin) -> d { $data ~= $d }
> my $response = Net::HTTP::Response.new($data)

```

#### Net::HTTP::Dialer

```
my $url     = Net::HTTP::URL.new("http://google.com/");
my $request = Net::HTTP::Request.new(:$url, :method<GET>, header => :Host<google.com>);
my $socket  = Net::HTTP::Dialer.new.dial($request);

```

A role for providing access to scheme appropriate socket connections.


## callframe.md
callframe

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/CallFrame#sub_callframe)
for **sub callframe**.

```raku
sub callframe(Int:D $level = 0)
```

Returns a `CallFrame` object for the given level. If no level is given, the default level is 0. Positive levels move up the frame stack and negative levels move down (into the call to `callframe` and deeper).

Returns [`Mu`](/type/Mu) if there is no call information for the given level. Negative levels may result in an exception.


## nodispatcher.md
class X::NoDispatcher

Error due to calling a dispatch command in an ineligible scope

```raku
class X::NoDispatcher is Exception { }
```

When a redispatcher like `nextsame` is called without being in the dynamic scope of a call where a redispatch is possible, an X::NoDispatcher is thrown.

For example

```raku
nextsame; # In the mainline
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::NoDispatcher: nextsame is not in the dynamic scope of a dispatcher␤»
```

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

## [method redispatcher](#class_X::NoDispatcher "go to top of document")[§](#method_redispatcher "direct link")

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

Returns the name of the redispatcher function that did not succeed.


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

# NAME

Raku port of Perl's each() built-in

# SYNOPSIS

```
use P5each;

```

# DESCRIPTION

This module tries to mimic the behaviour of the Perl's `each` built-in as closely as possible in the Raku Programming Language.

# ORIGINAL PERL 5 DOCUMENTATION

```
each HASH
each ARRAY
each EXPR
        When called on a hash in list context, returns a 2-element list
        consisting of the key and value for the next element of a hash. In
        Perl 5.12 and later only, it will also return the index and value
        for the next element of an array so that you can iterate over it;
        older Perls consider this a syntax error. When called in scalar
        context, returns only the key (not the value) in a hash, or the
        index in an array.

        Hash entries are returned in an apparently random order. The
        actual random order is specific to a given hash; the exact same
        series of operations on two hashes may result in a different order
        for each hash. Any insertion into the hash may change the order,
        as will any deletion, with the exception that the most recent key
        returned by "each" or "keys" may be deleted without changing the
        order. So long as a given hash is unmodified you may rely on
        "keys", "values" and "each" to repeatedly return the same order as
        each other. See "Algorithmic Complexity Attacks" in perlsec for
        details on why hash order is randomized. Aside from the guarantees
        provided here the exact details of Perl's hash algorithm and the
        hash traversal order are subject to change in any release of Perl.

        After "each" has returned all entries from the hash or array, the
        next call to "each" returns the empty list in list context and
        "undef" in scalar context; the next call following that one
        restarts iteration. Each hash or array has its own internal
        iterator, accessed by "each", "keys", and "values". The iterator
        is implicitly reset when "each" has reached the end as just
        described; it can be explicitly reset by calling "keys" or
        "values" on the hash or array. If you add or delete a hash's
        elements while iterating over it, the effect on the iterator is
        unspecified; for example, entries may be skipped or duplicated--so
        don't do that. Exception: It is always safe to delete the item
        most recently returned by "each()", so the following code works
        properly:

                while (($key, $value) = each %hash) {
                  print $key, "\n";
                  delete $hash{$key};   # This is safe
                }

        This prints out your environment like the printenv(1) program, but
        in a different order:

            while (($key,$value) = each %ENV) {
                print "$key=$value\n";
            }

        Starting with Perl 5.14, "each" can take a scalar EXPR, which must
        hold reference to an unblessed hash or array. The argument will be
        dereferenced automatically. This aspect of "each" is considered
        highly experimental. The exact behaviour may change in a future
        version of Perl.

            while (($key,$value) = each $hashref) { ... }

        As of Perl 5.18 you can use a bare "each" in a "while" loop, which
        will set $_ on every iteration.

            while(each %ENV) {
                print "$_=$ENV{$_}\n";
            }

        To avoid confusing would-be users of your code who are running
        earlier versions of Perl with mysterious syntax errors, put this
        sort of thing at the top of your file to signal that your code
        will work only on Perls of a recent vintage:

            use 5.012;  # so keys/values/each work on arrays
            use 5.014;  # so keys/values/each work on scalars (experimental)
            use 5.018;  # so each assigns to $_ in a lone while test

        See also "keys", "values", and "sort".

```

# PORTING CAVEATS

Using list assignments in `while` loops will not work, because the assignment will happen anyway even if an empty list is returned, so that this:

```
while (($key, $value) = each %hash) { }

```

will loop forever. There is unfortunately no way to fix this in Raku module space at the moment. But a slightly different syntax, will work as expected:

```
while each(%hash) -> ($key,$value) { }

```

Also, this will alias the values in the list, so you don't actually need to define `$key` and `$value` outside of the `while` loop to make this work.

# AUTHOR

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

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

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021 Elizabeth Mattijsen

Re-imagined from Perl as part of the CPAN Butterfly Plan.

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