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

# NAME

Math::Libgsl::RunningStatistics - An interface to libgsl, the Gnu Scientific Library - Running Statistics

# SYNOPSIS

```
use Math::Libgsl::RunningStatistics;

my Math::Libgsl::RunningStatistics $r .= new;
$r.add($_) for (^10);
say $r.mean;
say $r.variance;
say $r.sd;

```

# DESCRIPTION

Math::Libgsl::RunningStatistics is an interface to the Running Statistics functions of libgsl, the Gnu Scientific Library.

This class is suitable for handling large datasets for which it may be inconvenient or impractical to store in memory all at once.

### new(:@quantile = 0.5,)

The constructor accepts one optional parameter, the quantile array, which defaults to just one value: 0.5 i.e. the median. The @quantile argument will be used only if one uses the quantile methods.

### add(Num() $x --> Int)

This method adds a value to the accumulator. It returns GSL\_SUCCESS if successful.

### n(--> Int)

This method returns the number of data added so far to the accumulator.

### min(--> Num)

This method returns the minimum value added to the accumulator.

### max(--> Num)

This method returns the maximum value added to the accumulator.

### mean(--> Num)

This method returns the mean of all data added to the accumulator.

### variance(--> Num)

This method returns the variance of all data added to the accumulator.

### sd(--> Num)

This method returns the standard deviation of all data added to the accumulator.

### sd-mean(--> Num)

This method returns the standard deviation of the mean.

### rms(--> Num)

This method returns the root mean square of all data added to the accumulator.

### skew(--> Num)

This method returns the skewness of all data added to the accumulator.

### kurtosis(--> Num)

This method returns the kurtosis of all data added to the accumulator.

### median(--> Num)

This method returns the median of all data added to the accumulator.

### reset(--> Int)

This method resets the accumulator.

### qadd(Num() $x --> Int)

This method adds a value to the quantile accumulators. It returns GSL\_SUCCESS if successful. If not successful it returns the first error found and the accumulators are left in an undefined state, so you're advised to .qreset() them.

### qget(Num() $x --> List)

This method returns a List of all the current estimate of the quantiles specified when the object was created.

### qreset(--> Int)

This method resets the quantile accumulators. It returns GSL\_SUCCESS if successful. If not successful it returns the first error found.

# C Library Documentation

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

# Prerequisites

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

## Debian Linux and Ubuntu 20.04+

```
sudo apt install libgsl23 libgsl-dev libgslcblas0

```

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

## Ubuntu 18.04

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

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

# Installation

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

```
$ zef install Math::Libgsl::RunningStatistics

```

# AUTHOR

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

# COPYRIGHT AND LICENSE

Copyright 2020 Fernando Santagata

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


## dist_zef-vrurg-IP-Addr.md
# NAME

IP::Addr - dealing with IPv4/IPv6 addresses

# SYNOPSIS

```
my $cidr = IP::Addr.new( "192.0.2.2/27" );
say $cidr;
say $cidr.ip;
for $cidr.network.each -> $ip {
    say $ip;
}

my $cidr6 = IP::Addr.new( "600d::f00d/123" );
say $cidr6;
say $cidr6.ip;

```

# DESCRIPTION

This module provides functionality for working with IPv4/IPv6 addresses.

## Module Structure

The main interface is provided by `IP::Addr` class. Typical class usage is demonstrated in the synopsis. The class is a frontend which tries to determine version of the IP address provided to its constructor and creates corresponding handler object available on its `handler` attribute. All methods of the handler are available on `IP::Addr` object via `handles` trait.

For example, for an arbitrary `$ip` object of the class `$ip.ip` call is actually same as calling `$ip.handler.ip`. Method `ip` is a universal one for both v4 and v6 addresses and therefore it is not necessary to care about what exact kind of object we're currently dealing with.

Similarly, version-dependant methods are available too but only when corresponding handler is active. For example:

```
say IP::Addr.new( "192.0.2.2/27" ).broadcast;

```

is a valid call; while

```
say IP::Addr.new( "2001:db8::/123" ).broadcast;

```

will fail with "no method" exception because `broadcast` is not available for IPv6 addresses.

## Glossary

### Address forms

Besides of its version each IP address has one more characteristic property: form. It is defined by handler's attribute of the same name: `$!form`. Particular forms are defined by IP-FORM enum defined in `IP::Addr::Common`:

* *ip*

  Simple IP address. It has prefix length of 32 bits.
* *cidr*

  CIDR form is an IP address with *prefix* defined.

  ```
  192.0.2.3/24
  192.0.2.3/255.255.255.0
  2001::/64

  ```
* *range*

  A range is defined by its first and last IP addresses. It has a *selected* or *current* IP address which could be changed as a result of increase, decrease, or iteration operations.

  ```
  192.0.2.3-192.0.2.20
  2001::1-2001::1f

  ```

### Ranged forms

CIDR and ranges are *ranged forms* contrary to a single IP form.

### N-tets

As it is known IP addresses are represented by groups of integers called *octets* for IPv4 and *hextets* for IPv6 (there are variations but I chose these two). *N-tets* is used as a general term for both of them.

# METHODS

## Constructor

Class constructor `new` simply re-dispatches its arguments to method `set`.

## `set`

* *`$ip.set( Str $source )` / `$ip.set( Str :$source! )`*

  `$source` is a string representation of an IP address in either plain or CIDR notation, or of a range of addresses in a form \*- \*. Formats of valid IP addresses are defined by corresponding standards.
* *`$ip.set( [ :v4 | :v6 ], *%params )`*

  Creates a handler object of specified version of handler (v4 or v6) by passing named `%params` to its constructor.

  For example, the following statement:

  ```
  $ip.set( :v4, ip => 3221225986, prefix-len => 24 )

  ```

  Is equivalent to:

  ```
  $ip.set( "192.0.2.2/24" )

  ```

  **Note:** all calls to `set` method result in creation of a new handler object. I.e.:

  ```
  my $old-handler = $ip.handler;
  $ip.set( ... );
  say $old-handler === $ip.handler; # False

  ```

## `Str`

Returns a valid string representation of the IP object.

## `gist`

Same as `Str` method.

## `each`

Returns an iterable object which would iterate over IPs contained in the current object starting with selected address (i.e. the one returned by `ip` method). For ranged forms to iterate over the whole range (from the `first-ip` to the `last-ip`) use of method `first` is recommended:

```
.say for IP::Addr.new( "192.0.2.3/29" ).each;           # 192.0.2.3/29\n192.0.2.4/29 ...
.say for IP::Addr.new( "192.0.2.3/29" ).first.each;     # 192.0.2.0/29\n192.0.2.1/29 ...

```

## `Supply`

Similar to `each` method but returns a `Supply` object. Same rule about starting with selected IP and use of `first` method apply.

# HANDLER METHODS

This sections documents methods common for both IPv4 and IPv6 handlers.

## Notes

For all methods accepting another IP address as a parameter and where descriptions has a statement *"same version only"* `X::IPAddr::TypeCheck` exception would be thrown if object with a handler of different version is passed.

Address method parameters could either be `IP::Addr` instances or string representations.

## `set`

Configures the handler object.

**Note** In the following subsection `$handler` notation is used instead of `$ip.handler`.

* *`$handler.set( Str:D $source )` / `$handler.set( Str:D :$source! )`*

  Handler attributes are set by parsing a string representation of IP address.
* *`$handler.set( Int:D :$ip!, Int:D :$!prefix-len )`*

  Configures handler object as *CIDR* form.
* *`$handler.set( Int:D :$first!, Int:D :$!last, Int :$ip? )`*

  Configures handler object as *range* form. Optional named parameter `:ip` defines selected IP within range (i.e. the one returned by `ip` method). If omitted then range initial selected IP is its first address.
* *`$handler.set( Int:D $ip! )`*

  Configures a single IP form.
* *`$handler.set( Int:D @n-tets )`*

  Configures a single IP form from integer octets for IPv4 or hextets for IPv6. Number of elements in @n-tets array is defined by the method of the same name.

## `addr-len`

Returns number of bits for correponding IP version (*32* for IPv4 and *128* for IPv6).

## `n-tets`

Returns number of n-tets for the current handler (*4* for IPv4 and *8* for IPv6).

## `version`

Returns integer version of the IP object (*4* or *6*).

## `ip-classes`

Returns list of hashes of reserved IP ranges. Each hash has two keys:

* *net*

  `IP::Addr` object representing the reserved range.
* *info*

  Another hash containing information about the scope of the reserved range in very brief text description:

  * *scope*

    Scopes are defined by `SCOPE` enum in `IP::Addr::Common`. Currently the following scopes are known:

    * `undetermined`
    * `mpublic`
    * `software`
    * `private`
    * `host`
    * `subnet`
    * `documentation`
    * `internet`
    * `routing`
    * `link`

    Of those `routing` and `link` are specific to IPv6. `public` isn't officially recognized but used to represent anything not been reserved. `undetermined` is also a special value to be returned if a requested range of IP addresses overlaps with a reserved range but isn't fully contained in it.
  * *description*

    Textual information about the reserved block.

## `ip`

Returns a new `IP::Addr` object representing just an IP address of the current `IP::Addr` object.

```
my $ip = IP::Addr.new( "192.0.2.3/24" );
say $ip;            # 192.0.2.3/24
say $ip.ip;         # 192.0.2.3
say $ip.ip.WHO;     # IP::Addr

```

## `prefix`

Returns CIDR representation of any form of IP address. For example:

```
say IP::Addr.new( "192.0.2.3" ).prefix;     # 192.0.2.3/32

```

For IPv4 handler additional named parameter `:mask` can be used to use network mask instead of prefix length:

```
say IP::Addr.new( "192.0.2.3/24" ).prefix( :mask );     # 192.0.2.3/255.255.255.0

```

## `first-ip`

`IP::Addr` object for the first IP address in the range. For single IP will be the same as `ip` method.

## `last-ip`

`IP::Addr` object for the last IP address in the range. For single IP will be the same as `ip` method.

## `network`

`IP::Addr` object of the network current IP object belongs to. Makes real sense for CIDR form only though can be used with any other form too.

## `mask`

Returns string representation of the current IP object mask. Doesn't make much sense for IPv6 addresses because there is officially no such thing for them.

## `wildcard`

Returns string representation of current IP object wildcard. Doesn't make much sense for IPv6 addresses because there is officially no such thing for them.

## `size`

Returns number of IP addresses contained in the current `IP::Addr` object. For example:

```
say IP::Addr.new( "192.0.0.0/13" ).size;            # 524288
say IP::Addr.new( "192.0.2.3-192.0.2.23" );         # 21

```

## `int-ip`

Returns integer value of the IP address.

## `int-first-ip`

Returns integer value of the first IP address in the current IP object.

## `int-last-ip`

Returns integer value of the last IP address in the current IP object.

## `int-mask`

Returns integer value of current IP object mask. Though not defined as such for IPv6 addresses but could be useful in some address arithmetics.

## `int-wildcard`

Returns integer value of current IP object wildcard. Though not defined as such for IPv6 addresses but could be useful in some address arithmetics.

## `inc` / `succ`

Increments IP address by *1*. For ranged IP forms result of this operation won't be greater than the last IP of the range:

```
my $ip = IP::Addr.new( "192.0.2.255/24" );
say $ip.inc;                # 192.0.2.255/24

```

Rerturns current `IP::Addr` object.

## `dec` / `pred`

Decrements IP address by *1*. For ranged IP forms result of this operation won't be less than the first IP of the range:

```
my $ip = IP::Addr.new( "192.0.2.0/24" );
say $ip.dec;                # 192.0.2.0/24

```

Returns current `IP::Addr` object.

## `add( Int:D $count )`

Shifts IP of the current object by `$count` positions higher. `$count` could be negative. For ranged IP form the result of the operation won't leave the range boundaries:

```
my $ip = IP::Addr.new( "192.0.2.255/24" );
say $ip.add( 10 );              # 192.0.2.255/24
say $ip.add( -300 );            # 192.0.2.0/24

```

Returns current `IP::Addr` object.

## `eq( $addr )`

Same version only.

Returns *True* if current object is equal to `$addr`.

## `lt( $addr )`

Same version only.

Returns true if the current object is less than `$addr`.

## `gt( $addr )`

Same version only.

Returns true if the current object is greater than `$addr`

## `cmp( $addr )`

Same version only.

Returns one of three `Order` values: `Less`, `Same`, or `More`. For ranges comparison is performed by the selected IP.

## `contains( $addr )`

Same version only.

Returns *True* if current object contains `$addr`. Wether the `$addr` object is the same (e.g. `eq` method would return *True*) then it is also considered as contained.

## `overlaps( $addr )`

Same version only.

Returns *True* if the current object and `$addr` have at least one common IP address. Useful for starting iteration:

## `first`

Returns a new `IP::Addr` object whose IP address is the first IP of the current object. Useful for starting iteration.

```
my $ip = IP::Addr.new( "192.0.2.12/24" );
for $ip.first.each { say $_ }       # 192.0.2.0\n192.0.2.1\n...

```

See `each` method.

## `next`

Returns a new `IP::Addr` object successive to the current object or *Nil* if current is the last IP of the range.

## `prev`

Returns a new `IP::Addr` object preceding the current object or *Nil* if current is the first IP of the range.

## `next-network`

Returns a new `IP::Addr` object containing network successive to the network of the current object. Valid for CIDR form only. Flips over begining/end of IP range:

```
$ip = IP::Addr.new( "255.255.255.13/24" );
say $ip.next-network;               # 0.0.0.0/24

```

## `prev-network`

Returns a new `IP::Addr` object containing network preceding the network of the current object. Valid for CIDR form only. Flips over the begining of IP range:

```
$ip = IP::Addr.new( "0.0.0.2/24" );
say $ip.prev-network;               # 255.255.255.0/24

```

## `next-range`

Returns a new `IP::Addr` object containing range of the same length successive to the current object. Valid for range form only.

## `prev-range`

Returns a new `IP::Addr` object containing range of the same length preceding the current object. Valid for range form only.

## `to-int( @n-tets )`

Converts an array of n-tets to integer value corresponding to the current handler's IP version.

## `to-n-tets( Int:D $addr )`

Splits integer represnation of IP address into n-tets corresponding to the current handler's IP version.

## `info`

Returns a hash with information about the current IP object. The hash contains two keys: `scope` and `description`. See `ip-classes` method for more information.

## `Str`

Stringifies current IP object with regard to its form.

# OPERATORS

For all supported operators where both operands are addresses at least one of them has to be a `IP::Addr` object. The other one could be a string representation of an address.

## `prefix/postfix ++` and `prefix/postfix --`

Standard Raku operatios working by calling `succ`/`pred` methods on `IP::Addr` object.

## `infix + ( $addr, $int )`

Adds an integer value to the address. The resulting address will never get out of network/range boundaries for objects of corresponding forms. A new `IP::Addr` object is returned.

```
$ip2 = $ip1 + 3;

```

## `infix - ( $addr, $int )`

Deducts an integer value from the address. The resulting address will never get out of network/range boundaries for objects of corresponding forms. A new `IP::Addr` object is returned.

```
$ip2 = $ip1 - 3;

```

## `infix cmp ( $addr1, $addr2 )`

Compares two IP addresses.

```
given $ip1 cmp $ip2 {
    when Less { say "smaller" }
    when Same { say "same" }
    when More { say "bigger" }
}

```

## `infix eqv / infix == ( $addr1, $addr2 )`

Checks if two addresses are equal. See handler's `eq` method.

## `infix < ( $addr1, $addr2 )`

*True* if `$addr1` is less than `$addr2`. See handler's `lt` method.

## `infix <= / infix ≤ ( $addr1, $addr2 )`

*True* if `$addr1` is less than or equal to `$addr2`.

## `infix > ( $addr1, $addr2 )`

*True* if `$addr1` is greater than `$addr2`. See handler's `gt` method.

## `infix >= / infix ≥ ( $addr1, $addr2 )`

*True* `$addr1` greater than or equal to `$addr2`.

## `infix (cont) / infix ⊇ ( $addr1, $addr2 )`

*True* if `$addr1` object contains `$addr2`. See handler's `contains` method.

## `infix ⊆ ( $addr1, $addr2 )`

*True* if `$addr1` is contained by `$addr2`.

# CAVEATS

The author doesn't use IPv6 in his setups. All the functionality provided here is developed using information from corresponding Wikipedia pages. Therefore, "here be dragons"©. Please, report back any issue encountered!

# SEE ALSO

[ChangeLog](ChangeLog.md)

# AUTHOR

Vadim Belman [vrurg@cpan.org](mailto:vrurg@cpan.org)


## cannotconvert.md
class X::Numeric::CannotConvert

Error while trying to coerce a number to another type

```raku
class X::Numeric::CannotConvert is Exception { }
```

Occurs when an attempt to coerce an [`Inf`](/type/Num#Inf) or a [`NaN`](/type/Num#NaN) to a [`Numeric`](/type/Numeric) type.

For example

```raku
say Inf.Int;
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Numeric::CannotConvert: Cannot convert Inf to Int␤»
```

Most other conversion errors throw [`X::Numeric::Real`](/type/X/Numeric/Real).

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

## [method source](#class_X::Numeric::CannotConvert "go to top of document")[§](#method_source "direct link")

```raku
method source()
```

Returns the value that failed to coerce.

## [method target](#class_X::Numeric::CannotConvert "go to top of document")[§](#method_target "direct link")

```raku
method target()
```

Returns the type to which the coercion was attempted.

## [method reason](#class_X::Numeric::CannotConvert "go to top of document")[§](#method_reason "direct link")

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

Returns the reason that the conversion failed.


## div.md
div

Combined from primary sources listed below.

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

See primary documentation
[in context](/language/operators#infix_div)
for **infix div**.

```raku
multi infix:<div>(Int:D, Int:D --> Int:D)
```

Integer division operator. Rounds down.

Note there is also [`/`](#infix_/) for [`Numeric`](/type/Numeric) division.

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

See primary documentation
[in context](/type/Int#infix_div)
for **infix div**.

```raku
multi infix:<div>(Int:D, Int:D --> Int:D)
```

Does an integer division, rounded down.


## dist_cpan-JMASLAK-Net-BGP.md
[![Build Status](https://travis-ci.org/jmaslak/Raku-Net-BGP.svg?branch=master)](https://travis-ci.org/jmaslak/Raku-Net-BGP)

# NAME

Net::BGP - BGP Server Support

# SYNOPSIS

```
use Net::BGP

my $bgp = Net::BGP.new( port => 179 );  # Create a server object

```

# DESCRIPTION

This provides framework to support the BGP protocol within a Raku application.

This is a pre-release of the final version, and as such the interface may change. The best way of seeing how this module works is to look at `bin/bgpmon.pl6` and examining it. If you are interested in using this module, and have any suggestions at all, please let me know!

# ATTRIBUTES

## port

The port attribute defaults to 179 (the IETF assigned port default), but can be set to any value between 0 and 65535. It can also be set to Nil, meaning that it will be an ephimeral port that will be set once the listener is started.

## listen-host

The host to listen on (defaults to the IPv4 any-host IP, 0.0.0.0).

## server-channel

Returns the channel communicate to command the BGP server process. This will not be defined until `listen()` is executed. It is intended that user code will send messages to the BGP server.

## user-channel

Returns the channel communicate for the BGP server process to communicate to user code.

## add-unknown-peers

If this is `True` (default is `False`), connections from unknown peers are allowed. When they first connect, a new peer is added to the peer list using the remote address and the ASN sent in the peer's OPEN message.

# METHODS

## listen

```
$bgp.listen();

```

Starts BGP listener, on the port provided in the port attribute.

For a given instance of the BGP class, only one listener can be active at any point in time.

## peer-add

```
$bgp.peer-add(
              :peer-asn(65001),
              :peer-ip("192.0.2.1"),
              :peer-port(179),
              :passive(False),
              :ipv4(True),
              :ipv6(False),
              :md5($key),
);

```

Add a new peer to the BGP server.

Providing `peer-asn` and `peer-ip` is required. However, if the `peer-port` is not provided, `179` will be used. If `passive` is not used, the connection will not be configured as a passive connection. If `ipv4` is not provided, it defaults to `True` (enabling the IPv4 address family), while `ipv6` defaults to `False` (disabling the IPv6 address family). If an `md5` parameter is provided, this is used to set up MD5 associations (on OSes that support this via the `TCP::LowLevel` module).

# PATRONS

Mythic Beasts, a managed and unmanaged VPS, dedicated server, web and email hosting company (among many other services) generously donated the use of a VPS host with IPv4 and IPv6 BGP feeds for the development of this module. Check them out at <https://www.mythic-beasts.com/>.

# AUTHOR

Joelle Maslak [jmaslak@antelope.net](mailto:jmaslak@antelope.net)

# COPYRIGHT AND LICENSE

Copyright © 2018-2020 Joelle Maslak

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


## dist_cpan-MZIESCHA-Bailador-Plugin-NamedQueries.md
# NAME

DBIx::NamedQueries - a predefined sql framework for Perl6

# SYNOPSIS

Build a class for your predefined SQL-Statements

```
use Bailador;
use Bailador::Plugin::NamedQueries;

get '/' => sub {
    template 'index.html', _html_render_fix {
        result  => self.plugins.get('NamedQueries').read: 'user/select'
    }
}

baile();

```

# INSTALLATION

```
> zef install DBIx::NamedQueries

```

# DESCRIPTION

This plugin is a thin wrapper around DBIx::NamedQueries.

# CONFIGURATION

Configuration can be done in your <Bailador> config file. This is a minimal example:

```
plugins:
  NamedQueries:
    divider: '/'
    namespace: R3Scheduler::Db::Queries
    handle:
      type: DBIish
      driver: SQLite
      database: test.sqlite3

```

# FUNCTIONS

## read

## read

## write

## write

## create

## insert

## select

## object

Returns the DBIx::NamedQueries object for itself.

## dispose

# TODO

more documentation

# SEE ALSO

<https://github.com/perl6/DBIish>, <https://modules.perl6.org/dist/DBIx::NamedQueries>

# AUTHOR

Mario Zieschang <mziescha [at] cpan.org>

# COPYRIGHT AND LICENSE

Copyright 2018 Mario Zieschang

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


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

# NAME

**Github::PublicKeys** - Provides a program to add Github's ssh keys to a user's '$HOME/.ssh/known\_hosts' file

Note versions previous to v0.2.0 are not reliable. Use a newer version to ensure no erroneous keys were added.

# SYNOPSIS

```
$ gh-add-keys go
Success, check your '~/.ssh/known_hosts' file for
the 3 added keys at the end:
  github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
  github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
  github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=

```

# DESCRIPTION

**Github::PublicKeys** Provides an installed Raku program, `gh-add-keys`, to add any of Github's latest public keys for individual users that are missing into your `$HOME/.ssh/known_hosts` file. Finally, it will report actions taken.

The key data and instructions are documented at [Github.com](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints)

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


## dist_github-gfldex-HTTP-Server-Simple.md
# HTTP::Server::Simple

[![Build Status](https://travis-ci.org/gfldex/http-server-simple.svg?branch=master)](https://travis-ci.org/gfldex/http-server-simple)

This simple embedded web server is similar to HTTP::Daemon, but provides
more hooks for subclassing and extending. The subclasses CGI and PSGI give
ways to host existing web applications or frameworks that use those APIs.

The Perl Server Gateway Interface is a more powerful and efficient web
server API than CGI. Several well known Perl 5 products are based on it,
for example Plack and Dancer. This Perl 6 based project offers the same
web server foundation on Rakudo, to assist the porting of such web
frameworks to Perl 6.

The object hierarchy follows its Perl 5 based prototype closely, except
where the CGI concerns were not separated from the web server. In this
Perl 6 implementation the PSGI concerns are fully separated from the CGI
ones.

# EXAMPLES

Included are examples of minimal web servers and some that demonstrate use
of extension hooks and subclassing.

# TESTING

The code is badly under tested, contributions would be welcome.

# SEE ALSO

The Perl 6 Web.pm project: <http://github.com/masak/web>
The Perl Dancer project: perldancer.org
PSGI spec: <http://github.com/miyagawa/psgi-specs/blob/master/PSGI.pod>
Rack spec: <http://rack.rubyforge.org/doc/SPEC.html>


## dist_cpan-JGOFF-Perl6-Tidy.md
[![Build Status](https://travis-ci.org/drforr/perl6-Perl6-Tidy.svg?branch=master)](https://travis-ci.org/drforr/perl6-Perl6-Tidy)

# NAME

Perl6::Tidy - Tidy Perl 6 source code according to your guidelines

# SYNOPSIS

```
bin/perl6-tidy

Indents code to match simple tab style (mine in this case).

Choices of tab style include:
    'tab' (aka 1-true-brace-style or k-n-r)
    'Allman'
    'GNU'
    'Whitesmiths'
    'Horstmann'
    'Pico'
    'Ratliff'
    'Lisp'

# This *will* execute phasers such as BEGIN in your existing code.
# This may constitute a security hole, at least until the author figures
# out how to truly make the Perl 6 grammar standalone.

```

# DESCRIPTION

Uses Perl6::Parser to parse your source into a Perl 6 data structure, then walks the data structure and prints it according to your format guidelines.

# Indentation

Just as a reminder, here are quasi-formal names for common indentation styles.

'tab' - "One True Brace Style", "K&R":

```
while (x == y) {
    something();
    somethingelse();
}

```

Allman:

```
while (x == y)
{
    something();
    somethingelse();
}

```

GNU:

```
while (x == y)
{
    something();
    somethingelse();
}

```

Whitesmiths:

```
while (x == y)
  {
    something();
    somethingelse();
  }

```

Horstmann

```
while (x == y)
{   something();
    somethingelse();
}

```

Pico

```
while (x == y)
{   something();
    somethingelse(); }

```

Ratliff

```
while (x == y) {
    something();
    somethingelse();
    }

```

Lisp

```
while (x == y) {
    something();
    somethingelse(); }

```

# Installation

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

```
    zef update && zef install Perl6::Tidy

```

## Testing

To run tests:

```
    prove -e perl6

```

## Author

Jeffrey Goff, DrForr on #perl6, <https://github.com/drforr/>

## License

Artistic License 2.0


## dist_cpan-NINE-Inline-Perl5.md
# TITLE

Inline::Perl5

[![Build Status](https://travis-ci.org/niner/Inline-Perl5.svg?branch=master)](https://travis-ci.org/niner/Inline-Perl5)

# SYNOPSIS

```
    use DBI:from<Perl5>;

    my $dbh = DBI.connect('dbi:Pg:database=test');
    my $products = $dbh.selectall_arrayref(
    	'select * from products', {Slice => {}}
    );

```

# DESCRIPTION

Module for executing Perl 5 code and accessing Perl 5 modules from Raku.

Supports Perl 5 modules including XS modules. Allows passing integers,
strings, arrays, hashes, code references, file handles and objects between
Perl 5 and Raku. Also supports calling methods on Perl 5 objects from
Raku and calling methods on Raku objects from Perl 5 and subclass
Perl 5 classes in Raku.

Note that installing Inline::Perl5 requires the Perl 5 library to be installed.
See the BUILDING section for more information.

# HOW DO I?

## Load a Perl 5 module

Raku's use statement allows you to load modules from other languages as well.
Inline::Perl5 registers as a handler for the Perl5 language. Rakudo will
automatically load Inline::Perl5 as long as it is installed:

```
    use Test::More:from<Perl5>;

```

In Raku the :ver adverb is used for requiring a minimum version of a loaded
module:

```
    use Test::More:from<Perl5>:ver<1.001014>;

```

Inline::Perl5's use() method maps to Perl 5's use statement:

```
    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;
    $p5.use('Test::More');

```

To load a Perl 5 module from a specific folder:

```
    use lib:from<Perl5> 'lib';
    use MyModule:from<Perl5>;

```

## Load a Perl 5 module and import functions

Just list the functions or groups you want to import

```
    use Digest::SHA1:from<Perl5> <sha1_hex>;

```

```
    use Data::Random:from<Perl5> <:all>;

```

## Call a Perl 5 function

Inline::Perl5 creates wrappers for loaded Perl 5 modules and their functions.
They can be used as if they were Raku modules:

```
    use Test::More:from<Perl5>;
    plan tests => 1;
    ok 'yes', 'looks like a Raku function';

```

In this example, the `plan` function exported by `Test::More` is called.

Inline::Perl5's call($name, \*@args) method allows calling arbitrary Perl 5
functions. Use a fully qualified name (like "Test::More::ok") if the function
is not in the "main" namespace.

```
    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;
    $p5.call('print', 'Hello World');
    $p5.use('Test::More');
    $p5.call('Test::More::plan', tests => 1);

```

Please note that since Raku does not have the same concept of "context",
Perl 5 functions are by default called in list context. See "Invoking a
method in scalar context" for how to get around that.

## Create a Perl 5 object / call a Perl 5 package method

Creating Perl 5 objects works just the same as in Perl 5: invoke their
constructor (usually called "new").

```
    use Inline::Perl5;
    use Data::Dumper:from<Perl5>;
    my $dumper = Data::Dumper.new;

```

Or using the low level methods:

```
    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;
    $p5.use('Data::Dumper');
    my $dumper = $p5.invoke('Data::Dumper', 'new');

```

Please note that since Raku does not have the same concept of "context",
Perl 5 methods are by default called in list context. See "Invoking a
method in scalar context" for how to get around that.

## Invoke a method on a Perl 5 object

Once you have a Perl 5 object in a variable it will behave just like a Raku
object. You can call methods on it like on any other object.

```
    use IO::Compress::Bzip2:from<Perl5>;
    my $bzip2 = IO::Compress::Bzip2.new('/tmp/foo.bz2');
    $bzip2.print($data);
    $bzip2.close;

```

### Invoking a method in scalar context

Please note that since Raku does not have the same concept of "context",
Perl 5 methods are by default called in list context. If you need to call the
method in scalar context, you can tell it so explicitly, by passing the
`Scalar` type object as first argument:

```
    use IO::Compress::Bzip2:from<Perl5>;
    my $bzip2 = IO::Compress::Bzip2.new(Scalar, '/tmp/foo.bz2');
    $bzip2.print(Scalar, $data);
    $bzip2.close(Scalar);

```

This may be neccessary if the Perl 5 method exposes different behavior when
called in list and scalar context. Calling in scalar context may also improve
performance in some cases.

## Access a Perl 5 object's data directly

Most objects in Perl 5 are blessed hash references. Some of them don't even
provide accessor methods but require you to just access the hash fields
directly. This works the same in Raku:

```
    use Foo:from<Perl5>;
    my $foo = Foo.new;
    say $foo<some_attribute>;

```

## Run arbitrary Perl 5 code

Raku's EVAL function supports multiple languages, just like the "use"
statement. It allows for execution of arbitrary Perl 5 code given as string:

```
    EVAL "print 'Hello from Perl 5';", :lang<Perl5>;

```

The low level interface to this functionality is Inline::Perl5's run($str)
method:

```
    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;

    $p5.run(q'
        sub test {
            return Hello from Perl 5';
        }
    ');

```

Both "EVAL" and "run" return the value of the last statement in the EVAL'ed
code.

## Call a Raku function from Perl 5

Inline::Perl5 creates a Perl 5 package called "v6". This package contains
a "call" function which allows for calling Raku functions from Perl 5,
same as Inline::Perl5's "call" method. It takes the name of the function
to call and passes on any additional arguments and returns the return value
of the called Perl 5 function.

```
    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;

    our sub foo($str) {
        say "Raku says hello to $str";
    };

    $p5.run(q:to/PERL5/);
        v6::call("foo", "Perl 5");
    PERL5

```

## Invoke a method on a Raku object from Perl 5

Raku objects passed to Perl 5 functions will behave just like any other
objects in Perl 5, so you can invoke methods using the -> operator.

```
    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;

    $p5.run(q'
        sub test {
            my ($raku) = @_;
            $raku->hello;
        }
    );

    class Foo {
        method hello {
            say "Hello Raku";
        }
    }

    $p5.call('test', Foo.new);

```

## Run arbitrary Raku code from Perl 5

The "run" function in the automatically created "v6" package can be used to
execute arbitrary Raku code from Perl 5. It returns the value of the last
evaluated expression in the executed code.

```
    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;

    $p5.run(q:to/PERL5/);
        v6::run("say foo");
    PERL5

```

## Inherit from a Perl 5 class

Inline::Perl5 creates a corresponding Raku class for each Perl 5 module
loaded via the `use Foo:from` or `$p5.use('Foo')`
mechanisms.

You can subclass these automatically created classes as if they were original
Raku classes:

```
    use Data::Dumper:from<Perl5>;
    class MyDumper is Data::Dumper {
        has $.bar;
        method foo { say "foo!"; }
    }
    my $dumper = MyDumper.new([1], bar => 1);
    say $dumper.Dump();
    say $dumper.foo;
    say $dumper.bar;

```

You can override methods and the overridden methods will be called even by the
Perl 5 methods in your base class. However, it is not yet possible to directly
write to the Perl 5 object's data, i.e. `$self->{foo} = 1;`. Read
access however is possible, i.e. `my $foo = self;`.

When `use` cannot be used to load the Perl 5 module, the
Inline::Perl5::Perl5Parent role allows can be used for subclassing.
Pass the Perl 5 package's name as parameter to the role. Pass the Inline::Perl5
object as named parameter to your classes constructor when creating objects.

```
    $p5.run(q:heredoc/PERL5/);

    package Foo;

    sub test {
        my ($self) = @_;

        return $self->bar;
    }

    PERL5

    class Bar does Inline::Perl5::Perl5Parent['Foo'] {
        method bar {
            return "Raku";
        }
    }

    use Inline::Perl5;
    my $p5 = Inline::Perl5.new;
    say Bar.new(perl5 => $p5).test;

```

## Pass a scalar reference to Perl 5 code

Simply pass a [`Capture`](https://docs.raku.org/type/Capture) object containing
the object you want to pass as a reference:

```
    $p5obj.takes-a-scalar-ref-to-str: \("the string");

```

`HASH` and `ARRAY` references are made automatically if the Raku objects
are [containerized](https://perl6advent.wordpress.com/2017/12/02/):

```
    $p5obj.takes-an-array:      [<a b c>];
    $p5obj.takes-an-array-ref: $[<a b c>];

```

`CODE` objects are passed by reference automatically:

```
    $p5obj.takes-a-coderef: *.so;

```

`Regex` objects are passed by reference automatically:

```
    $p5obj.takes-a-regex: /foo/;

```

## Catch exceptions thrown by Perl 5 code

Perl 5's exceptions (die) are translated to X::AdHoc exceptions in Raku and
can be caught like any other Raku exceptions:

```
    {
        EVAL "die 'a Perl 5 exception!';", :lang<Perl5>;
        CATCH {
            when X::AdHoc {
                say "Caught a Perl 5 exception: $_";
            }
        }
    }

```

## Catch exceptions thrown by Raku code in Perl 5

Raku's exceptions (die) are translated to Perl 5 exceptions and
can be caught like any other Perl 5 exceptions:

```
    EVAL q:to:PERL5, :lang<Perl5>;
        use 5.10.0;
        eval {
            v6::run('die("test");');
        };
        say $@;
    PERL5

```

## Mix Perl 5 and Raku code in the same file

Inline::Perl5 creates a virtual module called "v6-inline". By saying
"use v6-inline;" in a Perl 5 module, you can declare that the rest of the file
is written in Raku:

```
    package Some::Perl5::Module;

    use v6-inline;

    has $.name;

    sub greet {
        say "Hello $.name";
    }

```

Note that this Perl 5 module obviously will only work when Inline::Perl5 is
loaded, i.e. in a Raku program or if you are using Inline::Perl6 in Perl 5.
This functionality is aimed at supporting Perl 5 frameworks (think Catalyst
or DBIx::Class or Dancer or ...) that automatically load modules and of course
expect these modules to be written in Perl 5.

# BUILDING

The oldest rakudo version supported is 2019.03.1.
The oldest perl version supported is 5.20.0.

You will need a perl 5 built with the -fPIC option (position independent
code). Most distributions build their Perl 5 that way. When you use perlbrew,
you have to build it as:

```
perlbrew install perl-stable -Duseshrplib

```

(or, if you want to use more than one Inline::Perl5 interpeter safely, for
instance from within Raku threads, add the `-Dusemultiplicity` option as well)

If you use plenv:

```
plenv install 5.24.0 -Duseshrplib

```

If you use the perl that comes with a Linux distribution, you may need to
install a separate package containing the perl library. Consult the table below
or the distribution documentation for details.

| Distribution | Package name |
| --- | --- |
| Fedora/Red Hat/CentOs | perl-libs |
| Debian/Ubuntu/Linux Mint | libperl-dev |
| openSUSE | perl |
| Arch Linux/Manjaro | perl |

Build Inline::Perl5 with

```
raku configure.pl6
make

```

and test with

```
make test

```

and install with

```
make install

```

# AUTHOR

Stefan Seifert [nine@detonation.org](mailto:nine@detonation.org)


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

# NAME

rak - plumbing to be able to look for stuff

# SYNOPSIS

```
use rak;

# look for "foo" in all .txt files from current directory
my $rak = rak / foo /, :file(/ \.txt $/);

# show results
for $rak.result -> (:key($path), :value(@found)) {
    if @found {
        say "$path:";
        say .key ~ ':' ~ .value for @found;
    }
}

```

# DESCRIPTION

The `rak` subroutine provides a mostly abstract core search (plumbing) functionality to be used by modules such as (porcelain) `App::Rak`.

# THEORY OF OPERATION

The `rak` subroutine basically goes through 6 steps to produce a `Rak` object.

### 1. Acquire sources

The first step is determining the objects that should be searched for the specified pattern. If an object is a `Str`, it will be assumed that it is a path specification of a file to be searched in some form and an `IO::Path` object will be created for it.

Related named arguments are (in alphabetical order):

| argument | meaning |
| --- | --- |
| :dir | filter for directory basename check to include |
| :file | filter for file basename check to include |
| :files-from | file containing filenames as source |
| :ioify | code to create IO::Path-like objects with |
| :paths | paths to recurse into if directory |
| :paths-from | file containing paths to recurse into |
| :recurse-symlinked-dir | recurse into symlinked directories |
| :recurse-unmatched-dir | recurse into directories not matching :dir |
| :sources | list of objects to be considered as source |
| :under-version-control | only include paths under version control |

The result of this step, is a (potentially lazy and hyperable) sequence of objects.

### 2. Filter applicable objects

Filter down the list of sources from step 1 on any additional filesystem related properties. This assumes that the list of objects created are strings of absolute paths to be checked (except where otherwise indicated).

| argument | meaning |
| --- | --- |
| :accept | given an IO::Path, is path acceptable |
| :accessed | when was path last accessed |
| :blocks | number of filesystem blocks |
| :created | when was path created |
| :deny | given an IO::Path, is path NOT acceptable |
| :device-number | device number on which path is located |
| :exec | run program, include if successful |
| :filesize | size of the path in bytes |
| :gid | numeric gid of the path |
| :hard-links | number of hard-links to path on filesystem |
| :has-setgid | has SETGID bit set in attributes |
| :has-setuid | has SETUID bit set in attributes |
| :inode | inode of path on filesystem |
| :is-empty | is path empty (filesize == 0) |
| :is-executable | is path executable by current user |
| :is-group-executable | is path executable by group |
| :is-group-readable | is path readable by group |
| :is-group-writable | is path writable by group |
| :is-moarvm | is path a MoarVM bytecode file |
| :is-owned-by-group | is path owned by group of current user |
| :is-owned-by-user | is path owned by current user |
| :is-owner-executable | is path executable by owner |
| :is-owner-readable | is path readable by owner |
| :is-owner-writable | is path writable by owner |
| :is-pdf | is path a PDF file |
| :is-readable | is path readable by current user |
| :is-sticky | has STICKY bit set in attributes |
| :is-symbolic-link | is path a symbolic link |
| :is-text | does path contains text? |
| :is-world-executable | is path executable by any user |
| :is-world-readable | is path readable by any user |
| :is-world-writable | is path writable by any user |
| :is-writable | is path writable by current user |
| :meta-modified | when meta information of path was modified |
| :mode | the mode of the path |
| :modified | when path was last modified |
| :shell | run shell command, include if successful |
| :uid | numeric uid of path |

The result of this step, is a (potentially lazy and hyperable) sequence of objects.

### 3. Produce items to search in (apply transformers)

The third step is to create the logic for creating items to search in from the objects in step 2. If search is to be done per object, then `.slurp` is called on the object. Otherwise `.lines` is called on the object. Unless one provides their own logic for producing items to search in.

Related named arguments are (in alphabetical order):

| argument | meaning |
| --- | --- |
| :encoding | encoding to be used when creating items |
| :find | map sequence of step 1 to item producer |
| :produce-one | produce one item per given source |
| :produce-many | produce zero or more items by given source |
| :produce-many-pairs | produce zero or more items by given source as pairs |
| :omit-item-number | do not store item numbers in result |
| :with-line-ending | produce lines with line endings |

The result of this step, is a (potentially lazy and hyperable) sequence of objects.

### 4. Create logic for matching

Take the logic of the pattern `Callable`, and create a `Callable` to do the actual matching with the items produced in step 3.

Related named arguments are (in alphabetical order):

| argument | meaning |
| --- | --- |
| :invert-match | invert the logic of matching |
| :old-new | produce pairs of old/new state |
| :quietly | absorb any warnings produced by the matcher |
| :silently | absorb any output done by the matcher |
| :stats | produce results and full statistics |
| :stats-only | don't produce results, just statistics |

### 5. Create logic for running

Take the matcher logic of the `Callable` of step 4 and create a runner `Callable` that will produce the items found and their possible context (such as extra items before or after). Assuming no context, the runner changes a return value of `False` from the matcher into `Empty`, a return value of `True` in the original item, and passes through any other value.

Related named arguments are (in alphabetical order):

| argument | meaning |
| --- | --- |
| :also-first | initial items to show if there is a match |
| :always-first | initial items to show always |
| :after-context | number of items to show after a match |
| :before-context | number of items to show before a match |
| :context | number of items to show around a match |
| :paragraph-context | items around match until false item |
| :passthru-context | pass on \*all\* items if there is a match |
| :max-matches-per-source | max # of matches per source |
| :passthru | pass on \*all\* items always |

Matching items are represented by `PairMatched` objects, and items that have been added because of the above context arguments, are represented by `PairContext` objects. Unless `:omit-item-number` has been specified with a trueish value, in which case items will always be just a string, whether they matched or not (if part of a context specification).

### 6. Run the sequence(s)

The final step is to take the `Callable` of step 5 and run that repeatedly on the sequence of step 3. Make sure any phasers (`FIRST`, `NEXT` and `LAST`) are called at the appropriate time in a thread-safe manner. Inside the `Callable` of step 5, the dynamic variable `$*SOURCE` will be set to the source of the items being checked.

Either produces a sequence in which the key is the source, and the value is a `Slip` of `Pair`s where the key is the item-number and the value is item with the match, or whatever the pattern matcher returned.

Or, produces sequence of whatever a specified mapper returned and/or with uniqueifying enabled.

Related named arguments are (in alphabetical order):

| argument | meaning |
| --- | --- |
| :categorize | classify items according to zero or more keys |
| :classify | classify items according to a single key |
| :eager | produce all results before creating Rak object |
| :frequencies | produce items and their frequencies |
| :map-all | also call mapper if a source has no matches |
| :mapper | code to map results of a single source |
| :progress | code to show progress of running |
| :sort | sort the result of :unique |
| :sort-sources | sort the sources before processing |
| :sources-only | only produce the source of any match |
| :sources-without-only | produce the source without any match |
| :unique | only produce unique items |

# EXPORTED CLASSES

## Rak

The return value of a `rak` search. Contains the following attributes:

### completed

A `Bool` indicating whether the search has already been completed.

### exception

Any `Exception` object that was caught.

### nr-changes

Number of items (that would have been) changed.

### nr-items

Number of items inspected.

### nr-matches

Number of items that matched.

### nr-passthrus

Number of items that have passed through.

### nr-sources

Number of sources seen.

### result

A `Seq` with search results. This could be a lazy `Seq` or a `Seq` on a fully vivified `List`.

### stats

A `Map` with any statistics collected (so far, in case an exception was thrown). If the `Map` is not empty, it contains the following keys:

| argument | meaning |
| --- | --- |
| nr-sources | number of sources seen |
| nr-items | number of items inspected |
| nr-matches | number of items that matched |
| nr-passthrus | number of items that have passed through |
| nr-changes | number of items that would have been changed |

If the `Map` is empty, then no statistics (other than `nr-sources`) have been collected.

Note that if the result is lazy, then the statistics won't be complete until every result has been processed.

## PairContext

A subclass of `Pair` of which both the `matched` **and** `changed` method return `False`. Used for non-matching items when item-numbers are required to be returned and a certain item context was requested.

## PairMatched

A subclass of `PairContext` of which the `matched` method returns `True`, but the `changed` method returns `False`. Used for matching items when item-numbers are required to be returned.

## PairChanged

A subclass of `PairMatched` of which the `matched` **and** `changed` method return `True`. Used for changed items when item-numbers are required to be returned.

## Progress

Passed to the `:progress` `Callable` 5 times per second while searching is taking place. It provides several methods that allow a search application to show what is going on.

### nr-changes

Number of items (that would have been) changed. Continuously updated if the search has not been completed yet.

### nr-items

Number of items inspected. Continuously updated if the search has not been completed yet.

### nr-matches

Number of items that matched. Continuously updated if the search has not been completed yet.

### nr-passthrus

Number of items that have passed through. Continuously updated if the search has not been completed yet.

### nr-sources

Number of sources seen. Continuously updated if the search has not been completed yet.

# EXPORTED SUBROUTINES

## rak

The `rak` subroutine takes a `Callable` (or `Regex`) pattern as the only positional argument and quite a number of named arguments. Or it takes a `Callable` (or `Regex`) as the first positional argument for the pattern, and a hash with named arguments as the second positional argument. In the latter case, the hash will have the arguments removed that the `rak` subroutine needed for its configuration and execution.

### Return value

A `Rak` object (see above) is always returned. The object provides three attributes: `result` (with the result `Iterable`), `completed` (a Bool indicating whether all searching has been done already), and `exception` (any `Exception` object or `Nil`).

Additionally it provides five methods that allow you to monitor progress and/or provide statistics at the end of a search. They are: `nr-sources`, `nr-items`, `nr-matches`, `nr-changes`, `nr-passthrus`.

#### Result Iterable

If the `:unique` argument was specified with a trueish value, then the result `Iterable` will just produce the unique values that were either explicitely returned by the matcher, or the unique items that matched.

Otherwise the value is an `Iterable` of `Pair`s which contain the source object as key (by default the absolute path of the file in which the pattern was found).

If there was only one item produced per source, then the value will be that value, or whatever was produced by the matching logic.

Otherwise the value will be a `Slip`. If no item numbers were requested, each element contains the result of matching. If item-numbers were requested, each element is a `Pair`, of which the key is the item-number where the pattern was found, and the value is the product of the search (which, by default, is the item in which the pattern was found).

In a graph:

```
rak(...)
 |- Rak
     |- exception: Exception object or Nil
     |- nr-sources: number of sources seen
     |- nr-items: number of items seen
     |- nr-matches: number of matches seen
     |- nr-changes: number of changes (that could be) done
     |- nr-passthrus: number of passthrus done
     |- completed: Bool whether all searching done already
     |- result: Iterable
          |- Pair
          |   |- key: source object
          |   |- value:
          |        |- Slip
          |        |   |- PairMatched|PairContext
          |        |   |   |- key: item-number
          |        |   |   \- value: match result
          |        |   or
          |        |   \- match result
          |        or
          |        \- single item match result
          or
          \- unique match result

```

### Named Arguments

The following named arguments can be specified (in alphabetical order):

#### :accept(&filter)

If specified, indicates a `Callable` filter that will be given an `IO::Path` of the path. It should return `True` if the path is acceptable.

#### :accessed(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **access** time of the path. The `Callable` is passed a `Num` value of the access time (number of seconds since epoch) and is expected to return a trueish value to have the path be considered for further selection.

#### :after-context(N)

Indicate the number of items that should also be returned **after** an item with a pattern match. Defaults to **0**.

#### :also-first(N)

Indicate the number of initial items to be produced **if** there is an item with a pattern match. Defaults to **0**. If specified as a flag, will assume **1**.

#### :always-first(N)

Indicate the number of initial items to be **always** be produced regardless whether there is an item with a pattern match or not. Defaults to **0**. If specified as a flag, will assume **1**.

#### :batch(N)

When hypering over multiple cores, indicate how many items should be processed per thread at a time. Defaults to whatever the system thinks is best (which **may** be sub-optimal).

#### :before-context(N)

Indicate the number of items that should also be returned **before** an item with a pattern match. Defaults to **0**.

#### :blocks(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **number of blocks** used by the path on the filesystem on which the path is located. The `Callable` is passed the number of blocks of a path and is expected to return a trueish value to have the path be considered for further selection.

#### :categorize(&categorizer)

If specified, indicates the `Callable` that should return zero or more keys for a given item to have it categorized. This effectively replaces the source if an item by any of its key in the result. The result will contain the key/item(s) pairs ordered by most to least number of items per key.

#### :classify(&classifier)

If specified, indicates the `Callable` that should return a key for a given item to have it classified. This effectively replaces the source if an item by its key in the result. The result will contain the key/item(s) pairs ordered by most to least number of items per key.

#### :context(N)

Indicate the number of items that should also be returned around an item with a pattern match. Defaults to **0**.

#### :created(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **creation** time of the path. The `Callable` is passed a `Num` value of the creation time (number of seconds since epoch) and is expected to return a trueish value to have the path be considered for further selection.

#### :degree(N)

When hypering over multiple cores, indicate the maximum number of threads that should be used. Defaults to whatever the system thinks is best (which **may** be sub-optimal).

#### :deny(&filter)

If specified, indicates a `Callable` filter that will be given an `IO::Path` of the path. It should return `True` if the path is **NOT** acceptable.

#### :device-number(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **device number** of the path. The `Callable` is passed the device number of the device on which the path is located and is expected to return a trueish value to have the path be considered for further selection.

#### :dir(&dir-matcher)

If specified, indicates the matcher that should be used to select acceptable directories with the `paths` utility. Defaults to `True` indicating **all** directories should be recursed into. Applicable for any situation where `paths` is used to create the list of files to check.

#### :dont-catch

Flag. If specified with a trueish value, will **not** catch any error during processing, but will throw any error again. Defaults to `False`, making sure that errors **will** be caught.

#### :eager

Flag. If specified with a trueish value, will **always** produce **all** results before returning the `Rak` object. Defaults to `False`, making result production lazy if possible.

#### :encoding("utf8-c8")

When specified with a string, indicates the name of the encoding to be used to produce items to check (typically by calling `lines` or `slurp`). Defaults to `utf8-c8`, the UTF-8 encoding that is permissive of encoding issues.

#### :exec($invocation)

If specified, indicates the name of a program and its arguments to be executed. Any `$_` in the invocation string will be replaced by the file being checked. The file will be included if the program runs to a successful conclusion.

#### :file(&file-matcher)

If specified, indicates the matcher that should be used to select acceptable files with the `paths` utility. Defaults to `True` indicating **all** files should be checked. Applicable for any situation where `paths` is used to create the list of files to check.

If the boolean value `False` is specified, then only directory paths will be produced. This only makes sense if `:find` is also specified.

#### :filesize(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **number of bytes** of the path. The `Callable` is passed the number of bytes of a path and is expected to return a trueish value to have the path be considered for further selection.

#### :files-from($filename)

If specified, indicates the name of the file from which a list of files to be used as sources will be read.

#### :find

Flag. If specified, maps the sources of items into items to search.

#### :frequencies

Flag. If specified, produces key/value `Pair`s in which the key is the item, and the value is the frequency with which the item was seen.

#### :gid(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **gid** of the path. The `Callable` is passed the numeric gid of a path and is expected to return a trueish value to have the path be considered for further selection. See also `owner` and `group` filters.

#### :hard-links(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **number of hard-links** of the path. The `Callable` is passed the number of hard-links of a path and is expected to return a trueish value to have the path be considered for further selection.

#### :has-setgid

Flag. If specified, indicates paths that have the SETGID bit set in their attributes, are (not) acceptable for further selection. Usually only makes sense when uses together with `:find`.

#### :has-setuid

Flag. If specified, indicates paths that have the SETUID bit set in their attributes, are (not) acceptable for further selection. Usually only makes sense when uses together with `:find`.

#### :inode(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **inode** of the path. The `Callable` is passed the inode of a path and is expected to return a trueish value to have the path be considered for further selection.

#### :invert-match

Flag. If specified with a trueish value, will negate the return value of the pattern if a `Bool` was returned. Defaults to `False`.

#### :ioify(&coercer)

If specified, indicates the `Callable` that will be called with a path and which should return an object on which `.lines` and `.slurp` can be called. Defaults to `*.IO`, creating an `IO::Path` object by default.

#### :is-empty

Flag. If specified, indicates paths, that are empty (aka: have a filesize of 0 bytes), are (not) acceptable for further selection. Usually only makes sense when uses together with `:find`.

#### :is-executable

Flag. If specified, indicates paths, that are **executable** by the current **user**, are (not) acceptable for further selection.

#### :is-group-executable

Flag. If specified, indicates paths, that are **executable** by the current **group**, are (not) acceptable for further selection.

#### :is-group-readable

Flag. If specified, indicates paths, that are **readable** by the current **group**, are (not) acceptable for further selection.

#### :is-group-writable

Flag. If specified, indicates paths, that are **writable** by the current **group**, are (not) acceptable for further selection.

#### :is-moarvm

Flag. If specified, indicates only paths that are `MoarVM` bytecode files are (not) acceptable for further selection.

#### :is-owned-by-group

Flag. If specified, indicates only paths that are **owned** by the **group** of the current user, are (not) acceptable for further selection.

#### :is-owned-by-user

Flag. If specified, indicates only paths that are **owned** by the current **user**, are (not) acceptable for further selection.

#### :is-owner-executable

Flag. If specified, indicates paths, that are **executable** by the owner, are (not) acceptable for further selection.

#### :is-owner-readable

Flag. If specified, indicates paths, that are **readable** by the owner, are (not) acceptable for further selection.

#### :is-owner-writable

Flag. If specified, indicates paths, that are **writable** by the owner, are (not) acceptable for further selection.

#### :is-pdf

Flag. If specified, indicates only paths that are `PDF` files are (not) acceptable for further selection.

#### :is-readable

Flag. If specified, indicates paths, that are **readable** by the current **user**, are (not) acceptable for further selection.

#### :is-sticky

Flag. If specified, indicates paths that have the STICKY bit set in their attributes, are (not) acceptable for further selection. Usually only makes sense when uses together with `:find`.

#### :is-symbolic-link

Flag. If specified, indicates only paths that are symbolic links, are (not) acceptable for further selection.

#### :is-text

Flag. If specified, indicates only paths that contain text are (not) acceptable for further selection.

#### :is-world-executable

Flag. If specified, indicates paths, that are **executable** by any user or group, are (not) acceptable for further selection.

#### :is-world-readable

Flag. If specified, indicates paths, that are **readable** by any user or group, are (not) acceptable for further selection.

#### :is-world-writeable

Flag. If specified, indicates paths, that are **writable** by any user or group, are (not) acceptable for further selection.

#### :is-writable

Flag. If specified, indicates paths, that are **writable** by the current **user**, are (not) acceptable for further selection.

#### :mapper(&mapper)

If specified, indicates the `Callable` that will be called (in a thread-safe manner) for each source, with the matches of that source. The `Callable` is passed the source object, and a list of matches, if there were any matches. If you want the `Callable` to be called for every source, then you must also specify `:map-all`.

Whatever the mapper `Callable` returns, will become the result of the call to the `rak` subroutine. If you don't want any result to be returned, you can return `Empty` from the mapper `Callable`.

#### :map-all

Flag. If specified with a trueish value, will call the mapper logic, as specified with `:mapper`, even if a source has no matches. Defaults to `False`.

#### :max-matches-per-source(N)

Indicate the maximum number of items that may be produce per source. Defaults to **all** (which can also be specified by a falsish value).

#### :meta-modified(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **modification** time of the path. The `Callable` is passed a `Num` value of the modification time (number of seconds since epoch) and is expected to return a trueish value to have the path be considered for further selection.

#### :mode(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **mode** of the path. The `Callable` is passed the mode of a path and is expected to return a trueish value to have the path be considered for further selection. This is really for advanced types of tests: it's probably easier to use any of the `readable`, `writeable` and `executable` filters.

#### :modified(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **modification** time of the path. The `Callable` is passed a `Num` value of the modification time (number of seconds since epoch) and is expected to return a trueish value to have the path be considered for further selection.

#### :old-new

Flag. If specified with a trueish value, will produce `Pair`s of the current value being investigated, and whatever was returned by the `Callable` pattern for that value (if what was returned was **not** a `Bool`, `Empty` or `Nil`) **if** that value was different from the original value. Defaults to `False`, meaning to just produce according to what was returned.

#### :omit-item-number

Flag. If specified with a trueish value, won't produce any `PairMatched` or `PairContext` objects in the result, but will just produce the result of the match. Defaults to `False`, meaning to include item numbers.

#### :paragraph-context

Flag. If specified with a trueish value, produce items **around** the empty with a pattern match until a falsish item is encountered.

#### :passthru

Flag. If specified with a trueish value, produces **all** items always.

#### :passthru-context

Flag. If specified with a trueish value, produces **all** items if there is at least one match.

#### :paths-from($filename)

If specified, indicates the name of the file from which a list of paths to be used as the base of the production of filename with a `paths` search.

#### :paths(@paths)

If specified, indicates a list of paths that should be used as the base of the production of filename with a `paths` search. If there is no other sources specification (from either the `:files-from`, `:paths-from` or `:sources`) then the current directory (aka ".") will be assumed. If that directory appears to be the top directory in a git repository, then `:under-version-control` will be assumed, only producing files that are under version control under that directory.

#### :produce-many(&producer)

If specified, indicates a `Callable` that will be called given a source, and is expected to produce zero or more items to be inspected. Defaults to a producer that calles the `lines` method on a given source, with the `:encoding` and `:with-line-ending` arguments.

The `Callable` should return `Empty` if for some reason nothing could be produced.

#### :produce-many-pairs(&producer)

If specified, indicates a `Callable` that will be called given a source, and is expected to produce zero or more `PairContext` objects to be inspected, in which the key represents the item number.

This option will set the `:omit-item-number` option to `False`.

The `Callable` should return `Empty` if for some reason nothing could be produced.

#### :produce-one(&producer)

If specified, indicates a `Callable` that will be called given a source, and is expected to produce one items to be inspected.

The `Callable` should return `Nil` if for some reason nothing could be produced).

#### :progress(&announcer)

If specified, indicates a `Callable` that will be called 5 times per second to indicate how the search action is progressing. It will either be called with a `Progress` object (while the search action is still progressing) or **without** any arguments to indicate that search has completed.

#### :recurse-symlinked-dir

Flag. If specified with a trueish value, will recurse into directories that are actually symbolic links. The default is `False`: do **not** recurse into symlinked directories.

#### :recurse-unmatched-dir

Flag. If specified with a trueish value, will recurse into directories that did **not** pass the :. No files will ever be produced from such directories, but further recursion will be done if directories are encountered. The default is `False`: do **not** recurse into directories that didn't match the `:dir` specification.

#### :quietly

Flag. If specified with a trueish value, will absorb any warnings that may occur when looking for the pattern.

#### :shell($invocation)

If specified, indicates the command(s) to be executed in a shell. Any `$_` in the invocation string will be replaced by the file being checked. The file will be included if the shell command(s) run to a successful conclusion.

#### :silently("out,err")

When specified with `True`, will absorb any output on STDOUT and STDERR. Optionally can only absorb STDOUT ("out"), STDERR ("err") and both STDOUT and STDERR ("out,err").

#### :sort(&logic)

When specified with `True`, will sort the result alphabetically (using foldcase logic). Can also be specified with a `Callable`, which should contain the logic sorting (just as the argument to the `.sort` method).

Only supported with `:unique` at this time.

#### :sort-sources(&logic)

When specified with `True`, will sort the sources alphabetically (using foldcase logic). Can also be specified with a `Callable`, which should contain the logic sorting (just as the argument to the `.sort` method).

#### :sources(@objects)

If specified, indicates a list of objects that should be used as a source for the production of items. Which generally means they cannot be just strings.

#### :sources-only

Flag. If specified with a trueish value, will only produce the source of a match once per source. Defaults to `False`.

#### :sources-without-only

Flag. If specified with a trueish value, will only produce the source of a match if there is **not** a single match. Defaults to `False`.

#### :stats

Flag. If specified with a trueish value, will keep stats on number number of items seen, number of matches, number of changes and number of passthrus. Stats on number of sources seen, will always be kept.

Note that on lazy results, the statistics won't be complete until all results have been processed.

#### :stats-only

Flag. If specified with a trueish value, will perform all searching, but only update counters and not produce any result. The statistics will be available in `nr-xxx` methods, and the `result` attribute will be `Empty`. Note that this causes eager evaluation.

#### :uid(&filter)

If specified, indicates the `Callable` filter that should be used to select acceptable paths by the **uid** of the path. The `Callable` is passed the numeric uid of a path and is expected to return a trueish value to have the path be considered for further selection. See also `owner` and `group` filters.

#### :under-version-control($name = 'git')

If specified, indicates that any path specification that is a directory, should be considered as the root of a directory structure under some form of version control. If specified as `True`, will assume `git`. If such a path is under version control, then only files that are actually controlled, will be produced for further inspection. If it is **not** under version control, **no** files will be produced.

Currently, only `git` is supported.

#### :unique

Flag. If specified, indicates that only unique matches will be returned, instead of the normal sequence of source => result pairs.

#### :with-line-ending

Flag. If specified, indicates line endings are to be kept when producing items to check. Defaults to `False`, meaning that line endings are removed from items to check. Only applicable with line-based checking.

## PATTERN RETURN VALUES

The return value of the pattern `Callable` match is interpreted in the following way:

### True

If the `Bool`ean True value is returned, assume the pattern is found. Produce the item unless `:invert-match` was specified.

### False

If the `Bool`ean False value is returned, assume the pattern is **not** found. Do **not** produce the item unless `:invert-match` was specified.

### Nil

If `Nil` is returned, assume the pattern is **not** found. This can typically happen when a `try` is used in a pattern, and an execution error occurred. Do **not** produce the item unless `:invert-match` was specified.

### Empty

If the empty `Slip` is returned, assume the pattern is **not** found. Do **not** produce the item unless `:invert-match` was specified. Shown in stats as a `passthru`.

### any other value

Produce that value.

## PHASERS

Any `FIRST`, `NEXT` and `LAST` phaser that are specified in the pattern `Callable`, will be executed at the correct time.

## MATCHED ITEMS vs CONTEXT ITEMS

The `Pair`s that contain the search result within an object, have an additional method mixed in: `matched`. This returns `True` for items that matched, and `False` for items that have been added because of a context specification (`:context`, `:before-context`, `:after-context`, `paragraph-context` or `passthru-context`).

These `Pair`s can also be recognized by their class: `PairMatched` versus `PairContext`, which are also exported.

# AUTHOR

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

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

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

# COPYRIGHT AND LICENSE

Copyright 2022, 2023, 2024, 2025 Elizabeth Mattijsen

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


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

# NAME

**App::Gitstatus** - Provides an installed program, `git-status-check`, to help maintain a directory of Git repositories

# SYNOPSIS

Execute `git-status-check` without arguments to see its capabilities:

```
$ git-status-check # OUTPUT:
Usage: git-status-check <dir> [...options...]

Checks the Git status of all directories under
directory 'dir' which are 'dirty' (i.e., having
a non-zero 'Git::Status') and lists those
directories.

Options:
  all        - report details of all dirty directories
  first      - report the first directory only
  last       - report the last directory only
  ignore=/X/ - ignore directory names satisfying regex /X/
  select=/X/ - select directory names satisfying regex /X/
  debug

```

# DESCRIPTION

The installed program will be very useful for any user who has to maintain many Git repositories, especially when the user has to keep those same repositories synchronized on multiple hosts.

# CREDITS

A big tip of my hat to prolific Raku module author and major core developer, Elizabeth Mattijsen (AKA @lizmat) for her very useful `Git::Status` module which this module depends upon.

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


## dist_github-donaldh-RPi-GpioDirect.md
# RPi::GpioDirect

Access the Raspberry Pi GPIO

## Overview

The RPi::GpioDirect module provides access to the Raspberry Pi GPIO without any dependency on C libraries.
RPi::GpioDirect makes use of /dev/gpiomem so that it can run without elevated privileges.

RPi::GpioDirect has only been tested with a Raspberry Pi 3 but is likely to work with a Pi 2. RPi::GpioDirect is also
dependent on a kernel with /dev/gpiomem.

## Installation

```
$ panda install RPi::GpioDirect

```

## Usage

```
use RPi::GpioDirect;

my $pi = RPi::GpioDirect.new;

say 'Pin  Name      Value  Mode';
for $pi.gpio-pins -> $pin {
    say sprintf('%2s   %-8s  %5s  %4s',
                $pin, $pi.pin-name($pin), $pi.read($pin), $pi.function($pin)
               );
}

say '';
say 'Pin  Name      Value';
for 11, 12 -> $pin {
    $pi.set-function($pin, Out);
    for Off, On, Off, On -> $value {
        $pi.write($pin, $value);
        say sprintf('%2s   %-8s  %5s',
                    $pin, $pi.pin-name($pin), $pi.read($pin));
    }
}

```

## Author

Donald Hunter - donaldh @ #perl6


## dist_zef-finanalyst-Elucid8-Build.md
# Build a website from current directory

```
The Build component for the Elucid8 framework

```

---

## Table of Contents

[SYNOPSIS](#SYNOPSIS)
[Assumptions](#Assumptions)
[Plugins](#Plugins)
[Render workflow](#Render_workflow)
[Configuration](#Configuration)
  - [All configuration keys](#All_configuration_keys)
[Credits](#Credits)
[VERSION](#VERSION_0)

## SYNOPSIS

The component is part of the `Elucid8` distribution and is installed as

```
    zef install Elucid8-build

```

The utility `elucid8-build` will generate a static website according to the [configuration](Configuration) in the Current Working Directory (CWD).

If the CWD is empty, `elucid8-build install` will create a default structure

If the CWD has a custom (localised) config file, which may be any localised name, and the contents have the keys required (in English) but with localised values (eg. Kostom), then `elucid8-build --config=Kostom --install` then the subdirectories will be localised as well.

Elucid8 may be used in two ways:

1. All the RakuDoc sources are in the main website directory, under the `sources` subdirectory.
2. The RakuDoc sources may be located in various repositories.

For the second scenario, the `gather-sources` utility is used first. See [Gather and Build](Build-Gather.md) for more information.

Once the website has been built, the `run-locally` utility will serve the HTML files, and can be browsed in a browser as `localhost:3000`. (The port can be changed in the plugins-configuration config).

Run `elucid8-build -h` to get information on command line flags.

Subsequent calls to `elucid8-build` will only rebuild modified source files, but see *-f* and *-with-only*

## Assumptions

The Build component of Elucid8 assumes the following structure.

```
sandpit                      # a test bed for a web site built with elucid8
    - config/                 # contains the website configuration
    - misc/                  # contains the dictionaries from the canonical to derived languages
    - sources/               # Only directories containing language sources permitted here
      - canonical/           # RakuDoc content in canonical language, which is en by default
      - xx/                  # content in language with code xx
      - xx-YY/               # regional content in language with code xx-YY

```

All names in the structure, except for `config/`, may be modified by changing fields in the files in `config/`.

The name of the ****config/**** directory may be changed by setting the `--config` option to `elucid8-build`. For example, if the canonical language is Mandarin, and the term used to mean 'config' is `布局`, then

```
elucid8-build --config=<布局>

```

will set the configuration directory *布局*. This will be called the *localised config*.

## Plugins

The following HTML plugins are available:

1. [UISwitcher](UISwitcher.md)
2. SiteMap - creates `sitemap.xml` which can be read by robots
3. AutoIndex - creates a `landing-page` file for the whole website from all glue files

Each website can have its own plugins, stored in `local-lib`

## Render workflow

For each human language (h-language), the sources files in the appropriately named sub-directory of `sources` (or local equivalent), each generate a separate web page.

> Elucid8 is being designed for large websites and currently these are not optimally viewed using the *single page* paradigm. In the future, this view may change, in which case, each source will generate a section of the page.

The source files in an h-language directory are of two sorts:

1. content

sources that are the basis of the website. They may contain explicit links to other pages.

2. glue

sources that are automatically generated to contain links to web pages generated by content (and possibly other glue) sources.

3. info

sources that contain site information not to be included in the search, such License or about.

4. landing-page

the name of the web page that is the default for a browser. By default it is auto-generated from the TITLEs and SUBTITLEs of the glue files in each h-language.

Consequently,

1. content web pages must be generated first
2. info web pages must be generated next
3. glue web pages must be generated after all content sources
4. glue pages must be rendered in an explicit order
5. if no content sources have changed since the last rendering, then glue web pages do not need to be re-generated, unless a glue source has itself been modified.

In addition,

1. a change in a canonical content source should trigger a change of style in the [equivalent content file](Canonical<->derived links)
2. editing of derived sources will be more frequent than editing of the canonical sources

For simplicity and initial development, the following are required:

1. glue sources must be exist for each language (no super-language glue sources)
2. the filename of each glue source must be the same in each directory
3. content sources are implicitly assigned a generation order of zero
4. the name and generation order of each glue source is defined in the config directory

Consequently, the render order is as follows:

1. the canonical language sources must be rendered first
2. a content source is only re-generated if:

2.1. the force flag is True

2.2. there is no existing rendered file with the same name

2.3. the content source is newer than the generate file

1. if a canonical content source is re-generated, the equivalent source in all of the h-language directories must be re-generated too
2. if a source (content or glue) is regenerated, all the glue files at the next generation order must be re-generated
3. if no sources are regenerated at some level, then the glue sources at the next generation order do not need to be regenerated **unless** the glue source itself is modified. (This implies that changes cascade up the regeneration order)
4. the sources in each derived language are rendered in an unspecified order of languages
5. a content source is only re-generated if:

7.1. the force flag is True

7.2. the equivalent canonical source was rendered in this build cycle

7.3. there is no existing rendered file with the same name

7.4. the content source is newer than the generated file

1. the glue sources are generated as per the canonical glue sources
2. the **landing-page** is generated

9.1. By default, a web page with the name **landing-page**\*.html\* is auto-generated

9.2. If a source with the name **landing-page**\*.rakudoc\* exists in the ****sources**** directory, it is used to generate the landing page. A custom block is defined to add the glue contents that are auto-generated.

## Configuration

A directory called `config/` (or its preconfigured alternative) is required in the CWD.

The ****config/**** directory follows the conventions set out in the distribution `raku-config`.

If a *localised config* has been specified, then one key must be called by the same name, and must contain a hash in which the key is a key of the default (English) *config* and the value is a string that is a key in the localised config.

If some of the keys in the default are missing in the localised config, then the value of the default config is used.

This allows for some or all of the configuration to be specified in a canonical language other than English.

The full set of [configuration keys](All configuration keys) and their defaults are in English.

For example, suppose we have a web-site where Welsh is the canonical language and the *config* file is partially in Welsh. Suppose further that the build command is:

```
    elucid8-build --config=ffurfwedd

```

Then in this case, the directory `ffurfwedd/` should contain a file, typically named *01-ffurfwedd.raku*, with the content:

```
    ffurfwedd => %(
        sources => 'ffynhonnell',
        canonical => 'gofyddebol',
        Misc => 'lleoliad',
    )

```

Then the web-site would need to be structured as follows

```
<web-site directory>/
|- config/
|- lleoliad/
|- ffurfwedd/
    |- 01-ffurfwedd.raku
|- ffynhonnell/
    |- gofyddebol/
    |- en-GB/

```

The **config** directory and its contents are needed because the localised config is incomplete.

If **all** the mandatory config keys are defined in the *localised config*, and all the keys have values, then the default can be removed.

### All configuration keys

The following is a list of all the mandatory config keys and their default values.

| **Key name** | **Value** | **Description** |
| --- | --- | --- |
| misc | misc | the directory containing global information for translation, and file-data, repo-info |
| sources | sources | content as RakuDoc sources, sub-directories are for content by language. See repositories |
| canonical | canonical | sub-directory of sources containing content, only sub-dir that needs defining in the config file |
| extensions | <rakudoc rakumod> | an array of file extensions containing source |
| quiet | False | output runtime progress information |
| with-only | () | a list of strings or regexes, matching filenames only will be rendered (useful for debugging) |
| ignore | () | list of strings or regexes, matching files will not be rendered |
| publication | 'publication' | directory relative to CWD where HTML and assets are rendered |
| landing-page | 'index' | the name of the page that is the default route for a web-site |
|  | The plugins needed are more easily kept in a separate file, typically `02-plugins.raku` |  |
| plugins | <Bulma Hilite ListFiles> | plugins attached to the Rendering engine ***packaged with rakuast-rakudoc-render*** |
| plugins | plugins ,= <Graphviz FontAwesome Latex LeafletMaps> | custom blocks ***packaged with rakuast-rakudoc-render*** |
| plugins | plugins ,= 'UISwitcher', | Adds multi-lingual UI ***packaged with Elucid8*** |
| plugins | plugins ,= 'SCSS', | must be last plugin enabled, converts SCSS in other plugins to CSS ***packaged with rakuast-rakudoc-render*** |

## Credits

Richard Hainsworth, aka finanalyst

## VERSION

v0.1.0

---

---

Rendered from docs/README.rakudoc/README at 20:27 UTC on 2025-03-24

Source last modified at 20:26 UTC on 2025-03-24


## dist_cpan-TYIL-IRC-Client-Plugin-DiceRolls.md
### has Config $.config

A Config instance to hold all configuration.

### has Str $!prefix

The calculated prefix for the dice roll command.

# NAME

IRC::Client::Plugin::DiceRolls

# VERSION

0.2.1

# AUTHOR

Patrick Spek [p.spek@tyil.nl](mailto:p.spek@tyil.nl)

# LICENSE

Copyright © 2020

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

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

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


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

# NAME

Terminal::ReadKey - Read non-blocking key presses from the keyboard buffer.

# SYNOPSIS

```
use Terminal::ReadKey;

react { whenever key-pressed() { .say } }

```

# DESCRIPTION

Terminal::ReadKey makes it easy to get non-blocking key presses from the keyboard buffer, even multibyte, combination key presses.

# USAGE

Terminal::ReadKey has a few options you can set to modify its behavior.

Defaults to cooked mode, where it returns a string containing the named key press. If you want the byte values instead, pass in the parameter :raw set to a truthy value. Raw mode returns a sequence of bytes decoded to an ASCII string. For printable characters it is effectively the same as cooked mode. For non-printables, (function keys, navigation keys, Alt, or Ctrl keys) it won't look like much.

When in cooked mode, if there is an unrecognized keypress, returns the byte string as a stringified list of ordinals.

By default, does not echo each keypress to STDOUT. If you would prefer it to, pass in the parameter :echo set to a truthy value.

```
use Terminal::ReadKey;

# cooked mode
react { whenever key-pressed() { .say } }

```

or

```
use Terminal::ReadKey;

# raw mode
react { whenever key-pressed( :raw ) { .ords.say } }

```

Also, selectively exports the cooked() routine if you want to convert raw output to cooked manually.

```
use Terminal::ReadKey :cooked;

my $fh = open( :a, 'key-cap.txt' ) or die $_;
react { whenever key-pressed( :raw, :echo ) { $fh.print( .&cooked ); $fh.flush } }

```

# BUGS

Since Terminal::ReadKey interacts with the keyboard buffer rather than reading the keyboard directly, it has no way to differentiate different keypress sequences that result in the same keypress code(s) in the buffer. For instance, if it reads a "Ctrl PgUp", it has no way to tell *which* Ctrl key or *which* PgUp key may have been pressed, only that there *was* one of each pressed. Same with Shift, Enter, or any other key combination that may be entered in multiple ways.

That also means that it can be affected by the OS / window managers typing repeat setting. It doesn't see, and is not responding to the actual key press, rather the presence of key codes in the keyboard buffer.

All of the Ctrl plus an alphabetic key sequences return uppercase alphabetics, regardless of the case of the key pressed. Not really a bug, just the reality of the situation, something to be aware of. 'Ctrl a' and 'Ctrl A' keypresses both return the same key codes so both evaluate to 'Ctrl A'. There isn't any way to differentiate.

There are a few key combinations that I haven't yet been able to capture because something else grabs the key code before it can be processed.

```
Notably missing (or at least, unverified):

```

* Alt F1
* Alt F2
* Alt F3
* Alt Tab
* Ctrl C
* Ctrl Z
* Ctrl Insert
* Ctrl Shift |
* Shift PgUp
* Shift PgDn
* Shift Home
* Shift End
* Shift Insert

The key combination "Shift Insert" stuffs the keyboard buffer with whatever is in the cut/paste buffer rather than the actual key codes, so doesn't reliably return a repeatable keypress sequence (if the cut/paste buffer contents changes).

This was written and tested on a US English keyboard. Characters on non-US keyboards may not have correct "cooked" mode support.

# AUTHOR

Based on Term::ReadKey by jkramer - github.com/jkramer/p6-Term-ReadKey

Modified to recognize multibyte (non-printable) key presses and support "cooked" mode by Stephen Schulze - aka thundergnat [thundergnat@gmail.com](mailto:thundergnat@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2022 Stephen Schulze

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


## write.md
write

Combined from primary sources listed below.

# [In IO::Socket::Async](#___top "go to top of document")[§](#(IO::Socket::Async)_method_write "direct link")

See primary documentation
[in context](/type/IO/Socket/Async#method_write)
for **method write**.

```raku
method write(IO::Socket::Async:D: Blob $b --> Promise)
```

This method will attempt to send the bytes in `$b` on the `IO::Socket::Async` that will have been obtained indirectly via `connect` or `listen`, returning a [`Promise`](/type/Promise) that will be kept with the number of bytes sent or broken if there was an error sending.

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

See primary documentation
[in context](/type/IO/Handle#method_write)
for **method write**.

```raku
method write(IO::Handle:D: Blob:D $buf --> True)
```

Writes `$buf` to the filehandle. This method can be called even when the handle is not [in binary mode](/type/IO/Handle#method_encoding).

# [In Proc::Async](#___top "go to top of document")[§](#(Proc::Async)_method_write "direct link")

See primary documentation
[in context](/type/Proc/Async#method_write)
for **method write**.

```raku
method write(Proc::Async:D: Blob:D $b, :$scheduler = $*SCHEDULER --> Promise:D)
```

Write the binary data in `$b` to the standard input stream of the external program.

Returns a [`Promise`](/type/Promise) that will be kept once the data has fully landed in the input buffer of the external program.

The `Proc::Async` object must be created for writing (with `Proc::Async.new(:w, $path, @args)`). Otherwise an [`X::Proc::Async::OpenForWriting`](/type/X/Proc/Async/OpenForWriting) exception will the thrown.

`start` must have been called before calling method write, otherwise an [`X::Proc::Async::MustBeStarted`](/type/X/Proc/Async/MustBeStarted) exception is thrown.

# [In role IO::Socket](#___top "go to top of document")[§](#(role_IO::Socket)_method_write "direct link")

See primary documentation
[in context](/type/IO/Socket#method_write)
for **method write**.

```raku
method write(IO::Socket:D: Blob:D $buf)
```

Writes the supplied buffer to the socket, thus sending it to other end of the connection. The string version is [method print](#method_print).

Fails if the socket is not connected.