## dist_cpan-FRITH-Math-Libgsl-Matrix.md
## Chunk 1 of 2
[![Actions Status](https://github.com/frithnanth/raku-Math-Libgsl-Matrix/workflows/test/badge.svg)](https://github.com/frithnanth/raku-Math-Libgsl-Matrix/actions)

# NAME

Math::Libgsl::Matrix Math::Libgsl::Vector - An interface to libgsl, the Gnu Scientific Library - Vector and matrix algebra.

# SYNOPSIS

```
use Math::Libgsl::Vector;
use Math::Libgsl::Matrix;

```

# DESCRIPTION

Math::Libgsl::Matrix provides an interface to the vector and matrix algebra functions of libgsl - the GNU Scientific Library.

This package provides both the low-level interface to the C library (Raw) and a more comfortable interface layer for the Raku programmer.

This module comes with two classes, Vector and Matrix, available in 12 data types, so it offers 24 classes:

* Math::Libgsl::Vector - default, corresponding to a Math::Libgsl::Vector::Num64
* Math::Libgsl::Vector::Num32
* Math::Libgsl::Vector::Int32
* Math::Libgsl::Vector::UInt32
* Math::Libgsl::Vector::Int64
* Math::Libgsl::Vector::UInt64
* Math::Libgsl::Vector::Int16
* Math::Libgsl::Vector::UInt16
* Math::Libgsl::Vector::Int8
* Math::Libgsl::Vector::UInt8
* Math::Libgsl::Vector::Complex32
* Math::Libgsl::Vector::Complex64
* Math::Libgsl::Matrix - default, corresponding to a Math::Libgsl::Matrix::Num64
* Math::Libgsl::Matrix::Num32
* Math::Libgsl::Matrix::Int32
* Math::Libgsl::Matrix::UInt32
* Math::Libgsl::Matrix::Int64
* Math::Libgsl::Matrix::UInt64
* Math::Libgsl::Matrix::Int16
* Math::Libgsl::Matrix::UInt16
* Math::Libgsl::Matrix::Int8
* Math::Libgsl::Matrix::UInt8
* Math::Libgsl::Matrix::Complex32
* Math::Libgsl::Matrix::Complex64

All the following methods are available for the classes correspondig to each datatype, except where noted.

## Vector

### new(Int $size!)

### new(Int :$size!)

The constructor accepts one parameter: the vector's size; it can be passed as a Pair or as a single value.

### get(Int:D $index! where \* < $!vector.size --> Num)

This method returns the value of a vector's element. It is possible to address a vector element as a Raku array element:

```
say $vector[1];

```

or even:

```
say $vector[^10];

```

### set(Int:D $index! where \* < $!vector.size, Num(Cool)

This method sets the value of a vector's element. This method can be chained. It is possible to address a vector element as a Raku array element:

```
$vector[1] = 3;

```

Note that it's not possible to set a range of elements (yet). When used as a Raku array, this method can't be chained.

### setall(Num(Cool))

Sets all the elements of the vector to the same value. This method can be chained.

### zero()

Sets all the elements of the vector to zero. This method can be chained.

### basis(Int:D $index! where \* < $!vector.size)

Sets all the elements of the vector to zero except for the element at $index, which is set to one. This method can be chained.

### size(--> UInt)

This method outputs the vector's size.

### write(Str $filename!)

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

### read(Str $filename!)

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

### printf(Str $filename!, Str $format!)

Writes the vector to a file using the specified format. This method can be chained.

### scanf(Str $filename!)

Reads the vector from a file containing formatted data. This method can be chained.

### copy(Math::Libgsl::Vector $src where $!vector.size == .vector.size)

This method copies the vector $src into the current object. This method can be chained.

### swap(Math::Libgsl::Vector $w where $!vector.size == .vector.size)

This method exchanges the elements of the current vector with the ones of the vector $w. This method can be chained.

### swap-elems(Int $i where \* < $!vector.size, Int $j where \* < $!vector.size)

This method exchanges the $i-th and $j-th elements in place. This method can be chained.

### reverse()

This method reverses the order of the elements of the vector. This method can be chained.

### add(Math::Libgsl::Vector $b where $!vector.size == .vector.size)

### sub(Math::Libgsl::Vector $b where $!vector.size == .vector.size)

### mul(Math::Libgsl::Vector $b where $!vector.size == .vector.size)

### div(Math::Libgsl::Vector $b where $!vector.size == .vector.size)

These methods perform operations on the elements of two vectors. The object on which the method is called is the one whose values are changed. All these methods can be chained.

### scale(Num(Cool) $x)

This method multiplies the elements of the vector by a factor $x. This method can be chained.

### add-constant(Num(Cool) $x)

This method adds a constant to the elements of the vector. This method can be chained.

### sum(--> Num)

This method returns the sum of the elements of the vector. This method fails if the underlying C library's version is less than 2.7.

### axpby(Num(Cool) $alpha, Num(Cool) $beta, Math::Libgsl::Vector $b where $!vector.size == .vector.size)

This method performs the operation αx + βy and returns the result in the vector $b. This method can be chained. This method fails if the underlying C library's version is less than 2.7.

### max(--> Num)

### min(--> Num)

These two methods return the min and max value in the vector. Not available in Math::Libgsl::Vector::Complex32 and Math::Libgsl::Vector::Complex64.

### minmax(--> List)

This method returns a list of two values: the min and max value in the vector. Not available in Math::Libgsl::Vector::Complex32 and Math::Libgsl::Vector::Complex64.

### max-index(--> Int)

### min-index(--> Int)

These two methods return the index of the min and max value in the vector. Not available in Math::Libgsl::Vector::Complex32 and Math::Libgsl::Vector::Complex64.

### minmax-index(--> List)

This method returns a list of two values: the indices of the min and max value in the vector. Not available in Math::Libgsl::Vector::Complex32 and Math::Libgsl::Vector::Complex64.

### is-null(--> Bool)

### is-pos(--> Bool)

### is-neg(--> Bool)

### is-nonneg(--> Bool)

These methods return True if all the elements of the vector are zero, strictly positive, strictly negative, or non-negative.

### is-equal(Math::Libgsl::Vector $b --> Bool)

This method returns True if the two vectors are equal element-wise.

## Views

Views are extremely handy, but their C-language interface uses a couple of low-level tricks that makes difficult to write a simple interface for high-level languages. A View is a reference to data in a Vector, Matrix, or array, so it makes possible to work on a subset of that data without having to duplicate it in memory or do complex address calculation to access it. Since a View is a reference to an object, the programmer needs to take care that the original object doesn't go out of scope, or the virtual machine might deallocate its memory causing the underlying C library to crash. Look in the **examples/** directory for more programs showing what can be done with views.

## Vector View

```
use Math::Libgsl::Vector;

my Math::Libgsl::Vector $v .= new(30);                            # Create a 30-element vector
my Math::Libgsl::Vector::View $vv .= new;                         # Create a Vector View
my Math::Libgsl::Vector $v1 = $vv.subvector-stride($v, 0, 3, 10); # Get a subvector view with stride
$v1.setall(42);                                                   # Set all elements of the subvector view to 42
say $v[^30]; # output: (42 0 0 42 0 0 42 0 0 42 0 0 42 0 0 42 0 0 42 0 0 42 0 0 42 0 0 42 0 0)

```

There are two kinds of Vector Views: a Vector View on a Vector or a Vector View on a Raku array. These are Views of the first kind:

### subvector(Math::Libgsl::Vector $v, size\_t $offset where \* < $v.vector.size, size\_t $n --> Math::Libgsl::Vector)

Creates a view on a subset of the vector, starting from $offset and of length $n. This method returns a new Vector object. Any operation done on this view affects the original vector as well.

### subvector-stride(Math::Libgsl::Vector $v, size\_t $offset where \* < $v.vector.size, size\_t $stride, size\_t $n --> Math::Libgsl::Vector)

Creates a view on a subset of the vector, starting from $offset and of length $n, with stride $stride. This method returns a new Vector object. Any operation done on this view affects the original vector as well.

Views on a Raku array are a bit more complex, because it's not possible to simply pass a Raku array to a C-language function. So for this to work the programmer has to *prepare* the array to be passed to the library. Both the View object and the *prepared* array must not go out of scope.

There are three ways to access a Raku array as a Math::Libgsl::Vector object:

* The hard way - use NativeCall's CArray to create a C-language-happy array.
* The easy way - use the \*-prepvec sub to convert a Raku array into a C array.
* The easiest way - use the \*-array-vec sub, pass it the Raku array or list and a closure or anonymous sub.

This is an example of the "hard way":

```
use Math::Libgsl::Vector;
use NativeCall;

my CArray[num64] $array .= new: (1 xx 10)».Num;         # define a CArray
my Math::Libgsl::Vector::View $vv .= new;               # view: an object that will contain the view information
my Math::Libgsl::Vector $v = $vv.array($array);         # create an Math::Libgsl::Vector object
$v[0] = 2;                                              # assign a value to the first vector element
say $v[^10];                                            # output: (2 1 1 1 1 1 1 1 1 1)

```

This is an example of the "easy way":

```
use Math::Libgsl::Vector;

my @array = 1 xx 10;                                    # define an array
my $parray = num64-prepvec(@array);                     # prepare the array to be used as a Math::Libgsl::Vector
my Math::Libgsl::Vector::View $vv .= new;               # view: an object that will contain the view information
my Math::Libgsl::Vector $v = $vv.array($parray);        # create an Math::Libgsl::Vector object
$v[0] = 2;                                              # assign a value to the first vector element
say $v[^10];                                            # output: (2 1 1 1 1 1 1 1 1 1)

```

Here are some examples of the "easiest way":

```
use Math::Libgsl::Vector;

my @array = ^10;                                                    # initialize an array
my ($min, $max) = num64-array-vec(-> $vec { $vec.minmax }, @array); # find min and max value
say "$min $max";                                                    # output: 0 9

```

```
use Math::Libgsl::Constants;
use Math::Libgsl::Vector;
use Math::Libgsl::MovingWindow;

my @array = ^10;                                        # initialize an array
my Math::Libgsl::MovingWindow $mw .= new: :samples(5);  # initialize a MovingWindow object with a 5-sample window
                                                        # compute the moving-window mean of the array
my $w = num64-array-vec(-> $vec { $mw.mean($vec, :endtype(GSL_MOVSTAT_END_PADVALUE)) }, @array);
say $w[^10];                                            # output: (0.6 1.2 2 3 4 5 6 7 7.8 8.4)

```

Even using this last construct, if the Vector object is to be used outside of the closure it must be declared before calling array-vec.

```
use Math::Libgsl::Vector;

my @array = 1 xx 10;                                            # define an array
my Math::Libgsl::Vector $v .= new: 10;                          # declare a Math::Libgsl::Vector
num64-array-vec(-> $vec { $v.copy($vec); $v[0] = 2; }, @array); # assign a value to the first vector element
say $v[^10];                                                    # output: (2 1 1 1 1 1 1 1 1 1)

```

### num64-prepvec(@array)

This is just a sub, not a method; it gets a regular array and outputs a *prepared* array, kept in a scalar variable. There are similar functions for every data type, so for example if one is working with int16 Vectors, one will use the **int16-prepvec** sub. The num64, being the default data type, has a special **prepvec** alias. Once *prepared*, the original array can be discarded.

### array($parray --> Math::Libgsl::Vector)

This method gets a *prepared* array and returns a Math::Libgsl::Vector object.

### array-stride($array, size\_t $stride --> Math::Libgsl::Vector)

This method gets a *prepared* array and a **$stride** and returns a Math::Libgsl::Vector object.

### sub num64-array-vec(Block $bl, \*@data)

This sub arguments are a Block to execute and a regular Raku array. Internally it uses a vector view to convert the array into libgsl's own vector data type, obtains the Math::Libgsl::Vector from the View, and passes it to the Block. When the Block exits the Math::Libgsl::Vector object ceases to exist, so it must be consumed inside the Block, or copied into another externally defined variable. The num64, being the default data type, has a special **array-vec** alias.

### sub num64-array-stride-vec(Block $bl, size\_t $stride, \*@data)

This sub arguments are a Block to execute, a stride, and a regular Raku array. Internally it uses a vector view to convert the array into libgsl's own vector data type, obtains the Math::Libgsl::Vector from the View, and passes it to the Block. When the Block exits the Math::Libgsl::Vector object ceases to exist, so it must be consumed inside the Block, or copied into another externally defined variable. The num64, being the default data type, has a special **array-stride-vec** alias.

## Matrix

### new(Int $size1!, Int $size2!)

### new(Int :$size1!, Int :$size2!)

The constructor accepts two parameters: the matrix sizes; they can be passed as Pairs or as single values.

### get(Int:D $i! where \* < $!matrix.size1, Int:D $j! where \* < $!matrix.size2 --> Num)

This method returns the value of a matrix element. It is possible to address a matrix element as a Raku shaped array element:

```
say $matrix[1;2];

```

### set(Int:D $i! where \* < $!matrix.size1, Int:D $j! where \* < $!matrix.size2, Num(Cool)

This method sets the value of a matrix element. This method can be chained. It is possible to address a matrix element as a Raku shaped array element:

```
$matrix[1;3] = 3;

```

### setall(Num(Cool))

Sets all the elements of the matrix to the same value. This method can be chained.

### zero()

Sets all the elements of the matrix to zero. This method can be chained.

### identity()

Sets all elements of the matrix to the corrisponding elements of the identity matrix.

### size1(--> UInt)

### size2(--> UInt)

### size(--> List)

These methods return the first, second, or both the matrix sizes.

### write(Str $filename!)

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

### read(Str $filename!)

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

### printf(Str $filename!, Str $format!)

Writes the matrix to a file using the specified format. This method can be chained.

### scanf(Str $filename!)

Reads the matrix from a file containing formatted data. This method can be chained.

### copy(Math::Libgsl::Matrix $src where $!matrix.size1 == .matrix.size1 && $!matrix.size2 == .matrix.size2)

This method copies the $src matrix into the current one. This method can be chained.

### swap(Math::Libgsl::Matrix $src where $!matrix.size1 == .matrix.size1 && $!matrix.size2 == .matrix.size2)

This method swaps elements of the $src matrix and the current one. This method can be chained.

### tricpy(Math::Libgsl::Matrix $src where $!matrix.size1 == .matrix.size1 && $!matrix.size2 == .matrix.size2, Int $Uplo, Int $Diag)

This method copies the upper or lower trianglular matrix from **$src** to **self**. Use the **cblas-uplo** enumeration to specify which triangle copy. Use the **cblas-diag** enumeration to specify whether to copy the matrix diagonal. This method can be chained.

### get-row(Int:D $i where \* < $!matrix.size1)

This method returns an array from row number $i.

### get-col(Int:D $j where \* < $!matrix.size2)

This method returns an array from column number $j.

### set-row(Int:D $i where \* ≤ $!matrix.size1, @row where \*.elems == $!matrix.size2)

### set-row(Int:D $i where \* ≤ $!matrix.size1, Math::Libgsl::Vector $v where .vector.size == $!matrix.size2)

These methods set row number $i of the matrix from a Raku array or a Vector object. This method can be chained.

### set-col(Int:D $j where \* ≤ $!matrix.size2, @col where \*.elems == $!matrix.size1)

### set-col(Int:D $j where \* ≤ $!matrix.size2, Math::Libgsl::Vector $v where .vector.size == $!matrix.size1)

These methods set column number $j of the matrix from a Raku array or a Vector object. This method can be chained.

### swap-rows(Int:D $i where \* ≤ $!matrix.size1, Int:D $j where \* ≤ $!matrix.size1)

This method swaps rows $i and $j. This method can be chained.

### swap-cols(Int:D $i where \* ≤ $!matrix.size2, Int:D $j where \* ≤ $!matrix.size2)

This method swaps columns $i and $j. This method can be chained.

### swap-rowcol(Int:D $i where \* ≤ $!matrix.size1, Int:D $j where \* ≤ $!matrix.size1)

This method exchanges row number $i with column number $j of a square matrix. This method can be chained.

### copy-transpose(Math::Libgsl::Matrix $src where $!matrix.size1 == .matrix.size2 && $!matrix.size2 == .matrix.size1)

This method copies a matrix into the current one, while transposing the elements. This method can be chained.

### transpose()

This method transposes the current matrix. This method can be chained.

### transpose-tricpy(Math::Libgsl::Matrix $src where $!matrix.size1 == .matrix.size2 && $!matrix.size2 == .matrix.size1, Int $Uplo, Int $Diag)

This method copies a triangle from the **$src** matrix into the current one, while transposing the elements. Use the **cblas-uplo** enumeration to specify which triangle copy. Use the **cblas-diag** enumeration to specify whether to copy the matrix diagonal. This method can be chained.

### add(Math::Libgsl::Matrix $b where $!matrix.size1 == .matrix.size1 && $!matrix.size2 == .matrix.size2)

This method adds a matrix to the current one element-wise. This method can be chained.

### sub(Math::Libgsl::Matrix $b where $!matrix.size1 == .matrix.size1 && $!matrix.size2 == .matrix.size2)

This method subtracts a matrix from the current one element-wise. This method can be chained.

### mul(Math::Libgsl::Matrix $b where $!matrix.size1 == .matrix.size1 && $!matrix.size2 == .matrix.size2)

This method multiplies a matrix to the current one element-wise. This method can be chained.

### div(Math::Libgsl::Matrix $b where $!matrix.size1 == .matrix.size1 && $!matrix.size2 == .matrix.size2)

This method divides the current matrix by another one element-wise. This method can be chained.

### scale(Num(Cool) $x)

This method multiplies the elements of the current matrix by a constant value. This method can be chained.

### scale-rows(Math::Libgsl::Vector $x where .size == $!matrix.size1)

This method scales the rows of the M-by-N matrix by the elements of the vector $x, of length N. The i-th row of the matrix is multiplied by $xᵢ. This method can be chained. This method fails if the underlying C library's version is less than 2.7.

### scale-columns(Math::Libgsl::Vector $x where .size == $!matrix.size1)

This method scales the columns of the M-by-N matrix by the elements of the vector $x, of length N. The j-th column of the matrix is multiplied by $xⱼ. This method can be chained. This method fails if the underlying C library's version is less than 2.7.

### add-constant(Num(Cool) $x)

This method adds a constant to the elements of the current matrix. This method can be chained.

### max(--> Num)

### min(--> Num)

These two methods return the min and max value in the matrix. Not available in Math::Libgsl::Matrix::Complex32 and Math::Libgsl::Matrix::Complex64.

### minmax(--> List)

This method returns a list of two values: the min and max value in the matrix. Not available in Math::Libgsl::Matrix::Complex32 and Math::Libgsl::Matrix::Complex64.

### max-index(--> Int)

### min-index(--> Int)

These two methods return the index of the min and max value in the matrix. Not available in Math::Libgsl::Matrix::Complex32 and Math::Libgsl::Matrix::Complex64.

### minmax-index(--> List)

This method returns a list of two values: the indices of the min and max value in the matrix. Not available in Math::Libgsl::Matrix::Complex32 and Math::Libgsl::Matrix::Complex64.

### is-null(--> Bool)

### is-pos(--> Bool)

### is-neg(--> Bool)

### is-nonneg(--> Bool)

These methods return True if all the elements of the matrix are zero, strictly positive, strictly negative, or non-negative.

### is-equal(Math::Libgsl::Matrix $b --> Bool)

This method returns True if the matrices are equal element-wise.

### norm1(--> Num)

This method returns the 1-norm of the m-by-n matrix, defined as the maximum column sum. This method fails if the underlying C library's version is less than 2.7.

## Matrix View

```
use Math::Libgsl::Matrix;

my Math::Libgsl::Matrix $m1 .= new(:size1(3), :size2(4));      # create a 3x4 matrix
$m1.setall(1);                                                 # set all elements to 1
my Math::Libgsl::Matrix::View $mv .= new;                      # create a Matrix View
my Math::Libgsl::Matrix $m2 = $mv.submatrix($m1, 1, 1, 2, 2);  # get a submatrix
$m2.setall(12);                                                # set the submatrix elements to 12
$m1.get-row($_)».fmt('%2d').put for ^3;                        # print the original matrix
# output:
# 1  1  1  1
# 1 12 12  1
# 1 12 12  1

```

There are three kinds of Matrix Views: a Matrix View on a Matrix, a Matrix View on a Vector, and a Matrix View on a Raku array.

This is the View of the first kind:

### submatrix(Math::Libgsl::Matrix $m, size\_t $k1 where \* < $m.size1, size\_t $k2 where \* < $m.size2, size\_t $n1, size\_t $n2 --> Math::Libgsl::Matrix)

Creates a view on a subset of the matrix, starting from coordinates ($k1, $k2) with $n1 rows and $n2 columns. This method returns a new Matrix object. Any operation done on the returned matrix affects the original matrix as well.

These three methods create a matrix view on a Raku array:

There are three ways to view a Raku array as a Math::Libgsl::Vector object:

* The hard way - use NativeCall's CArray to create a C-language-happy array.
* The easy way - use the \*-prepvec sub to convert a Raku array into a C array.
* The easiest way - use the \*-array-vec sub, pass it the Raku array or list and a closure or anonymous sub.

This is an example of the "hard way":

```
use Math::Libgsl::Matrix;
use NativeCall;

my CArray[num64] $array .= new: (1..6)».Num;            # define a CArray
my Math::Libgsl::Matrix::View $mv .= new;               # view: an object that will contain the view information
my Math::Libgsl::Matrix $m = $mv.array($array, 2, 3);   # create an Math::Libgsl::Matrix object
$m[0;0] = 2;                                            # assign a value to the first matrix element
say $m.get-row($_) for ^2;
# output:
# 2 2 3
# 4 5 6

```

This is an example of the "easy way":

Views on a Raku array are a bit more complex, because it's not possible to simply pass a Raku array to a C-language function. So for this to work the programmer has to *prepare* the array to be passed to the library. Both the View object and the *prepared* array must not go out of scope.

```
use Math::Libgsl::Matrix;

my @array = 1 xx 10;                                    # define an array
my $parray = prepmat(@array);                           # prepare the array to be used as a Math::Libgsl::Matrix
my Math::Libgsl::Matrix::View $mv .= new;               # view: an object that will contain the view information
my Math::Libgsl::Matrix $m = $mv.array($parray, 2, 5);  # create an Math::Libgsl::Matrix object
$m[0;0] = 2;                                            # assign a value to the first matrix element
$m.get-row($_).put for ^2;
# output:
# 2 1 1 1 1
# 1 1 1 1 1

```

This is an example of the "easiest way":

```
use Math::Libgsl::Matrix;

my @array = 1..6;                                                                 # initialize an array
my Math::Libgsl::Matrix $matrix .= new: 2, 3;                                     # declare a Math::Libgsl::Matrix
num64-array-mat(-> $mat { $matrix.copy($mat); $matrix[0;0] = 0 }, 2, 3, @array);  # assign 0 to matrix element [0;0]
$matrix.get-row($_).put for ^2;
# output:
# 0 2 3
# 4 5 6

```

### num64-prepmat(@array)

This is just a sub, not a method; it gets a regular array and outputs a *prepared* array, kept in a scalar variable. There are similar functions for every data type, so for example if one is working with int16 Vectors, one will use the **int16-prepmat** sub. The num64, being the default data type, has a special **prepmat** alias. Once *prepared*, the original array can be discarded.

### array($array, UInt $size1, UInt $size2 --> Math::Libgsl::Matrix)

This method gets a *prepared* array and returns a Math::Libgsl::Matrix object.

### array-tda($array, UInt $size1, UInt $size2, size\_t $tda where \* > $size2 --> Math::Libgsl::Matrix)

This method gets a *prepared* array with a number of physical columns **$tda**, which may differ from the corresponding dimension of the matrix, and returns a Math::Libgsl::Matrix object.

### sub num64-array-mat(Block $bl, UInt $size1, UInt $size2, \*@data)

This sub arguments are a Block to execute, the sizes of the desired resulting matrix, and a regular Raku array. Internally it uses a matrix view to convert the array into libgsl's own matrix data type, obtains the Math::Libgsl::Matrix from the View, and passes it to the Block. When the Block exits the Math::Libgsl::Matrix object ceases to exist, so it must be consumed inside the Block, or copied into another externally defined variable. The num64, being the default data type, has a special **array-mat** alias.

### sub num64-array-tda-mat(Block $bl, UInt $size1, UInt $size2, size\_t $tda where \* > $size2, \*@data)

This sub arguments are a Block to execute, the sizes of the desired resulting matrix, the number of physical columns **$tda**, and a regular Raku array. Internally it uses a matrix view to convert the array into libgsl's own matrix data type, obtains the Math::Libgsl::Matrix from the View, and passes it to the Block. When the Block exits the Math::Libgsl::Matrix object ceases to exist, so it must be consumed inside the Block, or copied into another externally defined variable. The num64, being the default data type, has a special **array-tda-mat** alias.

There are two methods to create a Matrix View on a Vector:

### vector(Math::Libgsl::Vector $v, size\_t $n1, size\_t $n2 --> Math::Libgsl::Matrix)

This method creates a Matrix object from a Vector object. The resultimg matrix will have $n1 rows and $n2 columns.

### vector-tda(Math::Libgsl::Vector $v, size\_t $n1, size\_t $n2, size\_t $tda where \* > $n2 --> Math::Libgsl::Matrix)

This method creates a Matrix object from a Vector object, with a physical number of columns $tda which may differ from the correspondig dimension of the matrix. The resultimg matrix will have $n1 rows and $n2 columns.

## Vector View on a Matrix

There is a fourth kind of View that involves a Matrix: a Vector View on a Matrix. The following are methods of the Matrix class, not of the Matrix::View class, take a Vector::View argument, and deliver a Vector object. The Matrix object must not go out of scope while one is operating on the resulting Vector.

### row-view(Math::Libgsl::Vector::View $vv, size\_t $i where \* < $!matrix.size1 --> Math::Libgsl::Vector)

This method creates a Vector object from row $i of the matrix.

### col-view(Math::Libgsl::Vector::View $vv, size\_t $j where \* < $!matrix.size2 --> Math::Libgsl::Vector)

This method creates a Vector object from column $j of the matrix.

### subrow-view(Math::Libgsl::Vector::View $vv, size\_t $i where \* < $!matrix.size1, size\_t $offset, size\_t $n --> Math::Libgsl::Vector)

This method creates a Vector object from row $i of the matrix, starting from $offset and containing $n elements.

### subcol-view(Math::Libgsl::Vector::View $vv, size\_t $j where \* < $!matrix.size2, size\_t $offset, size\_t $n --> Math::Libgsl::Vector)

This method creates a Vector object from column $j of the matrix, starting from $offset and containing $n elements.

### diagonal-view(Math::Libgsl::Vector::View $vv --> Math::Libgsl::Vector)

This method creates a Vector object from the diagonal of the matrix.

### subdiagonal-view(Math::Libgsl::Vector::View $vv, size\_t $k where \* < min($!matrix.size1, $!matrix.size2) --> Math::Libgsl::Vector)

This method creates a Vector object from the subdiagonal number $k of the matrix.

### superdiagonal-view(Math::Libgsl::Vector::View $vv, size\_t $k where \* < min($!matrix.size1, $!matrix.size2) --> Math::Libgsl::Vector)

This method creates a Vector object from the superdiagonal number $k of the matrix.

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


## dist_cpan-FRITH-Math-Libgsl-Matrix.md
## Chunk 2 of 2
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::Matrix

```

# 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_cpan-RYNIX-Terminal-Spinners.md
# Terminal::Spinners

Simple spinners and progress bars for Raku.

## Install

```
zef install Terminal::Spinners

```

## Usage

Classic Spinner `|/-\`

```
my $spinner = Spinner.new;                        # a new default (classic) spinner
my $promise = Promise.start: { sleep 2; 40 + 2 }; # promise of your long running process
my $result  = $spinner.await: $promise;           # await returns the promise result

```

-or-

```
my $classic = Spinner.new;   # a new default (classic) spinner
my $promise = start sleep 2; # promise of your long running process
until $promise.status {
    $classic.next;           # prints the next spinner frame
}

```

Hash Progress Bar `[##########..........] 50.00%`

```
my $hash-bar = Bar.new;            # defaults to the hash progress bar
$hash-bar.show: 0;                 # print a 0% progress bar
for 1 .. 3000 {
    my $percent = $_ / 3000 * 100; # calculate a percentage
    sleep 0.0002;                  # do iterative work here
    $hash-bar.show: $percent;      # print the progress bar and percent
}

```

## More options

For spinners you can set the speed:

```
my $spinner = Spinner.new: speed => 0; # speed in seconds
# defaults to 0.08. this provides smooth animation for use as in the example above.
# 0 seconds can be useful if you want to print the next frame each time an action occurs.

```

And change the type of spinner:

```
my $spinner = Spinner.new: type => 'bounce';

```

Choose from these types:

```

classic     | / - \
bounce      [=   ] [==  ] [=== ] [ ===] [  ==] [   =] [    ] [   =] [  ==] [ ===] [====] [=== ] [==  ] [=   ] [    ]
bounce2     ( ●    ) (  ●   ) (   ●  ) (    ● ) (     ●) (    ● ) (   ●  ) (  ●   ) ( ●    ) (●     )
dots        ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
dots2       ⢄ ⢂ ⢁ ⡁ ⡈ ⡐ ⡠
dots3       ⠈ ⠐ ⠠ ⢀ ⡀ ⠄ ⠂ ⠁
three-dots  .  .. ...
three-dots2 .  .. ... ..  .
bar         ▁  ▃  ▄  ▅  ▆  ▇  ▆  ▅  ▄  ▃  ▁
bar2        ▏  ▎  ▍  ▌  ▊  ▉  ▊  ▋  ▌  ▍  ▎

```

For bars you can change the length:

```
my $bar = Bar.new: length => 50;

```

And you can change the type:

```
my $bar = Bar.new: type => 'equals';

```

Choose from these types:

```

hash      [##########..........] 50.00%
hash-dash [##########----------] 50.00%
equals    [==========          ] 50.00%
bar       ███████████░░░░░░░░░░░ 50.00%

```

## Adverbs

`:no-overwrite` or `:now`:

Suppresses overwriting the previous spinner/bar. Works with `next()`, `await()`, and `show()` methods. Particularly useful on Windows where the formatting is not as expected when printing in combination with other text.

`:no-print` or `:nop`:

Suppresses printing and also skips any animation delays. Works with the `next()` and `show()` methods, which also return the spinner-frame or progress-bar, respectively, as a string.

`:no-final-newline` or `:non`:

By default, `await()` will print a newline when it's done waiting for the promise. This suppresses that newline. Only works with the `await()` method.

## Copyright

Copyright (c) 2018-2020, ryn1x

## License

Terminal::Spinners is released under the Artistic License 2.0.


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

# NAME

Map::Ordered - role for ordered Maps

# SYNOPSIS

```
use Map::Ordered;

my %m is Map::Ordered = a => 42, b => 666;

```

# DESCRIPTION

Exports a `Map::Ordered` role that can be used to indicate the implementation of a `Map` in which the keys are ordered the way the `Map` got initialized.

Since `Map::Ordered` is a role, you can also use it as a base for creating your own custom implementations of maps.

# AUTHOR

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

Source can be located at: <https://github.com/lizmat/Map-Ordered> . 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 2018, 2019, 2021, 2023, 2024, 2025 Elizabeth Mattijsen

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


## attribute.md
class Attribute

Member variable

```raku
class Attribute { }
```

In Raku lingo, an *attribute* refers to a per-instance/object storage slot. An `Attribute` is used to talk about classes' and roles' attributes at the metalevel.

Normal usage of attributes does not require the user to use this class explicitly.

# [Traits](#class_Attribute "go to top of document")[§](#Traits "direct link")

## [Trait is default](#class_Attribute "go to top of document")[§](#Trait_is_default "direct link")

An attribute that is assigned [`Nil`](/type/Nil) will revert to its default value set with the trait `is default`. In the case of arrays or associatives, the argument of `is default` will set the default item value or hash value.

```raku
class C {
    has $.a is default(42) is rw = 666
}
my $c = C.new;
say $c;
$c.a = Nil;
say $c;
# OUTPUT: «C.new(a => 666)␤C.new(a => 42)␤»
class Foo {
    has @.bar is default(42) is rw
};
my $foo = Foo.new( bar => <a b c> );
$foo.bar =Nil;
say $foo; # OUTPUT: «Foo.new(bar => [42])␤»
```

## [Trait is required](#class_Attribute "go to top of document")[§](#Trait_is_required "direct link")

```raku
multi trait_mod:<is> (Attribute $attr, :$required!)
```

The trait `is required` will mark the attribute as to be filled with a value when the object is instantiated. Failing to do so will result in a runtime error.

```raku
class C {
    has $.a is required
}
my $c = C.new;
CATCH{ default { say .^name, ': ', .Str } }
# OUTPUT: «X::Attribute::Required: The attribute '$!a' is required, but you did not provide a value for it.␤»
```

This trait also allows attributes to be typed with types that have a `:D` smiley without giving them a default value:

```raku
class Power {
    has Numeric:D $.base     is required;
    has Numeric:D $.exponent is required;
    multi method Numeric(::?CLASS:D: --> Numeric:D) {
        $!base ** $!exponent
    }
}
```

**Available as of 6.d language version** (early implementation exists in Rakudo compiler 2018.08+): You can specify a reason why the attribute is required:

```raku
class D {
    has $.a is required("it is a good idea");
}
my $d = D.new;
CATCH{ default { say .^name, ': ', .Str } }
# OUTPUT: «X::Attribute::Required: The attribute '$!a' is required because it is a good idea,␤but you did not provide a value for it.␤»

```

`is required` doesn't just affect the default constructor, it checks for the attribute at a lower level, so it will work for custom constructors written using [bless](/routine/bless).

## [trait is DEPRECATED](#class_Attribute "go to top of document")[§](#trait_is_DEPRECATED "direct link")

```raku
multi trait_mod:<is>(Attribute:D $r, :$DEPRECATED!)
```

Marks an attribute as deprecated, optionally with a message what to use instead.

```raku
class C {
    has $.foo is DEPRECATED("'bar'");
}
my $c = C.new( foo => 42 );  # doesn't trigger with initialization (yet)
say $c.foo;                  # does trigger on usage
```

**After** the program is finished, this will show something like this on STDERR:

```raku
# Saw 1 occurrence of deprecated code.
# =====================================
# Method foo (from C) seen at:
# script.raku, line 5
# Please use 'bar' instead.
```

## [trait is rw](#class_Attribute "go to top of document")[§](#trait_is_rw "direct link")

```raku
multi trait_mod:<is> (Attribute:D $attr, :$rw!)
```

Marks an attribute as read/write as opposed to the default `readonly`. The default accessor for the attribute will return a writable value.

```raku
class Boo {
   has $.bar is rw;
   has $.baz;
};

my $boo = Boo.new;
$boo.bar = 42; # works
$boo.baz = 42;
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Assignment::RO: Cannot modify an immutable Any␤»
```

## [trait is built](#class_Attribute "go to top of document")[§](#trait_is_built "direct link")

```raku
multi trait_mod:<is>(Attribute:D $a, :$built!)
```

By default, this trait allows setting up a *private attribute* during object construction via `.new`. The same trait can be used to prevent setting up a *public attribute* via `.new` by passing it the Boolean value `False`.

```raku
class Foo {
    has $!bar is built; # same as `is built(True)`
    has $.baz is built(False);

    method bar {
        $!bar
    }
}

my $foo = Foo.new(bar => 1, baz => 2);
say $foo.bar; # OUTPUT: «1␤»
say $foo.baz; # OUTPUT: «Any␤»
```

The `built` trait also allows named arguments to be specified. Currently the `:bind` named argument can be specified. In that case, any (default) value will be **bound** to the attribute, rather than assigned. This allows for specifying a `Proxy` to an attribute:

```raku
class Foo {
    has $!foo is built(:bind) = Proxy.new: :STORE{...}, :FETCH{...}
}
```

Available as of the 2020.01 release of the Rakudo compiler.

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

The usual way to obtain an object of type `Attribute` is by introspection:

```raku
class Useless {
    has @!things;
}
my $a = Useless.^attributes(:local)[0];
say $a.raku;            # OUTPUT: «Attribute.new␤»
say $a.name;            # OUTPUT: «@!things␤»
say $a.package;         # OUTPUT: «(Useless)␤»
say $a.has_accessor;    # OUTPUT: «False␤»
```

Modifying a private attribute from the outside is usually not possible, but since Attribute is at the level of the metaclass, all is fair game.

## [method name](#class_Attribute "go to top of document")[§](#method_name "direct link")

```raku
method name(Attribute:D: --> Str:D)
```

Returns the name of the attribute. Note that this is always the private name, so if an attribute is declared as `has $.a`, the name returned is `$!a`.

```raku
class Foo {
    has @!bar;
}
my $a = Foo.^attributes(:local)[0];
say $a.name;            # OUTPUT: «@!bar␤»
```

## [method package](#class_Attribute "go to top of document")[§](#method_package "direct link")

```raku
method package()
```

Returns the package (class/grammar/role) to which this attribute belongs.

```raku
class Boo {
    has @!baz;
}
my $a = Boo.^attributes(:local)[0];
say $a.package;         # OUTPUT: «(Boo)␤»
```

## [method has\_accessor](#class_Attribute "go to top of document")[§](#method_has_accessor "direct link")

```raku
method has_accessor(Attribute:D: --> Bool:D)
```

Returns `True` if the attribute has a public accessor method.

```raku
class Container {
    has $!private;
    has $.public;
}
my $private = Container.^attributes(:local)[0];
my $public = Container.^attributes(:local)[1];
say $private.has_accessor; # OUTPUT: «False␤»
say $public.has_accessor;  # OUTPUT: «True␤»
```

## [method rw](#class_Attribute "go to top of document")[§](#method_rw "direct link")

```raku
method rw(Attribute:D: --> Bool:D)
```

Returns `True` for attributes that have the "is rw" trait applied to them.

```raku
class Library {
    has $.address; # Read-only value
    has @.new-books is rw;
}
my $addr = Library.^attributes(:local)[0];
my $new-books = Library.^attributes(:local)[1];
say $addr.rw;      # OUTPUT: «False␤»
say $new-books.rw; # OUTPUT: «True␤»
```

## [method readonly](#class_Attribute "go to top of document")[§](#method_readonly "direct link")

```raku
method readonly(Attribute:D: --> Bool:D)
```

Returns `True` for readonly attributes, which is the default, or `False` for attributes marked as `is rw`.

```raku
class Library {
    has $.address; # Read-only value
    has @.new-books is rw;
}
my $addr = Library.^attributes(:local)[0];
my $new-books = Library.^attributes(:local)[1];
say $addr.readonly;      # OUTPUT: «True␤»
say $new-books.readonly; # OUTPUT: «False␤»
```

## [method required](#class_Attribute "go to top of document")[§](#method_required "direct link")

```raku
method required(Attribute:D: --> Any:D)
```

Returns `1` for attributes that have the "is required" trait applied, or [`Mu`](/type/Mu) if the attribute did not have that trait applied. If the "is required" trait is applied with a string, then that string will be returned instead of `1`.

```raku
class Library {
    has $.address is required;
    has @.new-books is required("we always need more books");
}
my $addr = Library.^attributes(:local)[0];
my $new-books = Library.^attributes(:local)[1];
say $addr.required;      # OUTPUT: «1␤»
say $new-books.readonly; # OUTPUT: «"we always need more books"␤»
```

## [method type](#class_Attribute "go to top of document")[§](#method_type "direct link")

```raku
method type(Attribute:D: --> Mu)
```

Returns the type constraint of the attribute.

```raku
class TypeHouse {
    has Int @.array;
    has $!scalar;
    has @.mystery;
}
my @types = TypeHouse.^attributes(:local)[0..2];
for 0..2 { say @types[$_].type }
# OUTPUT: «(Positional[Int])
# (Mu)
# (Positional)␤»
```

## [method get\_value](#class_Attribute "go to top of document")[§](#method_get_value "direct link")

```raku
method get_value(Mu $obj)
```

Returns the value stored in this attribute of object `$obj`.

```raku
class Violated {
    has $!private-thing = 5;
}
my $private = Violated.^attributes(:local)[0];
say $private.get_value(Violated.new); # OUTPUT: «5␤»
```

Note that this method violates encapsulation of the object, and should be used with care. Here be dragons.

## [method set\_value](#class_Attribute "go to top of document")[§](#method_set_value "direct link")

```raku
method set_value(Mu $obj, Mu \new_val)
```

Binds the value `new_val` to this attribute of object `$obj`.

```raku
class A {
    has $!a = 5;
    method speak() { say $!a; }
}
my $attr = A.^attributes(:local)[0];
my $a = A.new;
$a.speak; # OUTPUT: «5␤»
$attr.set_value($a, 42);
$a.speak; # OUTPUT: «42␤»
```

Note that this method violates encapsulation of the object, and should be used with care. Here be dragons.

## [method gist](#class_Attribute "go to top of document")[§](#method_gist "direct link")

```raku
multi method gist(Attribute:D:)
```

Returns the name of the type followed by the name of the attribute.

```raku
class Hero {
    has @!inventory;
    has Str $.name;
    submethod BUILD( :$name, :@inventory ) {
        $!name = $name;
        @!inventory = @inventory
    }
}
say Hero.^attributes(:local)[0]; # OUTPUT: «Positional @!inventory␤»

```

Since say implicitly calls `.gist`, that is what produces the output here.

# [Optional introspection](#class_Attribute "go to top of document")[§](#Optional_introspection "direct link")

## [DEPRECATED](#class_Attribute "go to top of document")[§](#DEPRECATED "direct link")

If an attribute is marked as `DEPRECATED`, then calling the `DEPRECATED` method is possible and will return `"something else"` (if no specific reason was specified) or the string that was specified with the `DEPRECATED` trait.

If an attribute is **not** marked as DEPRECATED, one **cannot** call the `DEPRECATED` method. Therefore, the `.?method` syntax should be used.

```raku
class Hangout {
    has $.table;
    has $.bar is DEPRECATED("the patio");
}
my $attr-table = Hangout.^attributes(:local)[0];
my $attr-bar = Hangout.^attributes(:local)[1];
with $attr-table.?DEPRECATED -> $text {     # does not trigger
    say "Table is deprecated with '$text'";
    # OUTPUT:
}
with $attr-bar.?DEPRECATED -> $text {
    say "Bar is deprecated with '$text'";
    # OUTPUT: «Bar is deprecated with 'the patio'"␤»
}
```

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

Type relations for `Attribute`

raku-type-graph

Attribute
Attribute

Any
Any

Attribute->Any

Mu
Mu

Any->Mu

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


## dist_zef-jonathanstowe-Audio-Liquidsoap.md
# Audio::Liquidsoap

Interact with the Liquidsoap telnet interface.

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

## Synopsis

```

use Audio::Liquidsoap;

my $ls = Audio::Liquidsoap.new;

say "Connected to liquidsoap { $ls.version } up since { DateTime.new($ls.uptime) }";

...

```

There are more complete examples in the [Examples Directory](./examples)

## Description

This provides a mechanism to interact with the [Liquidsoap media
toolkit](https://liquidsoap.info/) and possibly build radio applications
with it.

It provides abstractions to interact with the defined Inputs, Outputs,
Queues, Playlists and Requests to the extent allowed by the "telnet"
or "socket" interface of `liquidsoap`. There is also a generalised
mechanism for sending arbitrary commands to the server, such as those
that may have been provided by the liquidsoap `server.register` function.
However it should be borne in mind that you will almost certainly need
to still actually write some liquidsoap script in order to declare the
things to manipulate.

This supports both the "telnet" (TCP) and "socket" (Unix domain socket,)
server interfaces which can be configured as described in [the Liquidsoap
settings](https://www.liquidsoap.info/doc-1.4.3/settings.html#server-configuration).
The Unix domain socket interface is to be preferred for production use
as there is no authentication on the server interface.

## Installation

You will need to have "liquidsoap" installed on your system in order to
be able to use this. Some Linux distributions and some versions of FreeBSD
provide it as a package.

If you are on some platform that doesn't provide liquidsoap as a package
then you may be able to install it from [source](http://liquidsoap.info/download.html).

It's written in OCaml and has lots of dependencies that you are unlikely
to already have but it's doable on most platforms. Alternatively there is
a [docker image](https://hub.docker.com/repository/docker/jonathanstowe/rakudo-liquidsoap)
want to use that to run the tests, it is described in the README in the repository.

The tests assume that you have `liquidsoap` installed somewhere in your
path and will run an instance on an unused port so as not to interfere
with some running instance you may already have. If your `liquidsoap`
is installed somewhere that is not in your path then you can set the
environment variable `LIQUIDSOAP` to the full path of the binary
before running the tests.

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

```
# From the source directory

zef install .

# Remote installation

zef install Audio::Liquidsoap

```

## Support

Because of the potential complexity that can be achieved in
custom liquidsoap scripts, this almost certainly doesn't cover
every possibility in the interface, but if you really need
something I have omitted or have other suggestions please raise
an issue at [github](https://github.com/jonathanstowe/Audio-Liquidsoap/issues)

And I'll see what I can do.

I'm also probably not the best person to ask if you have anything
but the most simple questions about liquidsoap itself, which may
probably be raised via the liquidsoap website.

## Licence

This is free software.

Please see the <LICENCE> file in the distribution

© Jonathan Stowe 2016 - 2021


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

# NAME

**Astro::Utils** - Provides utility functions for astronomical calculations

# SYNOPSIS

```
use Astro::Utils :ALL;
my $x = 1.234;
my $y = 5.5678;
say Frac $x;       # OUTPUT: «0.234␤»
say Modulo $x, $y; # OUTPUT: «1.234␤»
say Modulo $y, $x; # OUTPUT: «0.6318␤»

```

# DESCRIPTION

Raku module **Astro::Utils** is a collection of utility functions from several popular astronomy-related books by authors such as *Montenbruck*, *Meeus*, and *Lawrence*. Also included are functions from Perl module [Astro::Montenbruck](https://github.com/skrushinsky/astro-montenbruck).

## Exported functions

### Frac

```
sub Frac($x --> Real) is export(:Frac) {...}

```

Returns the fractional part of a number (from Ref. 1, p. 8). (Note it is the same as the `frac` function from Raku module `Math::FractionalPart`.)

### Modulo

```
sub Modulo($x, $y) is export(:Modulo) {...}

```

Returns $x mod $y (from Ref. 1, p. 8). (Note it is the same as the Raku infix operator `%`.)

### delta-T

```
sub delta-T($year, $month --> Real) is export(:delta-T) {...}

```

Returns the `delta-T` value for the given year and month.

From <https://eclipse.gsfc.nasa.gov/SEhelp/deltatpoly2004.html>:

The orbital positions of the Sun and Moon required by eclipse predictions, are calculated using Terrestrial Dynamical Time (TD) because it is a uniform time scale. However, world time zones and daily life are based on Universal Time[1] (UT). In order to convert eclipse predictions from TD to UT, the difference between these two time scales must be known. The parameter delta-T (ΔT) is the arithmetic difference, in seconds, between the two as:

```
ΔT = TD - UT

```

### delta-T2

```
sub delta-T2(DateTime $T --> Real) is export(:delta-T2) {...}

```

Also returns ΔT (see routine `delta-T`), but using code based on the `delta_t` function from Ref. 3, file '../Time/DeltaT.pm'.

### dayfrac2hms

```
sub dayfrac2hms($dayfraction is copy --> List) is export(:dayfrac2hms) {...}

```

Returns the `$dayfraction` as a list of `hours` (Int), `minutes` (Int), and `minutes` (Real) (from Ref. 2).

`$dayfraction` must be a fraction of a day of 24 hours. The input's integral portion, if any, is ignored.

### polynome

```
sub polynome($t, @terms) is export(:polynome) {...}

```

Calculates the polynomial `a0*t**0 + a1*t**1 + a2*t**2 + a3*t**3...` using code based on the `polynome` function from Ref. 3, file '../Montenbruck/MathUtils.pm'.

Parameters: `$t` is the coefficient (in astronomical routines it's usually time in centuries) and `@terms` is a list of any number of decimal values.

## References

1. *Astronomy on the Personal Computer, 4th Edition*, Oliver Montenbruck and Thomas Pfleger, 2000, Springer-Verlag.
2. *Celestial Calculations*, J. L. Lawrence.
3. Perl module [Astro::Montenbruck](https://github.com/skrushinsky/astro-montenbruck).

# AUTHOR

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

# COPYRIGHT and LICENSE

Copyright © 2021, 2023, 2025 Tom Browder

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


## dist_zef-guifa-Timezones-ZoneInfo.md
# Timezones::ZoneInfo

A Raku module containing data (as well as some support routines) based on IANA's TZ database.
This module is not normally expected to be consumed on its own — it is designed to be as light weight as possible.
Its intended use is for authors of various time-related tools.

Current IANA database version: **2022f**

When updating this module, ensure all modules that depend on it are recompiled.

# Usage

The first four subs are exported by default. All methods work on times with integral seconds. It is currently left to the end user to handle any fractional seconds.

* **`sub timezones-as-set(:$standard = True, :$aliases = False, :$historical = False --> Set)`**
  This provides a list of all timezone identifiers as a set (if you need it as a list, `.keys`). By default it does not include various aliases (generally, but not always, spell changes in identifiers like *Kiev*→*Kyiv*). Historical zones are those that go back to the early part of the 20th century and farther back and rarely if ever needed. They are currently NYI.
* **`timezone-data (Str() $olson-id --> State)`**
  Obtains the data for the given timezone. The identifier is the Olson ID for the zone. Backlinks for legacy IDs are followed. If the zone does not exist, a warning is issued and the data for `Etc/GMT` is provided as a fallback. See below for details on the `State` class.
* **`sub calendar-from-posix (int64 $time, State $tz-data, :$leapadjusted = False --> Time)`**
  Given a [POSIX `time_t` stamp](https://www.gnu.org/software/libc/manual/html_node/Time-Types.html), provides the associated date/time (in a `Time` structure) for the timezone. Passing `:leapadjusted` indicates that leapseconds are already included in the timestamp (this is not POSIX standard, but may be preferable for some applications).
* **`sub posix-from-calendar (Time $tm-struct, State $tz-data, :$leapadjust = False --> int64)`**
  Given a `Time` object (only ymdHMS values are used), provides the associated POSIX `time_t` timestamp and GMT offsets. Pay close attention to the `dst` attribute: use `1` or `0` if you know the time to be in daylight savings time or not, use `-1` if you are not sure. Passing `:leapadjust` will include leap seconds in the timestamp (not POSIX standard, but may be preferable for some applications).

The final two methods are available by providing the `tz-shift` option in the `use` statement. They will return a time in the same format provided.

* **`sub next-tz-shift (Time|int64 $time, State $tz-data, :$leapadjust = False --> Time|int64)`**
  Given either a `Time` object (only ymdHMS values are used) or a POSIX `time_t` timestamp, indicates when the next shift in GMT offsets will occur. Generally, that's when daylight savings time will start or end, but it may also be when an area shifts timezones entirely (e.g. when Russia makes adjustments to its timezones at various periods throughout the year). Passing `:leapadjust` will include leap seconds in the timestamp (not POSIX standard, but may be preferable for some applications). This routine returns values in the same format provided.
* **`sub prev-tz-shift (Time|int64 $time, State $tz-data, :$leapadjust = False --> Time|int64)`**
  Same as `next-tz-shift` but in reverse. Finds the most recent previous shift in timezone data.

Both `next-tz-shift` and `prev-tz-shift` can potentially return a special extremely small or large integer value.
Such values are intended to represent an “infinite” past or future, but may be different given compiler/architecture/system.
`Timezones::ZoneInfo` will detect your system's maximum and minimum time values upon installation and those
values can be obtained using the constants `max-posix-time` and `min-posix-time` (exported with `:constants` in the `use` statement).
On my system, for instance, these are **263 - 1 - 27**, and **0 - 263**, where 27 is the current number of leapseconds.

# Class reference

### Timezones::ZoneInfo::Time

A Raku version of the [POSIX `tm` struct](https://www.gnu.org/software/libc/manual/html_node/Broken_002ddown-Time.html) (with BSD/GNU extension). Attributes include

* `.year` (**-∞..∞**, *years since 1900, 1910 = 10*)
* `.month` (**0..11**, *months since January*)
* `.day` (**1..31**)
* `.hour` (**0..23**)
* `.minute` (**0..59**)
* `.second` (**0..61**, *values of 60-61 for leapseconds*)
* `.weekday` (**0..6**, *days since Sunday; Monday = 1*)
* `.yearday` (**0..365**, *day index in year, 0 = January 1st*)
* `.dst` (**-1..1**; *0 standard time, 1 summer time, -1 unknown/automatic*)
* `.gmt-offset` (**-∞..∞**, *offset of GMT, positive = east of GMT*)
* `.tz-abbr` (*three or four letter abbreviation, non-unique*)

The infinite ranged elements aren't actually that as they're stored as `int32`.

### Timezones::ZoneInfo::State

A Raku version of `tz`'s `state` struct. It will be made more easily introspectable in the future. For now, these are the attributes:

* `.leapcnt` (*number of leap seconds*)
* `.lsis` (*array of `LeapSecInfo`, describing when they occur and by how much*)
* `.timecnt` (*number of moments when time shifts*)
* `.ats` (*array of moments, as `time_t` when time shifts*)
* `.typecnt` (*number of transition types*)
* `.ttis` (*array of `TransTimeInfo`, providing meta data for time shifts*)
* `.types` (*array of indexes pointing to meta data for time shifts*)
* `.chars` (*c-style string data indicating timezone abbreviations*)
* `.charcnt` (*length of `chars`*)
* `.name` (*the Olson ID for the zone*)

# Data

The data comes from IANA's [**tz** database](https://www.iana.org/time-zones).

# Todo

* Add support for fractional seconds
* Tweak custom warning throwing

# Version history

* 0.4.5
  * Updated to 2025b version of the database
    * Historical changes to numerous timezones in Mexico, Mongolia and Portugal
* 0.4.4
  * Updated to 2024a version of the database
    * Kazakhstan unifies its timezones
    * Palestine adjusts its DST transition
    * Fixes to Vietnam, Canada and France's historical data
* 0.4.3
  * Updated to 2023c version of the database incorporating changes from 2023a and 2023b
    * Lebanon delays DST start (2023b) — but not actually (2023c)
    * Egypt uses DST again (2023a)
    * Greenland will still use DST (2023a)
    * Palestine delays DST (2023a)
    * Jordan starts DST earlier this year (2023a)
* 0.4.2
  * Updated to 2022g version of the database
    * Mexico's Chihuahua state will follow DST
    * Most of Greenland will not follow DST after March 2023
    * Fixes to Colombia, Singapore, and Canada's historical data
  * Bug fix for single offset timezones like GMT+5
* 0.4.1
  * Updated to 2022f version of the database
    * Mexico and Fiji no longer observes DST in most areas
    * `GMT` is now the standard form for `Etc/GMT` (both will still work)
* 0.4.0
  * Add new feature to find previous/next shifts in timezone (`next-tz-rule-change` and `prev-tz-rule-change`)
  * Fixed a major calculation bug in interpreting POSIX tz strings
  * New tests to guard against future bugs
  * Moved maintenance tools out of `resources` and into `tools` (they aren't needed at runtime)
  * Updated to 2022e version of the database
    * Jordan and Syria will now observe DST year round
    * Minor fixes for historical data in Mexico
* 0.3.1
  * Debug-mode–guarded some code that was spitting random hyphens
* 0.3.0
  * Added new exported routine `timezones-as-set`
  * Updated to 2022d version of the database (2022c did not have new tz data)
    * Palestine will enter DST on Saturdays
    * Ukraine zones simplified
* 0.2.2
  * Updated to 2022b version of the database
    * Urgent update for Chile
    * Iran will no longer use DST
* 0.2.1
  * Updated to 2022a version of the database
    * Urgent update for Palestine
    * Improvements to historical data for Ukraine and Chile.
* 0.2.0
  * Added support for version 3 files (these allow for full repeat into the future)
* 0.1.0
  * First public release

# Copyright and license

The `tz` database and the code in it is public domain. Therefore, the author of this module (Matthew Stephen Stuckwisch) would find it unconscionable to release this module under any license, even for his own additions. Consequently, this module is similarly expressly released into the public domain. For jurisdictions where that is not possible, this module may be considered © 2021–2022 and licensed under CC0 v1.0 (see accompanying license file).


## slangs.md
Slangs

Slangs in Raku

The term "Slang" is used two different ways within the Raku community:

* To refer to sublanguages within Raku, such as the quoting sublanguage or the regex sublanguage.
* To refer to variants of Raku that are created by adding in a slang module that modifies the grammar of the language.

# [Sublanguages within Raku](#Slangs "go to top of document")[§](#Sublanguages_within_Raku "direct link")

The `~` twigil is for referring to sublanguages (called slangs). The following are useful:

|  |  |
| --- | --- |
| $~MAIN | the current main language (e.g., Raku statements) |
| $~Quote | the current root of quoting language |
| $~Quasi | the current root of quasiquoting language |
| $~Regex | the current root of regex language |
| $~Trans | the current root of transliteration language |
| $~P5Regex | the current root of the Perl regex language |

You `augment` these languages in your current lexical scope.

```raku
use MONKEY-TYPING;
augment slang Regex {  # derive from $~Regex and then modify $~Regex
    token backslash:std<\Y> { YY };
}

```

The `MONKEY-TYPING` pragma is a necessary prerequisite to using the `augment` keyword. It can be thought of as a reminder that the following code is of a type that's usually discouraged. More documentation on `augment` is at [the augment declarator](/language/variables#The_augment_declarator).

# [Slangs that Modify the Language](#Slangs "go to top of document")[§](#Slangs_that_Modify_the_Language "direct link")

## [Existing Slangs](#Slangs "go to top of document")[§](#Existing_Slangs "direct link")

Many slangs are made available as modules through zef. These are useful for:

* Using directly, so you don't have to write your own slang
* As examples, for inspiration in writing your own slangs

To see the existing Slang modules, we can look at:

* [Everything tagged Slang](https://raku.land/tags/slang)
* [A search for slang](https://raku.land/?q=slang)

## [Prerequisites for Understanding Slangs](#Slangs "go to top of document")[§](#Prerequisites_for_Understanding_Slangs "direct link")

If all you wish to do is use existing Slangs, you can stop reading now. However, if you wish to understand better how to make or modify Slangs, then the recommended reading before continuing is:

* [Grammar tutorial](/language/grammar_tutorial)
* [Grammars](/language/grammars)
* Not required, but helpful: [class Grammar](/type/Grammar)

## [A Slang Example](#Slangs "go to top of document")[§](#A_Slang_Example "direct link")

To get a good view of a nice, simple Slang, the best candidate would be the source for [Slang::Lambda](https://raku.land/zef:lizmat/Slang::Lambda).

Slang::Lambda modifies the Raku grammar to make it possible to use the `λ` (lambda) symbol as the starter symbol of a pointy block (which is usually `->`). The source is so short we can include it here:

```raku
my role RakuLambda {
    token pointy-block-starter { '->' | '→' | '<->' | '↔' | 'λ' }
}

my role LegacyLambda {
    token lambda { '->' | '<->' | 'λ' }
}

use Slangify:ver<0.0.4+>:auth<zef:lizmat> RakuLambda, Mu, LegacyLambda;

```

Then to use it, we do:

```raku
use Slang::Lambda;

say (1,2,3).map: λ $x { $x+1 }  # (2 3 4)

```

The code is self-evident to those familiar with Raku's grammars. This is all well and good, but sometimes there's a large gap between being able to read code, and being able to write it. How did Elizabeth (the author of Slang::Lambda) know to use Slangify? How did she know what token names to declare? In her case, it was through extensive study of Raku and how it works, but in order to avoid this, we're going to step through some of these things now.

## [Slangify](#Slangs "go to top of document")[§](#Slangify "direct link")

To ease the process of creating Slangs, Elizabeth Mattijsen also created the [Slangify](https://raku.land/zef:lizmat/Slangify) module (that's how she knew about it!) The Slangify module is a module intended for slang developers.

It abstracts the internals of slang creation and activation so that module developers of slangs have a consistent interface they can work with across current and future versions of the Raku Programming Language.

To use it you do the following:

```raku
use Slangify Foo::Grammar, Foo::Actions;

```

Either the Grammar or the Actions can be replaced with `Mu` to indicate that they should remain unchanged.

Two additional parameters, for legacy grammars and legacy actions, are also accepted.

While using Slangify is logically the last step in your code, it's worth understanding it somewhat before you begin, so that you can align your code with it. For further details, read the documentation for [Slangify](https://raku.land/zef:lizmat/Slangify).

## [The Raku Grammar](#Slangs "go to top of document")[§](#The_Raku_Grammar "direct link")

This is the point where you need to do the most digging. The Raku grammar is not small, and nor is it simple; its extensive error messages, which are great when programming, hinder the readability.

The sources for the Raku grammar are:

* [The new AST grammar](https://github.com/rakudo/rakudo/blob/main/src/Raku/Grammar.nqp)
* [The old, pre-AST grammar](https://github.com/rakudo/rakudo/blob/main/src/Perl6/Grammar.nqp)

Unfortunately there's no substitute for digging through the grammar and locating the tokens/rules which you wish to override.

## [The Slang Grammar](#Slangs "go to top of document")[§](#The_Slang_Grammar "direct link")

Now you need to write the slang grammar, much like Slang::Lambda. The links above to the grammar documentation should help here.

## [The Slang Actions](#Slangs "go to top of document")[§](#The_Slang_Actions "direct link")

Many slangs will also need an Actions class backing them. This is also documented in the grammar documentation linked above.

## [Publishing the module](#Slangs "go to top of document")[§](#Publishing_the_module "direct link")

You'll want to get your module published too. To do this, follow the instructions under [Upload your module to zef ecosystem](/language/modules#Upload_your_module_to_zef_ecosystem).


## dist_zef-vrurg-Config-BINDish.md
# NAME

`Config::BINDish` - parse BIND9/named kind of config files

# SYNOPSIS my $cfg = Config::BINDish.new; $cfg.read: string => q:to/CFG/; server "s1" { name "my.server"; paths { base "/opt/myapp"; pool "files" static { "pub/img"; "static/img"; "docs"; }; pool "files" dynamic { "users/reports"; "system/reports" } } } CFG say $cfg.top.get( :server("s1") => :paths => :pool("images") => 'root' ); # ./pub/img

$cfg.read: file => $my-config-filename;

# DISCLAIMER

This module is very much experimental in the sense of the API methods it provides. The grammar is expected to be more stable, yet no warranties can be given at the moment.

# DESCRIPTION

In this documentation I'll be referring to the configuration format implemented by the module as *BINDish config* or simply *BINDish*.

# EXTENSIONS

BINDish configuration parser can be augmented with 3rd-party extensions. Every extension is implemented as a role which will be used to build the final grammar or actions classes (see [`Grammar`](https://docs.raku.org/type/Grammar)). The classes are based upon [`Config::BINDish::Grammar`](docs/md/Config/BINDish/Grammar.md) and [`Config::BINDish::Actions`](docs/md/Config/BINDish/Actions.md) respectively. Here is the steps `Config::BINDish` does to build them:

* An empty class is created which will serve as the final version
* Extension roles are punned and added as parents to the class
* Then the base class is added as the last parent

The order in which the extensions are added is defined by the order and the way they're registered. The later added ones serve as the earlier parents meaning that Raku's method call dispatching will have their methods invoked first.

There are two and a half ways to extend the parser. First is to use `is BINDish-grammar` or `is BINDish-actions` trait:

```
unit module Config::BINDish::Ext1;
use Config::BINDish;
role Grammar is BINDish-grammar {
    token value:sym<mine> {
        ...
    }
}
role Actions is BINDish-actions {
    method value:sym<mine>($/) {
        ...
    }
}

```

In this case the role they're applied to will be auto-registered with `Config::BINDish`. When such extension is contained by a module then it would be added when the module is `use`d:

```
use Config::BINDish::Ext1;
use Config::BINDish::Ext2;

```

*Note* that considering the order of `use` statements, `Ext2` will be able to override methods of `Ext1`.

The specificifty of using the traits is that extensions declared this way will become application-wide available. So, even if the extension module is used by a module used by the main code, the extension will be available to any instance of `Config::BINDish`.

**Note:** We say that extensions registered with the traits are registered *statically*.

The other 1.5 ways of adding the extensions are to use `extend-grammar` and `extend-actions` constructor arguments or methods with the same names:

```
my $cfg = Config::BINDish.new: :extend-grammar(ExtG1, ExtG2), :extend-actions(ExtA1, ExtA2);
$cfg.extend-grammar(ExtG3)
    .extend-actions(ExtA3);

```

In this case extension roles don't need the traits applied. This way we call *dynamic* registration.

The other specific of dynamic extensions is that they will go after the static ones. I.e. in the above examples `ExtG*` and `ExtA*` will be positioned before `Ext1` and `Ext2` in the MRO order, prioritizing the former over the latter ones.

Why is the above called *1.5 ways*? Because the constructor eventually uses the `extend-*` methods with corresponding `:extend-*` named attributes.

See also [`Config::BINDish::Grammar`](docs/md/Config/BINDish/Grammar.md) and [`Config::BINDish::Actions`](docs/md/Config/BINDish/Actions.md).

# ATTRIBUTES

## [`Config::BINDish::Grammar::Strictness`](docs/md/Config/BINDish/Grammar/Strictness.md) `$.strict`

The default grammar strictness mode. See [`Config::BINDish::Grammar::Strictness`](docs/md/Config/BINDish/Grammar/Strictness.md) documentation for details.

## [`Pair:D`](https://docs.raku.org/type/Pair) `@.blocks`, [`Pair:D`](https://docs.raku.org/type/Pair) `@.options`

These two attributes contain user-defined (pre-declared) structure of the config file. More information about them can be found in [Config::BINDish::Grammar](BINDish/Grammar.md) documentation, in [Pre-declaration](BINDish/Grammar.md#Pre-declaration) section.

## `$.grammar`, `$.actions`

The final grammar and actions class versions with all registered extensions applied. Both attributes are *lazy* and `clearable` in terms of [`AttrX::Mooish`](https://modules.raku.org/dist/AttrX::Mooish). It means that the following is possible:

```
say $cfg.grammar.^name; # Config::BINDish::Grammar...
$cfg.extend-grammar(MyApp::GrammarMod);
$cfg.clear-grammar;     # Actually, extend-grammar already does this. This line is here to demo the concept only.
say $cfg.grammar.^name; # Config::BINDish::Grammar+{MyApp::GrammarMod}...

```

## [`IO::Path`](https://docs.raku.org/type/IO::Path) `$.file`

If `read` method was called with `:file<...>` argument then this attribute will hold corresponding `IO::Path` object for the file name.

## [`Bool`](https://docs.raku.org/type/Bool) `$.flat = False`

If set to `True` then [`Config::BINDish::Actions`](docs/md/Config/BINDish/Actions.md) will act in flattening mode.

## `$.top`

The top node produced by the grammar actions. I.e. it is the result of `$<TOP>.ast` of the [`Match`](https://docs.raku.org/type/Match) object produced by grammar's `parse` method. For [`Config::BINDish::Actions`](docs/md/Config/BINDish/Actions.md) it would be an instance of [`Config::BINDish::AST::TOP`](docs/md/Config/BINDish/AST/TOP.md). But an extension can produce something to its taste which wouldn't be an AST whatsoever. The only requirement imposed on the object stored in the attribute is to provide `get` method.

This attribute `handles` method `get`.

## `$.match`

This attribute stores the [`Match`](https://docs.raku.org/type/Match) object produced by grammar's `parse` method.

# METHODS

## `extend-grammar( +@ext )`, `extend-actions( +@ext )`

Interface to dynamically register extensions. Take a list of roles and records them as extensions. Then it clears `$.grammar` or `$.actions` attributes, respectively. Both return `self` to allow method call chaining.

## `build-grammar()`, `build-actions()`

Methods used by [`AttrX::Mooish`](https://modules.raku.org/dist/AttrX::Mooish) to lazily initialize `$.grammar` and `$.actions` attributes respectively.

`multi method read(Config::BINDish:U: |args)`

Instantiates `Config::BINDish` class and re-invokes `read` method on the instance with `args` capture.

## `multi method read(IO:D(Str:D) :$file, |args)`, `multi method read(Str:D :$string, |args)`

Parses a configuration stored either in a `$string` or in a `$file` and returns the resulting [`Match`](https://docs.raku.org/type/Match) object. The capture `args` is passed over to the `parse` method of `$.grammar` alongside with `$.actions`, `$.strict`, `$.flat`, `%.blocks`, and `%.options` attributes.

The method returns what is returned by grammar's `parse` method. The same value is then stored in `$.match` attribute.

### `multi get(...)`

Method is handled by `$.top` attribute. See [`Config::BINDish::AST::Blockish`](docs/md/Config/BINDish/AST/Blockish.md) for detailed method description.

# EXPORTS

By default this module exports only `BINDish-grammar` and `BINDish-actions` traits. But if `use`d with either "op" or "ascii-op" positional arguments it will also export *request operator* in either unicode or ASCII form:

```
use Config::BINDish <op>;
my $cfg = Config::BINDish.new.read(...);
say $cfg ∷ :top-block<name> ∷ "option";

```

Or:

```
use Config::BINDish <ascii-op>;
my $cfg = Config::BINDish.new.read(...);
say $cfg :: :top-block<name> :: "option";

```

*Note* that `::` (ASCII version) may conflict with Raku's name resolution. Though in my tests this never happened, I would still prefer the unicode version over the ASCII.

More information about the operator can be found in [`Config::BINDish::Ops`](docs/md/Config/BINDish/Ops.md).

# SEE ALSO

* [`Config::BINDish::Grammar`](docs/md/Config/BINDish/Grammar.md)
* [`Config::BINDish::AST`](docs/md/Config/BINDish/AST.md)
* [`Config::BINDish::Ops`](docs/md/Config/BINDish/Ops.md)
* [`Config::BINDish::Expandable`](docs/md/Config/BINDish/Expandable.md)
* [`Config::BINDish::INET`](docs/md/Config/BINDish/INET.md)
* [`README`](README.md)
* [`INDEX`](INDEX.md)

# COPYRIGHT

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

# LICENSE

Artistic License 2.0

See the [*LICENSE*](LICENSE) file in this distributio


## slurp-rest.md
slurp-rest

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/IO/Handle#method_slurp-rest)
for **method slurp-rest**.

```raku
multi method slurp-rest(IO::Handle:D: :$bin! --> Buf)
multi method slurp-rest(IO::Handle:D: :$enc --> Str)
```

**DEPRECATION NOTICE:** this method is deprecated in the `6.d` version. Do not use it for new code, use [`.slurp` method](/routine/slurp) instead.

Returns the remaining content of the file from the current file position (which may have been set by previous reads or by `seek`.) If the adverb `:bin` is provided a [`Buf`](/type/Buf) will be returned; otherwise the return will be a [`Str`](/type/Str) with the optional encoding `:enc`.


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

# NAME

Terminal::ANSIColor - Color screen output using ANSI escape sequences

# SYNOPSIS

```
use Terminal::ANSIColor;

say color('bold'), "this is in bold", color('reset');
say colored('what a lovely colours!', 'underline red on_green');
say BOLD, 'good to be fat!', BOLD_OFF;
say 'ok' if colorvalid('magenta', 'on_black', 'inverse');
say '\e[36m is ', uncolor('\e36m');
say colorstrip("\e[1mThis is bold\e[0m");

```

# DESCRIPTION

Terminal::ANSIColor provides an interface for using colored output in terminals. The following functions are available:

## color

Given a string with color names, the output produced by `color()` sets the terminal output so the text printed after it will be colored as specified. The following color names are recognised:

```
reset bold italic underline inverse
bold_off italic_off underline_off inverse_off
black red green yellow blue magenta cyan white
default on_black on_red on_green on_yellow
on_blue on_magenta on_cyan on_white on_default

```

The on\_\* family of colors correspond to the background colors. One or three numeric color values in the range 0..255 may also be specified:

```
N     # 256-color map: 8 default + 8 bright + 216 rgb cube + 24 gray
on_N  # Same, but background

N,N,N     # 24-bit r,g,b foreground color
on_N,N,N  # 24-bit r,g,b background color

```

## colored

`colored()` is similar to `color()`. It takes two Str arguments, where the first is the string to be colored, and the second is the (space-separated) colors to be used. The `reset` sequence is automagically placed after the string.

## colorvalid

`colorvalid()` gets an array of color specifications (like those passed to `color()`) and returns true if all of them are valid, false otherwise.

## colorstrip

`colorstrip`, given a string, removes all the color escape sequences in it, leaving the plain text without color effects.

## uncolor

Given escape sequences, `uncolor()` returns a string with readable color names. E.g. passing "\e[36;44m" will result in "cyan on\_blue".

# Constants

`Terminal::ANSIColor` provides constants which are just strings of appropriate escape sequences. The following constants are available:

```
RESET BOLD ITALIC UNDERLINE INVERSE
BOLD_OFF ITALIC_OFF UNDERLINE_OFF INVERSE_OFF

```

# AUTHORS

Tadeusz “tadzik” Sośnierz

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

Source can be located at: <https://github.com/lizmat/Terminal-ANSIColor> . 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 2010 - 2018 Tadeusz “tadzik” Sośnierz

Copyright 2022 - 2024 Elizabeth Mattijsen

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


## dist_zef-jonathanstowe-Audio-Convert-Samplerate.md
# Audio::Convert::Samplerate

Convert the samplerate of PCM audio data using libsamplerate (AKA "Secret Rabbit Code".)

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

## Description

This provides a mechanism for doing sample rate conversion of PCM audio
data using libsamplerate (<http://www.mega-nerd.com/libsamplerate/>)
the implementation of which is both fairly quick and accurate.

The interface is fairly simple, providing methods to work with native
C arrays where the raw speed is important as well as Raku arrays where
further processing is required on the data.

The native library is designed to work only with 32 bit floating point
samples so working with other sample types requires some conversion
and a subsequent small loss of efficiency (although the int and short
to float conversions are done in C code and so are reasonably quick.)
There is no support for 64 bit int (long) or float (double) data.

The full documentation is available as POD or [Markdown](Documentation.md)

## Installation

You will need to have "libsamplerate" installed on your system in order to
be able to use this. Most Linux distributions offer it as a package, though
it is such a common dependency for multimedia applications that you may well
already have it installed.

If you are on some platform that doesn't provide libsamplerate as a package
then you may be able to install it from source:

<http://www.mega-nerd.com/libsamplerate/download.html>

I am however unlikely to be able to offer help with installing it this way.

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

```
# From the source directory

zef install .

# Remote installation

zef install Audio::Convert::Samplerate

```

Other install mechanisms may be become available in the future.

## Support

Suggestions/patches are welcomed via [github](https://github.com/jonathanstowe/Audio-Convert-Samplerate/issues)

## Licence

Please see the <LICENCE> file in the distribution

© Jonathan Stowe 2015 - 2024


## noself.md
class X::Syntax::NoSelf

Compilation error due to implicitly using a `self` that is not there

```raku
class X::Syntax::NoSelf does X::Syntax { }
```

Compile time error thrown when `$.foo` style calls are used where no invocant is available.

For example the code

```raku
$.meth;

```

in the program body throws the error

｢text｣ without highlighting

```

```

===SORRY!===
Variable $.meth used where no 'self' is available

```

```

because `$.meth` is short for `$(self.meth)`, and there is no `self` available in mainline.

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

## [method variable](#class_X::Syntax::NoSelf "go to top of document")[§](#method_variable "direct link")

Returns the variable/method call that caused the error.


## dist_zef-jonathanstowe-NativeHelpers-Array.md
# NativeHelpers::Array

Helper subroutines for working with Raku Native Arrays (CArray)

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

## Description

This provides a number of exported subroutines that may prove
useful when dealing with array data in a native binding.

The subroutines themselves are not particularly sophisticated
but having them in a separate module saves copying the code
into modules where they may be useful.

## Installation

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

```
zef install .

```

Remote installation

```
zef install NativeHelpers::Array

```

Other install mechanisms may be become available in the future.

## Support

Suggestions/patches are welcomed via github at <https://github.com/jonathanstowe/NativeHelpers-Array/issues>

## Licence

This is free software.

Please see the <LICENCE> file in the distribution for details.

© Jonathan Stowe 2015 - 2021


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

# NAME

SSH::LibSSH::Tunnel - establish remote forwarding SSH tunnel

# SYNOPSIS

```
use SSH::LibSSH::Tunnel;

my SSH::LibSSH::Tunnel:D $ssh-tunnel .= new: :tunnel-host<intermediary>,
   :tunnel-user<useratintermediary>,
   :tunnel-port(22), # default is 22 (ssh)
   :local-host<127.0.0.1>, # default is 127.0.0.1 (localhost)
   :local-port<33333>, # default (zero) means "let the OS choose"
   :remote-host<finaldestination>,
   :remote-port<3306>,
   :private-key-file($*HOME.add: '.ssh/some_key'),
   :timeout(30); # default is 30s -- passed to SSH::LibSSH
my $connection = $ssh-tunnel.connect;
# at this point, the tunnel is already connected
my $port-to-connect = $ssh-tunnel.local-port; # useful if passed the default

```

# DESCRIPTION

SSH::LibSSH::Tunnel is a library (based on SSH::LibSSH) to simplify the setup of forwarding SSH tunnels.

# FIELDS

### has Str $.local-host

address that will listen locally for the tunnel

### has Int(Any) $.local-port

port that will listen locally for the tunnel

### has Str $.tunnel-host

intermediary host (will connect on it via ssh)

### has Int(Any) $.tunnel-port

intermediary SSH service port

### has Str $.tunnel-user

SSH user on the intermediary host

### has IO(Any) $.private-key-file

SSH private key file for connection (no password, for now)

### has Str $.remote-host

destination tunnel host

### has Int(Any) $.remote-port

destination tunnel port

### has Int(Any) $.timeout

destination tunnel port

# METHOD

### method connect

```
method connect() returns SSH::LibSSH::Tunnel

```

Establish the connection, synchronously. Returns self.

# AUTHOR

Humberto Massa [humbertomassa@gmail.com](mailto:humbertomassa@gmail.com)

# COPYRIGHT AND LICENSE

Copyright © 2023 - 2024 Humberto Massa

This library is free software; you can redistribute it and/or modify it under either the Artistic License 2.0 or the LGPL v3.0, at your convenience.


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

# NAME

Net::SMTP - A pure Raku implementation of an SMTP client

# SYNOPSIS

```
use Net::SMTP;

# raw interface
my $client = Net::SMTP.new(:server("your.server.here"), :port(587), :debug, :raw);
$client.get-response; # 220 your.server.here ...
$client.ehlo; # 250-STARTTLS\r\n250 ...
$client.mail-from('from@your.server.here'); # 250 OK
$client.rcpt-to('to@your.server.here'); # 250 OK
$client.data; # 354 Enter message
$client.payload($email); # 250 OK
$client.quit; # 221 closing connection

#simple interface
my $client = Net::SMTP.new(:server("your.server.here"), :port(587), :debug);
$client.auth($username, $password);
$client.send($from, @to, $message);
$client.send($message); # find From/To/CC/(BCC)? lines
$client.quit;

```

# DESCRIPTION

The `Net::SMTP` distribution includes two different modes of operation for sending emails to an SMTP server: a raw mode (sending raw SMTP commands), and a simple mode (just send this email!).

# SIMPLE MODE METHODS

Note that all of these methods should return a true value on success or a Failure object if something goes wrong.

## new(:$server!, :$port = 25, :$hostname, :$debug, :$socket, :$ssl, :$starttls, :$plain)>

Creates a new SMTP client and opens the connection to the server. It takes the following named arguments:

### :server

Named argument `:$server` is required and defines which server to connect to. Note that this does **not** do a MX lookup - if you need to find the MX server, use [Net::DNS](https://raku.land/zef:rbt/Net::DNS) or similar.

### :port

Named argument `:$port` specifies the port number to connect to on the remote server. It defaults to 25.

### :hostname

Named argument `:$hostname` specifies the hostname given to the remote server in the initial HELO or EHLO message. It defaults to `$*KERNEL.hostname`.

### :debug

Named argument `:$debug` specifies whether debugging is to be enabled. When set to a true value, will print the SMTP traffic to stderr. Defaults to `False`.

### :socket

Named argument `:$socket` allows you to specify a class other than `IO::Socket::INET` to be used for network communication. If you pass a defined object, Net::SMTP will assume it is a ready-to-use socket.

### :ssl, :starttls, :plain

By default, this module will use STARTTLS if the server reveals that it is supported, otherwise it uses plain-text communication.

To override this, you can pass one of these named arguments:

* `:ssl` for an initial SSL connection
* `:starttls` to force STARTTLS usage
* `:plain` to disable transport encryption completely

## auth-methods

Returns a list of auth methods that are both supported by the server and by this module.

## auth-methods-raw

Returns a raw list of authentication methods supported by the server. Response is a space-seperated string.

## auth($username, $password, :@methods, :@disallow, :$force)

Authenticates with the SMTP server with the given `$username` and `$password`.

Currently supports CRAM-MD5, LOGIN, PLAIN.

You can set the `:@methods` named argument to explicitly declare which authentication methods you would like to try, in your order of preference. If not set, `:methods` will default to the result of `.auth-methods`.

You can set the `:@disallow` named argument to disable authentication methods from being attempted (to disable the insecure auth types, for example).

You can set the `:$force` named argument with a true value to mean that this module won't check the list of server supported authentication types - it will simply assume the server supports everything. This is possibly useful if you have an SMTP server that doesn't support EHLO, but still supports authentication.

## send($from, $to, $message, :$keep-going)

Sends an email $message (which can be a Str or something with a Str method) from $from; and to $to (which can be either a single address or a list of addresses). If $keep-going is set to a true value, will attempt to send the message even if sending to one of the recipients fails.

## send($message, :$keep-going)

Attempts to extract from and to information from the email headers (using [Email::Simplei](https://raku.land/zef:raku-community-modules/Email::Simple)), and then calls the above send method.

Note that if you pass a `Email::Simple` or `Email::MIME` object, this method will **not** create a new object, it will just use what was given.

## quit

Closes the connection to the server.

# RAW MODE METHODS

These methods allow access to low-level SMTP protocol interactions:

* get-response
* send($stuff)
* ehlo($hostname = $\*KERNEL.hostname)
* helo($hostname = $\*KERNEL.hostname)
* starttls
* switch-to-ssl
* auth-login($username, $password)
* auth-plain($username, $password)
* mail-from($address)
* rcpt-to($address)
* data
* payload($mail)
* rset
* quit

# AUTHOR

Andrew Egeler

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

# COPYRIGHT AND LICENSE

Copyright 2014 - 2021 Andrew Egeler

Copyright 2022, 2024 Raku Community

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


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

# NAME

Test::Coverage - Check test files for sufficient coverage

# SYNOPSIS

```
# in xt/coverage.rakutest
use Test::Coverage;

plan 2;

coverage-at-least 80;  # ok if at least 80% of lines is covered

uncovered-at-most 10;  # ok if at most 10 lines are not covered

```

# DESCRIPTION

The `Test::Coverage` distribution provides an easy way for Raku module developers to see whether the test-suite of their module covers as much as possible of the code of their module.

As such it exports subroutines to allow easy checking in a test script that lives in the "xt" directory, so that it will only be run by the author.

Note that as such, this does **not** add any dependencies to a module, **not** even for testing as "test-depends" as these tests should only be run by the author in normal circumstances.

By default, all of the test files in the "t" directory, and its subdirectories (extensions `.rakutest` and `.t`) will be run against all of the unique files provided by the `provides` section in the `META6.json` file.

For convenience, all of the features of the `Test` module are also exported by this module.

# SUBROUTINES

## coverage-at-least

```
coverage-at-least 80;  # ok if at least 80% of lines is covered

```

The `coverage-at-least` subroutine counts as a single test, and reports a passed test if the percentage of lines covered by the tests in the module reached the given amount (or more).

## uncovered-at-most

```
uncovered-at-most 10;  # ok if at most 10 lines are not covered

```

The `uncovered-at-most` subroutine counts as a single test, and reports a passed test if the number of lines **not** covered by the tests in the module is less then or equal to the number given.

## must-be-complete

```
# in xt/coverage.rakutest
use Test::Coverage;

must-be-complete;

```

The `must-be-complete` subroutine can be called as the **only** subroutine in a coverage test file. It sets the `plan` at `1`, counts as a single test, and passes the test if **all** the coverable lines have been covered. This is usually used for very small modules, and only as a insurance against accidental regressions.

If the test does **not** pass, then the `source-with-coverage` and `report` subroutines will be called to give the onlooker an idea of what is going wrong.

## default-coverage-setup

```
default-coverage-setup;

# run the actual tests and calculate coverage
run;

coverage-at-least 80;  # ok if at least 80% of lines is covered
uncovered-at-most 10;  # ok if at most 10 lines are not covered

```

The `default-coverage-setup` subroutine sets up the underlying [`Code::Coverage`](https://raku.land/zef:lizmat/Code::Coverage) object, sets the `$*CODE-COVERAGE` environment variable with it and returns that.

In most situations this is not needed, as any call to the `coverage-at-least` and `uncovered-at-most` subroutines will trigger the setup and running of the tests automatically.

## run

```
my $*CODE-COVERAGE := Code::Coverage.new(...);

run;

# check results

```

The `run` subroutine runs the tests and updates any information in the `Code::Coverage` object that should be available in the `$*CODE-COVERAGE` environment variable.

It is only needed if some non-standard setup is needed, or if you need to run the tests in a non-standard way:

```
default-coverage-setup;

run("foo");
run("bar");

# check results

```

## report

```
report                          # show report if test failed
  unless uncovered-at-most 10;  # ok if at most 10 lines are not covered

```

The `report` subroutine will print a report of the coverage tests if called in sink context. It is typically only called if a test fails.

If not in sink context, will return the string of the report:

```
mail report, :to<coverage@reports.org>;

```

## source-with-coverage

```
source-with-coverage;  # produce as sibling dir to script

source-with-coverage($dir);

```

The `source-with-coverage` subroutine will produce the annotated source of all targets in the given directory (as an `IO::Path`) with the `.rakucov` extension. If called without any argument, will assume a directory with the same name (but without extension) as the name of the script one directory up from where the test-file resides.

So e.g. a script in `xt/coverage.rakutest` in a `Foo::Bar` distribution would create a directory `xt/coverage/Foo` and write the annotated source in `xt/coverage/Foo/Bar.rakucov`.

Note: if you're making use of this feature, it's probably wise to add `*.rakucov` to the `.gitignore` file.

# SEE ALSO

The [`App:RaCoCo`](https://raku.land/zef:atroxaper/App::RaCoCo) distribution provides similar functionality, but is more app oriented rather than test file-based.

# AUTHOR

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

Source can be located at: <https://github.com/lizmat/Test-Coverage> . 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 2025 Elizabeth Mattijsen

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