## react.md
react

Combined from primary sources listed below.

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

See primary documentation
[in context](/language/concurrency#react)
for **react**.

The `react` keyword introduces a block of code containing one or more `whenever` keywords to watch asynchronous events. The main difference between a supply block and a react block is that the code in a react block runs where it appears in the code flow, whereas a supply block has to be tapped before it does anything.

Another difference is that a supply block can be used without the `whenever` keyword, but a react block requires at least one `whenever` to be of any real use.

```raku
react {
    whenever Supply.interval(2) -> $v {
        say $v;
        done() if $v == 4;
    }
}
```

Here the `whenever` keyword uses [`.act`](/type/Supply#method_act) to create a tap on the [`Supply`](/type/Supply) from the provided block. The `react` block is exited when `done()` is called in one of the taps. Using `last` to exit the block would produce an error indicating that it's not really a loop construct.

An `on-demand` [`Supply`](/type/Supply) can also be created from a list of values that will be emitted in turn, thus the first `on-demand` example could be written as:

```raku
react {
    whenever Supply.from-list(1..10) -> $v {
        say $v;
    }
}
```


## comp.md
role X::Comp

Common role for compile-time errors

```raku
role X::Comp is Exception { }
```

Common role for compile-time errors.

Note that since the backtrace of a compile time error generally shows routines from the compiler, not from user-space programs, the [`Backtrace`](/type/Backtrace) returned from the [backtrace](/routine/backtrace) method is not very informative. Instead the exception carries its own `filename`, `line` and `column` attributes and public accessors.

If an error occurs while creating an object (like a class or routine) at compile time, generally the exception associated with it does not hold a reference to the object (for example a class would not be fully composed, and thus not usable). In those cases the name of the would-be-created object is included in the error message instead.

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

## [method filename](#role_X::Comp "go to top of document")[§](#method_filename "direct link")

The filename in which the compilation error occurred

## [method line](#role_X::Comp "go to top of document")[§](#method_line "direct link")

The line number in which the compilation error occurred.

## [method column](#role_X::Comp "go to top of document")[§](#method_column "direct link")

The column number of location where the compilation error occurred. (Rakudo does not implement that yet).


## dist_github-shuppet-Command-Despatch.md
![logo](https://user-images.githubusercontent.com/12242877/92306033-2db85c80-ef84-11ea-9b76-dc375d5b5bd7.png)

Raku module for parsing generic commands and arguments from a hash table.


## dist_cpan-PATRICKZ-RPi-ButtonWatcher.md
# NAME

RPi::ButtonWatcher - A button push event supplier

# SYNOPSIS

```
use RPi::Wiring::Pi;
use RPi::ButtonWatcher;

die if wiringPiSetup() != 0;

# Takes WiringPi pin numbers.
my $watcher = RPi::ButtonWatcher.new(pins => ( 4, 5, 6 ), edge => BOTH, PUD => PULL_UP);
$watcher.getSupply.tap( -> %v {
    my $e = %v<edge> == Edge.RISING ?? 'up' !! 'down';
    say "Pin: %v<pin>, Edge: $e";
});

```

# DESCRIPTION

This library provides a supplier of GPIO pin state changes.

Read/write access to */sys/class/gpio/export* and */sys/class/gpio/gpioXX/* is required for this library to work. This usually means the user running the code has to be in the *gpio* group.

This module uses polling to detect state changes. A polling interval of 0.1 seconds is usually fast enough for normal button pushes.

The Sysfs interface is documented here: <https://www.kernel.org/doc/Documentation/gpio/sysfs.txt>

# METHODS

## new

Do initialize WiringPi before using this class using `wiringPiSetup`!

Takes the following parameters:

* pins

A list of WiringPi pin numbers to watch.

* edge

The edges to listen for.

```
* `Edge.RISING`

```

Triggered when a button is released.

```
* `Edge.FALLING`

```

Triggered when a button is pressed.

```
* `Edge.BOTH`

```

Triggered on both, button presses and releases.

* debounce

Time in seconds to sleep between polls. Faster means more responsive, but also more system resource eating. Defaults to 0.1 (100ms).

## getSupply

Returns a supply that can be tapped. The supply will emit hashes with two entries:

* pin

The WiringPi pin number that was triggered.

* edge

Either `Edge.RISING` or `Edge.FALLING`.


## attributecontainer.md
role Metamodel::AttributeContainer

Metaobject that can hold attributes

```raku
role Metamodel::AttributeContainer {}
```

*Warning*: this role is part of the Rakudo implementation, and is not a part of the language specification.

Classes, roles and grammars can have attributes. Storage and introspection of attributes is implemented by this role.

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

## [method add\_attribute](#role_Metamodel::AttributeContainer "go to top of document")[§](#method_add_attribute "direct link")

```raku
method add_attribute($obj, $attribute)
```

Adds an attribute. `$attribute` must be an object that supports the methods `name`, `type` and `package`, which are called without arguments. It can for example be of [type Attribute](/type/Attribute).

## [method attributes](#role_Metamodel::AttributeContainer "go to top of document")[§](#method_attributes "direct link")

```raku
method attributes($obj)
```

Returns a list of attributes. For most Raku types, these will be objects of [type Attribute](/type/Attribute).

## [method set\_rw](#role_Metamodel::AttributeContainer "go to top of document")[§](#method_set_rw "direct link")

```raku
method set_rw($obj)
```

Marks a type whose attributes default to having a write accessor. For example in

```raku
class Point is rw {
    has $.x;
    has $.y;
}
```

The `is rw` trait on the class calls the `set_rw` method on the metaclass, making all the attributes implicitly writable, so that you can write;

```raku
my $p = Point.new(x => 1, y => 2);
$p.x = 42;

```

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

```raku
method rw($obj)
```

Returns a true value if [method set\_rw](#method_set_rw) has been called on this object, that is, if new public attributes are writable by default.


## mixins.md
role Metamodel::Mixins

Metaobject for generating mixins

```raku
role Metamodel::Mixins {}
```

*Warning*: this role is part of the Rakudo implementation, and is not a part of the language specification.

Using the `does` and `but` infix operators, *mixins* of a base object and an arbitrary number of roles (or another object) can be created. These are objects whose types have properties of both operands' types. Respectively, these rebless the existing object to have the generated mixin type and clone said object with said mixin type:

```raku
class Billboard {
    has Str:D $.advertisement is required;

    method vandalism(::?CLASS:D: --> Str:D) { ... }

    multi method Str(::?CLASS:D: --> Str:D) { $!advertisement }

    role Vandalized[Str:D :$vandalism] {
        method vandalism(::?CLASS:D: --> Str:D) { $vandalism }

        multi method Str(::?CLASS:D: --> Str:D) { $vandalism }
    }
}

my Str:D $advertisement = Q:to/ADVERTISEMENT/.chomp;
Brilliant Solutions: sane and knowledgeable consultants.
We have been providing excellent services since 1972!
ADVERTISEMENT
my Str:D $vandalism = Q:to/VANDALISM/.chomp;
          S       s  s ne     k          l   o   l     .
We    e  ee            e  e  e    e    e      e     !
VANDALISM

my Billboard:D $billboard .= new: :$advertisement;
say $billboard eq $advertisement; # OUTPUT: «True␤»

my Billboard:D $draft = $billboard but Billboard::Vandalized[:$vandalism];
say $draft eq $vandalism; # OUTPUT: «True␤»

$billboard does Billboard::Vandalized[:$vandalism];
say $billboard eq $vandalism; # OUTPUT: «True␤»

```

Optionally, mixins may have a *mixin attribute*. This occurs when only one role having only one public attribute gets mixed into an object. If a mixin attribute exists on a resulting mixin's type, it can be initialized by `but` or `does` using its `value` named parameter. This makes it possible for mixins to not only have composable methods, but composable state as well. Using this feature, the example above can be rewritten so billboards can be vandalized more than once without needing to generate more mixins by making `Billboard::Vandalism`'s `$vandalism` named parameter a [rw](/type/Attribute#trait_is_rw) mixin attribute instead:

```raku
class Billboard {
    has Str:D $.advertisement is required;

    method vandalism(::?CLASS:D: --> Str:D) { ... }

    multi method Str(::?CLASS:D: --> Str:D) { $!advertisement }

    role Vandalized {
        has Str:D $.vandalism is required is rw;

        multi method Str(::?CLASS:D: --> Str:D) { $!vandalism }
    }
}

my Str:D $advertisement = Q:to/ADVERTISEMENT/.chomp;
Brilliant Solutions: sane and knowledgeable consultants.
We have been providing excellent services since 1972!
ADVERTISEMENT
my Str:D $vandalism = Q:to/VANDALISM/.chomp;
          S       s  s ne     k          l   o   l     .
We    e  ee            e  e  e    e    e      e     !
VANDALISM
my Str:D $false-alarm = Qs:to/FALSE-ALARM/.chomp;
$vandalism
⬆ This is just one of our namesakes we at Brilliant Solutions have been
helping people like you create since 1972!
FALSE-ALARM

my Billboard:D $billboard .= new: :$advertisement;
say $billboard eq $advertisement; # OUTPUT: «True␤»

$billboard does Billboard::Vandalized :value($vandalism);
say $billboard eq $vandalism; # OUTPUT: «True␤»

$billboard.vandalism = $false-alarm;
say $billboard eq $false-alarm; # OUTPUT: «True␤»

```

`Metamodel::Mixins` is the metarole that implements the behavior of said mixins. Formally, mixins are objects whose HOW inherits from a base composable metaobject and applies an arbitrary number of roles, resulting in an object whose HOW has a combination of their properties. In particular, the metamethods this metarole provides are used to implement the behavior of the `but` and `does` infix operators, but these also support introspection related to mixins. For example, the work done by `but` when invoked with an object and one role can be written explicitly using the `mixin` metamethod provided:

```raku
class Foo { }
role Bar { }

say Foo.new but Bar;     # OUTPUT: «Foo+{Bar}.new␤»
say Foo.new.^mixin(Bar); # OUTPUT: «Foo+{Bar}.new␤»

```

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

## [method set\_is\_mixin](#role_Metamodel::Mixins "go to top of document")[§](#method_set_is_mixin "direct link")

```raku
method set_is_mixin($obj)
```

Marks `$obj` as being a mixin.

## [method is\_mixin](#role_Metamodel::Mixins "go to top of document")[§](#method_is_mixin "direct link")

```raku
method is_mixin($obj)
```

Returns `1` If `$obj` has been marked as being a mixin with `set_is_mixin`, otherwise returns `0`.

## [method set\_mixin\_attribute](#role_Metamodel::Mixins "go to top of document")[§](#method_set_mixin_attribute "direct link")

```raku
method set_mixin_attribute($obj, $attr)
```

Sets the mixin attribute for `$obj` to `$attr` (which should be an [`Attribute`](/type/Attribute) instance).

## [method mixin\_attribute](#role_Metamodel::Mixins "go to top of document")[§](#method_mixin_attribute "direct link")

```raku
method mixin_attribute($obj)
```

Returns the mixin attribute for `$obj` set with `set_mixin_attribute`.

## [method setup\_mixin\_cache](#role_Metamodel::Mixins "go to top of document")[§](#method_setup_mixin_cache "direct link")

```raku
method setup_mixin_cache($obj)
```

Sets up caching of mixins for `$obj`. After this metamethod has been called, calls to `mixin` will not create a new type for mixins of `$obj` given the same list of roles more than once. This should be called at some point before composition.

## [method flush\_cache](#role_Metamodel::Mixins "go to top of document")[§](#method_flush_cache "direct link")

```raku
method flush_cache($obj)
```

No-op.

## [method generate\_mixin](#role_Metamodel::Mixins "go to top of document")[§](#method_generate_mixin "direct link")

```raku
method generate_mixin($obj, @roles)
```

Creates a new mixin metaobject that inherits from `$obj` and does each of the roles in `@roles`. This is then composed and has its mixin attribute set (if any exists) before getting returned.

While this generates a new mixin type, this doesn't actually mix it into `$obj`; if that is what you intend to do, use the [mixin](/routine/mixin) metamethod instead.

## [method mixin](#role_Metamodel::Mixins "go to top of document")[§](#method_mixin "direct link")

```raku
method mixin($obj, *@roles, :$needs-mixin-attribute)
```

Generates a new mixin type by calling `generate_mixin` with `$obj` and `@roles`. If `$obj` is composed, the mixin cache of `$obj` will be checked for any existing mixin for these beforehand. If `$obj` is an instance of a type, this will return `$obj` reblessed with the mixin generated, otherwise this will return the mixin itself.

If `$needs-mixin-attribute` is `True`, this will throw an exception if no mixin attribute exists on the mixin generated before returning.


## dist_zef-bduggan-WebService-Overpass.md
[![Actions Status](https://github.com/bduggan/raku-webservice-overpass/actions/workflows/linux.yml/badge.svg)](https://github.com/bduggan/raku-webservice-overpass/actions/workflows/linux.yml)
[![Actions Status](https://github.com/bduggan/raku-webservice-overpass/actions/workflows/macos.yml/badge.svg)](https://github.com/bduggan/raku-webservice-overpass/actions/workflows/macos.yml)

# NAME

WebService::Overpass - A simple interface to the Overpass API

# SYNOPSIS

Get a node from OpenStreetMap:

```
use WebService::Overpass 'op', '-debug';

say op.query: q:to/OQL/;
    [out:json];
    node(1);
    out;
  OQL

```

Output:

```
2024-11-28T08:38:08.234432-05:00 (1) debug: Running overpass query
2024-11-28T08:38:08.238386-05:00 (1) debug: > [out:json];
2024-11-28T08:38:08.238688-05:00 (1) debug: > node(1);
2024-11-28T08:38:08.239029-05:00 (1) debug: > out;

{
  "version": 0.6,
  "generator": "Overpass API 0.7.62.4 2390de5a",
  "elements": [
      {
        "type": "node",
        "id": 1,
        "lat": 42.7957187,
        "lon": 13.5690032,
        ...
      }
  ],
  ...
}

```

Get XML of nodes in a bounding box:

```
say op.query: q:to/OQL/;
  [bbox:-25.38653, 130.99883, -25.31478, 131.08938];
  node;
  out skel;
OQL

```

Output:

```
<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="Overpass API 0.7.62.4 2390de5a">
<note>The data included in this document is from www.openstreetmap.org. The data is made available under ODbL.</note>
<meta osm_base="2024-11-28T13:47:15Z"/>
...

  <bounds minlat="-25.3865300" minlon="130.9988300" maxlat="-25.3147800" maxlon="131.0893800"/>

  <node id="29342040" lat="-25.3572166" lon="131.0427522"/>
  <node id="29342041" lat="-25.3570627" lon="131.0413463"/>
...

```

Get a CSV with nodes tagged as cave entrance:

```
say op.query: q:to/OQL/;
   [out:csv(::id, ::lat, ::lon, name; true; ",")];
  (
    node(-25.38653, 130.99883, -25.31478, 131.08938)["natural"="cave_entrance"];
  );
  out body;
OQL

```

Output:

```
@id,@lat,@lon,name
2377985489,-25.3431812,131.0229585,Itjaritjatiku Yuu
2377985491,-25.3409557,131.0252996,Kulpi Minymaku
2377985515,-25.3427478,131.0246858,Kulpi Watiku
...

```

Construct queries with the `statements` attribute:

```
use WebService::Overpass;

op.statements = <node(1); out meta;>;

# same thing:
say op.execute(:xml).elements[2].attribs<lat lon>.map(+*).List.raku;
say op.execute(:json)<elements>[0]<lat lon>.raku;

```

See the [tutorial](https://osm-queries.ldodds.com/tutorial/index.html) for more examples.

# DESCRIPTION

This is a simple interface to the Overpass API. Overpass is an API for retrieving OpenStreetMap data. Queries use the Overpass Query Language (Overpass QL).

# EXPORTS

If an argument is given to the module, it is assumed to be a name and the module creates a new object of type `WebService::Overpass` and exports it. Also "-debug" will send debug output to stderr. So these are equivalent:

```
use WebService::Overpass 'op', '-debug';

```

and

```
use WebService::Overpass;
my \op = WebService::Overpass.new;
op.logger.send-to: $*ERR;

```

# METHODS

## query

```
method query($data, Bool :$json, Bool :$xml) returns Str

```

Send a complete query and return the result (as a string).

The `$data` parameter should be a complete overpass query. Overpass queries consist of "settings" followed by a semicolon, and then "statements". The settings are key-value pairs in square brackets.

The format of the response depends on the first line of the query (csv, json etc). If `:json` is True, the response is parsed as JSON. If `:xml` is True, the response is parsed as XML. Otherwise, it is returned as a string. For "smarter" behavior, use the `execute` method below.

## execute

```
method execute(:$xml, :$json, :$raw) returns Any

```

Send a query and return the result as a raku data structure.

The `statements` and `settings` attributes are used to construct the query. The `statements` attribute is an array of strings, each of which is a line in the query. The `settings` attribute is a hash of settings that are prepended to the query.

The `:xml` and `:json` parameters are optional and specify the output format. They also add an "out" setting to the query. Note that CSVs need to be done manually, because the fields are part of the settings. For instance

```
op.settings<out> = 'csv(::id, ::lat, ::lon, name; true; ",")';

```

The "true" indicates that a header row should be included. The comma is the separator.

The `:raw` parameter is optional and specifies that the raw response should be returned as a string. Sending `:json` and `:raw` for instance will set the format to json in the payload, but then return the raw unparsed JSON in the response.

# ATTRIBUTES

## url

```
has $.url = 'https://overpass-api.de/api/interpreter';

```

The URL of the Overpass API endpoint.

## settings

```
has %.settings is rw;

```

A hash of settings that are prepended to the query. The keys are the setting names and the values are the setting values.

## statements

```
has Str @.statements is rw;

```

An array of strings, each of which is a line in the query. Every statement should end with a semicolon.

# EXAMPLES

Run the same query in different formats:

```
use WebService::Overpass;

my \op = WebService::Overpass.new;

op.statements = <node(1); out meta;>;

say op.execute(:xml).elements[2].attribs<lat lon>;

say op.execute(:json)<elements>[0]<lat lon>;

op.settings<out> = 'csv(::id, ::lat, ::lon, name; true; ",")';
say op.execute;

```

# SEE ALSO

<https://wiki.openstreetmap.org/wiki/Overpass_API>

# AUTHOR

Brian Duggan


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

# NAME

Test::Declare - Declare common test scenarios as data.

## CAVEAT

The author is a novice at Raku. Please be nice if you've stumbled across this and have opinions to express. Furthermore I somehow failed to notice the pre-existence of a Perl `Test::Declare`, to which this code is **no relation**. Apologies for any confusion; I renamed late in the day, being fed up with the length of my first choice of `Test::Declarative`.

# SYNOPSIS

```
use Test::Declare;

use Module::Under::Test;

declare(
    ${
        name => 'multiply',
        call => {
            class => Module::Under::Test,
            construct => \(2),
            method => 'multiply',
        },
        args => \(multiplicand => 4),
        expected => {
            return-value => 8,
        },
    },
    ${
        name => 'multiply fails',
        call => {
            class => Module::Under::Test,
            construct => \(2),
            method => 'multiply',
        },
        args => \(multiplicand => 'four'),
        expected => {
            dies => True,
        },
    },
    ${
        name => 'multiply fails',
        call => {
            class => Module::Under::Test,
            construct => \(2),
            method => 'multiply',
        },
        args => \(multiplicand => 8),
        expected => {
            # requires Test::Declare::Comparisons
            return-value => roughly(&[>], 10),
        },
    },
);

```

# DESCRIPTION

Test::Declare is an opinionated framework for writing tests without writing (much) code. The author hates bugs and strongly believes in the value of tests. Since most tests are code, they themselves are susceptible to bugs; this module provides a way to express a wide variety of common testing scenarios purely in a declarative way.

# USAGE

Direct usage of this module is via the exported subroutine `declare`. The tests within the distribution in [t/](https://github.com/raku-community-modules/Test-Declare/tree/main/t) can also be considered to be a suite of examples which exercise all the options available.

## declare(${ … }, ${ … })

`declare` takes an array of hashes describing the test scenarios and expectations. Each hash should look like this:

* name

The name of the test, for developer understanding in the TAP output.

* call

A hash describing the code to be called.

```
* class

```

The actual concrete class - not a string representation, and not an instance either.

```
* method

```

String name of the method to call.

```
* construct

```

If required, a [Capture](https://docs.raku.org/type/Capture.html) of the arguments to the class's `new` method.

* args

If required, a [Capture](https://docs.raku.org/type/Capture.html) of the arguments to the instance's method.

* expected

A hash describing the expected behaviour when the method gets called.

```
* return-value

```

The return value of the method, which will be compared to the actual return value via `eqv`.

```
* lives / dies / throws

```

`lives` and `dies` are booleans, expressing simply whether the code should work or not. `throws` should be an Exception type.

```
* stdout / stderr

```

Strings against which the method's output/error streams are compared, using `eqv` (i.e. not a regex).

# SEE ALSO

Elsewhere in this distribution:

* `Test::Declare::Comparisons` - for fuzzy matching including some naive/rudimentary attempts at copying the [Test::Deep](https://metacpan.org/pod/Test::Deep) interface where Raku does not have it builtin.
* [Test::Declare::Suite](https://github.com/raku-community-modules/Test-Declare/tree/main/lib/Test/Declare/Suite.rakumod) - for a role which bundles tests together against a common class / method, to reduce repetition.

# AUTHOR

Darren Foreman

# COPYRIGHT AND LICENSE

Copyright 2018 Darren Foreman

Copyright 2024 Raku Community

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


## dist_zef-guifa-Polyglot-Regexen.md
# Polyglot::Regexen

A module to enable use of non-Raku flavors of regex directly in Raku code.

### Why?

Because copy and paste. Also, there are lots of little gotchas when going between different flavors. What counts for `\s`, `\d`, `.`, or even `$` can vary substantially or in quite subtle ways.
If you have a battle-tested regex, don't worry about rewriting it. Just use it as is!

The goal of this module is to provide a variety of ways for you to use your favor flavors in Raku scripts — even in grammars!
When using regexen from this module, you can be assured that capture ordering is preserved, the meaning of whitespace won't get changed, etc.

## Support

The support for different flavors is shown below in a table, followed by a discussion on any (hopefully temporary) deviations from the standard.
The meaning of the columns is the following:

* **In grammars**: these can be used inside of grammars. Just declare the regex with the psuedo-adverb. Since `}` will necessarily be the terminating character, you may need to escape it in some way.
* **Bare quoted**: just as you can use `rx/foo/` for regular regexes, these allow you to prefix with, e.g., `rx:ecma/foo/`
* **Lexical scope**: these are defined by `my`/`our` scoping, e.g. `my ecma-regex { … }`

| Flavor | In grammars | Bare quoted (substitution) | Lexical scoped | adverb |
| --- | --- | --- | --- | --- |
| ECMA-262 (Javascript) | ✓ | ✓ (𐄂) | ✓ | ecma |
| Python | 𐄂 | 𐄂 (𐄂) | 𐄂 | py |
| Ruby | 𐄂 | 𐄂 (𐄂) | 𐄂 | ruby |
| PHP | 𐄂 | 𐄂 (𐄂) | 𐄂 | php |

(At the moment, only Javascript is supported. The others are aspirational.)

### Support Caveats

* General

  * Non-slash delimiters are not currently planned
* ECMA-262 (Javascript)

  * Not all options are currently available (right now, just `s`, `m`, and `i`).
  * In block form (defined with `regex:ecma { … }`, leading and trailing white space is ignored).
  * To add options in block form, use a colon: `regex:ecma:i { … }`
  * Unicode option is effectively always on. More testing will be required to tease out if/when that makes a difference

# Version History

* **v0.0.1**
  * Fixed ECMA262 positional match counting
  * Added support for named back references in ECMA262
  * RakuAST-ified for *much* better maintenance
  * Reorganized tests and added many new and detailed tests
* **v0.0.1**
  \* Initial public release with most of ECMA262 (JavaScript) regex supported


## run.md
run

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Thread#method_run)
for **method run**.

```raku
method run(Thread:D:)
```

Runs the thread, and returns the invocant. It is an error to run a thread that has already been started.

# [In Independent routines](#___top "go to top of document")[§](#(Independent_routines)_sub_run "direct link")

See primary documentation
[in context](/type/independent-routines#sub_run)
for **sub run**.

```raku
sub run(
    *@args ($, *@),
    :$in = '-',
    :$out = '-',
    :$err = '-',
    Bool :$bin = False,
    Bool :$chomp = True,
    Bool :$merge = False,
    Str:D :$enc = 'UTF-8',
    Str:D :$nl = "\n",
    :$cwd = $*CWD,
    Hash() :$env = %*ENV,
    :$arg0,
    :$win-verbatim-args = False
--> Proc:D)

```

Runs an external command *without involving a shell* and returns a [`Proc`](/type/Proc) object. By default, the external command will print to standard output and error, and read from standard input.

```raku
run 'touch', '--', '*.txt'; # Create a file named “*.txt”

run <rm -- *.txt>; # Another way to use run, using word quoting for the
                   # arguments
```

If you want to pass some variables you can still use `< >`, but try to avoid using `« »` as it will do word splitting if you forget to quote variables:

```raku
my $file = ‘--my arbitrary filename’;
run ‘touch’, ‘--’, $file;  # RIGHT
run <touch -->, $file;     # RIGHT

run «touch -- "$file"»;    # RIGHT but WRONG if you forget quotes
run «touch -- $file»;      # WRONG; touches ‘--my’, ‘arbitrary’ and ‘filename’
run ‘touch’, $file;        # WRONG; error from `touch`
run «touch "$file"»;       # WRONG; error from `touch`

```

Note that `--` is required for many programs to disambiguate between command-line arguments and [filenames that begin with hyphens](https://mywiki.wooledge.org/BashPitfalls#Filenames_with_leading_dashes).

A sunk [`Proc`](/type/Proc) object for a process that [exited](/routine/exitcode) unsuccessfully will throw an [`Exception`](/type/Exception). If you wish to ignore the exceptions, and return a [`Proc`](/type/Proc) you can introspect, use [run](/routine/run) in non-sink context:

```raku
run 'false';     # SUNK! Will throw an Exception
run('false').so; # OK. Evaluates Proc in Bool context; no sinking. Ignore returned Proc
my $a = run('false'); # Can call methods on the Proc in $a.
```

If you want to capture standard output or error instead of having it printed directly you can use the `:out` or `:err` arguments, which will make them available using their respective methods: [`Proc.out`](/type/Proc) and [`Proc.err`](/type/Proc).

```raku
my $proc = run 'echo', 'Raku is Great!', :out, :err;
$proc.out.slurp(:close).say; # OUTPUT: «Raku is Great!␤»
$proc.err.slurp(:close).say; # OUTPUT: «␤»
```

You can use these arguments to redirect them to a filehandle, thus creating a kind of *pipe*:

```raku
my $ls-alt-handle = open :w, '/tmp/cur-dir-ls-alt.txt';
my $proc = run "ls", "-alt", :out($ls-alt-handle);
# (The file will contain the output of the ls -alt command)
```

These argument are quite flexible and admit, for instance, handles to redirect them. See [`Proc`](/type/Proc) and [`Proc::Async`](/type/Proc/Async) for more details.

See also [`new`](/type/Proc#routine_new) and [`spawn`](/type/Proc#method_spawn) for more examples and explanation of all arguments.


## dist_zef-tony-o-Operator-feq.md
#`feq` Operator

Provides `feq` operator for clean fuzzy string comparisons.

Includes a precanned wrapper for Text::Levenshtein::Damerau (the wrapper uses just the Levenshtein algorithm by default)

#Usage

##Out of the Box™

```
use Operator::feq;

if '1234567890' feq '1234567899' {
  'I\'m here!'.say;
}

if '12345' feq '123' {
  'I don\'t get here'.say;
}

#outputs:
#I'm here!

```

See the tests for an example of how to extend/create custom comparison routines.

#Configuration

##`$*FEQLIB`

Defaults: `Text::Levenshtein::Damerau`

Set this dynamic variable to control which library 'feq' uses

##`$*FEQTHRESHOLD`

Defaults: `0.10` # 10%

Set this dynamic variable to control the threshold for the matching. Setting this variable to 0 will always cause `feq` to return `False`. Conversely, a value of `1` will always return `True`.

#Credit Cards

[@tony-o](https://www.gittip.com/tony-o/)

Nick Logan <ugexe>


## dist_zef-knarkhov-Trove.md
# Trove test harness

## Concept

Yet another [test harness written in Raku](https://github.com/pheix/raku-trove) language and inspired by `bash` driven test tool built for [Pheix](https://gitlab.com/pheix/dcms-raku) content management system.

Generally `Trove` is based on idea to create the wrapper over the unit tests in `t` folder. But with out-of-the-box Gitlab or Github CI/CD integration, extended logging and test-dependable options.

`Trove` includes `trove-cli` script as a primary worker for batch testing. It iterates over pre-configured stages and runs specific unit test linked to the stage. `trove-cli` is console oriented — all output is printed to `STDOUT` and `STDERR` data streams. Input is taken from command line arguments.

## TL;DR

`Trove` Christmas recipes at Raku Advent 2022 blog: <https://raku-advent.blog/2022/12/14/day-14-trove-yet-another-tap-harness>

## Usage

1. Command line arguments
   * [Colors](#colors)
   * [Stages management](#stages-management)
   * [File processor configuration](#file-processor-configuration)
   * [Versions consistency](#versions-consistency)
   * [Target configuration file](#target-configuration-file)
   * [First stage logging policy](#first-stage-logging-policy)
   * [Origin repository](#origin-repository)
2. Test configuration files — JSON & YAML
   * Configuration file sections
     * [Explore](#explore)
     * [Stage and substage](#stage-and-substage)
     * [Mix it up!](#mix-it-up)
   * [Trivial test configuration example](#trivial-test-configuration-example)
   * [Pheix test suite configuration files](#pheix-test-suite-configuration-files)
3. Test coverage management
   * [Gitlab](#gitlab)
   * [Coveralls](#coveralls)
     * [Setup automatic coverage upload](#setup-automatic-coverage-upload)
4. [Log test session](#log-test-session)
5. Integration with CI/CD environments
   * [github.com](#githubcom)
   * [gitlab.com](#gitlabcom)

### Command line arguments

#### Colors

To bring colors to the output `-c` option is used:

```
trove-cli -c --f=`pwd`/run-tests.conf.yml --p=yq

```

#### Stages management

To exclude specific stages from test `-s` option is used:

```
trove-cli -c --s=1,2,4,9,10,11,12,13,14,25,26 --f=`pwd`/run-tests.conf.yml --p=yq

```

### File processor configuration

`trove-cli` takes test scenario from configuration file. Default format is JSON, but you can use YAML on demand, for now `JSON::Fast` and `YAMLish` processing modules (processors) are integrated. To switch between the processors the next command line options should be used:

* `--p=jq` or do not use `--p` (default behavior) — [JSON](https://github.com/timo/json_fast) processor;
* `--p=yq` — [YAML](https://github.com/Leont/yamlish) processor.

### Versions consistency

To verify the version [consistency](https://gitlab.com/pheix-research/talks/-/tree/main/pre-RC2#version-control-consistency-in-git-commit-message-and-pheixmodelversion) on commit, the next command line options should be used:

* `--g` — path to git repo with version at latest commit in format `%0d.%0d.%0d`;
* `--v` — current version to commit (in format `%0d.%0d.%0d` as well).

```
trove-cli -c --g=~/git/raku-foo-bar --v=1.0.0

```

### Target configuration file

By default the next configuration targets are used:

* JSON — `./x/trove-configs/test.conf.json`;
* YAML — `./x/trove-configs/test.conf.yaml`.

These paths are used to test `Trove` itself with:

```
cd ~/git/raku-trove && bin/trove-cli -c && bin/trove-cli -c --p=yq

```

To use another configuration file you have to specify it via `--f` option:

```
trove-cli --f=/tmp/custom.jq.conf

```

### First stage logging policy

`trove-cli` is obviously used to test Pheix. First Pheix testing stage checks `www/user.rakumod` script with:

```
    raku $WWW/user.raku --mode=test # WWW == './www'

```

This command prints nothing to standard output and eventually nothing is needed to be saved to log file. By default first stage output is ignored. But if you use Pheix Tests tool to test some other module or application, i might be handy to force save first stage output. This is done by `-l` command line argument:

```
trove-cli --f=/tmp/custom.jq.conf -l

```

In case the stage with blank output is not skipped it's taken into coverage scope but marked as `WARN` in `trove-cli` output:

```
01. Testing ./www/user.raku                                [ WARN ]
02. Testing ./t/cgi/cgi_post_test.sh                       [ 6% covered ]
...

```

### Origin repository

By default origin repository is set up to `git@github.com:pheix/raku-trove.git` and you can change it to any value you prefer by `-o` argument:

```
trove-cli --f=/tmp/custom.jq.conf --o=git@gitlab.com:pheix/net-ethereum-perl6.git

```

## Test configuration files — JSON & YAML

### Configuration file sections

* `target` — description of test target;
* `explore` — explore file system and build test plan with stages automatically;
* `stages` — list of the test stages.

#### Explore

`explore` section is used to build test plan with test stages automatically. Consider a Perl module with some tests within `./t` folder — two options for you: add every unit test as stage manually or just configure some universal stage setup under the `explore` section.

```
target: Trivial one-liner test
explore:
  base: ./t
  pattern: (<[0..9]>+)\.t
  interpreter: perl
  recursive: 1

```

* `base` — relative or absolute base path where `Trove` will find unit test;
* `pattern` — Raku regular expression that will be used for matching;
* `interpreter` — default interpreter to run the unit tests;
* `recursive` — try to traverse sub folders recursively.

By default `interpreter` is `raku`, and `recursive` is disabled.

#### Stage and substage

* `test` — test command to execute;
* `args` — if command uses environment variables, they should be in `test` command line (`%SOMEVAR%` for `jq` and `$SOMEVAR` for `yq`) and in `args` list as `SOMEVAR` (no `$` or `%` chars);
* `environment` — command to set up environmental variables for the stage, e.g. `export HTTP_REFERER=//foo.bar` or whatever else, please keep in mind — `environment` is defines as list, but actually only first element of this list is used, so no matter how many command you set up there, only the first one will be used;
* `cleanup` — command to clean up environmental variables for the stage, the same restrictions are actual here;
* `substages` — list of the test substages;

#### Mix it up!

You can mix `explore` and `stages` sections to flexibly cover some edge test cases like:

```
target: Trivial one-liner test
explore:
  base: ./t
  pattern: (0 <[0..9]> ** 1..1)\.t
stages:
  - test: 'raku ./t/11.t $INPUT'
    args:
      - INPUT

```

In this sample `Trove` will automatically add stages for `./t/00.t` ... `./t/09.t` unit tests and will run one manually added stage with additional input argument from environmental variable for `./t/11.t` unit test.

### Trivial test configuration example

Trivial multi-interpreter one-liner test [configuration file](https://github.com/pheix/raku-trove/blob/main/x/trove-configs/test.conf.yaml.explorer) is included to `Trove`:

```
target: Trivial one-liner test
stages:
  - test: raku  -eok(1); -MTest
  - test: perl6 -eis($CONSTANT,2); -MTest
    args:
      - CONSTANT
  - test: perl  -eok(3);done_testing; -MTest::More

```

Test command to be executed:

```
CONSTANT=2 && trove-cli --f=/home/pheix/git/raku-trove/x/trove-configs/test.conf.yaml.explorer --p=yq -c

```

### Pheix test suite configuration files

Pheix test suite configuration files have a full set of features we talked above: `explore`, `stages`, `subtages`, environmental variables export, setup and clean up. These files could be used as basic examples to create test configuration for yet another module or application, no matter — Raku, Perl or something else.

Sample [snippet](https://gitlab.com/pheix/dcms-raku/-/blob/develop/run-tests.conf.yml) from `run-tests.conf.yml`:

```
target: Pheix test suite
explore:
  base: ./t
  pattern: (<[23]> ** 1..1 <[0..9]> ** 1..1)|(<[01]> ** 1..1 <[234569]> ** 1..1)|('07'|'08'|'10')<[a..z-]>+\.t
  interpreter: raku
stages:
  - test: 'raku $WWW/user.raku --mode=test'
    args:
      - WWW
  - test: ./t/cgi/cgi_post_test.sh
    substages:
      - test: raku ./t/00-november.t
  ...
  - test: 'raku ./t/11-version.t $GITVER $CURRVER'
    args:
      - GITVER
      - CURRVER
  ...
  - test: raku ./t/17-headers-proto-sn.t
    environment:
      - 'export SERVER_NAME=https://foo.bar'
    cleanup:
      - unset SERVER_NAME
    substages:
      - test: raku ./t/17-headers-proto-sn.t
        environment:
          - export SERVER_NAME=//foo.bar/
        cleanup:
          - unset SERVER_NAME
  - test: raku ./t/18-headers-proto.t
    substages:
      - test: raku ./t/18-headers-proto.t
        environment:
          - 'export HTTP_REFERER=https://foo.bar'
        cleanup:
          - unset HTTP_REFERER
  ...

```

## Test coverage management

### Gitlab

Coverage percentage in Gitlab is retrieved from job's standard output: while your tests are running, you have to print actual test progress in percents to console (`STDOUT`). Output log is parsed by runner on job finish, the matching patterns [should be set up](https://docs.gitlab.com/ee/ci/pipelines/settings.html#add-test-coverage-results-using-project-settings-removed) in `.gitlab-ci.yml` — CI/CD configuration file.

Consider trivial test configuration example from the [section above](#trivial-test-configuration-example), the standard output is:

```
01. Running -eok(1,'true');                              [ 33% covered ]
02. Running -eis(2,2,'2=2');                             [ 66% covered ]
03. Running -eok(3,'perl5');done_testing;                [ 100% covered ]

```

Matching pattern in `.gitlab-ci.yml` is set up:

```
...
trivial-test:
  stage: trivial-test-stable
  coverage: '/(\d+)% covered/'
  ...

```

### Coveralls

#### Basics

[Coveralls](https://coveralls.io/) is a web service that allows users to track the code coverage of their application over time in order to optimize the effectiveness of their unit tests. `Trove` test tool includes Coveralls integration via [API](https://docs.coveralls.io/api-reference).

API reference is quite clear — the generic objects are `job` and `source_file`. Array of source files should be included to the job:

```
{
  "service_job_id": "1234567890",
  "service_name": "Trove::Coveralls",
  "source_files": [
    {
      "name": "foo.raku",
      "source_digest": "3d2252fe32ac75568ea9fcc5b982f4a574d1ceee75f7ac0dfc3435afb3cfdd14",
      "coverage": [null, 1, null]
    },
    {
      "name": "bar.raku",
      "source_digest": "b2a00a5bf5afba881bf98cc992065e70810fb7856ee19f0cfb4109ae7b109f3f",
      "coverage": [null, 1, 4, null]
    }
  ]
}

```

In example above we covered `foo.raku` and `bar.raku` by our tests. File `foo.raku` has 3 lines of source code and only line no.2 is covered. File `bar.raku` has 4 lines of source code, lines no.2 and no.3 are covered, 2nd just once, 3rd — four times.

#### Test suite integration

We assume full coverage for some software part if its unit test is passed. Obviously this part is presented by its unit tests and `source_files` section in Coveralls request looks like:

```
...
"source_files": [
    {
      "name": "./t/01.t",
      "source_digest": "be4b2d7decf802cbd3c1bd399c03982dcca074104197426c34181266fde7d942",
      "coverage": [ 1 ]
    },
    {
      "name": "./t/02.t",
      "source_digest": "2d8cecc2fc198220e985eed304962961b28a1ac2b83640e09c280eaac801b4cd",
      "coverage": [ 1 ]
    }
  ]
...

```

We consider no lines to be covered, so it's enough to set `[ 1 ]` to `coverage` member.

Besides `source_files` member we have to set up a `git` [member](https://docs.coveralls.io/api-reference#arguments) as well. It's pointed as optional, but your build reports on Coveralls side will look anonymous without git details (commit, branch, message and others).

#### Setup automatic coverage upload

You have to set up your test environment to send coverage to Coveralls service automatically. Initially `Trove` was a simple bash script targeted to GitLab and relied on the next environmental variables:

* `CI_JOB_ID` - [predefined](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) GitLab CI job identifier, actually `CI_JOB_ID` can be any integer value you prefer — just `date +%s` or something dummy like `0`;
* `COVERALLSTOKEN` - Coveralls secret [repository token](https://docs.coveralls.io/api-introduction).

Sample `Trove` run with the subsequent test coverage upload to Coveralls:

```
CI_JOB_ID=`date +%s` COVERALLSTOKEN=<coveralls-secret-repo-token> RAKULIB=./lib trove-cli -c --f=`pwd`/x/trove-configs/test.conf.yaml.explore --p=yq

```

If you are familiar with GitLab, you can check [Pheix pipelines](https://gitlab.com/pheix/dcms-raku/-/pipelines). `Trove` is used there as a primary test tool since the late November 2022. GitLab sets up `CI_JOB_ID` automatically and `COVERALLSTOKEN` is configured manually with CI/CD [protected variables](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project). So, usage with GitLab is quite transparent/friendly:

![Gitlab CI/CD protected variables Pheix setup](https://user-images.githubusercontent.com/6272762/210155017-1914d50d-f46b-49ac-8334-f8e749c23faa.png)

## Log test session

While testing `trove-cli` does not output any TAP messages to standard output. Consider trivial multi-interpreter one-liner test again:

```
01. Running -eok(1,'true');                              [ 33% covered ]
02. Running -eis(2,2,'2=2');                             [ 66% covered ]
03. Running -eok(3,'perl5');done_testing;                [ 100% covered ]

```

On the background `trove-cli` saves the full log with extended test details. Log file is save to current (work) directory and has the next file name format: `testreport.*.log`, where `*` is test run date, for example: `testreport.2022-10-18_23-21-12.log`.

Test command to be executed:

```
cd ~/git/raku-trove && CONSTANT=2 bin/trove-cli --f=`pwd`/x/trove-configs/tests.conf.yml.oneliner --p=yq -c -l

```

Log file `testreport.*.log` content is:

```
----------- STAGE no.1 -----------
ok 1 - true

----------- STAGE no.2 -----------
ok 1 - 2=2

----------- STAGE no.3 -----------
ok 1 - perl5
1..1

```

## Integration with CI/CD environments

### github.com

Consider module `Acme::Insult::Lala`, to integrate `Trove` to [Github actions](https://github.com/features/actions) CI/CD environment we have to create `.github/workflows/pheix-test-suite.yml` with the next instructions:

```
name: CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    container:
      image: rakudo-star:latest

    steps:
      - uses: actions/checkout@v2
      - name: Perform test with Pheix test suite
        run: |
          zef install Trove
          ln -s `pwd` /tmp/Acme-Insult-Lala
          cd /tmp/Acme-Insult-Lala && RAKULIB=lib trove-cli --f=/tmp/Acme-Insult-Lala/.run-tests.conf.yml --p=yq -l -c
          cat `ls | grep "testreport"`

```

CI/CD magic happens at `run` instruction, let's explain it line by line:

1. `zef install Trove` — install `Trove` test tool;
2. `ln -s ...` — creating the module path consistent with `.run-tests.conf.yml`;
3. `cd /tmp/Acme-Insult-Lala && ...` — run the tests;
4. `cat ...` — print test log.

Check the job: <https://github.com/pheix/Acme-Insult-Lala/actions/runs/3621090976/jobs/6104091041>

![](https://gitlab.com/pheix-research/talks/-/raw/main/advent/assets/2022/ci-cd/github.png)

### gitlab.com

Let's integrate module perl5 module `Acme` with `Trove` to [Gitlab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) environment — we have to create `.gitlab-ci.yml` with the next instructions:

```
image: rakudo-star:latest

before_script:
  - apt update && apt -y install libspiffy-perl
  - zef install Trove
  - ln -s `pwd` /tmp/Acme-perl5
test:
  script:
    - cd /tmp/Acme-perl5 && PERL5LIB=lib trove-cli --f=/tmp/Acme-perl5/.run-tests.conf.yml --p=yq -l -c
    - cat `ls | grep "testreport"`
  only:
    - main

```

On Gitlab CI/CD magic happens in `before_script` and `test/script` instructions. Behavior is exactly the same as it was in `run` instruction for Github action.

Check the job: <https://gitlab.com/pheix-research/perl-acme/-/jobs/3424335705>

![](https://gitlab.com/pheix-research/talks/-/raw/main/advent/assets/2022/ci-cd/gitlab.png)

## License

This is free and opensource software, so you can redistribute it and/or modify it under the terms of the [The Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).

## Author

Please contact me via [LinkedIn](https://www.linkedin.com/in/knarkhov/) or [Twitter](https://twitter.com/CondemnedCell). Your feedback is welcome at [narkhov.pro](https://narkhov.pro/contact-information.html).


## dist_cpan-TYIL-Grammar-TodoTxt.md
# NAME

Grammar::TodoTxt

# AUTHOR

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

# VERSION

0.1.0

# Description

A grammar to parse todo.txt

# Installation

Install this module through [zef](https://github.com/ugexe/zef):

```
zef install Grammar::TodoTxt

```

# License

This module is distributed under the terms of the AGPL-3.0.


## dist_zef-uniejo-Cooklang.md
# NAME

Cooklang - `Raku` `Cooklang` parser

# SYNOPSIS

```
    use Cooklang;
    ...
    my $source = "some Cooklang text";
    my $recipe = Cooklang.new( recipe => $source );
    ...
    my $file = 'recipe.cook';
    my $recipe = Cooklang.new( recipe_file => $file );
    ...
    my @files = 'recipe1.cook', 'recipe2.cook';
    my $recipe = Cooklang.new( recipe_file => @files );
    # Currently does a simple join of all files, before parsing.
    ...
    my $metadata    = $recipe.metadata;
    my $ingredients = $recipe.ingredients;
    my $steps       = $recipe.steps;
    my $comments    = $recipe.comments;
    my $data        = $recipe.data;
    my $ast_tree    = $recipe.match;

```

# VERSION

```
version 1.1.0

```

# AVAILABILITY

Cooklang is implemented in `Raku` using grammer and grammar action to parse and build AST tree.

# DESCRIPTION

For the `Cooklang` syntax, see [Cooklang](https://cooklang.org/).

# DOCUMENTATION

Cooklang documentation is available as `POD6`. You can run `raku --doc` from a shell to read the documentation:

```
    % raku --doc lib/Cooklang.rakumod
    % raku --doc=Markdown lib/Cooklang.rakumod     # zef install Pod::To::Markdown
    % raku --doc=HTML lib/Cooklang.rakumod         # zef install Pod::To::HTML

```

# INSTALLATION

Installing Cooklang is straightforward.

## Installation with zef from CPAN6

If you have zef, you only need one line:

```
    % zef install Cooklang

```

## Installation with zef from git repository

```
    % zef install https://github.com/uniejo/cooklang-raku.git

```

# COMMUNITY

* [Code repository Wiki and Issue Tracker](https://github.com/uniejo/cooklang-raku)
* [Cooklang on modules.raku.org](https://modules.raku.org/dist/Cooklang:zef:zef:uniejo)

# AUTHOR

Erik Johansen - [uniejo@users.noreply.github.com](mailto:uniejo@users.noreply.github.com)

# COPYRIGHT

Erik Johansen 2023

# LICENSE

This software is licensed under the same terms as Perl itself.


## dist_cpan-FRITH-Math-Libgsl-LinearAlgebra.md
## Chunk 1 of 3
[![Actions Status](https://github.com/frithnanth/raku-Math-Libgsl-LinearAlgebra/workflows/test/badge.svg)](https://github.com/frithnanth/raku-Math-Libgsl-LinearAlgebra/actions) [![Build Status](https://travis-ci.org/frithnanth/raku-Math-Libgsl-LinearAlgebra.svg?branch=master)](https://travis-ci.org/frithnanth/raku-Math-Libgsl-LinearAlgebra)

# NAME

Math::Libgsl::LinearAlgebra - An interface to libgsl, the Gnu Scientific Library - Linear Algebra.

# SYNOPSIS

```
use Math::Libgsl::LinearAlgebra;

```

# DESCRIPTION

Math::Libgsl::LinearAlgebra is an interface to the linear 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 provides functions for Num and Complex data types.

## Num

### LU-decomp(Math::Libgsl::Matrix $A where \*.matrix.size1 == $A.matrix.size2 --> List)

This function factorizes the matrix A into the LU decomposition PA = LU. The factorization is done in place, so on output the diagonal and upper triangular (or trapezoidal) part of the input matrix A contain the matrix U. The lower triangular (or trapezoidal) part of the input matrix (excluding the diagonal) contains L. The diagonal elements of L are unity, and are not stored. The return value is a List: the sign of the permutation and a permutation object, which encodes the permutation matrix P. In case of error a failure object is returned.

### LU-solve(Math::Libgsl::Matrix $LU where \*.matrix.size1 == $LU.matrix.size2, Math::Libgsl::Permutation $p where \*.size == $LU.matrix.size1, Math::Libgsl::Vector $b where \*.vector.size == $LU.matrix.size1 --> Math::Libgsl::Vector)

This function solves the square system Ax = b using the LU decomposition of A into (LU, p) given by the output of LU-decomp. In case of error a failure object is returned.

### LU-svx(Math::Libgsl::Matrix $LU where \*.matrix.size1 == $LU.matrix.size2, Math::Libgsl::Permutation $p where \*.size == $LU.matrix.size1, Math::Libgsl::Vector $x where \*.size == $LU.matrix.size1 --> Int)

This function solves the square system Ax = b in-place using the precomputed LU decomposition of A into (LU, p). On input $x should contain the right-hand side b, which is replaced by the solution on output. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### LU-refine(Math::Libgsl::Matrix $A where \*.matrix.size1 == $A.matrix.size2, Math::Libgsl::Matrix $LU where { $LU.matrix.size1 == $LU.matrix.size2 && $A.matrix.size1 == $LU.matrix.size2 }, Math::Libgsl::Permutation $p where \*.size == $LU.matrix.size1, Math::Libgsl::Vector $b where \*.vector.size == $LU.matrix.size1, Math::Libgsl::Vector $x where \*.vector.size == $LU.matrix.size1 --> Int)

This function applies an iterative improvement to x, the solution of Ax = b, from the precomputed LU decomposition of A into (LU, p). This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### LU-invert(Math::Libgsl::Matrix $LU, Math::Libgsl::Permutation $p where \*.size == $LU.matrix.size1 --> Math::Libgsl::Matrix)

This function computes the inverse of a matrix A from its LU decomposition (LU, p), returning the matrix inverse. In case of error a failure object is returned.

### LU-det(Math::Libgsl::Matrix $LU, Int $signum where \* ~~ -1|1 --> Num)

This function computes the determinant of a matrix A from its LU decomposition, $LU, and the sign of the permutation, $signum. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### LU-lndet(Math::Libgsl::Matrix $LU --> Num)

This function computes the determinant the logarithm of the absolute value of the determinant of a matrix A, ln |det(A)|, from its LU decomposition, $LU. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### LU-sgndet(Math::Libgsl::Matrix $LU, Int $signum where \* ~~ -1|1 --> Int)

This function computes the sign or phase factor of the determinant of a matrix A, det(A)/|det(A)| from its LU decomposition, $LU. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QR-decomp(Math::Libgsl::Matrix $A --> Math::Libgsl::Vector)

This function factorizes the M-by-N matrix $A into the QR decomposition A = QR. On output the diagonal and upper triangular part of the input matrix contain the matrix R. The returned vector and the columns of the lower triangular part of the matrix A contain the Householder coefficients and Householder vectors which encode the orthogonal matrix Q. In case of error a failure object is returned.

### QR-solve(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == $QR.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $QR.matrix.size1 --> Math::Libgsl::Vector)

This function solves the square system Ax = b using the QR decomposition of A held in ($QR, $tau) which must have been computed previously with QR-decomp(). In case of error a failure object is returned.

### QR-svx(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == $QR.matrix.size2, Math::Libgsl::Vector $x where \*.vector.size == $QR.matrix.size1 --> Int)

This function solves the square system Ax = b in-place using the QR decomposition of A held in ($QR, $tau) which must have been computed previously by QR-decomp(). On input $x should contain the right-hand side b, which is replaced by the solution on output. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QR-lssolve(Math::Libgsl::Matrix $QR where \*.matrix.size1 ≥ $QR.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == $QR.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $QR.matrix.size1 --> List)

This function finds the least squares solution to the overdetermined system Ax = b where the matrix A has more rows than columns. The least squares solution minimizes the Euclidean norm of the residual, ||Ax − b||. The routine requires as input the QR decomposition of A into ($QR, $tau) given by QR-decomp(). The function returns a List of two Math::Libgsl::Vector objects: the solution x and the residual. In case of error a failure object is returned.

### QR-QTvec(Math::Libgsl::Matrix $QR, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2), Math::Libgsl::Vector $v where \*.vector.size == $QR.matrix.size1 --> Int)

These function applies the matrix T(Q) encoded in the decomposition (QR, tau) to the vector $v, storing the result T(Q) v in $v. The matrix multiplication is carried out directly using the encoding of the Householder vectors without needing to form the full matrix T(Q). This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QR-Qvec(Math::Libgsl::Matrix $QR, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2), Math::Libgsl::Vector $v where \*.vector.size == $QR.matrix.size1 --> Int)

This function applies the matrix Q encoded in the decomposition ($QR, $tau) to the vector $v, storing the result Qv in $v. The matrix multiplication is carried out directly using the encoding of the Householder vectors without needing to form the full matrix Q. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QR-QTmat(Math::Libgsl::Matrix $QR, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2), Math::Libgsl::Matrix $B where \*.matrix.size1 == $QR.matrix.size1 --> Int)

This function applies the matrix T(Q) encoded in the decomposition ($QR, $tau) to the M-by-K matrix $B, storing the result T(Q) B in $B. The matrix multiplication is carried out directly using the encoding of the Householder vectors without needing to form the full matrix T(Q). This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QR-Rsolve(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $QR.matrix.size1 --> Math::Libgsl::Vector)

This function solves the triangular system Rx = b and returns the Math::Libgsl::Vector object $x. In case of error a failure object is returned.

### QR-Rsvx(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Vector $x where \*.vector.size == $QR.matrix.size2 --> Int)

This function solves the triangular system Rx = b for x in-place. On input $x should contain the right-hand side b and is replaced by the solution on output. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QR-unpack(Math::Libgsl::Matrix $QR, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2) --> List)

This function unpacks the encoded QR decomposition ($QR, $tau) into the matrices Q and R. The function returns a List of two Math::Libgsl::Matrix objects: $Q which is M-by-M and $R which is M-by-N. In case of error a failure object is returned.

### QR-QRsolve(Math::Libgsl::Matrix $Q, Math::Libgsl::Matrix $R where { $R.matrix.size1 == $R.matrix.size2 && $Q.matrix.size1 == $R.matrix.size1 }, Math::Libgsl::Vector $b where \*.vector.size == $R.matrix.size1 --> Math::Libgsl::Vector)

This function solves the system Rx = T(Q) b for x. It can be used when the QR decomposition of a matrix is available in unpacked form as ($Q, $R). The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### QR-update(Math::Libgsl::Matrix $Q, Math::Libgsl::Matrix $R where { $Q.matrix.size1 == $R.matrix.size1 && $Q.matrix.size2 == $R.matrix.size1 }, Math::Libgsl::Vector $w where \*.vector.size == $R.matrix.size1, Math::Libgsl::Vector $v where \*.vector.size == $R.matrix.size2 --> Int)

This function performs a rank-1 update wT(v) of the QR decomposition ($Q, $R). The update is given by Q'R' = Q(R+wT(v)) where the output matrices $Q and $R are also orthogonal and right triangular. Note that $w is destroyed by the update. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### R-solve(Math::Libgsl::Matrix $R where \*.matrix.size1 == $R.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $R.matrix.size1 --> Math::Libgsl::Vector)

This function solves the triangular system Rx = b for the N-by-N matrix $R. The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### R-svx(Math::Libgsl::Matrix $R where \*.matrix.size1 == $R.matrix.size2, Math::Libgsl::Vector $x where \*.vector.size == $R.matrix.size2 --> Int)

This function solves the triangular system Rx = b in-place. On input $x should contain the right-hand side b, which is replaced by the solution on output. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QRPT-decomp(Math::Libgsl::Matrix $A --> List)

This function factorizes the M-by-N matrix $A into the QRT(P) decomposition A = QRT(P). On output the diagonal and upper triangular part of the input matrix contain the matrix R. The function's output is a List of three objects: the Math::Libgsl::Vector $tau, the Math::Libgsl::Permutation $p and the sign of the permutation Int $signum. In case of error a failure object is returned.

### QRPT-decomp2(Math::Libgsl::Matrix $A --> List)

This function factorizes the matrix $A into the decomposition A = QRT(P) without modifying $A itself. The function returns a List: the Math::Libgsl::Matrix $Q, the Math::Libgsl::Matrix $R, the Math::Libgsl::Permutation $p, and the sign of the permutation Int $signum. In case of error a failure object is returned.

### QRPT-solve(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2), Math::Libgsl::Permutation $p where \*.p.size == $QR.matrix.size1, Math::Libgsl::Vector $b where \*.vector.size == $QR.matrix.size1 --> Math::Libgsl::Vector)

This function solves the square system Ax = b using the QRT(P) decomposition of A held in ($QR, $tau, $p) which must have been computed previously by QRPT-decomp. The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### QRPT-svx(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2), Math::Libgsl::Permutation $p where \*.p.size == $QR.matrix.size1, Math::Libgsl::Vector $x where \*.vector.size == $QR.matrix.size2 --> Int)

This function solves the square system Ax = b in-place using the QRT(P) decomposition of A held in ($QR, $tau, $p). On input $x should contain the right-hand side b, which is replaced by the solution on output. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QRPT-lssolve(Math::Libgsl::Matrix $QR where \*.matrix.size1 ≥ $QR.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2), Math::Libgsl::Permutation $p where \*.p.size == $QR.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $QR.matrix.size1 --> List)

This function finds the least squares solution to the overdetermined system Ax = b where the matrix A has more rows than columns and is assumed to have full rank. The least squares solution minimizes the Euclidean norm of the residual, ||b − Ax||. The routine requires as input the QR decomposition of A into ($QR, $tau, $p) given by QRPT-decomp. The function returns a List of two Math::Libgsl::Vector objects: the solution x and the residual. In case of error a failure object is returned.

### QRPT-lssolve2(Math::Libgsl::Matrix $QR where \*.matrix.size1 ≥ $QR.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == min($QR.matrix.size1, $QR.matrix.size2), Math::Libgsl::Permutation $p where \*.p.size == $QR.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $QR.matrix.size1, Int $rank where 0 < \* ≤ $QR.matrix.size2 --> List)

This function finds the least squares solution to the overdetermined system Ax = b where the matrix A has more rows than columns and has rank given by the input rank. If the user does not know the rank of A, it may be estimated by calling QRPT-rank. The routine requires as input the QR decomposition of A into ($QR, $tau, $p) given by QRPT-decomp. The function returns a List of two Math::Libgsl::Vector objects: the solution x and the residual. In case of error a failure object is returned.

### QRPT-QRsolve(Math::Libgsl::Matrix $Q where \*.matrix.size1 == $Q.matrix.size2, Math::Libgsl::Matrix $R where {$R.matrix.size1 == $R.matrix.size2 && $R.matrix.size1 == $Q.matrix.size1}, Math::Libgsl::Permutation $p where \*.p.size == $Q.matrix.size1, Math::Libgsl::Vector $b where \*.vector.size == $Q.matrix.size1 --> Math::Libgsl::Vector)

This function solves the square system RT(P) x = T(Q) b for x. It can be used when the QR decomposition of a matrix is available in unpacked form as ($Q, $R). The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### QRPT-update(Math::Libgsl::Matrix $Q, Math::Libgsl::Matrix $R where { $Q.matrix.size1 == $R.matrix.size1 && $Q.matrix.size2 == $R.matrix.size1 }, Math::Libgsl::Permutation $p where \*.p.size == $R.matrix.size1, Math::Libgsl::Vector $w where \*.vector.size == $R.matrix.size1, Math::Libgsl::Vector $v where \*.vector.size == $R.matrix.size2 --> Int)

This function performs a rank-1 update wT(v) of the QRT(P) decomposition ($Q, $R, $p). The update is given by Q' R' = Q(R + wT(v) P) where the output matrices Q' and R' are also orthogonal and right triangular. Note that $w is destroyed by the update. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QRPT-Rsolve(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Permutation $p where \*.p.size == $QR.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $QR.matrix.size1 --> Math::Libgsl::Vector)

This function solves the triangular system RT(P) x = b for the N-by-N matrix R contained in $QR. The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### QRPT-Rsvx(Math::Libgsl::Matrix $QR where \*.matrix.size1 == $QR.matrix.size2, Math::Libgsl::Permutation $p where \*.p.size == $QR.matrix.size2, Math::Libgsl::Vector $x where \*.vector.size == $QR.matrix.size2 --> Int)

This function solves the triangular system RT(P) x = b in-place for the N-by-N matrix R contained in $QR. On input $x should contain the right-hand side b, which is replaced by the solution on output. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### QRPT-rank(Math::Libgsl::Matrix $QR, Num() $tolerance --> Int)

This function returns the rank of the triangular matrix R contained in $QR.

### QRPT-rcond(Math::Libgsl::Matrix $QR where \*.matrix.size1 ≥ $QR.matrix.size2 --> Num)

This function returns the reciprocal condition number (using the 1-norm) of the R factor, stored in the upper triangle of $QR. In case of error a failure object is returned.

### LQ-decomp(Math::Libgsl::Matrix $A --> Math::Libgsl::Vector)

This function factorizes the M-by-N matrix $A into the LQ decomposition A = LQ. On output the diagonal and lower trapezoidal part of the input matrix contain the matrix L. This function returns the Math::Libgsl::Vector $tau. The vector $tau and the elements above the diagonal of the matrix $A contain the Householder coefficients and Householder vectors which encode the orthogonal matrix Q. In case of error a failure object is returned.

### LQ-solve-T(Math::Libgsl::Matrix $LQ where \*.matrix.size1 == $LQ.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == min($LQ.matrix.size1, $LQ.matrix.size2), Math::Libgsl::Vector $b where \*.vector.size == $LQ.matrix.size2 --> Math::Libgsl::Vector)

This function finds the solution to the system Ax = b. The routine requires as input the LQ decomposition of A into ($LQ, $tau) given by LQ-decomp. The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### LQ-svx-T(Math::Libgsl::Matrix $LQ where \*.matrix.size1 == $LQ.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == min($LQ.matrix.size1, $LQ.matrix.size2), --> Math::Libgsl::Vector)

This function finds the solution to the system Ax = b. The routine requires as input the LQ decomposition of A into ($LQ, $tau) given by LQ-decomp. On input $x should contain the right-hand side b, which is replaced by the solution on output. In case of error a failure object is returned.

### LQ-lssolve-T(Math::Libgsl::Matrix $LQ where \*.matrix.size1 ≥ $LQ.matrix.size2, Math::Libgsl::Vector $tau where \*.vector.size == min($LQ.matrix.size1, $LQ.matrix.size2), Math::Libgsl::Vector $b where \*.vector.size == $LQ.matrix.size1 --> List)

This function finds the minimum norm least squares solution to the underdetermined system Ax = b, where the M-by-N matrix A has M ≤ N. The routine requires as input the LQ decomposition of A into ($LQ, $tau) given by LQ-decomp. The function returns a List of two Math::Libgsl::Vector objects: the solution x and the residual. In case of error a failure object is returned.

### LQ-Lsolve-T(Math::Libgsl::Matrix $LQ where \*.matrix.size1 == $LQ.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $LQ.matrix.size1 --> Math::Libgsl::Vector)

The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### LQ-Lsvx-T(Math::Libgsl::Matrix $LQ where \*.matrix.size1 == $LQ.matrix.size2 --> Math::Libgsl::Vector)

On input $x should contain the right-hand side b, which is replaced by the solution on output. In case of error a failure object is returned.

### L-solve-T(Math::Libgsl::Matrix $L where \*.matrix.size1 == $L.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $L.matrix.size2 --> Math::Libgsl::Vector)

The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### LQ-vecQ(Math::Libgsl::Matrix $LQ, Math::Libgsl::Vector $tau where \*.vector.size == min($LQ.matrix.size1, $LQ.matrix.size2), Math::Libgsl::Vector $v where \*.vector.size == $LQ.matrix.size1 --> Int)

This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### LQ-vecQT(Math::Libgsl::Matrix $LQ, Math::Libgsl::Vector $tau where \*.vector.size == min($LQ.matrix.size1, $LQ.matrix.size2), Math::Libgsl::Vector $v where \*.vector.size == $LQ.matrix.size1 --> Int)

This function applies T(Q) to the vector v, storing the result T(Q) v in $v on output. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### LQ-unpack(Math::Libgsl::Matrix $LQ, Math::Libgsl::Vector $tau where \*.vector.size == min($LQ.matrix.size1, $LQ.matrix.size2) --> List)

This function unpacks the encoded LQ decomposition ($LQ, $tau). The function outputs a List: the Math::Libgsl::Matrix $Q and the Math::Libgsl::Matrix $L. In case of error a failure object is returned.

### LQ-update(Math::Libgsl::Matrix $Q, Math::Libgsl::Matrix $L where { $L.matrix.size2 == $Q.matrix.size1 && $L.matrix.size2 == $Q.matrix.size2 }, Math::Libgsl::Vector $v where \*.vector.size == $L.matrix.size1, Math::Libgsl::Vector $w where \*.vector.size == $L.matrix.size2 --> Int)

This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### LQ-LQsolve(Math::Libgsl::Matrix $Q, Math::Libgsl::Matrix $L where { $L.matrix.size1 == $L.matrix.size2 && $Q.matrix.size1 == $L.matrix.size2 }, Math::Libgsl::Vector $b where \*.vector.size == $L.matrix.size2 --> Math::Libgsl::Vector)

In case of error a failure object is returned.

### COD-decomp(Math::Libgsl::Matrix $A --> List)

### COD-decomp-e(Math::Libgsl::Matrix $A, Num() $tolerance --> List)

These functions factor the M-by-N matrix $A into the decomposition A = QRZT(P). On output the matrix R₁₁ is stored in the upper rank-by-rank block of $A. The matrices Q and Z are encoded in packed storage in $A on output. This function outputs a List: two Math::Libgsl::Vector objects which contain the Householder scalars corresponding to the matrices Q and Z respectively, a Math::Libgsl::Permutation object which contain the permutation matrix P, and the rank of $A. In case of error a failure object is returned.

### COD-lssolve(Math::Libgsl::Matrix $QRZT where \*.matrix.size1 ≥ $QRZT.matrix.size2, Math::Libgsl::Vector $tau-Q where \*.vector.size == min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Vector $tau-Z where \*.vector.size == min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Permutation $p where \*.p.size == $QRZT.matrix.size2, Int $rank where \* ≤ min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Vector $b where \*.vector.size == $QRZT.matrix.size1 --> List)

This function finds the unique minimum norm least squares solution to the overdetermined system Ax = b where the matrix $A has more rows than columns. The least squares solution minimizes the Euclidean norm of the residual, ||b − Ax|| as well as the norm of the solution ||x||. The routine requires as input the QRZT decomposition of $A into ($QRZT, $tau\_Q, $tau\_Z, $p, $rank) given by COD-decomp. The function outputs a List: a Math::Libgsl::Vector object which is the solution x, and a Math::Libgsl::Vector object which stores the residual b − Ax. In case of error a failure object is returned.

### COD-lssolve2(Math::Libgsl::Matrix $QRZT where \*.matrix.size1 ≥ $QRZT.matrix.size2, Math::Libgsl::Vector $tau-Q where \*.vector.size == min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Vector $tau-Z where \*.vector.size == min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Permutation $p where \*.p.size == $QRZT.matrix.size2, Int $rank where \* ≤ min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Vector $b where \*.vector.size == $QRZT.matrix.size1, Num() $lambda --> List)

This function finds the solution to the regularized least squares problem in Tikhonov standard form, minₓ||b − Ax||² + λ²||x||². The routine requires as input the QRZT decomposition of A into ($QRZT, $tau\_Q, $tau\_Z, $p, $rank) given by COD-decomp. The parameter λ is supplied in $lambda. The function outputs a List: a Math::Libgsl::Vector object which is the solution x, and a Math::Libgsl::Vector object which stores the residual b − Ax. In case of error a failure object is returned.

### COD-unpack(Math::Libgsl::Matrix $QRZT, Math::Libgsl::Vector $tau-Q where \*.vector.size == min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Vector $tau-Z where \*.vector.size == min($QRZT.matrix.size1, $QRZT.matrix.size2), Int $rank where \* ≤ min($QRZT.matrix.size1, $QRZT.matrix.size2) --> List)

This function unpacks the encoded QRZT decomposition ($QRZT, $tau\_Q, $tau\_Z, $rank). The function returns a List of three Math::Libgsl::Matrix objects: $Q, $R, $Z. In case of error a failure object is returned.

### COD-matZ(Math::Libgsl::Matrix $QRZT, Math::Libgsl::Vector $tau-Z where \*.vector.size == min($QRZT.matrix.size1, $QRZT.matrix.size2), Math::Libgsl::Matrix $A where \*.matrix.size2 == $QRZT.matrix.size2, Int $rank --> Int)

This function multiplies the input matrix $A on the right by Z, A’ = AZ using the encoded QRZT decomposition ($QRZT, $tau\_Z, $rank). This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::gsl-error.

### SV-decomp(Math::Libgsl::Matrix $A where \*.matrix.size1 ≥ $A.matrix.size2 --> List)

This function factorizes the M-by-N matrix $A into the singular value decomposition A = UST(V) for M ≥ N. On output the matrix $A is replaced by U. The function returns a List: a Math::Libgsl::Matrix object which contains the elements of V in untransposed form, and a Math::Libgsl::Vector object which contains the diagonal elements of the singular value matrix S. The singular values are non-negative and form a non-increasing sequence from S₁ to Sₙ. In case of error a failure object is returned.

### SV-decomp-mod(Math::Libgsl::Matrix $A where \*.matrix.size1 ≥ $A.matrix.size2 --> List)

This function computes the SVD using the modified Golub-Reinsch algorithm, which is faster for M ≫ N. The function returns a List: a Math::Libgsl::Matrix object which contains the elements of V in untransposed form, and a Math::Libgsl::Vector object which contains the diagonal elements of the singular value matrix S. The singular values are non-negative and form a non-increasing sequence from S₁ to Sₙ. In case of error a failure object is returned.

### SV-decomp-jacobi(Math::Libgsl::Matrix $A where \*.matrix.size1 ≥ $A.matrix.size2 --> List)

This function computes the SVD of the M-by-N matrix A using one-sided Jacobi orthogonalization for M ≥ N. The function returns a List: a Math::Libgsl::Matrix object which contains the elements of V in untransposed form, and a Math::Libgsl::Vector object which contains the diagonal elements of the singular value matrix S. The singular values are non-negative and form a non-increasing sequence from S₁ to Sₙ. In case of error a failure object is returned.

### SV-solve(Math::Libgsl::Matrix $A where \*.matrix.size1 ≥ $A.matrix.size2, Math::Libgsl::Matrix $V where { $V.matrix.size1 == $V.matrix.size2 && $V.matrix.size1 == $A.matrix.size2 }, Math::Libgsl::Vector $S where \*.vector.size == $A.matrix.size2, Math::Libgsl::Vector $b where \*.vector.size == $A.matrix.size1 --> Math::Libgsl::Vector)

This function solves the system Ax = b using the singular value decomposition (U, S, V) of A which must have been computed previously with COD-decomp. Only non-zero singular values are used in computing the solution. The parts of the solution corresponding to singular values of zero are ignored. Other singular values can be edited out by setting them to zero before calling this function. The function returns the Math::Libgsl::Vector $x. In case of error a failure object is returned.

### SV-leverage(Math::Libgsl::Matrix $A --> Math::Libgsl::Vector)

This function computes the statistical leverage values hᵢ of a matrix A using its singular value decomposition (U, S, V) previously computed with COD-decomp. The function returns a Math::Libgsl::Vector object which stores the diagonal values of the matrix A(T(A)A)⁻¹T(A) and depend only on the matrix U which is the input to this function. In case of error a failure object is returned.

### cholesky-decomp1(Math::Libgsl::Matrix $A where \*.matrix.size1 == $A.matrix.size2 --> Int)

This function factorizes the symmetric, positive-definite square matrix $A into the Cholesky decomposition A = LT(L). On input, the values from the diagonal and lower-triangular part of the matrix $A are used (the upper triangular part is ignored). On output the diagonal and lower triangular part of the input matrix $A contain the matrix L, while the upper triangular part contains the original matrix. If the matrix is not positive-definite then the decomposition will fail, returning the error code GSL\_EDOM. This function returns GSL\_SUCCESS if successful, or one of the error codes listed in Math::Libgsl::Constants::