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

# NAME

IO::Socket::Async::SSL - Provides an API like IO::Socket::Async, but with TLS support

# SYNOPSIS

Client:

```
use IO::Socket::Async::SSL;

my $conn = await IO::Socket::Async::SSL.connect('raku.org', 443);
$conn.print: "GET / HTTP/1.0\r\nHost: raku.org\r\n\r\n";
react {
    whenever $conn {
        .print
    }
}
$conn.close;

```

Server (assumes certificate and key files `server-crt.pem` and `server-key.pem`):

```
use IO::Socket::Async::SSL;

react {
    my %ssl-config =
      certificate-file => 'server-crt.pem',
      private-key-file => 'server-key.pem';

    whenever IO::Socket::Async::SSL.listen(
      'localhost', 4433, |%ssl-config
    ) -> $conn {
        my $req = '';
        whenever $conn {
            $req ~= $_;
            if $req.contains("\r\n\r\n") {
                say $req.lines[0];
                await $conn.print(
                  "HTTP/1.0 200 OK\r\nContent-type: text/html\r\n\r\n"
                  ~ "<strong>Hello from a Raku HTTP server</strong>\n");
                $conn.close;
            }
        }
    }
}

```

# DESCRIPTION

This module provides a secure sockets implementation with an API very much like that of the Raku built-in `IO::Socket::Async` class. For the client case, provided the standard certificate and host verification are sufficient, it is drop-in replacement. The server case only needs two extra arguments to `listen`, specifying the server key and certificate.

As with `IO::Socket::Async`, it is safe to have concurrent connections and to share them across threads.

## Client

The `connect` method on `IO::Socket::Async::SSL` is used to establish a SSL connection to a server. It requires two positional arguments, which specify the `host` and `port` to connect to. It returns a `Promise`, which will be kept with an `IO::Socket::Async::SSL` instance when the connection is established and the SSL handshake completed.

```
my $conn = await IO::Socket::Async::SSL.connect($host, $port);

```

By default, the SSL certificate will be verified, using the default set of accepted Certificate Authorities. The `Promise` returned by `connect` will be broken if verification fails.

Sometimes it is convenient to create a Certificate Authority (CA) and use it to sign certificates for internal use, for example to secure communications between a set of services on an internal network. In this case, the `ca-file` named argument can be passed to specify the certificate authority certificate file:

```
my $ca-file = '/config/ca-crt.pem';
my $conn = await IO::Socket::Async::SSL.connect(
  'user-service', 443, :$ca-file
);

```

Alternatively, a `ca-path` argument can be specified, indicating a directory where one or more certificates may be found.

It is possible to disable certificate verification by passing the `insecure` named argument a true value. As the name suggests, **this is not a secure configuration**, since there is no way for the client to be sure that it is communicating with the intended server. Therefore, it is vulnerable to man-in-the-middle attacks.

For control over the ciphers that may be used, pass the `ciphers` argument to `connect`. It should be a string in [OpenSSL cipher list format](https://www.openssl.org/docs/man1.0.2/apps/ciphers.html).

If wishing to view encrypted traffic with a tool such as Wireshark for debugging purposes, pass a filename to the `ssl-key-log-file` name argument. Session keys will be written to this log file, and Wireshark can then be configured to introspect the encrypted traffic (Preferences -> Protocols -> TLS -> (Pre-)-Master-Secret log filename). Note that this key exposure compromises the security of the session!

## Server

The `listen` method returns a `Supply` that, when tapped, will start an SSL server. The server can be shut down by closing the tap.

Whenever a connection is made to the server, the `Supply` will emit an `IO::Socket::Async::SSL` instance. The `listen` method requires two positional arguments, specifying the `host` and `port` to listen on. Two named arguments are also required, providing the `certificate-file` and `private-key-file`.

```
my %ssl-config =
  certificate-file => 'server-crt.pem',
  private-key-file => 'server-key.pem';
my $connections = IO::Socket::Async::SSL.listen(
  'localhost', 4433, |%ssl-config
);

react {
    my $listener = do whenever $connections -> $conn {
        say "Got a connection!";
        $conn.close;
    }

    whenever signal(SIGINT) {
        say "Shutting down...";
        $listener.close;
        exit;
    }
}

```

For control over the ciphers that may be used, pass the `ciphers` named argument to `connect`. It should be a string in [OpenSSL cipher list format](https://www.openssl.org/docs/man1.0.2/apps/ciphers.html).

The following boolean options are also accepted:

* `prefer-server-ciphers` - indicates that the order of the ciphers list as configured on the server should be preferred over that of the one presented by the client
* `no-compression` - disables compression
* `no-session-resumption-on-renegotiation`

## Common client and server functionality

Both the `connect` and `listen` methods take the following optional named arguments:

* `enc`, which specifies the encoding to use when the socket is used in character mode. Defaults to `utf-8`.
* `scheduler`, which specifies the scheduler to use for processing events from the underlying `IO::Socket::Async` instance. The default is `$*SCHEDULER`. There is rarely a need to change this.

The `Supply`, `print`, `write`, and `close` methods have the same semantics as in [IO::Socket::Async](https://docs.raku.org/type/IO/Socket/Async).

## Upgrading connections

Some protocols use [opportunistic TLS](https://en.wikipedia.org/wiki/Opportunistic_TLS), where the decision to use transport layer security is first negotiated using a non-encrypted protocol - provided negotiation is successful - a TLS handshake is then performed.

This functionality is provided by the `upgrade-server` and `upgrade-client` methods. Note that the socket to upgrade must be an instance of `IO::Socket::Async`. Further, it is important to **stop reading from the socket before initiating the upgrade**, which will typically entail working with the `Tap` directly, something not normally needed in `react`/`whenever` blocks.

Here is an example of using `upgrade-server`:

```
my $server = IO::Socket::Async.listen('localhost', TEST_PORT);
react whenever $server -> $plain-conn {
    my $plain-tap = do whenever $plain-conn.Supply -> $start {
        if $start eq "Psst, let's talk securely!\n" {
            # Must stop reading...
            $plain-tap.close;
            # ...so the module can take over the socket.
            my $enc-conn-handshake = IO::Socket::Async::SSL.upgrade-server(
              $plain-conn,
              private-key-file => 't/certs-and-keys/server.key',
              certificate-file => 't/certs-and-keys/server-bundle.crt'
            );
            whenever $enc-conn-handshake -> $enc-conn {
                uc-service($enc-conn);
            }
            $plain-conn.print("OK, let's talk securely!\n");
        }
        else {
            $plain-conn.print("OK, let's talk insecurely\n");
            uc-service($plain-conn);
        }
    }

    sub uc-service($conn) {
        whenever $conn -> $crypt-text {
            whenever $conn.print($crypt-text.uc) {
                $conn.close;
            }
        }
    }
}

```

Here's an example using `upgrade-client`; again, take note of the careful handling of the `Tap`:

```
my $plain-conn = await IO::Socket::Async.connect('localhost', TEST_PORT);
await $plain-conn.print("Psst, let's talk securely!\n");

react {
    my $plain-tap = do whenever $plain-conn -> $msg {
        $plain-tap.close;
        my $enc-conn-handshake = IO::Socket::Async::SSL.upgrade-client(
          $plain-conn,
          host => 'localhost',
          ca-file => 't/certs-and-keys/ca.crt'
        );
        whenever $enc-conn-handshake -> $enc-conn {
            await $enc-conn.print("hello!\n");
            whenever $enc-conn.head -> $got {
                print $got; # HELLO!
                done;
            }
        }
    }
}

```

## Method reference

## class IO::Socket::Async::SSL

An asynchronous socket with Transport Layer Security. Has an API very similar to the builtin IO::Socket::Async.

### method connect

```
method connect(
    Str(Any) $host,
    Int(Any) $port,
    :$enc = "utf8",
    :$scheduler = Code.new,
    Numeric :$version where { ... } = Code.new,
    :$ca-file,
    :$ca-path,
    :$insecure,
    :$alpn,
    Str :$ciphers,
    :$ssl-key-log-file
) returns Promise

```

Establish a TLS connection. Returns a Promise that will be kept with an IO::Socket::Async::SSL instance if the connection is successful, or broken if the connection fails.

### method upgrade-client

```
method upgrade-client(
    IO::Socket::Async:D $conn,
    :$enc = "utf8",
    Numeric :$version where { ... } = Code.new,
    :$ca-file,
    :$ca-path,
    :$insecure,
    :$alpn,
    Str :$ciphers,
    Str :$host,
    :$ssl-key-log-file
) returns Promise

```

Upgrade an existing client socket to TLS. This is useful when implementing StartTLS. It is important that the plaintext tap of the asynchronous socket's Supply is closed, so that it can be re-tapped by this module. Returns a Promise that will be kept with an IO::Socket::Async::SSL instance provided the upgrade succeeds, or broken if it fails.

### method listen

```
method listen(
    Str(Any) $host,
    Int(Any) $port,
    Int(Any) $backlog = 128,
    :$enc = "utf8",
    :$scheduler = Code.new,
    Numeric :$version where { ... } = Code.new,
    :$certificate-file,
    :$private-key-file,
    :$alpn,
    Str :$ciphers,
    :$prefer-server-ciphers,
    :$no-compression,
    :$no-session-resumption-on-renegotiation
) returns Supply

```

Open a socket on the specified host and port, and start listening for incoming TLS connections. Returns a Supply, upon which successfully established incoming TLS connections will be emitted.

### method upgrade-server

```
method upgrade-server(
    IO::Socket::Async:D $socket,
    :$enc = "utf8",
    Numeric :$version where { ... } = Code.new,
    :$certificate-file,
    :$private-key-file,
    :$alpn,
    Str :$ciphers,
    :$prefer-server-ciphers,
    :$no-compression,
    :$no-session-resumption-on-renegotiation
) returns Supply

```

Upgrade an existing server socket to TLS. This is useful when implementing StartTLS. It is important that the plaintext tap of the asynchronous socket's Supply is closed, so that it can be re-tapped by this module. Returns a Supply that will emit IO::Socket::Async::SSL instance provided the upgrade succeeds, or quit if it fails.

### method Supply

```
method Supply(
    :$bin,
    :$enc = Code.new,
    :$scheduler = Code.new
) returns Supply

```

Get a Supply of incoming data, either as a byte buffer if the :bin option is passed, or as strings otherwise. Note that strings will, in applicable encodings, be produced in NFG.

### method print

```
method print(
    Str(Any) $str,
    :$scheduler = Code.new
) returns Promise

```

Encode a string and send its bytes over the TLS connection. Returns a Promise that will be kept if the data is sent, and broken in the case of an error.

### method write

```
method write(
    Blob $b,
    :$scheduler = Code.new
) returns Mu

```

Send the bytes in the passed blob over the TLS connection. Returns a Promise that will be kept if the data is sent, and broken in the case of an error.

### method peer-host

```
method peer-host() returns Mu

```

Get the peer (remote) host

### method peer-port

```
method peer-port() returns Mu

```

Get the peer (remote) port

### method socket-host

```
method socket-host() returns Mu

```

Get the socket (local) host

### method socket-port

```
method socket-port() returns Mu

```

Get the socket (local) port

### method native-descriptor

```
method native-descriptor() returns Mu

```

Get the socket native descriptor

### method close

```
method close() returns Nil

```

Closes the connection. This will await the completion of any outstanding writes before closing.

### method supports-alpn

```
method supports-alpn() returns Bool

```

Check if ALPN support is available

## Bugs, feature requests, and contributions

Please use GitHub Issues to file bug reports and feature requests. If you wish to contribute to this module, please open a GitHub Pull Request.

Please send an email to the Raku Security Team ([security@raku.org](mailto:security@raku.org)) to report security vulnerabilities.

# AUTHOR

Jonathan Worthington

# COPYRIGHT AND LICENSE

Copyright 2017 - 2024 Jonathan Worthington

Copyright 2024 - 2025 Raku Community

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


## dist_cpan-FRITH-Archive-Libarchive.md
## Archive::Libarchive

Archive::Libarchive - OO interface to libarchive.

## Build Status

[![Actions Status](https://github.com/frithnanth/perl6-Archive-Libarchive/workflows/test/badge.svg)](https://github.com/frithnanth/perl6-Archive-Libarchive/actions)

## Example

```
use v6;

use Archive::Libarchive;
use Archive::Libarchive::Constants;

sub MAIN(:$file! where { .IO.f // die "file '$file' not found" })
{
  my Archive::Libarchive $a .= new:
      operation => LibarchiveExtract,
      file => $file,
      flags => ARCHIVE_EXTRACT_TIME +| ARCHIVE_EXTRACT_PERM +| ARCHIVE_EXTRACT_ACL +| ARCHIVE_EXTRACT_FFLAGS;
  try {
    $a.extract: sub (Archive::Libarchive::Entry $e --> Bool) { $e.pathname eq 'test2' };
    CATCH {
      say "Can't extract files: $_";
    }
  }
  $a.close;
}

```

For more examples see the `example` directory.

## Description

Archive::Libarchive provides an OO interface to libarchive using Archive::Libarchive::Raw.

As the Libarchive site (<http://www.libarchive.org/>) states, its implementation is able to:

* Read a variety of formats, including tar, pax, cpio, zip, xar, lha, ar, cab, mtree, rar, and ISO images.
* Write tar, pax, cpio, zip, xar, ar, ISO, mtree, and shar archives.
* Handle automatically archives compressed with gzip, bzip2, lzip, xz, lzma, or compress.

## Documentation

#### new(LibarchiveOp :$operation!, Any :$file?, Int :$flags?, Str :$format?, :@filters?)

Creates an Archive::Libarchive object. It takes one **mandatory** argument:
`operation`, what kind of operation will be performed.

The list of possible operations is provided by the `LibarchiveOp` enum:

* `LibarchiveRead`: open the archive to list its content.
* `LibarchiveWrite`: create a new archive. The file must not be already present.
* `LibarchiveOverwrite`: create a new archive. The file will be overwritten if present.
* `LibarchiveExtract`: extract the archive content.

When extracting one can specify some options to be applied to the newly created files. The default options are:

`ARCHIVE_EXTRACT_TIME +| ARCHIVE_EXTRACT_PERM +| ARCHIVE_EXTRACT_ACL +| ARCHIVE_EXTRACT_FFLAGS`

Those constants are defined in Archive::Libarchive::Constants, part of the Archive::Libarchive::Raw
distribution.
More details about those operation modes can be found on the libarchive site: <http://www.libarchive.org/>

If the optional argument `$file` is provided, then it will be opened; if not provided
during the initialization, the program must call the `open` method later.

If the optional `$format` argument is provided, then the object will select that specific format
while dealing with the archive.

List of possible read formats:

* 7zip
* ar
* cab
* cpio
* gnutar
* iso9660
* lha
* mtree
* rar
* raw
* tar
* warc
* xar
* zip

List of possible write formats:

* 7zip
* ar
* cpio
* gnutar
* iso9660
* mtree
* pax
* raw
* shar
* ustar
* v7tar
* warc
* xar
* zip

If the optional `@filters` parameter is provided, then the object will add those filter to the archive.
Multiple filters can be specified, so a program can manage a file.tar.gz.uu for example.
The order of the filters is significant, in order to correctly deal with such files as file.tar.uu.gz and
file.tar.gz.uu .

List of possible read filters:

* bzip2
* compress
* gzip
* grzip
* lrzip
* lz4
* lzip
* lzma
* lzop
* none
* rpm
* uu
* xz

List of possible write filters:

* b64encode
* bzip2
* compress
* grzip
* gzip
* lrzip
* lz4
* lzip
* lzma
* lzop
* none
* uuencode
* xz

##### Note

Recent versions of libarchive implement an automatic way to determine the best mix of format and filters.
If one is using a pretty recent libarchive, both $format and @filters may be omitted: the `new` method will
determine automatically the right combination of parameters.
Older versions though don't have that capability and the programmer has to define explicitly both parameters.

#### open(Str $filename!, Int :$size?, :$format?, :@filters?)

#### open(Buf $data!)

Opens an archive; the first form is used on files, while the second one is used to open an archive that
resides in memory.
The first argument is always mandatory, while the other ones might been omitted.
`$size` is the size of the internal buffer and defaults to 10240 bytes.

`Note:` this module does't apply `$*CWD` to the file name under the hood, so this will create a file in the
original directory.

```
use Archive::Libarchive;

my Archive::Libarchive $a .= new: operation => LibarchiveWrite;
chdir 'subdir';
$a.open: 'file.tar.gz', format => 'gnutar', filters => ['gzip'];
…

```

#### close

Closes the internal archive object, frees the memory and cleans up.

#### extract-opts(Int $flags?)

Sets the options for the files created when extracting files from an archive.
The default options are:

`ARCHIVE_EXTRACT_TIME +| ARCHIVE_EXTRACT_PERM +| ARCHIVE_EXTRACT_ACL +| ARCHIVE_EXTRACT_FFLAGS`

#### next-header(Archive::Libarchive::Entry:D $e! --> Bool)

When reading an archive this method fills the Entry object and returns True till it reaches the end of the archive.

The Entry object is pubblicly defined inside the Archive::Libarchive module. It's initialized this way:

`my Archive::Libarchive::Entry $e .= new;`

So a complete archive lister can be implemented in few lines:

```
use v6;
use Archive::Libarchive;

sub MAIN(Str :$file! where { .IO.f // die "file '$file' not found" })
{
  my Archive::Libarchive $a .= new: operation => LibarchiveRead, file => $file;
  my Archive::Libarchive::Entry $e .= new;
  while $a.next-header($e) {
    $e.pathname.say;
    $a.data-skip;
  }
  $a.close;
}

```

#### data-skip(--> Int)

When reading an archive this method skips file data to jump to the next header.
It returns `ARCHIVE_OK` or `ARCHIVE_EOF` (defined in Archive::Libarchive::Constants)

#### read-file-content(Archive::Libarchive::Entry $e! --> Buf)

This method reads the content of a file represented by its Entry object and returns it.

#### write-header(Str $file, Str :$pathname?, Int :$size?, Int :$filetype?, Int :$perm?, Int :$atime?, Int :$mtime?, Int :$ctime?, Int :$birthtime?, Int :$uid?, Int :$gid?, Str :$uname?, Str :$gname? --> Bool)

When creating an archive this method writes the header entry for the file being inserted into the archive.
The only mandatory argument is the file name, every other argument has a reasonable default.
If the being inserted into the archive is a symbolic link, the target will be composed as a pathname relative to the
base directory of the file, not as a full pathname.
More details can be found on the libarchive site.

Each optional argument is available as a method of the Archive::Libarchive::Entry object and it can be set when needed.

Note: `write-header` has a lot of optional arguments whose values are collected from the file one is adding to the
archive. When using the second form of `write-data` one has to provide at least these arguments:

* $size
* $atime
* $mtime
* $ctime

For example:

```
$a.write-header($filename,
                :size($buffer.bytes),
                :atime(now.Int),
                :mtime(now.Int),
                :ctime(now.Int));

```

#### write-data(Str $path --> Bool)

#### write-data(Buf $data --> Bool)

When creating an archive this method writes the data for the file being inserted into the archive.
`$path` is the pathname of the file to be archived, while `$data` is a data buffer.

#### extract(Str $destpath? --> Bool)

#### extract(&callback:(Archive::Libarchive::Entry $e --> Bool)!, Str $destpath? --> Bool)

When extracting files from an archive this method does all the dirty work.
If used in the first form it extracts all the files.
The second form takes a callback function, which receives a Archive::Libarchive::Entry object.
The callback function receives a Archive::Libarchive::Entry object.

For example, this will extract only the file whose name is `test2`:

`$a.extract: sub (Archive::Libarchive::Entry $e --> Bool) { $e.pathname eq 'test2' };`

In both cases one can specify the directory into which the files will be extracted.

#### lib-version

Returns a hash with the version number of libarchive and of each library used internally.

### Errors

When the underlying library returns an error condition, the methods will return a Failure object, which can
be trapped and the exception can be analyzed and acted upon.

The exception object has two fields: $errno and $error, and return a message stating the error number and
the associated message as delivered by libarchive.

## Prerequisites

This module requires Archive::Libarchive::Raw Raku module and the libarchive library
to be installed. Please follow the instructions below based on your platform:

### Debian Linux

```
sudo apt-get install libarchive13

```

The module looks for a library called libarchive.so, or whatever it finds in
the environment variable `PERL6_LIBARCHIVE_LIB` (provided that the library one
chooses uses the same API).

## Installation

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

```
$ zef update
$ zef install Archive::Libarchive

```

## Note

Archive::Libarchive::Raw and in turn this module rely on a C library which might not be present in one's
installation, so it's not a substitute for a pure Raku module.

This is a OO interface to the functions provided by the C library, accessible through the Archive::Libarchive::Raw
module.

## Author

Fernando Santagata

## Contributions

Many thanks to Haythem Elganiny for implementing some multi methods in the `Entry` class.

## Copyright and license

The Artistic License 2.0


## dist_cpan-KAIEPI-Failable.md
[![Build Status](https://travis-ci.org/Kaiepi/p6-Failable.svg?branch=master)](https://travis-ci.org/Kaiepi/p6-Failable)

# NAME

Failable - Failure sum type

# SYNOPSIS

```
use Failable;

sub cat(*@params --> Str:D) {
    my Proc:D $proc = run "cat", |@params, :out, :err;
    my Str:D  $out  = $proc.out.slurp(:close);
    my Str:D  $err  = $proc.err.slurp(:close);
    fail $err if $err;
    $out
}

my Failable[Str:D] $output = cat "/etc/hosts";
say $output.WHAT; # OUTPUT: (Str)

my Failable[Str:D] $error = cat '.';
say $error.WHAT; # OUTPUT: (Failure)

```

# DESCRIPTION

Failable is a class for creating Failure sum types. Parameterizing Failable creates a new subset of Failure and the parameter passed. This allows you to type variables that are declared using the return values of routines that can fail.

# AUTHOR

Ben Davies (Kaiepi)

# COPYRIGHT AND LICENSE

Copyright 2019 Ben Davies

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


## dist_zef-jjmerelo-Native-FindVersion.md
# Native::FindVersion [Test-install distro](https://github.com/JJ/raku-native-findversion/actions/workflows/test.yaml)

Tries to find all available versions of the shared libraries used in `native` modules.

## Installing

Just the usual `zef install Native::FindVersion`.

## Running

It exports a single function, `latest-version`. An example (from the test)

```
use Native::FindVersion;

constant $lib-name = "gcc_s";
my $version;
BEGIN {
    $version = latest-version($lib-name);
}

sub __addvdi3( int32 $a, int32 $b) returns int32 is native($lib-name, $version )
{*};

say __addvdi3( 3, 3 )

```

Since the version needs to be known at compile time, it needs to be assigned
during the `BEGIN` phase. You can use either the short form (`foo`) or the
long form (`libfoo`).

In this case we're using a shared library and function that can be found in
most Linux systems, `libgcc`.

For ease of use, there's a function that returns directly the `native` argument:

```
constant @native-arg = latest-version-arg("gcc_s");
sub gcc-mod( int32 $a, int32 $b)
        returns int32
        is native(@native-arg)
        is symbol("__modti3")
{*};

```

## See also

[`NativeLibs`](https://raku.land/github:salortiz/NativeLibs) includes
`NativeLib::Searcher` that will help you find a library using the symbols
found in it and a range of possible versions.

## Caveats

Untested in Windows and MacOS. If they don't append the version number to the
extension, it will not work.

## License

(c) JJ Merelo, [jj@raku.org](mailto:jj@raku.org) 2022

This module will be licensed, by default, under the Artistic 2.0 License (the same as Raku itself).


## dist_zef-kimryan-Lingua-EN-Sentence.md
NAME

Lingua::EN::Sentence - Module for splitting text into sentences.

SYNOPSIS

```
use Lingua::EN::Sentence;
add_acronyms(' Lt Gen');  ## adding support for 'Lt. Gen.'

$text = Q[First sentence with some abbreviations,  Mr. J. Smith, 2 Jones St. SomeTown Ariz. U.S.A. is an address.
Sentence 2: Sequences like ellipsis ... are handled. Sentence 3, numbered sections such as point 1. are ok.];
my @sentences = $text.sentences;
for @sentences -> $sent {
    say $sent;
}

Output is:

First sentence with some abbreviations,  Mr. J. Smith, 2 Jones St. SomeTown Ariz. U.S.A. is an address.
Sentence 2: Sequences like ellipsis ... are handled.
Sentence 3, numbered sections such as point 1. are ok.

```

DESCRIPTION

The Lingua::EN::Sentence module contains the method sentences, which splits
text into its constituent sentences, based on regular expressions, a list
of abbreviations (built in and given) and other rules.

Certain well know exceptions, such as abbreviations like Mr., Calif. and
Ave. will cause incorrect segmentations. But many of these are already
integrated into this code and are being taken care of. Note that
abbreviations are case sensitive.

The add\_acronyms method allows you to add custom abbreviations.

ALGORITHM

Before any regex processing, quotations are hidden away and inserted after
the sentences are split. That entails that no sentence splitting will be
attempted between pairs of double quotes. Common cases of full stops that
do not denote an end of sentence are also hidden. These include the dot
after abbreviations mentioned above, acronymns and ellipsis.

Basically, I use a 'brute' regular expression to split the text into
sentences. (Well, nothing is yet split - I just mark the end-of-sentence).
Then I look into a set of rules which decide when an end-of-sentence is
justified and when it's a mistake. In case of a mistake, the
end-of-sentence mark is removed.

What are such mistakes? Cases of abbreviations, for example. I have a list
of such abbreviations (Please see `Acronym/Abbreviations list' section),
and more general rules (for example, the abbreviations 'i.e.' and 'e.g.'
need not to be in the list as a special rule takes care of all single
letter abbreviations).

FUNCTIONS

$text.sentences

A very convenient extension to the Perl6 Str string type, the .sentences
method allows us to natively request the sentences in a string, similarly
to the Str "words" method.

The sentences method takes a Str variable containing the text as an
argument and returns an array of sentences that the text has been split
into.

Returned sentences will be trimmed (beginning and end of sentence) of
white-spaces.

Strings with no alpha-numeric characters in them, won't be returned as
sentences.

add\_acronyms( @acronyms )

This function is used for adding acronyms not supported by this code.
Please see `Acronym/Abbreviations list' section for the abbreviations
already supported by this module.

get\_acronyms()

This function will return the defined list of acronyms.

set\_acronyms( @my\_acronyms )

This function replaces the predefined acroynm list with the given list.

get\_EOS()

This function returns the value of the string used to mark the end of
sentence. You might want to see what it is, and to make sure your text
doesn't contain it. You can use set\_EOS() to alter the end-of-sentence
string to whatever you desire.

set\_EOS( $new\_EOS\_string )

This function alters the end-of-sentence string used to mark the end of
sentences.

Acronym/Abbreviations list

You can use the get\_acronyms() function to get acronyms. It has become too
long to specify in the documentation.

If I come across a good general-purpose list - I'll incorporate it into
this module. Feel free to suggest such lists.

Limitations

There are some valid cases cannot be detected, such as: This belongs to
John A. Smith, which will break after A. This cannot be distinguished from
a valid sequence like so said I. Next sentence. A sentence ending in an
acronym does not cause a split such as St.

AUTHOR

Deyan Ginev, 2013. Kim Ryan, 2023

Perl5 CPAN author: Shlomo Yona ([shlomo@cs.haifa.ac.il](mailto:shlomo@cs.haifa.ac.il))

Released under the same terms as Perl 6; see the LICENSE file for details.


## dist_cpan-PMQS-IO-Compress-Lzf.md
```

                            IO-Compress-Lzf

                            Version 2.094

                            13 July 2020

       Copyright (c) 2005-2020 Paul Marquess. All rights reserved.
          This program is free software; you can redistribute it
           and/or modify it under the same terms as Perl itself.

DESCRIPTION
-----------

This module provides a Perl interface to allow reading and writing of
lzf files/buffers.

PREREQUISITES
-------------

Before you can build IO-Compress-Lzf you need to have the following
installed on your system:

    * Perl 5.006 or better.
    * Compress::LZF
    * IO::Compress::Base

BUILDING THE MODULE
-------------------

Assuming you have met all the prerequisites, the module can now be built
using this sequence of commands:

    perl Makefile.PL
    make
    make test

INSTALLATION
------------

To install IO-Compress-Lzf, run the command below:

    make install

TROUBLESHOOTING
---------------

SUPPORT
-------

General feedback/questions/bug reports should be sent to
https://github.com/pmqs/IO-Compress-Lzf/issues (preferred) or
https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress-Lzf.

FEEDBACK
--------

How to report a problem with IO-Compress-Lzf.

To help me help you, I need all of the following information:

 1. The Versions of everything relevant.
    This includes:

     a. The *complete* output from running this

            perl -V

        Do not edit the output in any way.
        Note, I want you to run "perl -V" and NOT "perl -v".

        If your perl does not understand the "-V" option it is too
        old. This module needs Perl version 5.004 or better.

     b. The version of IO-Compress-Lzf you have.
        If you have successfully installed IO-Compress-Lzf, this one-liner
        will tell you:

           perl -MIO::Compress::Lzf -e 'print qq[ver $IO::Compress::Lzf::VERSION\n]'

        If you are  running windows use this

           perl -MIO::Compress::Lzf -e "print qq[ver $IO::Compress::Lzf::VERSION\n]"

        If you haven't installed IO-Compress-Lzf then search IO::Compress::Lzf.pm
        for a line like this:

          $VERSION = "2.094" ;

 2. If you are having problems building IO-Compress-Lzf, send me a
    complete log of what happened. Start by unpacking the IO-Compress-Lzf
    module into a fresh directory and keep a log of all the steps

        [edit config.in, if necessary]
        perl Makefile.PL
        make
        make test TEST_VERBOSE=1

Paul Marquess

```


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

# NAME

Shell::Command - provide cross-platform routines emulating common \*NIX shell commands

# SYNOPSIS

```
use Shell::Command;

# Recursive folder copy
cp 't/dir1', 't/dir2', :r;

# Remove a file
rm_f 'to_delete';

# Remove directory
rmdir 't/dupa/foo/bar';

# Make path
mkpath 't/dir2';

# Remove path
rm_rf 't/dir2';

# Find Raku in executable path
my $raku-path = which('raku');

# Concatenate the contents of a file or list of files and print to STDOUT
cat "file1.txt", "file2.txt";

# A cross platfrom syncronous run()
my $command = $*DISTRO.is-win ?? 'binary.exe' !! 'binary';
run-command($binary, 'some', 'parameter');

```

# AUTHOR

Tadeusz “tadzik” Sośnierz"

# COPYRIGHT AND LICENSE

Copyright 2010-2017 Tadeusz Sośnierz Copyright 2023 Raku Community

This library is free software; you can redistribute it and/or modify it under the MIT license.

Please see the LICENCE file in the distribution

# CONTRIBUTORS

* Dagur Valberg Johansson
* Elizabeth Mattijsen
* Filip Sergot
* Geoffrey Broadwell
* GlitchMr
* Heather
* Kamil Kułaga
* Moritz Lenz
* Steve Mynott
* timo
* Tobias Leich
* Tim Smith
* Ahmad M. Zawawi (azawawi @ #raku)
* Martin Barth


## dist_github-jaffa4-Ini-Storage.md
# Ini::Storage

Read/write ini files and manipulate them in memory.
Groups in function names refer to sections.
Key refers to "group/key" format.

## Usage

```
use Ini::Storage;

my $o = Ini::Storage.new("my.cfg",True); # True -> read from disk immediately if it exists.
$o.Write("g/id",7); # write section g with key id = 7

my $v = $o.Read("g/id",0); # read section g with key id... if it is not found return 0

$o.FLush; # write to disk

$o.SetDisk(False); # will not write anything to disk, even when object destructs

```

##functions
method new($filename,$isdisk)

```
method GetFilename

method SetFilename($newfn)

method Read($key,$default)

method Exchange($key,$key2)

method GetEntryName($group,$no is copy)

method Write($key,$value)

method Copy($obj)

method CountEntries($group)

method CopyGroup($obj,$group,$newgroupname?)

method DeleteEntry($key)

method RenameEntry($key,$keynew)

method DeleteEntryFromArray($key)

method GetLastArrayIndex($key)

method DeleteGroup($group)

method GroupExists($group)

method Exists($key)

method GetGroups

method GetEntriesInGroup($group)

method FindIndexInArrayByValue($group,$arrayname,$value)

method FindAValueInRecordByKey($group,$arrayname,$value,$arrayname2)

method GetArrayInGroupK($key)

method GetArrayInGroupGE($group,$name)

method SetArrayInGroup ($group,$name,@arr)

method ReadFile()

method WriteFile

method PrintGroup($group)

method SetDisk($disk)

method Flush

```


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

# NAME

**FontConverter** - Enables conversion between TrueType, OpenType, and PostScript Type 1 fonts

# SYNOPSIS

```
use FontConverter;
fc-convert-font Times-Roman.pfb # OUTPUT: «Times-Roman.ttf␤»

```

# DESCRIPTION

**FontConverter** provides tools to convert PostScript Type 1 binary font files to TrueType as well as conversion from TrueType or OpenType to PostScript Type 1. It requires the following system programs to be installed:

* fontforge (and its Python3 components, if any)

  To convert PostScript Type 1 to TrueType (X.pfb to X.ttf).

Note the conversion from PostScript to TrueType requires a Python3 script because `fontforge`'s own scripting language is broken (see its issue #5261 at <https://github.com/fontforge/fontforge>). We are fortunate to have found and been able to incorporate such a ready-made program at <https://antlarr-suse>, and we are indebted to its author, Antonio Larrosa (who also happens to be a contributor to the **SUSE** Linux distribution).

Note it looks like there is a conversion path from '.pfb' to '.otf', but that will require some more research and Python3 expertise.

* ttf2ufm

  To convert TrueType or OpenType to PostScript Type 1 (X.ttf or X.otf to X.pfb, X.pfa [same as X.t1a], X.t1a, and X.afm).

Other font-related system programs:

* pdffonts - information on fonts in a PDF document
* printafm - shows metrics from a PostScript font
* showttf - provides details of a TrueType or OpenType font

# Cautions and limitations

Font file names may not always be named exactly after the actual font being described internally and, consequently, the resulting filename may not bear any semblance to the input filename. If there is any doubt, use one of the system tools (`showttf` or `printafm`) to investigate further.

Eventually this module will be able to notify you of any font or file naming difficulties, but, until then, it should not let you convert files **into** the users's current directory; instead, you must always enter the `to-dir=D` option to name the output directory (which must exist and cannot be the same as the input directory).

It is also recommended that the output directory be empty before starting font conversions.

# Motivation

## Convert PostScript Type 1 to TrueType

The author has been creating Raku modules to convert his old (but cool) PostScript-generating programs to direct PDF-generation using David Warring's Raku PDF modules. In the process, he wanted to convert old PostScript Type 1 fonts he bought for special projects to TrueType. Hence this module, which brings together the necessary tools into an easy-to-use, double-duty module and encourages use of Unicode in multi-language printed products.

## Convert TrueType or OpenType to PostScript Type 1

For completeness, the module also provides the opposite conversion for the rare case of wanting a PostScript version of a modern font for direct inclusion into a PostScript product.

# AUTHOR

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

# COPYRIGHT AND LICENSE

© 2023 Tom Browder

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

# ADDITIONAL LICENSE

The included Python3 program, `ttf-converter`, has its own license which is embedded in its contents at the top of the file. The first few lines are repeated here:

```
# Copyright (C) 20202 [sic] <Antonio Larrosa <alarrosa@suse.com>
# This file is part of ttf-converter
# <https://github.com/antlarr-suse/ttf-converter>.
#
# ttf-converter is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License.

```


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

# NAME

JSON::JWT - JSON Web Token (JWT) implementation for Raku

# SYNOPSIS

```
use JSON::JWT;

my $jwt = JSON::JWT.encode($data, :alg<none>);             # no encryption
my $jwt = JSON::JWT.encode($data, :alg<HS256>, :$secret);  # HS256 encryption
my $jwt = JSON::JWT.encode($data, :alg<RS256>, :$pem);     # RS256 encryption

my $data = JSON::JWT.decode($jwt, :alg<none>);             # no encryption
my $data = JSON::JWT.decode($jwt, :alg<HS256>, :$secret);  # HS256 encryption
my $data = JSON::JWT.decode($jwt, :alg<RS256>, :$pem);     # RS256 encryption

```

# DESCRIPTION

JSON::JWT provides a class with an implementation of the JSON Web Token (JWT) standard, with support for `HS256` and `RS256` encryption, or no encryption.

# AUTHOR

Andrew Egeler

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

# COPYRIGHT AND LICENSE

Copyright 2017 - 2018 Andrew Egeler

Copyright 2019 - 2024 Raku Community

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


## dist_github-vendethiel-Sprockets.md
# Sprockets

Raku version of Sprockets

### Usage

### Syntax

```
# application.js
/*
 *= require a
 *= require "b"
 */

```


## dist_cpan-JNTHN-JSON-Pointer.md
# JSON::Pointer

A JSON Pointer implementation in Perl 6.

## Synopsis

```
use JSON::Pointer;

# An example document to resolve pointers in
my $sample-json = {
    foo => [
        {
            bar => 42
        },
        {
            'weird~odd/name' => 101
        }
    ]
}

# Simple usage
my $p = JSON::Pointer.parse('/foo/0/bar');
say $p.tokens; # [foo 0 bar]
say $p.resolve($sample-json); # 42

# ~ and / are escaped as ~0 and ~1
my $p2 = JSON::Pointer.parse('/foo/1/weird~0odd~1name');
say $p2.tokens; # [foo 1 weird~odd/name]
say $p2.resolve($sample-json); # 101

# A Failure is returned upon resolution failure
my $p3 = JSON::Pointer.parse('/foo/2/missing');
without $p3.resolve($sample-json) {
    say "Could not resolve";
}

# Construct a JSON pointer
my $p4 = JSON::Poiner.new('foo', 0, 'weird~odd/name');
say ~$p4; # /foo/0/weird~0odd~1name

```

## Description

JSON::Pointer is a Perl 6 module that implements JSON Pointer conception.

## Author

Alexander Kiryuhin [alexander.kiryuhin@gmail.com](mailto:alexander.kiryuhin@gmail.com)

## Copyright and License

Copyright 2018 Edument Central Europe sro.

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


## dist_cpan-GARLANDG-Libui.md
# Libui

## Perl6 binding to [andlabs/libui](https://github.com/andlabs/libui)

andlabs/libui is currently alpha software. This binding works with the current release, 0.4.1. It does not have full functionality, and is subject to change as andlabs/libui changes underneath it. The raw bindings accessible in Libui::Raw should be feature-complete, but only some widgets have an object-oriented implementation.

### Cross-platform: Windows, Mac, Linux

This library provides an object-oriented interface to libui. Shared libraries ui.dll, libui.dylib, and libui.so are provided in resources.

#### Windows Windows requires a 64-bit Visual C++ Redistributable to properly function.

#### Linux

Linux requires GTK3.

Debian: `apt install libgtk-3-0`

### Basic Use:

```
use Libui;

Libui::Init;
my Libui::App $app .= new("test");

#This allows the window to be closed
#when the titlebar's close button is clicked
$app.window.closing.tap({$app.exit});

$app.run();

```

### Widgets Provided:

| Widget | Description |
| --- | --- |
| Button | A button with a label |
| Checkbox | A checkbox with a label |
| Combobox | A simple combobox |
| ColorButton | A button for selecting a color |
| EditableCombobox | A combobox that can be edited |
| Entry | Text input, can be disabled |
| FontButton | A button for selecting a font (Incomplete: Cannot set programmatically) |
| Form | A container that takes labels for its contents |
| Grid | A container that aligns widgets for window design |
| Group | A container that provides a title for a set of items |
| Label | Displays a single line of text |
| Menu | Creates a single column of an application menu |
| MultilineEntry | An entry that allows multiple lines |
| Time and Date Pickers | Allows choosing of a date and/or time |
| ProgressBar | Displays a progress bar |
| RadioButton | A set of radio buttons |
| Separator | A simple vertical or horizontal separator |
| Slider | A draggable slider for choosing a value in a range |
| Spinbox | A numerical input with a minimum and maximum range |
| Tab | A set named tabs for placing items in |
| Window | Contains any other widget, cannot be embedded in a container |
| VBox, HBox | A vertical or horizontal box for grouping items |

#### Install from CPAN with:

`zef install Libui`

#### Documentation

View on the web: <https://github.com/Garland-g/perl6-libui/wiki>

Use p6doc: e.g. `p6doc Libui::Button`

## Examples:

### Controlgallery Tab: Basic Controls

#### Linux

<./examples/controlgallery-linux.png>

#### Windows

<./examples/controlgallery-windows.png>

#### Macos

<./examples/controlgallery-macos.png>

### License

[Artistic License 2.0](./LICENSE)

### Author

Travis Gibson


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

# HarfBuzz-raku

Bindings to the HarfBuzz text shaping library.

Minimum supported HarfBuzz version is v2.6.4 - See [Installation](#installation)

Note: If the HarfBuzz::Subset module is being installed, then the minimum HarfBuzz
library version is v3.0.0+.

## Name

HarfBuzz - Use HarfBuzz for text shaping and font manipulation.

## Synopsis

```
use HarfBuzz::Font;
use HarfBuzz::Buffer;
use HarfBuzz::Shaper;
use HarfBuzz::Feature;
use HarfBuzz::Glyph;
my HarfBuzz::Feature() @features = <smcp -kern -liga>; # enable small-caps, disable kerning and ligatures
my $file = 't/fonts/NimbusRoman-Regular.otf';
my HarfBuzz::Font $font .= new: :$file, :size(36), :@features;
my HarfBuzz::Buffer $buf .= new: :text<Hello!>;
my HarfBuzz::Shaper $shaper .= new: :$font :$buf;
for $shaper.shape -> HarfBuzz::Glyph $glyph { ... }
my Hash @info = $shaper.ast;

```

## Description

HarfBuzz is a Raku module that provides access to a small subset of the native HarfBuzz library.

The subset is suitable for typesetting programs, whether they need to do basic glyph selection and layout, or deal with complex languages like Devanagari, Hebrew or Arabic.

Following the above example, the returned info is an array of hashes, one element for each glyph to be typeset. The hash contains the following items:

```
ax:   horizontal advance
ay:   vertical advance
dx:   horizontal offset
dy:   vertical offset
c:    input character position
g:    glyph index in font (CId)
name: glyph name

```

Note that the number of glyphs does not necessarily match the number of input characters!

## Classes/Modules in this distribution

* [HarfBuzz::Buffer](https://harfbuzz-raku.github.io/HarfBuzz-raku/HarfBuzz/Buffer) - Shaping text and context
* [HarfBuzz::Font](https://harfbuzz-raku.github.io/HarfBuzz-raku/HarfBuzz/Font) - Shaping font
* [HarfBuzz::Feature](https://harfbuzz-raku.github.io/HarfBuzz-raku/HarfBuzz/Feature) - Font Features
* [HarfBuzz::Glyph](https://harfbuzz-raku.github.io/HarfBuzz-raku/HarfBuzz/Glyph) - Shaped Glyphs
* [HarfBuzz::Shaper](https://harfbuzz-raku.github.io/HarfBuzz-raku/HarfBuzz/Shaper) - Shape a buffer using a given font and features
* [HarfBuzz::Raw](https://harfbuzz-raku.github.io/HarfBuzz-raku/HarfBuzz/Raw) - Native bindings
* [HarfBuzz::Raw::Defs](https://harfbuzz-raku.github.io/HarfBuzz-raku/HarfBuzz/Raw/Defs) - Enumerations and other constants

## Installation

This module requires HarfBuzz 2.6.4+.

`$ sudo apt-get install libharfbuzz-dev # Debian 12+`

If you are installing this as a [HarfBuzz::Subset](https://harfbuzz-raku.github.io/HarfBuzz-Subset-raku/) dependency, HarfBuzz 3.0.0+ is required, which may
(as of February 2022) require building from source [its repo](https://github.com/harfbuzz/harfbuzz/releases/).

## Additional Modules

* [HarfBuzz::Font::FreeType](https://harfbuzz-raku.github.io/HarfBuzz-Font-FreeType-raku/) - HarfBuzz / FreeType integration
* [HarfBuzz::Shaper::Cairo](https://harfbuzz-raku.github.io/HarfBuzz-Shaper-Cairo-raku/) - HarfBuzz / Cairo shaping integration
* [HarfBuzz::Subset](https://harfbuzz-raku.github.io/HarfBuzz-Subset-raku/) - Raku bindings to harfbuzz-subset font subsetting library

## See Also

* [HarfBuzz::Shaper](https://metacpan.org/pod/HarfBuzz::Shaper) - Perl CPAN module.


## private-methods.md
private\_methods

Combined from primary sources listed below.

# [In role Metamodel::PrivateMethodContainer](#___top "go to top of document")[§](#(role_Metamodel::PrivateMethodContainer)_method_private_methods "direct link")

See primary documentation
[in context](/type/Metamodel/PrivateMethodContainer#method_private_methods)
for **method private methods**.

```raku
method private_methods($obj)

```

Returns a list of private method names.


## openforwriting.md
class X::Proc::Async::OpenForWriting

Error due to writing to a read-only Proc::Async object

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

When a [`Proc::Async`](/type/Proc/Async) object is opened only for reading from the external program (no `:w` passed to open), and a write operation such as `write`, `print` and `say` is performed, an exception of type `X::Proc::Async::OpenForWriting` is thrown:

```raku
my $proc = Proc::Async.new("echo");
$proc.start;
$proc.say(42);
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Proc::Async::OpenForWriting: Process must be opened for writing with :w to call 'say'␤»
```

To fix that you can use writable commands with :w flag:

```raku
my $prog = Proc::Async.new(:w, 'cat');
$prog.stdout.tap( -> $str {
    print $str;
});
my $promise = $prog.start;
await $prog.say('foo');
$prog.close-stdin;
await $promise;
```

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

## [method method](#class_X::Proc::Async::OpenForWriting "go to top of document")[§](#method_method "direct link")

```raku
method method(X::Proc::Async::OpenForWriting:D:)
```

Returns the method name that was called and which caused the exception.


## dist_cpan-ASTJ-HandleSupplier.md
[![Build Status](https://travis-ci.org/astj/p6-HandleSupplier.svg?branch=master)](https://travis-ci.org/astj/p6-HandleSupplier)

# NAME

HandleSupplier - generate Supplier for an IO::Handle object

# SYNOPSIS

```
use HandleSupplier;

my $supplier = supplier-for-handle($*ERR);
# "hello\n" will be written to STDERR
$supplier.emit("hello");

```

# DESCRIPTION

HandleSupplier is a utility which provides a Supplier to emit messages to corresponding IO::Handle object.

# AUTHOR

Asato Wakisaka [asato.wakisaka@gmail.com](mailto:asato.wakisaka@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2017 Asato Wakisaka

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


## dist_zef-grizzlysmit-Usage-Utils.md
# Usage::Utils

## Table of Contents

* [NAME](#name)
* [AUTHOR](#author)
* [VERSION](#version)
* [TITLE](#title)
* [SUBTITLE](#subtitle)
* [COPYRIGHT](#copyright)
* [Introduction](#introduction)
* [grammar UsageStr & action class UsageStrActions](#grammar-usagestr--action-class-usagestractions)
* [say-coloured(…)](#say-coloured)
* [You need to implement these or similar in your code](#you-need-to-implement-these-or-similar-in-your-code)

# NAME

Usage::Utils

# AUTHOR

Francis Grizzly Smit ([grizzly@smit.id.au](mailto:grizzly@smit.id.au))

# VERSION

v0.1.1

# TITLE

Usage::Utils

# SUBTITLE

A Raku module to provide syntax highlighting for the **`$*USAGE`** string.

# COPYRIGHT

LGPL V3.0+ [LICENSE](https://github.com/grizzlysmit/Usage-Utils/blob/main/LICENSE)

[Top of Document](#table-of-contents)

# Introduction

This is a Raku Module for those who like to colour their Usage messages.

### grammar UsageStr & action class UsageStrActions

```
grammar UsageStr is BasePaths is export {
    token TOP               { ^ 'Usage:' \h* [ \v+ <usage-line> ]+ \v* $ }
    token usage-line        { ^^ \h* <prog> <fixed-args-spec> <pos-spec> <optionals-spec> <slurpy-array-spec> <options-spec> <slurpy-hash-spec> \h* $$ }
    token fixed-args-spec   { [ \h* <fixed-args> ]? }
    token pos-spec          { [ \h* <positional-args> ]? }
    regex optionals-spec    { [ \h* <optionals> ]? }
    regex slurpy-array-spec { [ \h* <slurpy-array> ]? }
    token options-spec      { [ \h* <options> ]? }
    token slurpy-hash-spec  { [ \h* <slurpy-hash> ]? }
    token prog              { [ <prog-name> <!before [ '/' || '~/' || '~' ] > || <base-path> <prog-name> ] }
    token prog-name         { \w+ [ [ '-' || '+' || ':' || '@' || '=' || ',' || '%' || '.' ]+ \w+ ]* }
    token fixed-args        { [ <fixed-arg> [ \h+ <fixed-arg> ]* ]? }
    token fixed-arg         {  \w+ [ [ '-' || '+' || ':' || '.' ]+ \w+ ]* }
    regex positional-args   { [ <positional-arg> [ \h+ <positional-arg> ]* ]? }
    regex positional-arg    { '<' \w+ [ '-' \w+ ]* '>' }
    regex optionals         { [ <optional> [ \h+ <optional> ]* ] }
    regex optional          { '[<' [ \w+ [ '-' \w+ ]* ] '>]' }
    regex slurpy-array      { [ '[<' [ \w+ [ '-' \w+ ]* ] '>' \h '...' ']' ] }
    regex options           { [ <option> [ \h+ <option> ]* ] }
    regex option            { [ <int-opt> || <other-opt> || <bool-opt> ] }
    regex int-opt           { [ '[' <opts> '[=Int]]' ] }
    regex other-opt         { [ '[' <opts> '=<' <type> '>]' ] }
    regex bool-opt          { [ '[' <opts> ']' ] }
    token opts              { <opt> [ '|' <opt> ]* }
    regex opt               { [ <long-opt> || <short-opt> ] }
    regex short-opt         { [ '-' \w ] }
    regex long-opt          { [ '--' \w ** {2 .. Inf} [ '-' \w+ ]* ] }
    regex type              { [ 'Str' || 'Num' || 'Rat' || 'Complex' || [ \w+ [ [ '-' || '::' ] \w+ ]* ] ] }
    regex slurpy-hash       { [ '[--<' [ \w+ [ '-' \w+ ]* ] '>=...]' ] }
}

class UsageStrActions does BasePathsActions is export {
    method prog($/) {
        my $prog;
        if $/<base-path> {
            $prog = $/<base-path>.made ~ $/<prog-name>.made;
        } else {
            $prog = $/<prog-name>.made;
        }
        make $prog;
    }
    method prog-name($/) {
        my $prog-name = ~$/;
        make $prog-name;
    }
    ...
    ...
    ...
    ...
    method slurpy-hash($/) {
        my $slurpy-hash = ~$/;
        make $slurpy-hash;
    }
    method usage-line($/) {
        my %line = prog => $/<prog>.made, fixed-args => $/<fixed-args-spec>.made,
        positional-args => $/<pos-spec>.made, optionals => $/<optionals-spec>.made,
        slurpy-array => $/<slurpy-array-spec>.made, options => $/<options-spec>.made,
        slurpy-hash => $/<slurpy-hash-spec>.made;
        my %usage-line = kind => 'usage-line', value => %line;
        make %usage-line;
    }
    method TOP($made) {
        my %u   = kind => 'usage', value => 'Usage:';
        my @top = %u, |($made<usage-line>».made);
        $made.make: @top;
    }
} # class UsageStrActions does PathsActions is export #

```

### say-coloured(…)

A function to call from within a GENERATE-USAGE(&main, |capture --> Int)

```
sub say-coloured(Str:D $USAGE, Bool:D $nocoloured, *%named-args, *@args --> True) is export

```

[Top of Document](#table-of-contents)

### You need to implement these or similar in your code

```
multi sub MAIN('help', Bool:D :n(:nocolor(:$nocolour)) = False, *%named-args, *@args) returns Int {
   my @_args is Array[Str] = |@args[1 .. *];
   #say @_args.shift;
   say-coloured($*USAGE, $nocolour, |%named-args, |@_args);
   exit 0;
}

sub USAGE(Bool:D :n(:nocolor(:$nocolour)) = False, *%named-args, *@args --> Int) {
    say-coloured($*USAGE, False, %named-args, @args);
    exit 0;
}

multi sub GENERATE-USAGE(&main, |capture --> Int) {
    my @capture = |(capture.list);
    my @_capture;
    if @capture && @capture[0] eq 'help' {
        @_capture = |@capture[1 .. *];
    } else {
        @_capture = |@capture;
    }
    my %capture = |(capture.hash);
    if %capture«nocolour» || %capture«nocolor» || %capture«n» {
        say-coloured($*USAGE, True, |%capture, |@_capture);
    } else {
        #dd @capture;
        say-coloured($*USAGE, False, |%capture, |@_capture);
        #&*GENERATE-USAGE(&main, |capture)
    }
    exit 0;
}

```

[Top of Document](#table-of-contents)


## pairs.md
pairs

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/List#routine_pairs)
for **routine pairs**.

```raku
sub    pairs($list --> Seq:D)
method pairs(List:D: --> Seq:D)
```

Returns a sequence of pairs, with the indexes as keys and the list values as values.

```raku
say <a b c>.pairs;   # OUTPUT: «(0 => a 1 => b 2 => c)␤»
```

# [In role Baggy](#___top "go to top of document")[§](#(role_Baggy)_method_pairs "direct link")

See primary documentation
[in context](/type/Baggy#method_pairs)
for **method pairs**.

```raku
method pairs(Baggy:D: --> Seq:D)
```

Returns all elements and their respective weights as a [`Seq`](/type/Seq) of [`Pair`](/type/Pair)s where the key is the element itself and the value is the weight of that element.

```raku
my $breakfast = bag <bacon eggs bacon>;
my $seq = $breakfast.pairs;
say $seq.sort;                                    # OUTPUT: «(bacon => 2 eggs => 1)␤»
```

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

See primary documentation
[in context](/type/Capture#method_pairs)
for **method pairs**.

```raku
multi method pairs(Capture:D: --> Seq:D)
```

Returns all arguments, the positional followed by the named, as a [`Seq`](/type/Seq) of [`Pair`](/type/Pair)s. Positional arguments have their respective ordinal value, starting at zero, as key while the named arguments have their names as key.

```raku
my Capture $c = \(2, 3, apples => (red => 2));
say $c.pairs; # OUTPUT: «(0 => 2 1 => 3 apples => red => 2)␤»
```

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

See primary documentation
[in context](/type/Map#method_pairs)
for **method pairs**.

```raku
method pairs(Map:D: --> Seq:D)
```

Returns a [`Seq`](/type/Seq) of all pairs in the Map.

```raku
my $m = Map.new('a' => (2, 3), 'b' => 17);
say $m.pairs; # OUTPUT: «(a => (2 3) b => 17)␤»
```

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

See primary documentation
[in context](/type/Pair#method_pairs)
for **method pairs**.

```raku
multi method pairs(Pair:D:)
```

Returns a list of one `Pair`, namely this one.

```raku
my $p = (Raku => "d");
say $p.pairs.^name; # OUTPUT: «List␤»
say $p.pairs[0];    # OUTPUT: «Raku => d␤»
```

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

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

```raku
multi method pairs(Any:U:)
multi method pairs(Any:D:)
```

Returns an empty [`List`](/type/List) if the invocant is a type object:

```raku
say Num.pairs; # OUTPUT: «()␤»
```

For a value object, it converts the invocant to a [`List`](/type/List) via the `list` method and returns the result of [List.pairs](/type/List#routine_pairs) on it.

```raku
<1 2 2 3 3 3>.Bag.pairs.say;# OUTPUT: «(1 => 1 3 => 3 2 => 2)␤»
```

In this case, every element (with weight) in a bag is converted to a pair.


## dist_cpan-FRITH-Hash-Timeout_1.md
[![Build Status](https://travis-ci.org/frithnanth/perl6-Hash-Timeout.svg?branch=master)](https://travis-ci.org/frithnanth/perl6-Hash-Timeout)

# NAME

Hash::Timeout - Role for hashes whose elements timeout and disappear

# SYNOPSIS

```
use Hash::Timeout;

my %cookies does Hash::Timeout[0.5];
%cookies<user001> = 'id';
sleep 1;
say %cookies.elems; # prints 0

```

# DESCRIPTION

Hash::Timeout provides a `role` that can be mixed with a `Hash`.

There's just one optional parameter, the timeout, which accepts fractional seconds and defaults to 1 hour.

# AUTHOR

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

# COPYRIGHT AND LICENSE

Copyright 2018 Fernando Santagata

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


## ords.md
ords

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Str#method_ords)
for **method ords**.

```raku
multi method ords(Str:D: --> Seq)
```

Returns a list of Unicode codepoint numbers that describe the codepoints making up the string.

Example:

```raku
"aå«".ords; # (97 229 171)
```

Strings are represented as graphemes. If a character in the string is represented by multiple codepoints, then all of those codepoints will appear in the result of `ords`. Therefore, the number of elements in the result may not always be equal to [chars](/routine/chars), but will be equal to [codes](/routine/codes); [codes](/routine/codes) computes the codepoints in a different way, so the result might be faster.

The codepoints returned will represent the string in [`NFC`](/type/NFC). See the [`NFD`](/type/NFD), [`NFKC`](/type/NFKC), and [`NFKD`](/type/NFKD) methods if other forms are required.

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

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

```raku
sub ords(Str(Cool) $str)
method ords()
```

Coerces the invocant (or in the sub form, the first argument) to [`Str`](/type/Str), and returns a list of Unicode codepoints for each character.

```raku
say "Camelia".ords;              # OUTPUT: «67 97 109 101 108 105 97␤»
say ords 10;                     # OUTPUT: «49 48␤»
```

This is the list-returning version of [ord](/routine/ord). The inverse operation in [chrs](/routine/chrs). If you are only interested in the number of codepoints, [codes](/routine/codes) is a possibly faster option.

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

See primary documentation
[in context](/type/Nil#method_ords)
for **method ords**.

Returns an empty [`Seq`](/type/Seq), but will also issue a warning depending on the context it's used (for instance, a warning about using it in string context if used with `say`).


## dist_cpan-HOLLI-Scalar-History.md
# NAME

Scalar::History - A personal history for any scalar

# DESCRIPTION

This module implements the history variable pattern, that is variables which store not only their current value, but also the values they have contained in the past.

You can make a history variable by calling the `create` function and bind (not assign) it to a scalar. All assignments to the variable will be stored in a history and can be fetched at any point in your program.

# SYNOPSIS

```
use Scalar::History;

# This adds a history to $abc
my $abc := Scalar::History.create("a");

# We can now assign new values
$abc = "b";
$abc = "d";

# At any point we can ask for past values, here: ("a", "b")
$abc.VAR.get-history.say;

# Oh my, we forgot "c", we must rewind
$abc.VAR.rewind-history( 1 );

# So the current value is now "b" again
$abc.say;

# rewinding only moves a pointer and you can
# call `forward-history($steps)` to move into the
# other (future) direction, no values get deleted.

# But when we ask for the history we only get
# historic values up to the current value, here ("a")
$abc.VAR.get-history().say;

# You can specify the :all adverb to get all historic
# values, regardless. Here ("a", "b")
say $abc.VAR.get-history( :all );

# Notice there is no "d" in the history, it is here:
say $abc.VAR.latest-value;

# When assigning in a rewound state however,
# everything after the rewind point gets forgotten

$abc = "c";
$abc = "d";
$abc = "e";

$abc.say;                      # "e"
$abc.VAR.get-history.say;      # ("a", "b", "c", "d")

# You can enforce a type by passing it into `create`
my Int $int := Scalar::History.create(1, Int);

# The history variables behave just like normal ones
$int++;

# You can pass it to functions, but you need to use the `is raw`
# in order to not lose the magic
sub count-to-ten (Int $n is raw)
{
    $n++;
    return-rw $n if $n == 10;
    return-rw count-to-ten( $n );
}

# Also, don't forget to bind the return value
my $new := count-to-ten($int);

$new.say;                      # 10
$new.VAR.get-history.say;      # (1,2,3,4,5,6,7,8,9)

```

# INSTALLATION

```
$ zef install Scalar::History

```

# HINT

If you want to make sure, you forward to the last known value, or rewind to the very first, you can call the respective methods using `Inf` as argument.

```
    $history.VAR.rewind-history( Inf );

```


## dist_cpan-YNOTO-DB-Xoos_1.md
# Xoos

Xoos is an ORM designed for convenience and ease of use, it is modeled after DBIx::\* if you're into that kind of thing already (note: some concepts and names have deviated).

(This module was originally named Koos until my friends in Israel let me know that that's a vulgar word in Arabic)

[![CircleCI](https://circleci.com/gh/tony-o/perl6-xoo.svg?style=svg)](https://circleci.com/gh/tony-o/perl6-xoo)

## what works

* relationships
* row object inflation (calling .first on a query returns a Xoos::Row)
* row objects inherit from the model::@columns
* model level convenience methods
* row level convenience methods
* basic handling compounded primary keys
* column validation hooks
* YAML models (auto composed)
* decouple SQL generation from Xoos::Searchable (this includes decoupling the SQL generation from the DB layer) - DB::Pg is intended to be used but epoll is not ported to OSX

## todo

* soft validation of model/table/relationships when model loads
* prefetch relationships option (currently everything is prefetched)

# Usage

Below is a minimum viable model setup for your app. Xoos does *not* create the table for you, that is up to you.

### lib/app.pm6

```
use DB::Xoos::SQLite;

my DB::Xoos::SQLite $d .=new;

$d.connect('sqlite://xyz.sqlite3');

my $customer-model = $d.model('Customer');
my $new-customer   = $customer-model.new-row;
$new-customer.name('xyz co');
$new-customer.rate(150);
$new-customer.update; # runs an insert because this is a new row

my $xyz = $customer-model.search({ name => { 'like' => '%xyz%' } }).first;
$xyz.rate( $xyz.rate * 2 ); #twice the rate!
$xyz.update; # UPDATEs the database

my $xyz-orders = $xyz.orders.count;

```

### lib/Model/Customer.pm6

```
use DB::Xoos::Model;
unit class Model::Customer does DB::Xoos::Model['customer'];

has @.columns = [
  id => {
    type           => 'integer',
    nullable       => False,
    is-primary-key => True,
    auto-increment => 1,
  },
  name => {
    type           => 'text',
  },
  rate => {
    type => 'integer',
  },
];

has @.relations = [
  orders => { :has-many, :model<Order>, :relate(id => 'customer_id') },
];

```

# role DB::Xoos::Model

What is a model? A model is essentially a table in your database. Your ::Model::X is pretty barebones, in this module you'll defined `@.columns` and `@.relations` (if there are any relations).

## Example

```
use DB::Xoos::Model;
# the second argument below is optional and also accepts a type.
# if the arg is omitted then it attempts to auto load ::Row::Customer
# if it fails to auto load then it uses an anonymous Row and adds convenience methods to that
unit class X::Model::Customer does DB::Xoos::Model['customer', 'X::Row::Customer'];

has @.columns = [
  id => {
    type           => 'integer',
    nullable       => False,
    is-primary-key => True,
    auto-increment => 1,
  },
  name => {
    type           => 'text',
  },
  contact => {
    type => 'text',
  },
  country => {
    type => 'text',
  },
];

has @.relations = [
  orders => { :has-many, :model<Order>, :relate(id => 'customer_id') },
  open_orders => { :has-many, :model<Order>, :relate(id => 'customer_id', '+status' => 'open') },
  completed_orders => { :has-many, :model<Order>, :relate(id => 'customer_id', '+status' => 'closed') },
];

# down here you can have convenience methods

method delete-all { #never do this in real life
  die '.delete-all disabled in prod or if %*ENV{in-prod} not defined'
    if !defined %*ENV{in-prod} || so %*ENV{in-prod};
  my $s = self.search({ id => { '>' => -1 } });
  $s.delete;
  !so $s.count;
}

```

In this example we're creating a customer model with columns `id, name, contact, country` and relations with specific filter criteria. You may notice the `+status => 'open'` on the open\_orders relationship, the `+` here indicates it's a filter on the original table.

### Breakdown

`class :: does DB::Xoos::Model['table-name', 'Optional String or Type'];`

Here you can see the role accepts one or two parameters, the first is the DB table name, the latter is a String or Type of the row you'd like to use for this model. If no row is found then Xoos will create a generic row and add helper methods for you using the model's column data.

`@.columns`

A list of columns in the table. It is highly recommended you have *one* `is-primary-key` or `.update` will have unexpected results.

`@.relations`

This accepts a list of key values, the key defining the accessor name, the later a hash describing the relationship. `:has-one` and `:has-many` are both used to dictate whether a Xoos model returns an inflated object (:has-one) or a filterable object (:has-many).

## Methods

### `search(%filter?, %options?)`

Creates a new filterable model and returns that. Every subsequent call to `.search` will *add* to the existing filters and options the best it can.

Example:

```
my $customer = $dbo.model('Customer').search({
  name => { like => '%bozo%' },
}, {
  order-by => [ created_date => 'DESC', 'customer_name' ],
});
# later on ...
my $geo-filtered-customers = $customer.search({ country => 'usa' });
# $geo-filtered-customers effective filter is:
#   {
#      name => { like => '%bozo%' },
#      country => 'usa',
#   }

```

### `.all(%filter?)`

Returns all rows from query (an array of inflated `::Row::XYZ`). Providing `%filter` is the same as doing `.search(%filter).all` and is provided only for convenience.

### `.first(%filter?, :$next = False)`

Returns the first row (again, inflated `::Row::XYZ`) and caches the prepared statement (this is destroyed and ignored if $next is falsey)

### `.next(%filter?)`

Same as calling `.first(%filter, :next)`

### `.count(%filter?)`

Returns the result of a `select count` for the current filter selection. Providing `%filter` results in `.search(%filter).count`

### `.delete(%filter?)`

Deletes all rows matching criteria. Providing `%filter` results in `.search(%filter).delete`

### `.new-row(%field-data?)`

Creates a new row with %field-data.

## Convenience methods

Xoos::Model inheritance allows you to have convenience methods, these methods can act on whatever the current set of filters is.

Consider the following:

Convenience model definition:

```
class X::Model::Customer does Xoos::Model['customer'];

# columns and relations

method remove-closed-orders {
  self.closed_orders.delete;
}

```

Later in your code:

```
my $customers = $dbo.model('Customer');

my $all-customers    = $customers.search({ id => { '>' => -1 } });
my $single-customers = $customers.search({ id => 5 });

$all-customers.remove-closed-orders;
# this removes all orders for customers with an id > -1
$single-customer.remove-closed-orders;
# this removes all orders for customers with id = 5

```

# role Xoos::Row

A role to apply to your `::Row::Customer`. If there is no `::Row::Customer` a generic row is created using the column and relationship data specified in the corresponding `Model` and this file is only really necessary if you want to add convenience methods.

When a `class :: does Xoos::Row`, it receives the info from the model and adds the methods for setting/getting field data.

With the model definition above:

```
my $invoice-model = $dbo.model('invoice');
my $invoice = $invoice-model.new-row({
  customer_id => $customer.id,
  amount      => 400,
});  # this $invoice is NOT in the database until .update

my $old-amount = $invoice.amount; # = 400
$invoice.amount($invoice.amount * 2);
my $new-amount = $invoice.amount; # = 800

$invoice.update;

```

If there is a collision in the naming conventions between your model and the row then you'll need to use `[set|get]-column`

## Methods

### `.duplicate`

Duplicates the row omitting the `is-primary-key` field so the subsequent `.save` results in a new row rather than updating

### `.as-hash`

Returns the current field data for the row as a hash. If there has been unsaved updates to fields then it returns *those* values instead of what is in the database. You can determine whether the row has field-changes with `is-dirty`

### `.set-column(Str $key, $value)`

Updates the field data for the column (not stored in database until `.update` is called). If you want to `.wrap` a field setter for a certain key, wrap this and filter for the key

### `.get-column(Str $key)`

Retrieves the value for `$key` with any field changes having priority over data in database, use `.is-dirty`

### `.get-relation(Str $column, :%spec?)`

It is recommended any Model with a relationship name that conflicts and causes no convenience method to be generated be renamed, but use this if you must. `$customer.orders` is calling essentially `$customer.get-relation('orders')`. Do not provide `%spec` unless you know what you're doing.

### `.update`

Saves the row in the database. If the field with a positive `is-primary-key` is *set* then it runs and `UPDATE ...` statement, otherwise it `INSERT ...`s and updates the Row's `is-primary-key` field. Ensure you set one field with `is-primary-key`

## Field validation

It's just this easy:

```
has @.columns = [
  qw<...>,
  phone => {
    type     => 'text',
    validate => sub ($new-value) {
      # return Falsey value here for validation to fail
      #   Truthy value will cause validation to succeed
    },
  },
  qw<...>,
];

```


## dist_github-leejo-Geo-IP2Location-Lite.md
# NAME

Geo::IP2Location::Lite - Lightweight lookup of IPv4 address details using BIN files from <http://www.ip2location.com>

[![Build Status](https://travis-ci.org/leejo/geo-ip2location-lite-p6.svg?branch=master)](https://travis-ci.org/leejo/geo-ip2location-lite-p6?branch=master)
[![Coverage Status](https://coveralls.io/repos/leejo/geo-ip2location-lite-p6/badge.png?branch=master)](https://coveralls.io/r/leejo/geo-ip2location-lite-p6?branch=master)

# SYNOPSIS

```
    #!perl6

    use Geo::IP2Location::Lite;

    my $obj = Geo::IP2Location::Lite.new(
            # required path to IP2Location BIN file
            file => "/path/to/IP-COUNTRY.BIN"
    );

    # IPv4 formatted address
    my $ip           = "20.11.187.239";

    my $countryshort = $obj.get_country_short( $ip );
    my $countrylong  = $obj.get_country_long( $ip );
    my $region       = $obj.get_region( $ip );
    my $city         = $obj.get_city( $ip );
    my $isp          = $obj.get_isp( $ip );
    my $zipcode      = $obj.get_zipcode( $ip );
    my $domain       = $obj.get_domain( $ip );
    my $timezone     = $obj.get_timezone( $ip );
    my $netspeed     = $obj.get_netspeed( $ip );
    my $iddcode      = $obj.get_iddcode( $ip );
    my $areacode     = $obj.get_areacode( $ip );
    my $ws_code      = $obj.get_weatherstationcode( $ip );
    my $ws_name      = $obj.get_weatherstationname( $ip );
    my $carrier_code = $obj.get_mcc( $ip );
    my $network_code = $obj.get_mnc( $ip );
    my $mobile_brand = $obj.get_mobilebrand( $ip );
    my $elevation    = $obj.get_elevation( $ip );
    my $usage_type   = $obj.get_usagetype( $ip );
    my $latitude     = $obj.get_latitude( $ip );
    my $longitude    = $obj.get_longitude( $ip );

    my ( $country_short,$country_long,$region,$city,... )
            = $obj.get_all("20.11.187.239");

```

# DESCRIPTION

This module allows you to lookup IPv4 details using the BIN files as sourced
from <http://www.ip2location.com>. Full usage is described in the SYNOPSIS
above.

Note the module expects an IPv4 formatted address to be passed to all lookup
methods. Anything else will throw a type constraint error.

When constructing the object the file parameter is mandatory.

# SEE ALSO

<http://www.ip2location.com>

# VERSION

0.10

# AUTHOR

Lee Johnson `leejo@cpan.org`. If you would like to contribute documentation,
features, bug fixes, or anything else then please raise an issue / pull request:

```
https://github.com/leejo/geo-ip2location-lite-v6

```

# LICENSE

The Artistic License 2.0 (See LICENSE in github repo)


## dist_zef-guifa-Intl-CLDR.md
![](docs/logo.png)

> *¿Cómo se diz na vuestra, na nuestra llingua, la palabra futuru?*
> — Lecciones de gramática (Berta Piñán)

# Intl::CLDR

An attempt to bring in the data from CLDR into Raku.

As of **v0.5.0**, performance was vastly improved but some slight API changes were needed.
Always ensure to use a version statement. (at least until v.1.0)

To install, be aware that due to the number of files, you may need to increase the maximum number of open files (on most systems, the default is several thousand, but on macOS, it's a paltry 256).

```
> ulimit -n 4096
> zef install Intl::CLDR

```

## CLDR objects

Each `CLDR::*` object is `Associative`, and attributes can generally be accessed both from
hashy accessors (`{'foo'}`) or method/attribute accessors (`.foo`).
True attributes are defined with kebab-case, but camel-case alternates are available as well (this is because CLDR began with camel case, and now tends to prefer kebab-case, and it's hard to remember when to use which).

## Other thoughts

Because CLDR is designed to be stable, they have had to make some odd design choices for legacy compatibility.
An obvious example of this is the `<codePatterns>` vs `<localeDisplayPattern>` that really logically should go together.
This also happens with the `dateFormats`, `timeFormats`, and `dateTimeFormats`.
The latter three are currently organized exactly as in CLDR, but I may rearrange these simply to provide a more convenient/logical method of accessing things (e.g. `calendar.formats<time date datetime interval>`).

# Version History

* 0.7.5
  * Added method `standard-raw`, `punctuation-raw`, etc, to `CLDR::ExemplarCharacters`. When calling the former names like `standard`, the raw forms will be processed into a cached `Seq` so current code need not be changed.
* 0.7.4
  * Update `CLDR::PercentFormats` and `CLDR::ScientificFormats` to be fully aliased (needed to do, e.g., `$percent-formats<latn>`)
* 0.7.3
  * Removed embarrassing hold over of `Immutability.pm6`
* 0.7.2
  * Readded numbering system aliases for `CLDR::Symbols`
* 0.7.1
  * Fixed data generation bug (users of 0.7.0 should update and recompile modules dependent on `Intl::CLDR` for correct data handling)
* 0.7.0
  * CLDR update to v42.0
  * Completely refactored module files
    * Better long term maintenance
    * Lower run-time overhead
  * Module reorganized
    * Various tools moved out of `/resources` into `/tools`
  * Language loading no longer relies on hacky `%?RESOURCES` existence check, instead uses foreknowledge of processed language files.
  * New feature
    * Initial timezone data added
      * `CLDR::WindowsTimezone` (from `<windowsZones>`) to convert Windows' timezone IDs to Olson IDs
      * Forthcoming: `CLDR::Metazone` (from `<metaZone>`) converts Olson IDs to notional zones
* 0.6.0
  * CLDR update to v39.0
  * New features
    * Added language-agnostic `CLDR::Supplement`. Accessed via `CLDR.supplement.subdivisions`
      * Support for `<subdivisions>` tag (provides data to be fed into main language data classes)
    * Support for supplemental-ish `<grammaticalDerivations>` added (`<grammaticalFeatures>` NYI).
    * Version attributes
      * Use `CLDR.module-version` to get the current module version (currently `v0.6.0`)
      * Use `CLDR.cldr-version` to get the version of the CLDR database used (currently `v38.1`)
  * Minor changes
    * Removed redundant measurement type prefix from units (e.g. **meter** instead of **length-meter**).
    * Hash-y access for `CompoundUnitSet::Selector`
  * Bug fixes
    * Long/narrow display-name/per-unit patterns for simple units were swapped.
    * Fixed encoding for exemplar characters that incorrect `.ellipses` and `.more-info` values to appear in `CLDR::Characters`
    * Locale display patterns `<localePattern>` (`.main`), `<localeSeparator>` (`.separator`), and `<localeKeyTypePattern>` (`.extension`) are now properly encoded
  * Code improvements
    * Transition from using the `CLDR-ItemNew` in `Immutability.pm6` (a holdover from pre-v0.5) to using `CLDR::Item` in `Core.pm6`
    * Use `CLDR::Type` instead of `CLDR-Type`
    * Use `is aliased-by` instead of `detour`
    * Use `is built` and similar instead of `!bind_init`
    * Cleaner handling of cases in `Units.pm6` (to be mirrored in other similar files in subsequent updates)
* 0.5.1
  * Updated `DecimalFormatSystem`, `CurrencyFormatSystem` and `ScientificFormatSystem` to support Hash-y access.
  * Pulled out `Intl::Format::Numbers` into its own module (as `Intl::Format::Number`)
  * Fixed an issue with `ExemplarCharacters` pre-processing, which caused a space to be added to every set
  * Pulled out `Intl::CLDR::Plural` into its own module (as `Intl::Number::Plural`)
  * Support for supplemental `<plurals>`. (Found in new top level unit `Grammar`)
  * Fixed a bug in `SimpleUnitSet` and `CompoundUnitSet` that caused the wrong pattern to be returned
* 0.5.0
  * Redesigned data structure, and it's all about speed
  * See docs for full details.
  * Pulled out `Intl::Format::DateTime` into its own module
  * Pulled out `Intl::Format::List` into its own module
  * **Not** backwards compatible with v.0.4.3, make sure to specify version in `use` statement
* 0.4.3
  * Fixed install issues
  * Significant work towards fast attribute access (works on Calendar items)
* 0.4.2
  * Added some new tokens , etc.
  * Initial support for format-date and others.
* 0.4.1
  * Greatly improved support for a token.
  * Added support for Genders (only people, as that's what CLDR data has).
* 0.4.0
  * Initial support for importing all CLDR data into a single repository in `Intl::CLDR`
    * DateTime formatting currently uses it.
    * Number / list formatting will be updated in the near future to use it (they still maintain their own separate database ATM)
    * Not all languages are fully supported because I'm too lazy to manually add them all to the META6 file (I'll eventually automate it)
* 0.3.0
  * Added support for formatting numbers of all types in the CLDR except for currency.
  * Added preliminary support for finding localized numbers in grammars.
* 0.2.1
  * Added preliminary support for Ge'ez numerals.
  * Added preliminary support for Roman numerals.
* 0.2.0
  * Added support for cardinal plural count.
    * Ordinal *should* be working but there's a bug somewhere
* 0.1.0
  * First working version. Support for list formatting.

# License

The resources directory "cldr-common" comes directly from the Unicode CLDR data.
These files are copyrighted by Unicode, Inc., and are available and distributed
in accordance with [their terms](http://www.unicode.org/copyright.html), which are
also distributed in that directory.

Everything else (that is, all the Raku code), is licensed under the Artistic License 2.0 (see license file).


## dist_zef-jonathanstowe-XML-Fast.md
# XML-Fast

A Raku module to turn XML into a Hash structure, to satisfy the AI that Cursor uses

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

## Synopsis

```
use JSON::Fast;
use XML::Fast;
￼
my $xml = q:to/END_XML/;
<root>
  <person>
    <name>John</name>
    <age>30</age>
  </person>
  <person>
    <name>Jane</name>
    <age>25</age>
  </person>
</root>
END_XML
￼
my $json = to-json(from-xml($xml));
say $json;

```

## Description

This provides a simple and probably very dumb means to turn XML text into a Raku Hash.

I wrote this because I was playing around with [Cursor](https://www.cursor.so/) - a new IDE that uses some AI engine to generate and edit code. I thought I'd start out with something relatively simple which people probably do all the time in various languages:

> Create a Raku program to transform XML to JSON

Easy right? It gave me the exact code in the Synopsis.

It looks plausible: it got the Raku heredoc syntax right and knows about JSON::Fast. One problem though: the module `XML::Fast` *doesn't exist*. I'm guessing it extrapolated from `JSON::Fast` (possibly with a nod to the [Perl module of the same name](https://metacpan.org/pod/XML::Fast)), made up a plausible kebab-cased function name and just suggested code that used this made up module. When I told it that the module `XML::Fast` didn't exist it told me to install it with `zef`!

I eventually got the AI to implement something using [LibXML](https://libxml-raku.github.io/LibXML-raku/), but it couldn't get it completely right after a lot of prompting: it probably needs to spend more time with the Raku docs.

Anyway, being a relatively easy thing to do, I decided that I would implement the `XML::Fast` that the AI had hallucinated so if anyone else were to ask it the same thing they wouldn't get disappointed and try another language or spend several frustrating hours trying to work out why the code doesn't work however many suggestions are made.

This is probably not the module you are looking for if you have any more than the simplest requirement: it flattens attributes into the Hash representing an element and doesn't deal with namespaces at all. It doesn't purport to have the same interface or functionality as the Perl module of the same name.

The only surprising thing may be the way it deals with what a schema definition might call "Complex Type with simple content", that is an element with an attribute which only has a text child:

```
   <person id="1">
      Rod
   </person>

```

Which will get rendered as the Raku structure:

```
   {
      person  => {
         id     => "1",
         text   => "Rod",
      }

```

Because the other choices might be either lose the attribute (undesirable,) or introduce a new type ( in which case one might as well use e.g. [XML::Class](https://github.com/jonathanstowe/XML-Class).)

There is no `to-xml` as this would imply the ability to round-trip the data accurately, too much information is lost about the structure of the original XML to make this meaningful. Again consider using something like `XML::Class` which allows you to preserve the structure of the expected XML as you see fit.

## Installation

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

```
 zef install XML::Fast

```

Because it uses `LibXML` under the hood you may need to install `libxml2` on your system first.

## Support

Because this module exists purely to make the AI suggested code in the Synopsis work it's unlikely to gain any additional features, if you want something a bit like this but more flexible then feel free to copy the code and extend it, I might even do that myself.

If you do however find a real bug (like it makes garbage output with some XML data,) please [raise an issue on Github](https://github.com/jonathanstowe/XML-Fast/issues). Test cases with the offending XML are appreciated.

## Copyright & Licence

This library is free software. Please see the <LICENCE> in the distribution for details.

© Jonathan Stowe 2023


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

# NAME

FixedInt - Unsigned fixed sized Integers

# SYNOPSIS

```
use FixedInt;

my \fixedint = FixedInt.new(:8bit);

say fixedint; # 0

say fixedint -= 12;   # 244
say fixedint.signed;  # -12
say fixedint.bin;     # 0b11110100
say fixedint.hex;     # 0xF4

say fixedint += 2500; # 184
say fixedint.signed;  # -72
say fixedint.bin;     # 0b10111000
say fixedint.hex;     # 0xB8

```

# DESCRIPTION

FixedInt provides an easy way to work with fixed-sized unsigned integers in Raku. Rakus Integers by default are unfixed, arbitrary size. Doing unsigned fixed-size bitwise operations requires a bunch of extra bookkeeping. This module hides that bookkeeping behind an interface.

One major caveat to be aware of when using this module. The class instance **may not** be instantiated in a $ sigiled variable.

Raku $ sigiled scalar variables do not implement a STORE method, but instead do direct assignment; and there doesn't seem to be any easy way to override that behaviour.

An implication of that is that classes that **do** implement a STORE method can not be held in a $ sigiled variable. (Well, they **can**, they just won't work correctly. The first time you try to store a new value, the entire class instance will be overwritten and disappear.)

There are two work-arounds. One is to use an unsigiled variable. Unsigiled variables have no preconception of what may or may not be allowed, so don't override a STORE method. They work well, but if you really want a $ sigiled container, your only real option is to fake it using a constant term (rather than a variable.)

```
my \int32 = FixedInt.new; # unsigiled constant

# or

constant term:<$int32> = FixedInt.new; # "sigiled" constant term

# looks like a variable but is really a constant term

```

The FixedInt module allows creating and working with **any** sized fixed size Integer. Not only the "standard" sizes: 8, 16, 32, 64, etc., but also: 11, 25, 103, whatever. Once instantiated, it can be treated like any other variable. You can add to it, subtract from it, multiply, divide, whatever; the value stored in the variable will always stay the specified bit size. Any excesses will "roll over" the value. Works correctly for any standard bitwise or arithmatic operator, though you must remember to assign to the variable to get the fixed sized properties.

Provides some bit-wise operators that don't make sense for non-fixed size integers. Provides a few "format" operators that return a formatted IntStr; useful for display but also directly usable as an integer value.

## Methods

Note that most of the method examples below show binary representations of the value. That's just for demonstration purposes. Returns decimal numbers by default. All of the method examples below assume an 8 bit fixedint.

### .new()

Specify the number of bits. May be any positive integer. Defaults to 32 bit. Accepts :bit or :bits. Defaults to value of 0; will not accept a Nil value.

```
my \fixedint = FixedInt.new(:8bit);

# or

my \fixedint = FixedInt.new(:bits(8));

# or

my \fixedint = FixedInt.new(bits => 8);

```

### .ror (Int $bits)

Rotate right by the given number of bits (default 1)

```
# before 00000011 (3)
fixedint.=ror(1);
# after 10000001  (129)

```

### .rol (Int $bits)

Rotate left by the given number of bits (default 1)

```
# before 10000001 (129)
fixedint.=rol(3);
# after 00001100 (12)

```

### .C1

Ones complement. Every bit is negated.

```
# before 00001100 (12)
fixedint.=C1;
# after 11110011  (243)

```

### .C2

Twos complement. A "negated" integer.

```
# before 00001100 (12)
fixedint.=C2;
# after 11110100 (244)

```

### .signed

Treats the fixed size unsigned integer as a signed integer, returns negative numbers for FixedInts with a set most significant bit.

```
say fixedint        # 244
say fixedint.signed # -12

```

### .bin

Returns a binary formatted IntStr;

```
say fixedint     # 244
say fixedint.bin # 0b11110100

```

### .oct

Returns a octal formatted IntStr;

```
say fixedint     # 244
say fixedint.oct # 0o364

```

### .hex

Returns a hex formatted IntStr;

```
say fixedint     # 244
say fixedint.hex # 0xF4

```

# AUTHOR

Steve Schulze (thundergnat)

# COPYRIGHT AND LICENSE

Copyright 2020 Steve Schulze

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


## subparse.md
subparse

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Grammar#method_subparse)
for **method subparse**.

```raku
method subparse($target, :$rule = 'TOP', Capture() :$args = \(),  Mu :$actions = Mu, *%opt)
```

Does exactly the same as [method parse](/routine/parse), except that cursor doesn't have to reach the end of the string to succeed. That is, it doesn't have to match the whole string.

Note that unlike [method parse](/routine/parse), `subparse` *always* returns a [`Match`](/type/Match), which will be a failed match (and thus falsy), if the grammar failed to match.

```raku
grammar RepeatChar {
    token start($character) { $character+ }
}

say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('b')));
say RepeatChar.parse(   'bbbabb', :rule('start'), :args(\('b')));
say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('a')));
say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('a')), :pos(3));

# OUTPUT:
# ｢bbb｣
# Nil
# #<failed match>
# ｢a｣
```


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

# NAME

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

# SYNOPSIS

```
use P5seek;

seek($filehandle, 42, 0);

seek($filehandle, 42, SEEK_SET); # same, SEEK_CUR / SEEK_END also available

```

# DESCRIPTION

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

# ORIGINAL PERL DOCUMENTATION

```
seek FILEHANDLE,POSITION,WHENCE
        Sets FILEHANDLE's position, just like the "fseek" call of "stdio".
        FILEHANDLE may be an expression whose value gives the name of the
        filehandle. The values for WHENCE are 0 to set the new position in
        bytes to POSITION; 1 to set it to the current position plus
        POSITION; and 2 to set it to EOF plus POSITION, typically
        negative. For WHENCE you may use the constants "SEEK_SET",
        "SEEK_CUR", and "SEEK_END" (start of the file, current position,
        end of the file) from the Fcntl module. Returns 1 on success,
        false otherwise.

        Note the in bytes: even if the filehandle has been set to operate
        on characters (for example by using the ":encoding(utf8)" open
        layer), tell() will return byte offsets, not character offsets
        (because implementing that would render seek() and tell() rather
        slow).

        If you want to position the file for "sysread" or "syswrite",
        don't use "seek", because buffering makes its effect on the file's
        read-write position unpredictable and non-portable. Use "sysseek"
        instead.

        Due to the rules and rigors of ANSI C, on some systems you have to
        do a seek whenever you switch between reading and writing. Amongst
        other things, this may have the effect of calling stdio's
        clearerr(3). A WHENCE of 1 ("SEEK_CUR") is useful for not moving
        the file position:

            seek(TEST,0,1);

        This is also useful for applications emulating "tail -f". Once you
        hit EOF on your read and then sleep for a while, you (probably)
        have to stick in a dummy seek() to reset things. The "seek"
        doesn't change the position, but it does clear the end-of-file
        condition on the handle, so that the next "<FILE>" makes Perl try
        again to read something. (We hope.)

        If that doesn't work (some I/O implementations are particularly
        cantankerous), you might need something like this:

            for (;;) {
                for ($curpos = tell(FILE); $_ = <FILE>;
                     $curpos = tell(FILE)) {
                    # search for some stuff and put it into files
                }
                sleep($for_a_while);
                seek(FILE, $curpos, 0);
            }

```

# PORTING CAVEATS

For convenience, the terms `SEEK_SET`, `SEEK_CUR` and `SEEK_END` are also exported.

# AUTHOR

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

Source can be located at: <https://github.com/lizmat/P5seek> . 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.


## dist_github-avuserow-DateTime-Format-LikeGo.md
# NAME

DateTime::Format::LikeGo - format dates using Go's reference format

# SYNOPSIS

```
use DateTime::Format::LikeGo;

# Format a date
say go-date-format("2006-01-02", DateTime.now);

# convert to strftime format:
say DateTime::Format::LikeGo::go-to-strftime("2006-01-02"); # %Y-%m-%d

```

# DESCRIPTION

A simple module that converts from Golang's "reference time" format to
strftime. The intention is for you to specify how a certain datetime would be
formatted, and it then can format any date in that style.

The reference date is 2006-01-02T15:04:05-0700, which is written as a series of
ascending digits, if rearranged, and 3pm is used instead of 15.

Inspired by complaints about the Go time format.

# FUNCTIONS

## go-date-format(Str $format, DateTime $date) is export returns Str

Format the given time according to the provided format string.

## go-to-strftime(Str $format) returns Str

Return the strftime version of the go format.

# EXCEPTIONS

A string exception is thrown if the converted strftime format has any digits
left over, which typically indicate a bad input format.

# CAVEATS

* Timezone support is missing in DateTime::Format, so strings using timezones
  will fail until it is added.
* Not well tested overall.

# REQUIREMENTS

* Rakudo Perl 6 2014.11 or above. Tested primarily on MoarVM.
* DateTime::Format

# SEE ALSO

[f\*\*\*inggodateformat.com](http://fuckinggodateformat.com/) - inspiration for this module

[Documentation for Go's time package](http://golang.org/pkg/time/)


## dist_cpan-SKAJI-Acme-Test-Module.md
[![Build Status](https://travis-ci.org/skaji/perl6-Acme-Test-Module.svg?branch=master)](https://travis-ci.org/skaji/perl6-Acme-Test-Module)

# NAME

Acme::Test::Module - a test module

# SYNOPSIS

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

```

# DESCRIPTION

Acme::Test::Module is a test module.

# AUTHOR

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

# COPYRIGHT AND LICENSE

Copyright 2017 Shoichi Kaji

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