## subscripts.md
## Chunk 2 of 2
 = Jan => 1, Feb => 2, Mar => 3;
say %month<Feb>:k;          # OUTPUT: «Feb␤»
say %month<Jan Foo Mar>:k;  # OUTPUT: «(Jan Mar)␤»
```

If you *don't* want to skip nonexistent elements, use the negated form:

```raku
say %month<Jan Foo Mar>:!k;  # OUTPUT: «(Jan Foo Mar)␤»

```

See also the [keys](/routine/keys) routine.

## [`:v`](#Subscripts "go to top of document")[§](#:v "direct link")

Return the bare value of the element (rather than potentially returning a mutable value container), and silently skip nonexistent elements:

```raku
my @tens = 0, 10, 20, 30;
say @tens[1]:v;        # OUTPUT: «10␤»
say @tens[0, 4, 2]:v;  # OUTPUT: «(0, 20)␤»
@tens[3] = 31;         # OK
@tens[3]:v = 31;       # ERROR, Cannot modify an immutable Int (31)

my %month = Jan => 1, Feb => 2, Mar => 3;
say %month<Feb>:v;          # OUTPUT: «2␤»
say %month<Jan Foo Mar>:v;  # OUTPUT: «(1 3)␤»

```

If you *don't* want to skip nonexistent elements, use the negated form:

```raku
say %month<Jan Foo Mar>:!v;  # OUTPUT: «(1 (Any) 3)␤»

```

See also the [values](/routine/values) routine.

# [Custom types](#Subscripts "go to top of document")[§](#Custom_types "direct link")

The subscripting interfaces described on this page are not meant to be exclusive to Raku's built-in collection types - you can (and should) reuse them for any custom type that wants to provide access to data by index or key.

You don't have to manually overload the [`postcircumfix [ ]`](/language/operators#postcircumfix_[_]) and [`postcircumfix { }`](/language/operators#postcircumfix_{_}) operators and re-implement all their magic, to achieve that - instead, you can rely on the fact that their standard implementation dispatches to a well-defined set of low-level methods behind the scenes. For example:

| when you write: | this gets called behind the scenes: |
| --- | --- |
| %foo<aa> | %foo.AT-KEY("aa") |
| %foo<aa>:delete | %foo.DELETE-KEY("aa") |
| @foo[3, 4, 5] | @foo.AT-POS(3), @foo.AT-POS(4), @foo.AT-POS(5) |
| @foo[\*-1] | @foo.AT-POS(@foo.elems - 1) |

So in order to make subscripting work, you only have to implement or delegate those low-level methods ([detailed below](#Methods_to_implement_for_positional_subscripting)) for your custom type.

If you do, you should also let your type compose the [`Positional`](/type/Positional) or [`Associative`](/type/Associative) role, respectively. This doesn't add any functionality per se, but announces (and may be used to check) that the type implements the corresponding subscripting interface.

## [Custom type example](#Subscripts "go to top of document")[§](#Custom_type_example "direct link")

Imagine a `HTTP::Header` type which, despite being a custom class with special behavior, can be indexed like a hash:

```raku
my $request = HTTP::Request.new(GET => "raku.org");
say $request.header.^name;  # OUTPUT: «HTTP::Header␤»

$request.header<Accept> = "text/plain";
$request.header{'Accept-' X~ <Charset Encoding Language>} = <utf-8 gzip en>;
$request.header.push('Accept-Language' => "fr");  # like .push on a Hash

say $request.header<Accept-Language>.raku;  # OUTPUT: «["en", "fr"]␤»

my $rawheader = $request.header.Str;  # stringify according to HTTP spec

```

A simple way to implement this class would be to give it an attribute of type [`Hash`](/type/Hash), and delegate all subscripting and iterating related functionality to that attribute (using a custom type constraint to make sure users don't insert anything invalid into it):

```raku
class HTTP::Header does Associative {
    subset StrOrArrayOfStr where Str | ( Array & {.all ~~ Str} );

    has %!fields of StrOrArrayOfStr
                 handles <AT-KEY EXISTS-KEY DELETE-KEY push
                          iterator list kv keys values>;

    method Str { #`[not shown, for brevity] }
}

```

However, HTTP header field names are supposed to be case-insensitive (and preferred in camel-case). We can accommodate this by taking the `*-KEY` and `push` methods out of the `handles` list, and implementing them separately like this:

```raku
method AT-KEY     ($key) is rw { %!fields{normalize-key $key}        }
method EXISTS-KEY ($key)       { %!fields{normalize-key $key}:exists }
method DELETE-KEY ($key)       { %!fields{normalize-key $key}:delete }
method push(*@_) { #`[not shown, for brevity] }

sub normalize-key ($key) { $key.subst(/\w+/, *.tc, :g) }

```

Note that subscripting `%!fields` returns an appropriate rw container, which our `AT-KEY` can simply pass on.

However, we may prefer to be less strict about user input and instead take care of sanitizing the field values ourselves. In that case, we can remove the `StrOrArrayOfStr` type constraint on `%!fields`, and replace our `AT-KEY` implementation with one that returns a custom [`Proxy`](/type/Proxy) container which takes care of sanitizing values on assignment:

```raku
multi method AT-KEY (::?CLASS:D: $key) is rw {
    my $element := %!fields{normalize-key $key};

    Proxy.new(
        FETCH => method () { $element },

        STORE => method ($value) {
            $element = do given $value».split(/',' \s+/).flat {
                when 1  { .[0] }    # a single value is stored as a string
                default { .Array }  # multiple values are stored as an array
            }
        }
    );
}

```

Note that declaring the method as `multi` and restricting it to `:D` (defined invocants) makes sure that the undefined case is passed through to the default implementation provided by [`Any`](/type/Any) (which is involved in auto-vivification).

## [Methods to implement for positional subscripting](#Subscripts "go to top of document")[§](#Methods_to_implement_for_positional_subscripting "direct link")

In order to make index-based subscripting via [`postcircumfix [ ]`](/language/operators#postcircumfix_[_]) work for your custom type, you should implement at least `elems`, `AT-POS` and `EXISTS-POS` - and optionally others as detailed below.

### [method elems](#Subscripts "go to top of document")[§](#method_elems "direct link")

```raku
multi method elems(::?CLASS:D:)
```

Expected to return a number indicating how many subscriptable elements there are in the object. May be called by users directly, and is also called by [`postcircumfix [ ]`](/language/operators#postcircumfix_[_]) when indexing elements from the end, as in `@foo[*-1]`.

If not implemented, your type will inherit the default implementation from [`Any`](/type/Any) that always returns `1` for defined invocants - which is most likely not what you want. So if the number of elements cannot be known for your positional type, add an implementation that [fail](/routine/fail)s or [die](/routine/die)s, to avoid silently doing the wrong thing.

### [method AT-POS](#Subscripts "go to top of document")[§](#method_AT-POS "direct link")

```raku
multi method AT-POS (::?CLASS:D: $index)
```

Expected to return the element at position `$index`. This is what [`postcircumfix [ ]`](/language/operators#postcircumfix_[_]) normally calls.

If you want an element to be mutable (like they are for the built-in [`Array`](/type/Array) type), you'll have to make sure to return it in the form of an item container that evaluates to the element's value when read, and updates it when assigned to. Remember to use `return-rw` or the `is rw` routine trait to make that work; see the [example](/language/subscripts#Custom_type_example).

### [method EXISTS-POS](#Subscripts "go to top of document")[§](#method_EXISTS-POS "direct link")

```raku
multi method EXISTS-POS (::?CLASS:D: $index)
```

Expected to return a Bool indicating whether or not there is an element at position `$index`. This is what [`postcircumfix [ ]`](/language/operators#postcircumfix_[_]) calls when invoked like `@foo[42]:exists`.

What "existence" of an element means, is up to your type.

If you don't implement this, your type will inherit the default implementation from [`Any`](/type/Any), which returns True for 0 and False for any other index - which is probably not what you want. So if checking for element existence cannot be done for your type, add an implementation that [fail](/routine/fail)s or [die](/routine/die)s, to avoid silently doing the wrong thing.

### [method DELETE-POS](#Subscripts "go to top of document")[§](#method_DELETE-POS "direct link")

```raku
multi method DELETE-POS (::?CLASS:D: $index)
```

Expected to delete the element at position `$index`, and return the value it had. This is what [`postcircumfix [ ]`](/language/operators#postcircumfix_[_]) calls when invoked like `@foo[42]:delete`.

What "deleting" an element means, is up to your type.

Implementing this method is optional; if you don't, users trying to delete elements from an object of this type will get an appropriate error message.

### [method ASSIGN-POS](#Subscripts "go to top of document")[§](#method_ASSIGN-POS "direct link")

```raku
multi method ASSIGN-POS (::?CLASS:D: $index, $new)
```

Expected to set the element at position `$index` to the value `$new`. Implementing this is entirely optional; if you don't, `self.AT-POS($index) = $new` is used instead, and if you do, you should make sure it has the same effect.

This is meant as an opt-in performance optimization, so that simple assignments like `@numbers[5] = "five"` can operate without having to call `AT-POS` (which would have to create and return a potentially expensive container object).

Note that implementing `ASSIGN-POS` does *not* relieve you from making `AT-POS` a `rw` method though, because less trivial assignments/modifications such as `@numbers[5]++` will still use `AT-POS`.

### [method BIND-POS](#Subscripts "go to top of document")[§](#method_BIND-POS "direct link")

```raku
multi method BIND-POS (::?CLASS:D: $index, \new)
```

Expected to bind the value or container `new` to the slot at position `$index`, replacing any container that would be naturally found there. This is what is called when you write:

```raku
my $x = 10;
@numbers[5] := $x;

```

The generic [`Array`](/type/Array) class supports this in order to allow building complex linked data structures, but for more domain-specific types it may not make sense, so don't feel compelled to implement it. If you don't, users will get an appropriate error message when they try to bind to a positional slot of an object of this type.

### [method STORE](#Subscripts "go to top of document")[§](#method_STORE "direct link")

```raku
method STORE (::?CLASS:D: \values, :$INITIALIZE)
```

This method should only be supplied if you want to support this syntax:

```raku
my @a is Foo = 1,2,3;

```

Which is used for binding your implementation of the [`Positional`](/type/Positional) role.

`STORE` should accept the values to (re-)initialize the object with. The optional named parameter will contain a `True` value when the method is called on the object for the first time. It should return the invocant.

```raku
role Logger { method log( Str $msg) {…}}

class ConsoLogger does Logger { method log ( Str $msg ) { "❢ $msg".say }}

class DNA {
    has $.chain;
    has Logger $!logger;

    submethod BUILD( :$chain, :$logger = ConsoLogger.new() ) {}

    method STORE (Str $chain where {
            /^^ <[ACGT]>+ $$ / and
            .chars %% 3
        },
        :$INITIALIZE --> DNA) {

        if ($INITIALIZE) {
            $!logger = ConsoLogger.new();
            $!logger.log( "Initialized" );
        }

        $!chain  := $chain;
        $!logger.log("Change value to $chain" );
        self
    }

    method Str(::?CLASS:D:) { return $!chain.comb.rotor(3).map( *.join("")).join("|") }
};

my @string is DNA = 'GAATCC';    # OUTPUT: «❢ Initialized␤❢ Change value to GAATCC␤»
say ~@string;                    # OUTPUT: «GAA|TCC␤»
@string = 'ACGTCG';              # OUTPUT: «❢ Change value to ACGTCG␤»
say  ~@string;                   # OUTPUT: «ACG|TCG␤»

```

This code takes into account the value of `$INITIALIZE`, which is set to `True` only if we are assigning a value to a variable declared using the `is` syntax for the first time; for instance, as in this case, we might need to initialize any injected dependency. The `STORE` method should set the `self` variable and return it in all cases, including when the variable has already been initialized; however, only in the first case we need to initialize the logger we are using in this example.

The presence of the `INITIALIZE` flag can be also used to create immutable data structures:

```raku
class A {
    has @.foo handles <Str gist raku>;
    multi method STORE(*@!foo, :$INITIALIZE!) { }
    multi method STORE(|) { die "Immutable" }
}

my @a is A = 1,2,3,4;
say @a;        # OUTPUT: «[1,2,3,4]␤»
@a = 4,5,6,7;  # dies: Immutable

```

## [Methods to implement for associative subscripting](#Subscripts "go to top of document")[§](#Methods_to_implement_for_associative_subscripting "direct link")

In order to make key-based subscripting via [`postcircumfix { }`](/language/operators#postcircumfix_{_}) work for your custom type, you should implement at least `AT-KEY` and `EXISTS-KEY` - and optionally others as detailed below.

### [method AT-KEY](#Subscripts "go to top of document")[§](#method_AT-KEY "direct link")

```raku
multi method AT-KEY (::?CLASS:D: $key)
```

Expected to return the element associated with `$key`. This is what [`postcircumfix { }`](/language/operators#postcircumfix_{_}) normally calls.

If you want an element to be mutable (like they are for the built-in [`Hash`](/type/Hash) type), you'll have to make sure to return it in the form of an item container that evaluates to the element's value when read, and updates it when assigned to. Remember to use `return-rw` or the `is rw` routine trait to make that work; see the [example](/language/subscripts#Custom_type_example).

On the other hand if you want your collection to be read-only, feel free to return non-container values directly.

### [method EXISTS-KEY](#Subscripts "go to top of document")[§](#method_EXISTS-KEY "direct link")

```raku
multi method EXISTS-KEY (::?CLASS:D: $key)
```

Expected to return a Bool indicating whether or not there is an element associated with `$key`. This is what [`postcircumfix { }`](/language/operators#postcircumfix_{_}) calls when invoked like `%foo<aa>:exists`.

What "existence" of an element means, is up to your type.

If you don't implement this, your type will inherit the default implementation from [`Any`](/type/Any), which always returns False - which is probably not what you want. So if checking for element existence cannot be done for your type, add an implementation that [fail](/routine/fail)s or [die](/routine/die)s, to avoid silently doing the wrong thing.

### [method DELETE-KEY](#Subscripts "go to top of document")[§](#method_DELETE-KEY "direct link")

```raku
multi method DELETE-KEY (::?CLASS:D: $key)
```

Expected to delete the element associated with `$key`, and return the value it had. This is what [`postcircumfix { }`](/language/operators#postcircumfix_{_}) calls when invoked like `%foo<aa>:delete`.

What "deleting" an element means, is up to your type - though it should usually cause `EXISTS-KEY` to become `False` for that key.

Implementing this method is optional; if you don't, users trying to delete elements from an object of this type will get an appropriate error message.

### [method ASSIGN-KEY](#Subscripts "go to top of document")[§](#method_ASSIGN-KEY "direct link")

```raku
multi method ASSIGN-KEY (::?CLASS:D: $key, $new)
```

Expected to set the element associated with `$key` to the value `$new`. Implementing this is entirely optional; if you don't, `self.AT-KEY($key) = $new` is used instead, and if you do, you should make sure it has the same effect.

This is meant as an opt-in performance optimization, so that simple assignments `%age<Claire> = 29` can operate without having to call `AT-KEY` (which would have to create and return a potentially expensive container object).

Note that implementing `ASSIGN-KEY` does *not* relieve you from making `AT-KEY` a `rw` method though, because less trivial assignments/modifications such as `%age<Claire>++` will still use `AT-KEY`.

### [method BIND-KEY](#Subscripts "go to top of document")[§](#method_BIND-KEY "direct link")

```raku
multi method BIND-KEY (::?CLASS:D: $key, \new)
```

Expected to bind the value or container `new` to the slot associated with `$key`, replacing any container that would be naturally found there. This is what is called when you write:

```raku
my $x = 10;
%age<Claire> := $x;

```

The generic [`Hash`](/type/Hash) class supports this in order to allow building complex linked data structures, but for more domain-specific types it may not make sense, so don't feel compelled to implement it. If you don't, users will get an appropriate error message when they try to bind to an associative slot of an object of this type.

### [method STORE](#Subscripts "go to top of document")[§](#method_STORE_0 "direct link")

```raku
method STORE (::?CLASS:D: \values, :$INITIALIZE)
```

This method should only be supplied if you want to support the:

```raku
my %h is Foo = a => 42, b => 666;

```

syntax for binding your implementation of the [`Associative`](/type/Associative) role.

Should accept the values to (re-)initialize the object with, which either could consist of [`Pair`](/type/Pair)s, or separate key/value pairs. The optional named parameter will contain a `True` value when the method is called on the object for the first time. Should return the invocant.


## dist_cpan-ROAM-Getopt-Std.md
# NAME

Getopt::Std - Process single-character options with option clustering

# SYNOPSIS

```
    use Getopt::Std;

    # Classical usage, slightly extended:
    # - for options that take an argument, return only the last one
    # - for options that don't, return a string containing the option
    #   name as many times as the option was specified

    my Str:D %opts = getopts('ho:V', @*ARGS);
    CATCH { when X::Getopt::Std { .message.note; usage } };

    version() if %opts<V>;
    usage(True) if %opts<h>;
    exit(0) if %opts{<V h>}:k;

    my $outfile = %opts<o> // 'a.out';

    # "All options" usage:
    # - for options that take an argument, return an array of all
    #   the arguments supplied if specified more than once
    # - for options that don't, return the option name as many times
    #   as it was specified

    my %opts = getopts-all('o:v', @*ARGS);

    $verbose_level = %opts<v>.elems;

    for %opts<o> -> $fname {
        process_outfile $fname;
    }

    # Permute usage (with both getopts() and getopts-all()):
    # - don't stop at the first non-option argument, look for more
    #   arguments starting with a dash
    # - stop at an -- argument

    my Str:D %opts;
    %opts = getopts('ho:V', @*ARGS, :permute);

```

# DESCRIPTION

This module exports the `getopts()` and `getopts-all()`> functions for parsing command-line arguments similarly to the POSIX getopt(3) standard C library routine.

The options are single letters (no long options) preceded by a single dash character. Options that do not accept arguments may be clustered (e.g. `-hV` for `-h` and `-V`); the last one may be an option that accepts an argument (e.g. `-vo outfile.txt`). Options that accept arguments may have their argument "glued" to the option or in the next element of the arguments array, i.e. `-ooutfile` is equivalent to `-o outfile`. There is no equals character between an option and its argument; if one is supplied, it will be considered the first character of the argument.

If an unrecognized option character is supplied in the arguments array, `getopts()` will throw an exception. Otherwise it will return a hash with the options found in the arguments array. The key in the returned hash is the option name (e.g. `h` or `o`); the value is the option argument for options that accept one or the option name (as many times as it has been specified) for options that do not.

# FUNCTIONS

* sub getopts

  ```
  sub getopts(Str:D $optstr, @args, Bool :$nonopts,
      Bool :$permute, Bool :$unknown) returns Hash[Str:D]

  ```

  Look for the command-line options specified in `$optstr` in the `@args` array. Return the options found in a hash, leave only the non-option arguments in the `@args` array.

  Note that if an option is specified more than once on the command line, `getopts()` will only record the last argument in the returned hash; see also the `getopts-all()` function below.

  The `:permute` flag specifies whether option parsing should stop at the first non-option argument, or go on and process any other arguments starting with a dash. A double dash (--) stops the processing in this case, too.

  The `:unknown` flag controls the handling of unknown options - ones not specified in the `$optstr`, but present in the `@args`. If it is false (the default), `getopts()` will throw an exception; otherwise, the unknown option character will be present in the returned hash as an argument to a `:` option and `getopts()` will still succeed. This is similar to the behavior of some `getopt(3)` implementations if `$optstr` starts with a `:` character.

  The `:nonopts` flag makes `getopts()` treat each non-option argument as an argument to an option with a character code 1. This is similar to the behavior of some `getopt(3)` implementations if `$optstr` starts with a `-` character. The `:permute` flag is redundant if `:nonopts` is specified since the processing will not stop until the arguments array has been exhausted.

  Throws an `X::Getopt::Std` exception if an invalid option string has been specified or an unknown option has been found in the arguments array.

  Current API available since version 1.0.0.
* sub getopts-all

  ```
  sub getopts-all(Str:D $optstr, @args, Bool :$nonopts,
      Bool :$permute, Bool :$unknown) returns Hash[Array[Str:D]]

  ```

  Same as the `getopts()` function, but all the returned values are arrays containing all the specified arguments if any options have been specified more than once.

  For example, the command line -vI foo -I bar -v, matched against an option string of I:v, would produce `{ :I<bar> :v<vv> }` with `getopts()` and `{ :I(['foo', 'bar']) :v(['v', 'v']) }` with `getopts-all()`.

  Current API available since version 1.0.0.

# AUTHOR

Peter Pentchev <[roam@ringlet.net](mailto:roam@ringlet.net)>

# COPYRIGHT

Copyright (C) 2016, 2017, 2020 Peter Pentchev

# LICENSE

The Getopt::Std module is distributed under the terms of the Artistic License 2.0. For more details, see the full text of the license in the file LICENSE in the source distribution.


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

# NAME

JSON::Path - Implementation of the JSONPath data structure query language

# SYNOPSIS

```
use JSON::Path;

# Example data.
my $data = {
  kitchen => {
    drawers => [
      { knife => '🔪' },
      { glass => '🍷' },
      { knife => '🗡' },
    ]
  }
};

# A query
my $jp = JSON::Path.new('$.kitchen.drawers[*].knife');

# The first result
dd $jp.value($data);  # "🔪"

# All results.
dd $jp.values($data); # ("🔪", "🗡").Seq

# All paths where the results were found.
dd $jp.paths($data);  # ("\$.kitchen.drawers[0].knife",
                      #  "\$.kitchen.drawers[2].knife").Seq

# Interleaved paths and values.
dd $jp.paths-and-values($data);
# ("\$.kitchen.drawers[0].knife", "🔪",
#  "\$.kitchen.drawers[2].knife", "🗡").Seq

```

# DESCRIPTION

The [JSONPath query language](https://goessner.net/articles/JsonPath/) was designed for indexing into JSON documents. It plays the same role as XPath does for XML documents.

This module implements `JSON::Path`. However, it is not restricted to working on JSON input. In fact, it will happily work over any data structure made up of arrays and hashes.

# Query Syntax Summary

The following syntax is supported:

```
$           root node
.key        index hash key
['key']     index hash key
[2]         index array element
[0,1]       index array slice
[4:5]       index array range
[:5]        index from the beginning
[-3:]       index to the end
.*          index all elements
[*]         index all elements
[?(expr)]   filter on (Raku) expression
..key       search all descendants for hash key

```

A query that is not rooted from `$` or specified using `..` will be evaluated from the document root (that is, same as an explicit `$` at the start).

# AUTHOR

Jonathan Worthington

# COPYRIGHT AND LICENSE

Copyright 2012 - 2024 Jonathan Worthington

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-FCO-Configuration.md
# TITLE

Configuration Module Documentation

# SUBTITLE

Effortlessly manage configurations in Raku applications

This documentation provides a comprehensive guide on using the Configuration module for Raku. The module is designed to simplify the management of configuration data in Raku applications, making it easier to define, use, and update configurations as needed.

[![Build Status](https://github.com/FCO/Configuration/workflows/test/badge.svg)](https://github.com/FCO/Configuration/actions) [![SparrowCI](https://ci.sparrowhub.io/project/git-FCO-Configuration/badge)](https://ci.sparrowhub.io)

Note: The module is in the early stages of development.

# SYNOPSIS

This documentation covers the following aspects of the Configuration module:

* Defining configuration schemas
* Writing configuration files
* Utilizing configurations in Raku programs
* Understanding Configuration Builders
* Handling Missing Configuration Files with Default Values
* Dynamically reloading configurations
* Handling default configuration file paths
* Monitoring specific configuration value changes with config-supply
* Configuration Error Handling and Resilience
* Testing with Configuration Adjustments
* Retrieving the current configuration with get-config
* Obtaining configuration without a Supply with single-config-run

# CONFIGURATION DEFINITION

To define your application's configuration structure, create a Raku class that does the `Configuration::Node` role. This class will specify the fields and default values for your configuration.

## Example: Defining a Configuration Class

```
use v6.d;

class RootConfig {
    has Int $.a;
    has Int $.b = $!a * 2;
    has Int $.c = $!b * 3;
}

use Configuration RootConfig;

```

# WRITING CONFIGURATION FILES

Configuration files are written in Raku, allowing you to leverage Raku's syntax for setting configuration values.

## Example: Creating a Configuration File (`my-conf.rakuconfig`)

```
use Test1Config;

config {
    .a = 1;
    .c = 42;
}

```

# UTILIZING CONFIGURATIONS IN YOUR PROGRAM

To use the defined configurations in your Raku application, simply use the module where the configuration was defined and call the appropriate functions to access the configuration data.

## Example: Accessing Configuration in a Raku Program

```
use Test1Config;

say await config-run :file<examples/test1.rakuconfig>;

```

# UNDERSTANDING CONFIGURATION BUILDERS

When utilizing the `config` function to define or modify configurations, it's crucial to understand that the object you interact with is not directly the configuration object itself. Instead, this object is a specialized builder object, designed to accumulate configuration data before creating the final configuration object.

## The Role of Configuration Builders

For each configuration class you define, the Configuration module automatically generates a corresponding builder class. This builder class is named by appending the word "Builder" to the name of your configuration class. The primary purpose of the builder is to provide a flexible and error-resistant way to gather configuration data.

## Accumulating Configuration Data

The builder class contains read-write (rw) methods corresponding to each attribute defined in your configuration class. These methods are used to set or modify the values of the configuration attributes in a staged manner. By calling these methods, you accumulate the data needed to instantiate the actual configuration object.

Here's how the process works:

* **Initialization**: When you call the `config` function, the Configuration module instantiates the corresponding builder object based on your configuration class.
* **Data Accumulation**: As you use the builder's methods to set configuration values, the builder accumulates this data internally. Each method call adjusts the pending configuration state represented by the builder.
* **Configuration Instantiation**: Once all necessary configuration data is set, the builder uses this accumulated data to create an instance of your configuration class, effectively materializing the final configuration object.

## Example: Using a Configuration Builder

Consider you have a configuration class named `AppConfig`. The corresponding builder class would be `AppConfigBuilder`.

```
class AppConfig {
    has Str $.api_key;
    has Int $.timeout;
}

# Using the builder to set configuration
config {
    .api_key = 'your_api_key_here';
    .timeout = 300;
}

```

In this example, `.api_key` and `.timeout` are methods of the `AppConfigBuilder` object provided to the block by the `config` function. These methods set the values that will be used to instantiate `AppConfig` with the provided values.

This builder pattern allows for a clear separation between the definition of configuration data and its usage, enabling more complex configurations to be defined in an intuitive and error-resistant manner.

# HANDLING MISSING CONFIGURATION FILES WITH DEFAULT VALUES

The Configuration module is designed to ensure maximum uptime and resilience for your application by employing a robust defaulting mechanism. In situations where a configuration file is expected but does not exist, the module gracefully defaults to using predefined values specified within your configuration class. This feature guarantees that your application can start and run even in the absence of an external configuration file.

## Default Value Mechanism

Upon initialization, if the Configuration module does not find the specified configuration file, it does not halt the application or throw an error. Instead, it proceeds to instantiate the configuration object using the default values declared in the configuration class. This behavior is critical for maintaining application operability, especially in new deployments or environments where the configuration file may not yet be set up.

## Example: Specifying and Utilizing Default Values

```
class AppConfig {
    has Str $.api_key = 'default_api_key';
    has Int $.timeout = 30;
}

use Configuration AppConfig;

```

In this example, `AppConfig` specifies default values for `api_key` and `timeout`. If the Configuration module does not find an external configuration file upon application start, it will create an `AppConfig` object with these default values. Consequently, the application remains functional and uses these defaults as its operational parameters.

## Advantages of Using Default Values

* **Flexibility**: Allows the application to run in diverse environments without requiring a configuration file to be present initially.
* **Simplicity**: Simplifies development and testing by not mandating the existence of a configuration file, especially in early stages of development.
* **Reliability**: Enhances the reliability of the application by ensuring it can always start up, reducing the risk of failures due to missing configuration data.

This defaulting mechanism underscores the Configuration module's design philosophy of resilience and ease of use, ensuring that applications remain robust and user-friendly across various deployment scenarios.

# DYNAMIC CONFIGURATION RELOADING

The Configuration module supports dynamic reloading of configurations, allowing your application to respond to changes in configuration without restarting.

## Example: Reloading Configuration on File Change

```
use Test1Config;

react whenever config-run :file<./my-conf.rakuconfig>, :watch {
    say "Configuration changed: { .raku }";
}

```

## Example: Reloading Configuration on Signal

```
use Test1Config;

react whenever config-run :file<./my-conf.rakuconfig>, :signal(SIGUSR1) {
    say "Configuration changed: { .raku }";
}

```

# USING DEFAULT CONFIGURATION FILE PATHS

When the file path for a configuration is not explicitly specified, the Configuration module intelligently searches for configuration files in default locations. This feature simplifies the configuration management process by automatically detecting and using configuration files based on standardized naming conventions and common directory locations.

The module follows a hierarchical approach to search for configuration files in the following order:

* The same directory as the executable, appending `.rakuconfig` to the executable name.
* The user's home directory.
* The `/etc` directory, typically used for system-wide configuration files.

## Example: Implicit Configuration File Usage

```
use Test1Config;

# No file path is specified; the module automatically searches for `app.rakuconfig` in default locations.
say await config-run;

```

# MONITORING SPECIFIC CONFIGURATION VALUE CHANGES WITH CONFIG-SUPPLY

The `config-supply` function in the Configuration module is a standout feature for applications needing to monitor and react to changes in specific configuration values in real-time. This approach is invaluable for creating highly responsive and adaptable applications that depend on dynamic configuration data.

By returning a `Supply` that emits updates whenever the monitored configuration value changes, `config-supply` facilitates a reactive programming model. This enables developers to specify precisely which configuration values to observe and to define actions that should occur in response to changes in these values.

## Focused Monitoring with `config-supply`

The purpose of `config-supply` is to offer a targeted and efficient way to watch individual configuration values. This is especially useful in complex applications where certain features or behaviors are controlled by specific configuration settings, and updates to these settings need to be handled promptly.

## Example: Reacting to Changes in a Specific Configuration Value

```
use Test1Config;

# Reacting to changes in the `.a` configuration value
config-supply(*.a).tap: {
    say ".a has changed: ", $_
};

```

This example highlights the use of `config-supply` to monitor changes to the `.a` configuration value. By tapping into the supply, the application can execute a block of code—in this case, logging the change—whenever `.a` is updated.

## Integration with Reactive Programming Patterns

`config-supply` integrates seamlessly with Raku's reactive programming constructs (`react` and `whenever`), allowing for elegant and powerful event-driven programming based on configuration changes.

## Example: Dynamic Behavior Adjustment Based on Configuration Changes

```
use Test1Config;

react {
    # Dynamically adjust behavior based on changes to the `.a` value
    whenever config-supply(*.a) -> $new-value {
        say ".a has changed to: $new-value";
    }
}

```

# CONFIGURATION ERROR HANDLING AND RESILIENCE

A key feature of the Configuration module is its robust error handling mechanism during runtime configuration changes. When the module detects an error in the configuration—such as invalid data types, missing required fields, or any condition that violates the configuration schema—it is designed to issue a warning rather than terminating the application. This approach ensures that your application remains operational, continuing with the last known correct configuration.

## Graceful Error Management

The Configuration module adopts a non-intrusive error management strategy to maximize application uptime and resilience. In scenarios where a runtime configuration change introduces errors:

* The module logs a warning detailing the nature of the error, making it visible to developers or system administrators for troubleshooting.
* It retains the previous valid configuration state, ensuring that the application continues to run with known-good settings.
* Subsequent attempts to apply configuration changes will follow the same pattern—errors will result in warnings, and only valid changes will be applied.

## Benefits of This Approach

This error handling strategy offers several benefits:

* `Reliability`: Your application remains operational, avoiding downtime due to configuration issues.
* `Safety`: Ensures that only valid configurations are applied, protecting the application from unstable states.
* `Visibility`: Provides clear feedback on configuration errors, aiding in quick diagnosis and correction.

By prioritizing continuity and stability, the Configuration module helps maintain the integrity of your application's runtime environment, even in the face of configuration errors. This design choice reflects a commitment to production-grade resilience and operability.

# TESTING WITH CONFIGURATION ADJUSTMENTS

A common use case for dynamic configuration in testing involves feature toggles, which enable or disable application features during runtime. This example demonstrates testing a function, `access-new-feature`, which behaves differently based on the `feature_flag` setting in the `AppConfig` class.

## AppConfig Definition

Define the `AppConfig` class with a `feature_flag` attribute. This boolean attribute determines whether a new feature is accessible within the application.

```
class AppConfig {
    has Bool $.feature_flag = False; # Default: Feature is off
}

```

## Dynamic Configuration Setup for Testing Feature Toggles

We'll dynamically adjust the `feature_flag` setting to test the application's behavior when the new feature is turned on and off, ensuring that the application responds correctly in both scenarios.

```
use Test;
use YourConfigurationModule;

# Test the `access-new-feature` function with the feature enabled
set-config -> {
    config {
        .feature_flag = True; # Enable the new feature
    }
};

is-deeply
    access-new-feature(),
    expected-output-with-feature-enabled(),
    "Feature enabled - Validates access-new-feature with the feature toggle on";

# Test the `access-new-feature` function with the feature disabled
set-config -> {
    config {
        .feature_flag = False; # Ensure the feature is disabled
    }
};

is-deeply
    access-new-feature(),
    expected-output-with-feature-disabled(),
    "Feature disabled - Validates access-new-feature with the feature toggle off";

```

In this example, `set-config` is used to temporarily modify the application's configuration before each test. By toggling the `feature_flag`, we simulate conditions where the new feature is both available and unavailable. Each test case then verifies that `access-new-feature` performs as expected under these conditions.

## Benefits of Testing Feature Toggles

* **Flexibility**: Easily test the application's behavior with various configuration states without changing the codebase.
* **Isolation**: Keep tests independent to ensure that enabling or disabling a feature for one test doesn't affect others.
* **Coverage**: Ensure that all paths work as expected, increasing the application's reliability.

Testing with dynamic configuration adjustments, especially for feature toggles, is essential for validating application behavior under different feature states. This approach enhances the ability to deliver reliable features and facilitates a smoother transition from development to production.

# RETRIEVING THE CURRENT CONFIGURATION WITH GET-CONFIG

The `get-config` function is a straightforward way to access the current value of your application's configuration. This function returns the current configuration object, allowing for immediate access to its properties without monitoring for changes.

## Example: Accessing Current Configuration Values

```
use Test1Config;

# Retrieve the current configuration
my $current-config = get-config();

say "Current configuration: ", $current-config.raku;

```

# OBTAINING CONFIGURATION WITHOUT A SUPPLY WITH SINGLE-CONFIG-RUN

While `config-run` provides a `Supply` that emits configuration changes over time, `single-config-run` is designed to return the configuration object a single time. This function is useful when you only need to read the configuration once and do not require a reactive setup to monitor for changes.

## Example: Using Single-Config-Run to Access Configuration

```
use Test1Config;

# Obtain the configuration a single time
my $config = single-config-run();

say "Configuration obtained once: ", $config.raku;

```

By incorporating these functions, developers are equipped with flexible tools for managing configuration according to the needs of their application, whether it's accessing the current configuration state, reacting to changes in real-time, or obtaining the configuration once without further monitoring.


## dist_cpan-FRITH-Math-Libgsl-Combination.md
[![Build Status](https://travis-ci.org/frithnanth/raku-Math-Libgsl-Combination.svg?branch=master)](https://travis-ci.org/frithnanth/raku-Math-Libgsl-Combination)

# NAME

Math::Libgsl::Combination - An interface to libgsl, the Gnu Scientific Library - Combinations.

# SYNOPSIS

```
use Math::Libgsl::Combination;

```

# DESCRIPTION

Math::Libgsl::Combination is an interface to the combination 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.

### new(:$n!, :$k!)

### new($n!, $k!)

The constructor accepts two parameters: the total number of elements in the set and the number of elements chosen from the set; the parameters can be passed as Pair-s or as single values. The combination object is already initialized in lexicographically first combination, i.e. (0, 1, 2, …, $k − 1).

### init(:$start? = TOP)

This method initialize the combination object and returns **self**. The default is to initialize the object in lexicographically first combination, but by specifying the optional parameter **$start** as **BOTTOM** the initialization is performed in the lexicographically last combination, i.e. ($n − $k, $n − $k + 1, …, $n − 1). TOP and BOTTOM are declared as values of the Starting-point enum.

### copy($src! where \* ~~ Math::Libgsl::Combination)

This method copies the combination **$src** into the current combination object and returns **self**.

### get(Int $elem! --> Int)

This method returns the combination value at position **$elem**.

### all(--> Seq)

This method returns a Seq of all the elements of the current combination.

### size(--> List)

This method returns the (n, k) parameters of the current combination object.

### is-valid(--> Bool)

This method checks whether the current combination is valid: the k elements should lie in the range 0 to $n − 1, with each value occurring once at most and in increasing order.

### next()

### prev()

These functions advance or step backwards the combination and return **self**, useful for method chaining.

### bnext(--> Bool)

### bprev(--> Bool)

These functions advance or step backwards the combination and return a Bool: **True** if successful or **False** if there's no more permutation to produce.

### write(Str $filename! --> Int)

This method writes the combination data to a file.

### read(Str $filename! --> Int)

This method reads the combination data from a file. The combination must be of the same size of the one to be read.

### fprintf(Str $filename!, Str $format! --> Int)

This method writes the combination data to a file, using the format specifier.

### fscanf(Str $filename!)

This method reads the combination data from a file. The combination must be of the same size of the one to be read.

# 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

```
sudo apt install libgsl23 libgsl-dev libgslcblas0

```

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

## Ubuntu 18.04

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

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

# Installation

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

```
$ zef install Math::Libgsl::Combination

```

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


## values.md
values

Combined from primary sources listed below.

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

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

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

Returns a sequence of the list elements, in order.

```raku
say (1,2,3,4).^name;        # OUTPUT: «List␤»
say (1,2,3,4).values.^name; # OUTPUT: «Seq␤»
```

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

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

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

Returns a [`Seq`](/type/Seq) of all values, i.e. weights, in the `Baggy` object.

```raku
my $breakfast = bag <eggs spam spam spam>;
say $breakfast.values.sort;                      # OUTPUT: «(1 3)␤»

my $n = ("a" => 5, "b" => 2, "a" => 1).BagHash;
say $n.values.sort;                              # OUTPUT: «(2 6)␤»
```

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

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

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

Returns a [`Seq`](/type/Seq) containing all positional values followed by all named argument values.

```raku
my $capture = \(2, 3, 5, apples => (red => 2));
say $capture.values; # OUTPUT: «(2 3 5 red => 2)␤»
```

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

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

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

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

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

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

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

```raku
multi method values(Pair:D: --> List:D)
```

Returns a [`List`](/type/List) containing the [value](/type/Pair#method_value) of the invocant.

```raku
say (Raku => "d").values;                         # OUTPUT: «(d)␤»
```

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

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

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

Will return an empty list for undefined or class arguments, and the object converted to a list otherwise.

```raku
say (1..3).values; # OUTPUT: «(1 2 3)␤»
say List.values;   # OUTPUT: «()␤»
```

# [In role Setty](#___top "go to top of document")[§](#(role_Setty)_method_values "direct link")

See primary documentation
[in context](/type/Setty#method_values)
for **method values**.

```raku
multi method values(Setty:D: --> Seq:D)
```

Returns a [`Seq`](/type/Seq) containing as many `True` values as the set has elements.

```raku
my $s = Set.new(1, 2, 3);
say $s.values;                                    # OUTPUT: «(True True True)␤»
```


## dist_github-pierre-vigier-Acme-Sudoku.md
# Perl6-Acme::Sudoku

[![Build Status](https://travis-ci.org/pierre-vigier/Perl6-Acme-Sudoku.svg?branch=master)](https://travis-ci.org/pierre-vigier/Perl6-Acme-Sudoku)

# NAME

Acme::Sudoku

# SYNOPSIS

Simple sudoku solver, keeping the Sudoku namespace clean, as it will use really naive algorithm

# DESCRIPTION

This module provides a naive sudoku solver

```
use Acme::Sudoku;

my $game = Acme::Sudoku.new( q:to/END/ );
. . . . . 8 . . .
7 . . . . . 9 . 5
. 1 4 . 3 5 8 . .
. 2 . . 1 6 . 3 .
. 5 . . . 9 6 . 1
8 . . . . . . . 4
3 . 9 2 . . 1 . .
. . 6 1 . 7 . . 2
1 . . 5 . . . 7 .
END

$game.solve;
say $game;

```

The only algorithm implemented now is for each case, looking for missing value in row/column/square. If we can reduce the missing set to 1 element, case is filled. That algorithm does not enusre the finding of a solution, and works only for extremly easy sudoku grid.


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

# NAME

Raku port of Perl's User::grent module

# SYNOPSIS

```
use User::grent;
$gr = getgrgid(0) or die "No group zero";
if $gr.name eq 'wheel' && $gr.members > 1 {
    print "gid zero name wheel, with other members";
}

use User::grent qw(:FIELDS);
getgrgid(0) or die "No group zero";
if $gr_name eq 'wheel' && @gr_members > 1 {
    print "gid zero name wheel, with other members";
}

$gr = getgr($whoever);

```

# DESCRIPTION

This module tries to mimic the behaviour of Perl's `User::grent` module as closely as possible in the Raku Programming Language.

This module's default exports `getgrent`, `getgrgid`, and `getgrnam` functions, replacing them with versions that return `User::grent` objects. This object has methods that return the similarly named structure field name from the C's passwd structure from grp.h; namely name, passwd, gid, and members (not mem). The first three return scalars, the last an array.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still exports the functions.) Access these fields as variables named with a preceding gr\_. Thus, `$group_obj.gid` corresponds to `$gr_gid` if you import the fields.

The `getgr` function is a simple front-end that forwards a numeric argumenti to `getgrgid` and the rest to `getgrnam`.

# PORTING CAVEATS

This module depends on the availability of POSIX semantics. This is generally not available on Windows, so this module will probably not work on Windows.

# AUTHOR

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

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

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021 Elizabeth Mattijsen

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

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


## dist_cpan-MOZNION-Backtrace-AsHTML.md
[![Build Status](https://travis-ci.org/moznion/p6-Backtrace-AsHTML.svg?branch=master)](https://travis-ci.org/moznion/p6-Backtrace-AsHTML)

# NAME

Backtrace::AsHTML - Displays back trace in HTML

# SYNOPSIS

```
use Backtrace::AsHTML;

my $trace = Backtrace.new;
my $html  = $trace.as-html;

```

# DESCRIPTION

Backtrace::AsHTML adds `as-html` method to <Backtrace> which displays the back trace in beautiful HTML, with code snippet context.

![](https://i.gyazo.com/6ac7f82ef6fb0a05d7de9a11dbdcaa0b.png)

This library is inspired by [Devel::StackTrace::AsHTML of perl5](https://metacpan.org/release/Devel-StackTrace-AsHTML) and much of code is taken from that.

# METHODS

* `as-html`

`as-html` shows the fully back trace in HTML.

This method will be added into <Backtrace> class automatically when used this.

# TODO

* show lexical variables for each frames (How?)
* show arguments for each frames? (How??)

# AUTHOR

moznion [moznion@gmail.com](mailto:moznion@gmail.com)

# COPYRIGHT AND LICENSE

```
Copyright 2015 moznion

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

```

And license of the original perl5's Devel::StackTrace::AsHTML is

```
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

```


## dist_zef-samy-Fortune.md
# NAME

Fortune - Unix fortune database interface

# SYNOPSIS

```
use Fortune;

## Object-oriented interface

my $fortune = Fortune.new: '/path/to/database';

my $pick = $fortune.fortune.pick;

$fortune.fortune.append: (q:to/HERE/).chomp;
Arnold's Laws of Documentation:
        (1) If it should exist, it doesn't.
        (2) If it does exist, it's out of date.
        (3) Only documentation for useless programs transcends the
            first two laws.
HERE

$fortune.write: '/path/to/new/database', :header('/path/to/header');

## Some convenience subs

strfile '/path/to/database', '/path/to/header';

$pick = fortune;

```

# DESCRIPTION

Fortune is a Raku module that provides an interface for reading and writing Unix fortune files, both the text database files and the binary header files.

## class Fortune

### Attributes

#### fortune

```
has Str @.fortune is rw

```

`Str` array of fortunes. Manipulating this array is how you can modify a fortune database.

```
# Add a fortune
$fortune.fortune.append: "A new fortune";

# Remove a fortune
$fortune.fortune.pop;

# Sort fortunes
$fortune.fortune.=sort;

# Shuffle fortunes
$fortune.fortune.=pick(*);

# etc. etc.

```

#### order

```
has FortuneOrder $.order is rw

```

Attribute that determines the order to write the header's offset table in. Does not determine the order of the fortunes stored in the object's `fortune` attribute.

See the `FortuneOrder` documentation below for documentation on valid values for `order`.

#### rot13

```
has Bool $.rot13 is rw

```

`Bool` that determines whether the source fortune database was ROT-13 ciphered or not. When set to `True`, the `Fortune` object will read and write databases as if they were ROT-13 ciphered.

#### delimit

```
has Char $.delimit is rw

```

Character that is used for delimitting lines in a source fortune database. Is usually a single percentage sign (`'%'`). `delimit` must be a string that represents a single ASCII character.

#### version

```
has Int $.version is rw

```

Version number of the fortune header. Valid values are `1` and `2`. Version 1 is the version used by most strfile implementations, version 2 is the version used by OpenBSD. The difference between the two versions is the way they store offsets in the fortune header: `1` stores offsets as 64-bit unsigned integars while `2` stores them as 32-bit unsigned integars. The version has no effect on the source fortune database.

### Methods

#### new

```
method new(
	$database?,
	:$header,
	:@fortune,
	FortuneOrder :$order,
	Bool :$rot13,
	Char :$delimit,
	Int :$version
)

```

Returns a new `Fortune` object. Will either create an entirely new database if `$database` is not provided, or read from an existing one if `$database` is provided.

`$database` is the path to the database to read fortunes from. The fortunes can be accessed and manipulated from the object's `fortune` attribute.

`$header` is the path to the database's corresponding binary header to read from. If `$header` is a value that evaluates to `False`, `new` will not attempt to read any header file. By default, `$header` will either be `$database` with the `'.dat'` suffix appended if `$database` was provided and such a header does exist, otherwise it will be set to `False`. Please note that when reading from `$header`, `new` will override any custom attributes that were supplied.

`@fortune` is the list of fortune strings to supply for the `fortune` attribute. Defaults to `Empty`. If `$database` is also provided, `new` will append the list of fortunes read from `$database` to the list provided by `@fortune`.

`$order` is the value to supply for the `order` attribute. Defaults to `FORTUNE_UNORDER`.

`$rot13` is the value to supply for the `rot13` attribute. Defaults to `False`.

`$delimit` is the value to supply for the `delimit` attribute. Defaults to `'%'`.

`$version` is the value to supply for the `version` attribute. Defaults to `1`.

#### read

```
method read(
	$database,
	:$header,
	Bool :$append
)

```

Reads data from the source database `$database` and (optionally) from the header `$header`.

`$header` will, by default, be `$database` with the `'.dat'` suffix if such a file exists, or `False` otherwise. If you do not wish to read from an existing header, `$header` can be set to `False`.

`$append` is a `Bool` determining whether to append new fortunes to the `fortunes` array or to overwrite it. Defautls to `False`.

Returns `True`, if successful.

#### read\_header

```
method read_header($header)

```

Reads data from the header file `$header`.

Returns `True`, if successful.

#### read\_database

```
method read_database(
	$database,
	Char :$delimit,
	Bool :$rot13,
	Bool :$append
)

```

Reads fortunes from the database file `$database`.

`$delimit` is the delimitting character to use when reading `$database`. Does not modify the `delimit` attribute. Defaults to the value of the `delimit` attribute.

`$rot13` determines whether to ROT-13 cipher the fortunes in `$database`. Does not modify the `rot13` attribute. Defaults to the value of the `rot13` attribute.

`$append` is a `Bool` determining whether to override the current fortune list in `fortune`, or to just append to it. Defaults to `False`.

Returns `True`, if successful.

#### write

```
method write(
	$database,
	:$header
)

```

Write fortune database to `$database` and (optionally) fortune header to `$header`.

By default, `$header` will be `$database` with the `'.dat'` suffix. If set to any value that evaluates to `False`, `write` will not try to write a header file.

Returns list of `IO` objects for each written file.

#### write\_database

```
method write_database($database)

```

Write fortune database to `$database`.

Returns `IO` object of written database.

#### write\_header

```
method write_header($header)

```

Write fortune header to `$header`.

Returns `IO` object of written header.

### Subroutines

The following subroutines were written to provide simple convenience functions for those who do not wish to interact with the object-oriented part of this module.

#### strfile

```
sub strfile(
	$database,
	$header?,
	Char :$delimit,
	FortuneOrder :$order,
	Bool :$rot13,
	Int :$version
)

```

Subroutine emulating the `strfile(8)` utility. Reads fortunes from `$database` and generates a corresponding fortune header to `$header`. If not supplied, `$header` will default to `$database` with the `'.dat'` suffix.

`$delimit` is the delimitting character `$database` uses. Defaults to `'%'`.

`$order` is the order to write the offset table in. Defaults to `FORTUNE_UNORDER`.

`$rot13` is a `Bool` determining whether the source database was ROT-13 ciphered or not. Defaults to `False`.

`$version` is the version number to use for the generated header. Defaults to `1`.

Returns the `IO` object of the written header.

#### fortune

```
multi sub fortune(
	Bool :$short,
	Bool :$long
)

multi sub fortune(
	$database,
	:$header,
	Bool :$short,
	Bool :$long,
	Bool :$equal,
	Bool :$all,
	Bool :$offensive,
	Char :$delimit,
	Bool :$rot13
)

multi sub fortune(
	$dir,
	Bool :$short,
	Bool :$long,
	Bool :$equal,
	Bool :$all,
	Bool :$offensive,
	Char :$delimit,
	Bool :$rot13
)

```

Subroutine somewhat emulating the `fortune(6)` utility. Picks a random fortune from a supplied database and returns it.

When ran without providing a fortune file/directory, returns a fortune from this module's own database.

When given a file as an argument, returns a random fortune from that file.

When given a directory as argument, returns a random fortune from one of the databases in that directory.

`$header` is the path to the header file to read from. Defaults to `$database` with the `'.dat'` suffix, or `False` if such a file does not exist. When `False`, `fortune` will not try to read any header file.

`$short` is a `Bool` determining whether to only pick from short fortunes. A short fortune is a fortune of 160 characters or less. Defaults to `False`.

`$long` is a `Bool` determining whether to only pick from long fortunes. A long fortune is a fortune that has more than 160 characters. Defaults to `False`.

`$equal` is a `Bool` determining whether to treat each fortune file in `$dir` of equal size. Is `False` by default, which means that `fortune()` is more likely to pick a fortune from a larger file.

`$all` is a `Bool` determining whether to include all fortunes files, including offensive ones, when picking a fortune. Is meaningless unless the fortune argument is a directory.

`$offensive` is a `Bool` that means `fortune()` will only pick offensive fortunes, which are fortunes located in a file with a `'-o'` suffix. Is meaningless unless the fortune argument is a directory. Also, to quote the `fortune(6)` manpage:

```
Please, please, please request a potentially offensive fortune if and only if
you believe, deep down in your heart, that you are willing to be offended.
(And that if you are, you'll just quit using [:offensive] rather than give us
grief about it, okay?)

    ...  let us keep in mind the basic governing philosophy of The Brotherhood,
    as handsomely summarized in these words:  we  believe  in  healthy,  hearty
    laughter -- at the expense of the whole human race, if needs be.  Needs be.
             --H. Allen Smith, "Rude Jokes"

```

`$delimit` is the delimitting character to use when reading from a database. Defaults to `'%'`.

`$rot13` is a `Bool` determining whether the database is ROT-13 ciphered or not. Defaults to `False`.

This subroutine caches the `Fortune` object it creates from reading a database, and will re-use it as long as it has the same arguments as the previous `fortune` call. This makes it efficient to call this subroutine on the same database multiple times.

### Global Variables

#### DATABASE

```
our constant $DATABASE

```

`IO` object of `Fortune`'s personal fortune database, which is the one used by default by `fortune()` and the `rfortune` script. Can be accessed via `$Fortune::DATABASE`.

## enum FortuneOrder

```
enum FortuneOrder <
	FORTUNE_UNORDER
	FORTUNE_ORDER
	FORTUNE_FC_ORDER
	FORTUNE_RANDOM
>

```

Enumeration representing the various ways a header file can order their offset tables.

* `FORTUNE_UNORDER`

  The offsets are ordered in the same way the fortunes are ordered in the `fortune` array.
* `FORTUNE_ORDER`

  The offsets are ordered alphabetically.
* `FORTUNE_FC_ORDER`

  The offsets are ordered alphabetically, case-insensitive.
* `FORTUNE_RANDOM`

  The offsets are ordered randomly.

# AUTHOR

Written by Samuel Young, <samyoung12788@gmail.com>.

The source for this module can be found on its [Codeberg page](https://codeberg.org/1-1sam/raku-Fortune). Comments and pull requests are welcome.

# COPYRIGHT

Copyright 2025, Samuel Young

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

# SEE ALSO

fortune(6), strfile(8)


## dist_zef-jnthn-Wasm-Emitter.md
# Wasm::Emitter

A Raku module to emit the [WebAssembly](https://webassembly.org/) binary
format.

## Example

This emits the "hello world" WebAssembly program using WASI (the WebAssembly
System Interface) to provide I/O functions.

```
# Create an instance of the emitter, which can emit a module.
my $emitter = Wasm::Emitter.new;

# Import fd_write
my $fd-write-type = $emitter.function-type:
        functype(resulttype(i32(), i32(), i32(), i32()), resulttype(i32()));
my $fd-write-index = $emitter.import-function("wasi_unstable", "fd_write", $fd-write-type);

# Declare and export a memory.
$emitter.export-memory("memory", $emitter.memory(limitstype(1)));

# Write 'hello world\n' to memory at an offset of 8 bytes
my $offset-expression = Wasm::Emitter::Expression.new;
$offset-expression.i32-const(8);
$emitter.active-data("hello world\n".encode('utf-8'), $offset-expression);

# Generate code to call fd_write.
my $code = Wasm::Emitter::Expression.new;
given $code {
    # (i32.store (i32.const 0) (i32.const 8))
    .i32-const(0);
    .i32-const(8);
    .i32-store;
    # (i32.store (i32.const 4) (i32.const 12))
    .i32-const(4);
    .i32-const(12);
    .i32-store;
    # (call $fd_write
    #   (i32.const 1) ;; file_descriptor - 1 for stdout
    #   (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0
    #   (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.
    #   (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written
    # )
    .i32-const(1);
    .i32-const(0);
    .i32-const(1);
    .i32-const(20);
    .call($fd-write-index);
    # Drop return value
    .drop;
}

# Declare and export the start function.
my $start-type = $emitter.function-type: functype(resulttype(), resulttype());
my $start-func-index = $emitter.function: Wasm::Emitter::Function.new:
        :type-index($start-type), :expression($code);
$emitter.export-function('_start', $start-func-index);

# Assemble and write to a file, which can be run by, for example, wasmtime.
my $buf = $emitter.assemble();
spurt 'hello.wasm', $buf;

```

## API Documentation

Refer to the Pod documentation on the types and functions.

## Functionality

To the best of my knowledge, this covers all of the WebAssembly 2.0 specified
features except the vector instructions. None of the proposed specifications
are currently implemented (although some of them are liable to attract my
attention ahead of the vector instructions).

## Support policy

This is a module developed for personal interest. I'm sharing it in case it's
fun or useful to anybody else, not because I want yet another open source
project to maintain. PRs that include tests and are provided in an easy to
review form will likely be merged quite quickly, so long as no major flaws
are noticed. For anything needing more effort on my part, please don't expect
a quick response.


## dist_zef-antononcube-DSL-Shared.md
# Raku DSL::Shared

This repository provides a Raku package for shared utilities and (grammar) roles
for family of packages that translate Domains Specific Languages (DSLs) into executable
programming languages code. (Also natural languages.)

Preliminary versions of the code in this repository can be found in the GitHub repository [AAr1].

The initial, "core" packages that use "DSL::Shared" are:

* ["DSL::English::ClassificationWorkflows"](https://github.com/antononcube/Raku-DSL-English-ClassificationWorkflows), [AAp4]
* ["DSL::English::DataQueryWorkflows"](https://github.com/antononcube/Raku-DSL-English-DataQueryWorkflows), [AAp5]
* ["DSL::English::LatentSemanticAnalysisWorkflows"](https://github.com/antononcube/Raku-DSL-English-LatentSemanticAnalysisWorkflows), [AAp6]
* ["DSL::English::QuantileRegressionWorkflows"](https://github.com/antononcube/Raku-DSL-English-QuantileRegressionWorkflows), [AAp7]
* ["DSL::English::RecommenderWorkflows"](https://github.com/antononcube/Raku-DSL-English-RecommenderWorkflows), [AAp8]

The package "DSL::Bulgarian", [AAp1], extends the English grammar based DSLs by providing
Bulgarian language *tokens* that correspond to the English tokens.

---

## Installation

Zef ecosystem:

```
zef install DSL::Shared

```

GitHub :

```
zef install https://github.com/antononcube/Raku-DSL-Shared.git

```

---

## Roles to share

One of the main reason for making this package is to encapsulate and easily share grammar roles for making DSL translators.

Here is a list:

* Error handling role
* Common English terms and phrases role used in workflows from Machine Learning, Data Science, or Scientific Computing
* Predicate specification role
* List management commands role
* User on-boarding role
* Time intervals specifications role
* Entity names parsing role

---

## Utilities to share

The package provides several different types of utilities for making DSL translators.

* Fuzzy matching functions
* DSL meta-specifications processing functions
* Universal command processing
* Resource access class and role

*Remark:* Initial versions of the Finite State Machine classes were part of this package.
Those classes were moved to "DSL::FiniteStateMachines", [AAp9]. Those initial versions are
kept here since they are referenced in presentations.

---

## Examples

The examples in the directory <./examples> show the different roles provided by the package
and how they can be utilized in different DSL commands.

---

## References

### Packages

[AAp1] Anton Antonov,
[DSL::Bulgarian Raku package](https://github.com/antononcube/Raku-DSL-Bulgarian),
(2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp2] Anton Antonov,
[Lingua::NumericWordForms, Raku project](https://github.com/antononcube/Raku-Lingua-NumericWordForms)
(2021-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp3] Anton Antonov,
[Grammar::TokenProcessing, Raku project](https://github.com/antononcube/Raku-Grammar-TokenProcessing)
(2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp4] Anton Antonov,
[DSL::English::ClassificationWorkflows, Raku package](https://github.com/antononcube/Raku-DSL-General-ClassificationWorkflows),
(2018-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp5] Anton Antonov,
[DSL::English::DataQueryWorkflows, Raku package](https://github.com/antononcube/Raku-DSL-English-DataQueryWorkflows),
(2020-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp6] Anton Antonov,
[DSL::English::LatentSemanticAnalysisWorkflows, Raku package](https://github.com/antononcube/Raku-DSL-General-LatentSemanticAnalysisWorkflows),
(2018-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp7] Anton Antonov,
[DSL::English::QuantileRegressionWorkflows, Raku package](https://github.com/antononcube/Raku-DSL-General-QuantileRegressionWorkflows),
(2018-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp8] Anton Antonov,
[DSL::English::RecommenderWorkflows, Raku package](https://github.com/antononcube/Raku-DSL-General-RecommenderWorkflows),
(2018-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp9] Anton Antonov,
[DSL::FiniteStateMachines, Raku package](https://github.com/antononcube/Raku-DSL-FiniteStateMachines),
(2021-2022),
[GitHub/antononcube](https://github.com/antononcube).

[NLp1] Nick Logan,
[Text::Levenshtein::Damerau, Raku project](https://github.com/ugexe/Perl6-Text--Levenshtein--Damerau)
(2016),
[GitHub/ugexe](https://github.com/ugexe).

### Repositories

[AAr1] Anton Antonov,
[Conversational Agents at GitHub](https://github.com/antononcube/ConversationalAgents),
(2018-2022),
[GitHub/antononcube](https://github.com/antononcube).


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

# NAME

EERPG - Emergent Economies for Role Playing Games

# SYNOPSIS

```
use EERPG;

```

# DESCRIPTION

The `EERPG` role provides all functionality shared by all objects in the `EERPG` distribution.

# AUTHOR

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

EERPG is an implementation of the "Emergent Economies for Role Playing Games" white paper by Jonathan Doran and Ian Parberry.

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

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2021 Elizabeth Mattijsen

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


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

# NAME

RakuAST::Utils - provide basic RakuAST utilities

# SYNOPSIS

```
use RakuAST::Utils;

say NameAST("Foo::Bar");

say TypeAST( Array[Int] );

sub foo(Int $a, Str $b) { }
say ParameterAST( &foo.signature.params[0] );

say SignatureAST( &foo.signature );

```

# DESCRIPTION

The `RakuAST::Utils` provides a number of subroutines that make the programmatical creation of code using RakuAST a lot easier.

# SUBROUTINES

## NameAST

```
say NameAST( "Foo" );
say NameAST( "Foo::Bar" );

```

```
RakuAST::Name.from-identifier("Foo")
RakuAST::Name.from-identifier-parts("Foo","Bar")

```

The `TypeAST` subroutine takes a package-like string and returns the RakUAST representation of that string.

## TypeAST

```
say TypeAST( Array[Int] );

```

```
RakuAST::Type::Parameterized.new(
  base-type => RakuAST::Type::Simple.new(
    RakuAST::Name.from-identifier("Array")
  ),
  args      => RakuAST::ArgList.new(
    RakuAST::Type::Simple.new(
      RakuAST::Name.from-identifier("Int")
    )
  )
)

```

The `TypeAST` subroutine takes a type object and returns the RakUAST representation of that type object.

## ParameterAST

```
sub foo(Int $a, Str $b --> Str:D) { }
say ParameterAST( &foo.signature.params[0] );

```

```
RakuAST::Parameter.new(
  type   => RakuAST::Type::Simple.new(
    RakuAST::Name.from-identifier("Int")
  ),
  target => RakuAST::ParameterTarget::Var.new(
    name => "\$a"
  )
)

```

The `ParameterAST` subroutine takes a [`Parameter`](https://docs.raku.org/type/Parameter) object and returns the RakUAST representation of that object.

## SignatureAST

```
sub foo(Int $a, Str $b --> Str:D) { }
say SignatureAST( &foo.signature );

```

```
RakuAST::Signature.new(
  parameters => (
    RakuAST::Parameter.new(
      type   => RakuAST::Type::Simple.new(
        RakuAST::Name.from-identifier("Int")
      ),
      target => RakuAST::ParameterTarget::Var.new(
        name => "\$a"
      )
    ),
    RakuAST::Parameter.new(
      type   => RakuAST::Type::Simple.new(
        RakuAST::Name.from-identifier("Str")
      ),
      target => RakuAST::ParameterTarget::Var.new(
        name => "\$b"
      )
    ),
  ),
  returns    => RakuAST::Type::Simple.new(
    RakuAST::Name.from-identifier("Str:D")
  )
)

```

The `SignatureAST` subroutine takes a [`Signature`](https://docs.raku.org/type/Signature) object and returns the RakUAST representation of that object.

# ACKNOWLEDGEMENTS

The initial version of this distribution was taken from the work on [`.assuming`](https://github.com/rakudo/rakudo/issues/2599), which was sponsored by the [Raku Foundation](https://raku.foundation).

# AUTHOR

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

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


## nl-in.md
nl-in

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/IO/Handle#method_nl-in)
for **method nl-in**.

```raku
method nl-in(--> Str:D) is rw
```

One of the attributes that can be set via `.new` or [open](/routine/open). Defaults to `["\x0A", "\r\n"]`. Takes either a [`Str`](/type/Str) or [`Array`](/type/Array) of [`Str`](/type/Str) specifying input line ending(s) for this handle. If `.chomp` attribute is set to `True`, will strip these endings in routines that `chomp`, such as [`get`](/routine/get) and [`lines`](/routine/lines).

```raku
with 'test'.IO {
    .spurt: '1foo2bar3foo'; # write some data into our test file
    my $fh will leave {.close} = .open; # can also set .nl-in via .open arg
    $fh.nl-in = [<foo bar>]; # set two possible line endings to use;
    $fh.lines.say; # OUTPUT: ("1", "2", "3").Seq
}

```

# [In IO::CatHandle](#___top "go to top of document")[§](#(IO::CatHandle)_method_nl-in "direct link")

See primary documentation
[in context](/type/IO/CatHandle#method_nl-in)
for **method nl-in**.

```raku
method nl-in(IO::CatHandle:D:) is rw
```

Sets the invocant's `$.nl-in` attribute to the assigned value, which can be a [`Str`](/type/Str) or a [`List`](/type/List) of [`Str`](/type/Str), where each [`Str`](/type/Str) object represents the end-of-line string. All source handles, including the active one will use the provided `$.nl-in` value. Note that source handle boundary is always counted as a new line break.

```raku
(my $f1 = 'foo'.IO).spurt: "A\nB\nC";
(my $f2 = 'bar'.IO).spurt: "DxEx";
with IO::CatHandle.new: $f1, $f2 {
    # .nl-in is ["\n", "\r\n"] by default:
    (.get xx 2).raku.say; # OUTPUT: «("A", "B").Seq␤»

    .nl-in = 'x';
    (.get xx 3).raku.say; # OUTPUT: «("C", "D", "E").Seq␤»
    .close
}

```


## dist_github-ppentchev-Shell-Capture.md
# NAME

Shell::Capture - capture a command's output and exit code

# SYNOPSIS

```
    use Shell::Capture;

    my Shell::Capture $c .= capture('id', '-u', '-n');
    if $c.exitcode != 0 {
        die "Could not execute id -u -n\n";
    } elsif $c.lines.elems != 1 {
        die "id -u -n returned something unexpected:\n" ~ $c.lines.join("\n") ~ "\n";
    }
    say "Got my username: " ~ $c.lines[0];

    sub fail($r, @cmd) {
        die "fail with exit code $r.exitcode() and $r.lines().elems() " ~
            "line(s) of output and cmd " ~ @cmd;
    }

    $c .= capture-check(:accept(0, 3), 'sh', '-c', 'date');
    say "The current date is $c.lines()[0]" if $c.exitcode == 0;

    $c .= capture-check(:accept(0, 3), 'sh', '-c', 'date; exit 3');
    say "The current date is $c.lines()[0]" if $c.exitcode == 3;

    $c .= capture-check(:accept(0, 3), :&fail, 'sh', '-c', 'date; exit 1');
    say 'not reached, fail() dies';

    $c .= capture-check('git', 'ls-files', '-z', :nl("\0"));
    say 'Got some unquoted filenames from Git:';
    $c.lines>>.say;

    $c .= capture-check('env', 'LANG=fr_FR.ISO-8859-1', 'date', :enc('ISO-8859-1'));

```

# DESCRIPTION

This class provides two methods to execute an external command, capture its output and exit code, and, in `capture-check()`, raise an error on unexpected exit code values.

# FIELDS

* exitcode

  ```
  Int:D $.exitcode

  ```

  The exit code of the executed external command.
* lines

  ```
  Str:D @.lines

  ```

  The output of the external command split into lines with the newline terminator removed.

# METHODS

* method capture()

  ```
  method capture(*@cmd, Str :$enc, Str :$nl)

  ```

  Execute the specified command in the same way as `run()` would, then create a new `Shell::Capture` object with its `exitcode` and `lines` members set respectively to the exit code of the command and its output split into lines, as described above.

  The `$enc` and `$nl` parameters, if supplied, are passed directly to `run()`, allowing the caller to specify the encoding of the data output by the external program and the character (or string) used to delimit lines in the output. See the `Proc.new()` documentation for more information.
* method capture-check()

  ```
  method capture-check(:$accept, :$fail, Str :$enc, Str :$nl, *@cmd)

  ```

  Execute the specified command and create a `Shell::Capture` object in the same way as `capture()`, then check the exit code against the `$accept` list (default: only 0). If the exit code is on the list, return the `Shell::Capture` object to the caller.

  If the exit code is not on the list and there is no `$fail` handler specified, output an error message to the standard error stream and terminate the program. If a fail handler is specified, invoke it with two arguments: the `Shell::Capture` object for further examination and the command executed; if the fail handler returns, `capture-check()` will return the `Shell::Capture` object to its caller (useful for writing tests).

  The `$enc` and `$nl` parameters, if specified, are passed directly to `run()` just as in `capture()`.

# AUTHOR

Peter Pentchev <[roam@ringlet.net](mailto:roam@ringlet.net)>

# COPYRIGHT

Copyright (C) 2016, 2017 Peter Pentchev

# LICENSE

The Shell::Capture module is distributed under the terms of the Artistic License 2.0. For more details, see the full text of the license in the file LICENSE in the source distribution.


## dist_zef-grizzlysmit-Gzz-Prompt.md
## Table of Contents

* [NAME](#name)
* [AUTHOR](#author)
* [VERSION](#version)
* [TITLE](#title)
* [SUBTITLE](#subtitle)
* [COPYRIGHT](#copyright)
* [Introduction](#introduction)
* [class Gzz\_readline](#class-gzz_readline) or [on raku.land class Gzz\_readline](#class-gzz-readline)

# NAME

Gzz::Prompt

# AUTHOR

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

# VERSION

0.1.2

# TITLE

Gzz::Prompt

# SUBTITLE

A Raku module to do basic prompting with editing and like readline but with the ability to prefill the value.

# COPYRIGHT

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

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

# Introduction

A Raku module to do basic prompting with editing and like readline but with the ability to prefill the value.

**NB: I use the NativeCall module to get at a C library `gzz_readline.so` which is a fork of the `readline` library, I had to fork it as it doesn't normally allow you to prefill the value** [See gzzReadline](https://github.com/grizzlysmit/gzzReadline).

[NOTE: you must install gzzReadline to use this](https://github.com/grizzlysmit/gzzReadline)

## class Gzz\_readline

```
class Gzz_readline is export

```

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


## dist_github-ugexe-CompUnit-Repository-Tar.md
## CompUnit::Repository::Tar

Load modules directly from a .tar.gz archive

## Synopsis

```
use CompUnit::Repository::Tar;
use lib "CompUnit::Repository::Tar#resources/test-dists/PathTools-v0.2.0.tar.gz";

require "lib/PathTools.rakumod"  # `require` by relative path
require "PathTools";             # `require` by name
use PathTools;                   # `use` by name

```

See: [tests](https://github.com/ugexe/Raku-CompUnit--Repository--Tar/blob/main/t)