## dist_zef-ugexe-zef.md
## Zef

Raku Module Management

# Installation

#### Manual

```
$ git clone https://github.com/ugexe/zef.git
$ cd zef
$ raku -I. bin/zef install .

```

#### Rakubrew

To install via rakubrew, please use the following command:

```
$ rakubrew build-zef

```

# USAGE

```
zef --help
zef --version

# install the CSV::Parser distribution
zef install CSV::Parser

# search for distribution names matching `CSV`
zef search CSV

# detailed information for a matching distribution
zef info CSV::Parser

# list all available distributions
zef list

# list reverse dependencies of an identity
zef rdepends HTTP::UserAgent

# test project in current directory
zef test .

# fetch a specific module only
zef fetch CSV::Parser

# fetch a module, then shell into its local path
zef look CSV::Parser

# smoke test modules from all repositories
zef smoke

# run Build.rakumod if one exists in given path
zef build .

# update Repository package lists
zef update

# upgrade all distributions (BETA)
zef upgrade

# upgrade specific distribution (BETA)
zef upgrade CSV::Parser

# lookup module info by name/path/sha1
zef --sha1 locate 9FA0AC28824EE9E5A9C0F99951CA870148AE378E

# launch browser to named support urls from meta data
zef browse zef bugtracker

```

## More CLI

#### **install** [\*@identities]

Note: The install process does not install anything until all phases have completed. So, if the user requested to
`install A`, and A required module B: both would be downloaded, potentially built, tested, and installed -- but only
if both passed all their tests. For example: if module A failed its tests, then module B would not be installed
(even if it passed its own tests) unless forced.

[`@identities`] can take the form of a file path (starting with **.** or **/**), URLs, paths, or identities:

```
# IDENTITY
zef install CSV::Parser
zef install "CSV::Parser:auth<tony-o>:ver<0.1.2>"
zef install "CSV::Parser:ver<0.1.2>"

# PATH
zef install ./Raku-Net--HTTP

# URL
zef -v install https://github.com/ugexe/zef.git
zef -v install https://github.com/ugexe/zef/archive/main.tar.gz
zef -v install https://github.com/ugexe/zef.git@v0.1.22

# STDIN
echo "Net::HTTP" | zef install -

```

A request may contain any number and combination of these. Paths and URLs will be resolved first so they are available
to fulfill any dependencies of other requested identities. An identity of `-` will treat each line of STDIN as an
identity.

**Options**

```
# Install to a custom locations
--install-to=<id> # site/home/vendor/perl, or
-to=<id>          # inst#/home/some/path/custom

# Install all transitive and direct dependencies
# even if they are already installed globally (BETA)
--contained

# Load a specific Zef config file
--config-path=/some/path/config.json

# Install only the dependency chains of the requested distributions
--deps-only

# Ignore errors occuring during the corresponding phase
--force-resolve
--force-fetch
--force-extract
--force-build
--force-test
--force-install

# or set the default to all unset --force-* flags to True
--force

# Set the timeout for corresponding phases
--fetch-timeout=600
--extract-timeout=3600
--build-timeout=3600
--test-timeout=3600
--install-timeout=3600

# or set the default to all unset --*-timeout flags to 0
--timeout=0

# Number of simultaneous distributions/jobs to process for the corresponding phases
--fetch-degree=5
--test-degree=1

# Disable precompilation during installation
--/precompile-install

# Do everything except the actual installations
--dry

# Build/Test/Install each dependency serially before proceeding to Build/Test/Install the next
--serial

# Disable testing
--/test

# Disable build phase
--/build

# Disable fetching dependencies
--/depends
--/build-depends
--/test-depends

# Force a refresh for all module index indexes
--update

# Force a refresh for a specific ecosystem module index
--update=[ecosystem]

# Skip refreshing all module index indexes
--/update

# Skip refreshing for a specific ecosystem module index
--/update=[ecosystem]

```

**ENV Options**

```
# Number of simultaneous distributions/jobs to process for the corresponding phases (see: --[phase]-degree options)
ZEF_FETCH_DEGREE=5
ZEF_TEST_DEGREE=1

# Set the timeout for corresponding phases (see: --[phase]-timeout options)
ZEF_FETCH_TIMEOUT=600
ZEF_EXTRACT_TIMEOUT=3600
ZEF_BUILD_TIMEOUT=3600
ZEF_TEST_TIMEOUT=3600
ZEF_INSTALL_TIMEOUT=3600

# Set default --install-to target
ZEF_INSTALL_TO=site

# Path to config file (see: --config-path option)
ZEF_CONFIG_PATH=$PWD/resources/config.json

# Override DefaultCUR from the config file
ZEF_CONFIG_DEFAULTCUR=auto

# Override StoreDir from the config file
ZEF_CONFIG_STOREDIR=/home/ugexe/.config/zef/store

# Override TempDir from the config file
ZEF_CONFIG_TEMPDIR=/home/ugexe/.config/zef/temp

```

#### **uninstall** [\*@identities]

Uninstall the specified distributions

#### **update**

Update the package indexes for all `Repository` backends

Note: Some `Repository` backends, like the default Ecosystems, have an `auto-update` option
in `resources/config.json` that can be enabled. This should be the number of hours until it should
auto update based on the file system last modified time of the ecosystem json file location.

#### **upgrade** [\*@identities] *BETA*

Upgrade specified identities. If no identities are provided, zef attempts to upgrade all installed distributions.

#### **search** [$identity]

How these are handled depends on the `Repository` engine used, which by default is `Zef::Repository::Ecosystems<fez>` and `Zef::Repository::Ecosystems<rea>`

```
$ zef -v search URI
===> Found 4 results
-------------------------------------------------------------------------
ID|From                              |Package             |Description
-------------------------------------------------------------------------
2 |Zef::Repository::Ecosystems<fez> |URI:ver<0.1.1>    |A URI impleme...
3 |Zef::Repository::Ecosystems<rea> |URI:ver<0.1.1>    |A URI impleme...
4 |Zef::Repository::Ecosystems<rea> |URI:ver<0.000.001>|A URI impleme...
------------------------------------------f-------------------------------

```

#### **info** [$identity]

View meta information of a distribution

```
$ zef info Distribution::Common::Remote -v
- Info for: Distribution::Common::Remote
- Identity: Distribution::Common::Remote:ver<0.1.0>:auth<github:ugexe>:api<0>
- Recommended By: Zef::Repository::Ecosystems<rea>
- Installed: No
Description:     Create an installable Distribution from common remote sources
License:     Artistic-2.0
Source-url:  https://raw.githubusercontent.com/raku/REA/main/archive/D/Distribution%3A%3ACommon%3A%3ARemote/Distribution%3A%3ACommon%3A%3ARemote%3Aver%3C0.1.0%3E%3Aauth%3Cgithub%3Augexe%3E.tar.gz
Provides: 2 modules
----------------------------------------------------------------------------------
Module                              |Path-Name
----------------------------------------------------------------------------------
Distribution::IO::Remote::Github    |lib/Distribution/IO/Remote/Github.rakumod
Distribution::Common::Remote::Github|lib/Distribution/Common/Remote/Github.rakumod
----------------------------------------------------------------------------------
Support:
#   bugtracker: https://github.com/ugexe/Raku-Distribution--Common--Remote/issues
#   source: https://github.com/ugexe/Raku-Distribution--Common--Remote.git
Depends: 2 items
----------------------------------
ID|Identity            |Installed?
----------------------------------
1 |Distribution::Common|✓
2 |Test                |✓
----------------------------------

```

**Options**

```
# Extra details (eg, list dependencies and which ones are installed)
-v

```

#### **list** [\*@from]

List known available distributions

```
$ zef --installed list
===> Found via /home/foo/.rakubrew/moar/install/share/perl6/site
CSV::Parser:ver<0.1.2>:auth<github:tony-o>
Zef:auth<github:ugexe>
===> Found via /home/foo/.rakubrew/moar/install/share/perl6
CORE:ver<6.c>:auth<perl>

```

Note that not every Repository may provide such a list, and such lists may only
be a subset. For example: We may not be able to get a list of every distribution
on cpan, but we \*can\* get the $x most recent additions (we use 100 for now).

[`@from`] allows you to show results from specific repositories only:

```
zef --installed list perl   # Only list modules installed by rakudo itself

zef list fez               # Only show available modules from the repository
zef list rea               # with a name field matching the arguments to `list`
zef list p6c               # (be sure the repository is enabled in config)
zef list cpan --cpan       # (or enabled via a cli flag)

```

Otherwise results from all enabled repositories will be returned.

**Options**

```
# Only list installed distributions
--installed

# Additionally list the modules of discovered distributions
-v

```

#### **depends** [$identity]

List direct and transitive dependencies to the first successful build graph for `$identity`

```
$ zef depends Cro::SSL
Cro::Core:ver<0.7>
IO::Socket::Async::SSL:ver<0.3>
OpenSSL:ver<0.1.14>:auth<github:sergot>

```

#### **rdepends** [$identity]

List available distributions that directly depend on `$identity`

```
$ zef rdepends Net::HTTP
Minecraft-Tools:ver<0.1.0>
LendingClub:ver<0.1.0>

```

#### **fetch** [\*@identities]

Fetches candidates for given identities

#### **test** [\*@paths]

Run tests on each distribution located at [`@paths`]

#### **build** [\*@paths]

Run the build step for each distribution located in the given [`@paths`]

Set the env variable **ZEF\_BUILDPM\_DEBUG=1** or use the *--debug* flag for additional debugging information.

If you want to create a build hook you have two options:

* **PREFERRED** List a builder module that can do what you need in the `builder` field of the META6.json file. For instace many cases of the I-need-to-run-make pattern can list `"builder":"Distribution::Builder::MakeFromJSON"` and supply some extra info to the `"build"` field (a non-standard `Distribution::Builder::MakeFromJSON` specific field). For a more concrete example check out how `Inline::Perl5` [uses the builder field](https://github.com/niner/Inline-Perl5/blob/2e7b99fb03d182d15df4f88818d835b151117786/META6.json#L58-L68). Remember to add any such module to your `build-depends` though! See `Zef::Service::Shell::DistributionBuilder` for more information.
* **DEPRECATED** (*but probably never going away*) Put the following dependency-free boilerplate in a file named `Build.rakumod` at the root of your distribution:

  ```
  class Build {
      method build($dist-path) {
          # do build stuff to your module
          # which is located at $dist-path
      }
  }

  ```

#### **look** [$identity]

Fetches the requested distribution and any dependencies (if requested), changes the directory to that of the fetched
distribution, and then stops program execution. This allows you modify or look at the source code before manually
continuing the install via `zef install .`

Note that the path to any dependencies that needed to be fetched will be set in env at **RAKULIB**, so you should
be able to run any build scripts, tests, or complete a manual install without having to specify their locations.

#### **browse** $identity [bugtracker | homepage | source]

**Options**

```
# disables launching a browser window (just shows url)
--/open

```

Output the url and launch a browser to open it.

```
# also opens browser
$ zef browse Net::HTTP bugtracker
https://github.com/ugexe/Raku-Net--HTTP/issues

# only outputs the url
$ zef browse Net::HTTP bugtracker --/open
https://github.com/ugexe/Raku-Net--HTTP/issues

```

#### **locate** [$identity, $name-path, $sha1-id]

**Options**

```
# The argument is a sha1-id (otherwise assumed to be an identity or name-path)
--sha1

```

Lookup a locally installed module by $identity, $name-path, or $sha1-id

```
$ zef --sha1 locate A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
lib/Zef/CLI.rakumod => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

$ zef locate Zef::CLI
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
lib/Zef/CLI.rakumod => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

$ zef locate lib/Zef/CLI.rakumod
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
Zef::CLI => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

```

#### **nuke** [StoreDir | TempDir]

Deletes all paths in the specific configuration directory

#### **nuke** [site | home]

Deletes all paths that are rooted in the prefix of the matching CompUnit::Repository name

```
# uninstall all modules
$ zef nuke site home

```

## Output Verbosity

You can control the logging level using the following flags:

```
# More/less detailed output
--error, --warn, --info (default), --verbose (-v), --debug

```

# Global Configuration

### Finding the configuration file

You can always see the configuration file that will be used by running:

```
$ zef --help

```

In most cases the default configuration combined with command line options should be enough for most users.

If you are most users (e.g. not: power users, packagers, zef plugin developers) you hopefully don't care about this section!

### How the configuration file is chosen

The configuration file will be chosen at runtime from one of two (technically four) locations.

First, and the most precise way, is to specify the config file by passing `--config-path="..."` to any zef command.

Second, third, and fourth we look at the path pointed to by `%?RESOURCES<config.json>`. This will point to `$zef-dir/resources/config.json`, where `$zef-dir` will be either:

* The prefix of a common configuration directory, such as `$XDG_CONFIG_HOME` or `$HOME/.config`.
* The prefix of a rakudo installation location - This is the case if the modules loaded for bin/zef come from an installation CompUnit::Repository.
* The current working directory `$*CWD` - This is the case when modules loaded for bin/zef come from a non-installation CompUnit::Repository (such as `-I $dist-path`).

  To understand how this is chosen, consider:

  ```
    # Modules not loaded from an ::Installation,
    # so %?RESOURCES is $*CWD/resources
    $ raku -I. bin/zef --help
    ...
    CONFIGURATION /home/user/raku/zef/resources/config.json
    ...

    # Installed zef script loads modules from an ::Installation,
    # so %?RESOURCES is $raku-share-dir/site/resources
    $ zef --help
    ...
    CONFIGURATION /home/user/raku/install/share/perl6/site/resources/EE5DBAABF07682ECBE72BEE98E6B95E5D08675DE.json
    ...

  ```

To summarize:

* You can edit the `resources/config.json` file before you install zef.

  When you `raku -I. bin/zef install .` that configuration file be be used to install zef and will also be installed with zef such that it will be the default.
* You can create a `$*HOME/.config/zef/config.json` file.

  To allow overriding zef config behavior on a per user basis (allows setting different `--install-to` targets for, say, a root user and a regular user). Alternative one can set the `XDG_CONFIG_HOME` env variable to instead look
  in `$XDG_CONFIG_HOME/zef/config.json`.
* You can override both of the previous entries by passing `zef --config-path="$path" <any command>`

### Configuration fields

#### Basic Settings

* **TempDir** - A staging area for items that have been fetched and need to be extracted/moved
* **StoreDir** - Where zef caches distributions, package lists, etc after they've been fetched and extracted
* **DefaultCUR** - This sets the default value for `--install-to="..."`. The default value of `auto` means it will first try installing to rakudo's installation prefix, and if its not writable by the current user it will install to `$*HOME/.raku`. These directories are not chosen by zef - they are actually represented by the magic strings `site` and `home` (which, like `auto`, are valid values despite not being paths along with `vendor` and `perl`)

#### Phases / Plugins Settings

These consist of an array of hashes that describe how to instantiate some class that fulfills the appropriate interface from *Zef.rakumod* (`Repository` `Fetcher` `Extractor` `Builder` `Tester` `Reporter`)

The descriptions follow this format:

```
{
    "short-name" : "fez",
    "enabled" : 1,
    "module" : "Zef::Repository::Ecosystems",
    "options" : { }
}

```

and are instantiated via

```
::($hash<module>).new(|($hash<options>)

```

* **short-name** - This adds an enable and disable flag by the same name to the CLI (e.g. `--fez` and `--/fez`) and is used when referencing which object took some action.
* **enabled** - Set to 0 to skip over the object during consideration (it will never be loaded). If omitted or if the value is non 0 then it will be enabled for use.
* **module** - The name of the class to instantiate. While it doesn't technically have to be a module it *does* need to be a known namespace to `require`.
* **options** - These are passed to the objects `new` method and may not be consistent between modules as they are free to implement their own requirements.

See the configuration file in [resources/config.json](https://github.com/ugexe/zef/blob/main/resources/config.json) for a
little more information on how plugins are invoked.

You can see debug output related to chosing and loading plugins by setting the env variable **ZEF\_PLUGIN\_DEBUG=1**

# FAQ

### Proxy support?

All the default fetching plugins have proxy support, but you'll need to refer to the backend program's
(wget, curl, git, etc) docs. You may need to set an *ENV* variable, or you may need to add a command line
option for that specific plugin in *resources/config.json*

### Custom installation locations?

Pass a path to the *-to* / *--install-to* option and prefix the path with `inst#` (unless you know what you're doing)

```
$ zef -to="inst#/home/raku/custom" install Text::Table::Simple
===> Searching for: Text::Table::Simple
===> Testing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
===> Testing [OK] for Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
===> Installing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>

```

To make the custom location discoverable:

```
# Set the RAKULIB env:
$ RAKULIB="inst#/home/raku/custom" raku -e "use Text::Table::Simple; say 'ok'"
ok

# or simply include it as needed
$ raku -Iinst#/home/raku/custom -e "use Text::Table::Simple; say 'ok'"
ok

```


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

# NAME

AccountableBagHash - be an accountable BagHash / MixHash

# SYNOPSIS

```
use AccountableBagHash;

my %abh is AccountableBagHash = a => 42, b => 666;
%abh<a> =  5; # ok
%abh<a> = -1; # throws

my %amh is AccountableMixHash = a => 3.14, b => 666;
%amh<a> =  6.28; # ok
%amh<a> = -1;    # throws

CATCH {
    when X::BagHash::Acountable {
        say "You do not have enough {.key}";
        .resume
    }
}

```

# DESCRIPTION

This module makes an `AccountableBagHash` / `AccountableMixHash` class available that can be used instead of the normal `BagHash` / `MixHash`. The only difference with a normal `BagHash` / `MixHash` is, is that if an attempt is made to set the value of a key to **less than 0**, that an exception is thrown rather than just deleting the key from the `BagHash` / `MixHash`.

Also exports a `X::BagHash::Accountable` error class that will be thrown if an attempt is made to set the value to below 0.

# AUTHOR

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

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

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

# COPYRIGHT AND LICENSE

Copyright 2018, 2020, 2021, 2022, 2025 Elizabeth Mattijsen

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


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

# NAME

silently - prevent any output from a block

# SYNOPSIS

```
use silently;

```

# DESCRIPTION

silently is module that exports a single sub called `silently` that takes a block to execute. Inside that block, all textual output to `$*OUT` and `$*ERR` is prevented from actually being sent to STDOUT and STDERR.

Note that if you're only interested in surpressing output from warnings, you should use the `quietly` statement prefix.

# SUBROUTINES

## silently

```
silently { say "hello world" }  # no output

my $captured = silently { note "tis wrong" }
if $captured.err -> $error {
  say "something went wrong: $error";
}

```

The `silently` subroutine takes a block as a parameter, and runs that block catching all output to `$*OUT` and `$*ERR`.

If the output is actually needed for inspection: the subroutine returns an object that provides two methods: `out` and `err`, giving the captured output to `$*OUT` and `$*ERR` respectively.

# AUTHOR

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

Source can be located at: <https://github.com/lizmat/silently> . 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 2020, 2021, 2022, 2025 Elizabeth Mattijsen

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


## dist_cpan-SCIMON-Timer-Breakable.md
[![Build Status](https://travis-ci.org/Scimon/Timer-Breakable.svg?branch=master)](https://travis-ci.org/Scimon/Timer-Breakable)

# NAME

Timer::Breakable - Timed block calls that can be broken externally.

# SYNOPSIS

```
use Timer::Breakable;

my $timer = Timer::Breakable.start( 10, { say "Times up" } );
... Stuff occurs ...
$timer.stop if $variable-from-stuff;

say $timer.result if $timer.status ~~ Kept;

```

# DESCRIPTION

Timer::Breakable is wrapper aroud the standard Promise.in() functionality that lets you stop the timer without running it's block.

## PUBLIC ATTRIBUTES

### promise

A vowed promise that can be handed to await, anyof or allof. Note that the promises status and results can be accessed from the Timer::Breakable object directly.

## PUBLIC METHODS

### start( $time where \* > 0, &block )

Factory method to start the timer. Expects the time to run and the block to run on completion.

### stop()

Stops the timer. Note that the timer itself will still run to completion but the given block will not be run.

### status()

As per Promise.status()

### result()

As per Promise.result()

# NOTES

Version 0.1.0 updated the object creation to use start as a factory method.

# AUTHOR

Simon Proctor [simon.proctor@gmail.com](mailto:simon.proctor@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2017 Simon Proctor

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


## dist_github-zengargoyle-Algorithm-Trie-libdatrie.md
[![Build Status](https://travis-ci.org/zengargoyle/p6-Algorithm-Trie-libdatrie.svg?branch=master)](https://travis-ci.org/zengargoyle/p6-Algorithm-Trie-libdatrie)

# NAME

Algorithm::Trie::libdatrie - a character keyed trie using the datrie library.

# SYNOPSIS

```
use Algorithm::Trie::libdatrie;

my Trie $t .= new: 'a'..'z', 'A'..'Z';
my @words = <pool prize preview prepare produce progress>;
for @words.kv -> $data, $word {
  $t.store( $word, $data );
}
$data = $t.retrieve($word);
my $iter = $t.iterator;
while $iter.next {
  $key = $iter.key;
  $data = $iter.value;
}

```

# WARNING

More documentation and maybe a few more features and tests are planned. For now the tests are probably the best documentation.

# DESCRIPTION

Algorithm::Trie::libdatrie is an implementation of a character keyed [trie](http://en.wikipedia.org/wiki/Trie) using the [datrie](http://linux.thai.net/~thep/datrie/datrie.html) library.

As the author of the datrie library states:

Trie is a kind of digital search tree, an efficient indexing method with O(1) time complexity for searching. Comparably as efficient as hashing, trie also provides flexibility on incremental matching and key spelling manipulation. This makes it ideal for lexical analyzers, as well as spelling dictionaries. This library is an implementation of double-array structure for representing trie, as proposed by Junichi Aoe. The details of the implementation can be found at <http://linux.thai.net/~thep/datrie/datrie.html>

# Classes and Methods

## Trie

```
multi method new(**@ranges) returns Trie
multi method new(Str $file) returns Trie
method save(Str $file) returns Bool
method is-dirty() returns Bool
method store(Str $key, Int $data) returns Bool
method store-if-absent(Str $key, Int $data) returns Bool
method retrieve(Str $key) returns Int
method delete(Str $key) returns Bool
method root() returns TrieState
method iterator() returns TrieIterator
method free()
/* NYI
sub enum_func(Str $key, Int $value, Pointer[void] $stash) returns Bool { * }
method enumerate(&enum_func, Pointer[void] $stash) returns Bool
*/

```

* new

  my Trie $t .= new: 'a'..'z', 'A'..'Z', '0'..'9';

The set of characters used in `key`s has a maximum size of 255. The characters themselves may be any unicode character who's code will fit in a 32 bit uint. The `new` function will map the input ranges into `0..254` internally.

```
my Trie $t .= new: $file;

```

A Trie may be loaded from a $file created by the `save` method.

* root, iterator

These methods return objects of class `TrieState` and `TrieIterator` that are positioned at the root of the Trie.

* the rest

Should be mostly self-explanatory. See the tests.

## TrieState

A TrieState object is used to walk through the Trie character by character. A TrieState object may also be used to create a TrieIterator in order to iterate over the nodes beneath the TrieStat's current position.

```
method clone() returns TrieState
method rewind()
method walk(Str $c where *.chars == 1) returns Bool
method is-walkable(Str $c where *.chars == 1) returns Bool
method walkable-chars() returns Array[Str]
method is-terminal() returns Bool
method is-single() returns Bool
method is-leaf() returns Bool
method value() returns Int
method free()

```

## TrieIterator

A TrieIterator can be created from the Trie directly via `$trie.iterator` or from a TrieState via `TrieIterator.new($trie-state)`.

```
method new(TrieState $state) returns TrieIterator
method next() returns Bool
method key() returns Str
method value() returns Int
method free()

```

# SEE ALSO

The datrie library: <http://linux.thai.net/~thep/datrie/datrie.html>

Wikipedia entry for: [Trie](http://en.wikipedia.org/wiki/Trie)

# AUTHOR

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

# COPYRIGHT AND LICENSE

Copyright 2015 zengargoyle

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


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

# NAME

Raku port of Perl's List::SomeUtils module 0.56

# SYNOPSIS

```
# import specific functions
use List::SomeUtils <any uniq>;

if any { /foo/ }, uniq @has_duplicates {
    # do stuff
}

# import everything
use List::SomeUtils ':all';

```

# DESCRIPTION

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

List::SomeUtils is a functional copy of List::MoreUtils. As for the reasons of its existence, please check the documentation of the Perl version.

# AUTHOR

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

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

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021 Elizabeth Mattijsen

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


## comment.md
class Pod::Block::Comment

Comment in a Pod document

```raku
class Pod::Block::Comment is Pod::Block { }
```

Class for a Pod comment.


## unix.md
class IO::Spec::Unix

Platform specific operations on file and directory paths for POSIX

```raku
class IO::Spec::Unix is IO::Spec  { }
```

An object of this type is available via the variable `$*SPEC` if the Raku interpreter is running on a Unix-like platform.

About this class and its related classes also see [`IO::Spec`](/type/IO/Spec).

# [Methods](#class_IO::Spec::Unix "go to top of document")[§](#Methods "direct link")

## [method abs2rel](#class_IO::Spec::Unix "go to top of document")[§](#method_abs2rel "direct link")

```raku
method abs2rel(IO::Path:D $path, IO::Path:D $base = $*CWD --> Str:D)
```

Returns a string that represents `$path`, but relative to `$base` path. Both `$path` and `$base` may be relative paths. `$base` defaults to `$*CWD`.

## [method basename](#class_IO::Spec::Unix "go to top of document")[§](#method_basename "direct link")

```raku
method basename(Str:D $path --> Str:D)
```

Takes a path as a string and returns a possibly-empty portion after the last slash:

```raku
IO::Spec::Unix.basename("foo/bar/") .raku.say; # OUTPUT: «""␤»
IO::Spec::Unix.basename("foo/bar/.").raku.say; # OUTPUT: «"."␤»
IO::Spec::Unix.basename("foo/bar")  .raku.say; # OUTPUT: «"bar"␤»
```

## [method canonpath](#class_IO::Spec::Unix "go to top of document")[§](#method_canonpath "direct link")

```raku
method canonpath(Str() $path, :$parent --> Str:D)
```

Returns a string that is a canonical representation of `$path`. If `:$parent` is set to true, will also clean up references to parent directories. **NOTE:** the routine does not access the filesystem, so no symlinks are followed.

```raku
IO::Spec::Unix.canonpath("foo//../bar/../ber").say;
# OUTPUT: «foo/../bar/../ber␤»

IO::Spec::Unix.canonpath("foo///./../bar/../ber").say;
# OUTPUT: «foo/../bar/../ber␤»

IO::Spec::Unix.canonpath("foo///./../bar/../ber", :parent).say;
# OUTPUT: «ber␤»
```

## [method catdir](#class_IO::Spec::Unix "go to top of document")[§](#method_catdir "direct link")

```raku
method catdir (*@parts --> Str:D)
```

Concatenates multiple path fragments and returns the canonical representation of the resultant path as a string. The `@parts` are [`Str`](/type/Str) objects and are allowed to contain path separators.

```raku
IO::Spec::Unix.catdir(<foo/bar ber raku>).say; # OUTPUT: «foo/bar/ber/raku␤»
```

## [method catfile](#class_IO::Spec::Unix "go to top of document")[§](#method_catfile "direct link")

Alias for [`catdir`](/routine/catdir).

## [method catpath](#class_IO::Spec::Unix "go to top of document")[§](#method_catpath "direct link")

```raku
method catpath ($, Str:D $part1, Str:D $part2 --> Str:D)
```

Takes two path fragments and concatenates them, adding or removing a path separator, if necessary. The first argument is ignored (it exists to maintain consistent interface with other [`IO::Spec`](/type/IO/Spec) types for systems that have volumes).

```raku
IO::Spec::Unix.catpath($, 'some/dir', 'and/more').say;
# OUTPUT: «some/dir/and/more␤»
```

## [method curdir](#class_IO::Spec::Unix "go to top of document")[§](#method_curdir "direct link")

```raku
method curdir()
```

Returns a string representing the current directory:

```raku
say '.' eq $*SPEC.curdir; # OUTPUT: «True␤»
```

## [method curupdir](#class_IO::Spec::Unix "go to top of document")[§](#method_curupdir "direct link")

```raku
method curupdir()
```

Returns a [`Block`](/type/Block) taking an argument. This block returns `True` if its argument is neither the string representing the current directory nor the string representing the directory one up from the current one. It returns `False` otherwise. This block is intended to be used with [smartmatching](/language/operators#infix_~~).

```raku
say $*SPEC.curupdir;
# OUTPUT: «-> str $dir { #`(Block|65335808) ... }␤»

my @dirs = <. foo .. bar>;
say @dirs.grep: { $_ ~~ $*SPEC.curupdir };
# OUTPUT: «(foo bar)␤»

```

Neither `foo` nor `bar` are equal to the representation of the current or parent directory, that is why they are returned by `grep`.

**Note**: Before Rakudo version 2020.06 a [`none`](/routine/none) [`Junction`](/type/Junction) was returned instead of a [`Block`](/type/Block).

## [method devnull](#class_IO::Spec::Unix "go to top of document")[§](#method_devnull "direct link")

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

Returns the string `"/dev/null"` representing the ["Null device"](https://en.wikipedia.org/wiki/Null_device):

```raku
$*SPEC.devnull.IO.spurt: "foo bar baz";

```

## [method dir-sep](#class_IO::Spec::Unix "go to top of document")[§](#method_dir-sep "direct link")

```raku
method dir-sep(--> Str:D)
```

Returns the string `"/"` representing canonical directory separator character.

```raku
IO::Spec::Unix.dir-sep.say; # OUTPUT: «/␤»

```

## [method extension](#class_IO::Spec::Unix "go to top of document")[§](#method_extension "direct link")

**NOTE:** Most users would want to use the higher-level routine [`IO::Path.extension`](/type/IO/Path#method_extension) instead of this lower-level version.

```raku
method extension(Str:D $path --> Str:D)
```

Takes a string representing a base name and returns the characters after the last dot (`"."`), or empty string if no dots are present. The routine makes no attempt to detect path separators and will return everything after the last dot.

```raku
$*SPEC.extension('foo.'      ).raku.say;  # OUTPUT: «""␤»
$*SPEC.extension('foo.txt'   ).raku.say;  # OUTPUT: «"txt"␤»
$*SPEC.extension('foo.tar.gz').raku.say;  # OUTPUT: «"gz"␤»
$*SPEC.extension('foo'       ).raku.say;  # OUTPUT: «""␤»
$*SPEC.extension('bar.foo/foo').raku.say; # OUTPUT: «"foo/foo"␤»
```

## [method is-absolute](#class_IO::Spec::Unix "go to top of document")[§](#method_is-absolute "direct link")

```raku
method is-absolute(Str:D $path --> Bool:D)
```

Returns `True` if the `$path` starts with a slash (`"/"`), even if it has combining character on it:

```raku
say IO::Spec::Unix.is-absolute: "/foo";        # OUTPUT: «True␤»
say IO::Spec::Unix.is-absolute: "/\x[308]foo"; # OUTPUT: «True␤»
say IO::Spec::Unix.is-absolute: "bar";         # OUTPUT: «False␤»
```

## [method join](#class_IO::Spec::Unix "go to top of document")[§](#method_join "direct link")

```raku
method join ($, Str:D $dir, Str:D $file --> Str:D)
```

Similar to [`catpath`](/routine/catpath), takes two path fragments and concatenates them, adding or removing a path separator, if necessary, except it will return just `$file` if both `$dir` and `$file` are string `'/'` or if `$dir` is the string `'.'`. The first argument is ignored (it exists to maintain consistent interface with other [`IO::Spec`](/type/IO/Spec) types for systems that have volumes).

```raku
IO::Spec::Unix.join($, 'foo', 'bar').say; # OUTPUT: «foo/bar␤»
IO::Spec::Unix.join($, '/', '/').say;     # OUTPUT: «/␤»
IO::Spec::Unix.join($, '.', 'foo').say;   # OUTPUT: «foo␤»
say $*SPEC.join(True,".","/foo");         # OUTPUT: «/foo␤»
```

## [method path](#class_IO::Spec::Unix "go to top of document")[§](#method_path "direct link")

```raku
method path(--> Seq:D)
```

Splits the value of `%*ENV<PATH>` on colons (`":"`), replaces empty parts with `"."`, and returns a [`Seq`](/type/Seq) with each of the resultant parts. Returns an empty [`Seq`](/type/Seq) if `%*ENV<PATH>` is not set or is an empty string.

```raku
%*ENV<PATH> = 'foo:bar/ber::foo:';
IO::Spec::Unix.path.raku.say;
# OUTPUT: «("foo", "bar/ber", ".", "foo", ".").Seq␤»
```

## [method rel2abs](#class_IO::Spec::Unix "go to top of document")[§](#method_rel2abs "direct link")

```raku
method rel2abs(Str() $path, $base = $*CWD --> Str:D)
```

Returns a string representing `$path` converted to absolute path, based at `$base`, which defaults to `$*CWD`. If `$base` is not an absolute path, it will be made absolute relative to `$*CWD`, unless `$*CWD` and `$base` are the same.

```raku
say $*CWD;                                  # OUTPUT: «"/home/camelia".IO␤»

say IO::Spec::Unix.rel2abs: 'foo';          # OUTPUT: «/home/camelia/foo␤»
say IO::Spec::Unix.rel2abs: './';           # OUTPUT: «/home/camelia␤»
say IO::Spec::Unix.rel2abs: 'foo/../../';   # OUTPUT: «/home/camelia/foo/../..␤»
say IO::Spec::Unix.rel2abs: '/foo/';        # OUTPUT: «/foo␤»

say IO::Spec::Unix.rel2abs: 'foo', 'bar';   # OUTPUT: «/home/camelia/bar/foo␤»
say IO::Spec::Unix.rel2abs: './', '/bar';   # OUTPUT: «/bar␤»
say IO::Spec::Unix.rel2abs: '/foo/', 'bar'; # OUTPUT: «/foo␤»

say IO::Spec::Unix.rel2abs: 'foo/../../', 'bar';
# OUTPUT: «/home/camelia/bar/foo/../..␤»

```

## [method rootdir](#class_IO::Spec::Unix "go to top of document")[§](#method_rootdir "direct link")

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

Returns string `'/'`, representing root directory.

## [method split](#class_IO::Spec::Unix "go to top of document")[§](#method_split "direct link")

```raku
method split(IO::Spec::Unix: Cool:D $path)
```

Creates an [`IO::Path::Parts`](/type/IO/Path/Parts) for `$path`, with an empty string as its `volume` attribute's value.

```raku
IO::Spec::Unix.split('C:/foo/bar.txt').raku.say;
# OUTPUT: «IO::Path::Parts.new("","C:/foo","bar.txt")␤»

IO::Spec::Unix.split('/foo/').raku.say;
# OUTPUT: «IO::Path::Parts.new("","/","foo")␤»

IO::Spec::Unix.split('///').raku.say;
# OUTPUT: «IO::Path::Parts.new("","/","/")␤»

IO::Spec::Unix.split('./').raku.say;
# OUTPUT: «IO::Path::Parts.new("",".",".")␤»

IO::Spec::Unix.split('.').raku.say;
# OUTPUT: «IO::Path::Parts.new("",".",".")␤»

IO::Spec::Unix.split('').raku.say;
# OUTPUT: «IO::Path::Parts.new("","","")␤»

```

**Note**: Before Rakudo version 2020.06 this method split the given `$path` into "volume", "dirname", and "basename" and returned the result as a [`List`](/type/List) of three [`Pair`](/type/Pair)s, in that order.

## [method splitdir](#class_IO::Spec::Unix "go to top of document")[§](#method_splitdir "direct link")

```raku
method splitdir(Cool:D $path --> List:D)
```

Splits the given `$path` on slashes.

```raku
IO::Spec::Unix.splitdir('C:\foo/bar.txt').raku.say;
# OUTPUT: «("C:\\foo", "bar.txt")␤»

IO::Spec::Unix.splitdir('/foo/').raku.say;
# OUTPUT: «("", "foo", "")␤»

IO::Spec::Unix.splitdir('///').raku.say;
# OUTPUT: «("", "", "", "")␤»

IO::Spec::Unix.splitdir('./').raku.say;
# OUTPUT: «(".", "")␤»

IO::Spec::Unix.splitdir('.').raku.say;
# OUTPUT: «(".",)␤»

IO::Spec::Unix.splitdir('').raku.say;
# OUTPUT: «("",)␤»

```

## [method splitpath](#class_IO::Spec::Unix "go to top of document")[§](#method_splitpath "direct link")

```raku
method splitpath(Cool:D $path, :$nofile --> List:D)
```

Splits the given `$path` into a list of 3 strings: volume, dirname, and file. The volume is always an empty string, returned for API compatibility with other [`IO::Spec`](/type/IO/Spec) types. If `:$nofile` named argument is set to `True`, the content of the file string is undefined and should be ignored; this is a means to get a performance boost, as implementations may use faster code path when file is not needed.

```raku
IO::Spec::Unix.splitpath('C:\foo/bar.txt').raku.say;
# OUTPUT: «("", "C:\\foo/", "bar.txt")␤»

IO::Spec::Unix.splitpath('C:\foo/bar.txt', :nofile).raku.say;
# OUTPUT: «("", "C:\\foo/bar.txt", "")␤»

IO::Spec::Unix.splitpath('/foo/').raku.say;
# OUTPUT: «("", "/foo/", "")␤»

IO::Spec::Unix.splitpath('/foo/', :nofile).raku.say;
# OUTPUT: «("", "/foo/", "")␤»

IO::Spec::Unix.splitpath('///').raku.say;
# OUTPUT: «("", "///", "")␤»

IO::Spec::Unix.splitpath('./').raku.say;
# OUTPUT: «("", "./", "")␤»

IO::Spec::Unix.splitpath('.').raku.say;
# OUTPUT: «("", "", ".")␤»

IO::Spec::Unix.splitpath('').raku.say;
# OUTPUT: «("", "", "")␤»

```

## [method tmpdir](#class_IO::Spec::Unix "go to top of document")[§](#method_tmpdir "direct link")

```raku
method tmpdir(--> IO::Path:D)
```

Attempts to locate a system's temporary directory by checking several typical directories and environment variables. Uses current directory if no suitable directories are found.

## [method updir](#class_IO::Spec::Unix "go to top of document")[§](#method_updir "direct link")

```raku
method updir()
```

Returns a string representing the directory one up from current:

```raku
say '..' eq $*SPEC.updir; # OUTPUT: «True␤»
```


## dist_zef-kuerbis-Term-Choose.md
# NAME

Term::Choose - Choose items from a list interactively.

# SYNOPSIS

```
use Term::Choose :choose;

my @list = <one two three four five>;

# Functional interface:

my $chosen = choose( @list, :2layout );

# OO interface:

my $tc = Term::Choose.new( :1mouse, :0order );

$chosen = $tc.choose( @list, :1layout, :2default );

```

# DESCRIPTION

Choose interactively from a list of items.

For `choose`, `choose-multi` and `pause` the first argument holds the list of the available choices.

The different options can be passed as key-values pairs. See [OPTIONS](#OPTIONS) to find the available options.

The return values are described in [Routines](#Routines)

# USAGE

To browse through the available list-elements use the keys described below.

If the items of the list don't fit on the screen, the user can scroll to the next (previous) page(s).

If the window size is changed, the screen is rewritten as soon as a key is pressed.

How to choose the items is described in [ROUTINES](#ROUTINES).

## Keys

* the Arrow keys (or h,j,k,l) to move up and down or to move to the right and to the left,
* the Tab key (or Ctrl-I) to move forward, the BackSpace key (or Ctrl-H) to move backward,
* the PageUp key (or Ctrl-P) to go to the previous page, the PageDown key (or Ctrl-N) to go to the next page,
* the Insert key to go back 10 pages, the Delete key to go forward 10 pages,
* the Home key (or Ctrl-A) to jump to the beginning of the list, the End key (or Ctrl-E) to jump to the end of the list.

For the usage of SpaceBar, Ctrl-SpaceBar, Return and the q-key see [choose](#choose), [choose-multi](#choose-multi) and [pause](#pause).

With *mouse* enabled use the the left mouse key instead the Return key and the right mouse key instead of the SpaceBar key. Instead of PageUp and PageDown it can be used the mouse wheel. See [mouse](#mouse)

Pressing the Ctrl-F allows one to enter a regular expression so that only the items that match the regular expression are displayed. When going back to the unfiltered menu (Return) the item highlighted in the filtered menu keeps the highlighting. Also (in *list context*) marked items retain there markings. The Raku function `prompt` is used to read the regular expression if <Readline> is not available. See option [search](#search).

# CONSTRUCTOR

The constructor method `new` can be called with named arguments. For the valid options see [OPTIONS](#OPTIONS). Setting the options in `new` overwrites the default values for the instance.

# ROUTINES

## choose

`choose` allows the user to choose one item from a list: the highlighted item is returned when Return is pressed.

`choose` returns nothing if the q or Ctrl-Q is pressed.

## choose-multi

The user can choose many items.

To choose an item mark the item with the SpaceBar. When Return is pressed `choose-multi` then returns the marked items as an Array. If the option *include-highlighted* is set to `1`, the highlighted item is also returned.

If Return is pressed with no marked items and [include-highlighted](#include-highlighted) is set to `2`, the highlighted item is returned.

Ctrl-SpaceBar (or Ctrl-@) inverts the choices: marked items are unmarked and unmarked items are marked.

`choose-multi` returns nothing if the q or Ctrl-Q is pressed.

## pause

Nothing can be chosen, nothing is returned but the user can move around and read the output until closed with Return, q or Ctrl-Q.

# OUTPUT

For the output on the screen the elements of the list are copied and then modified. Chosen elements are returned as they were passed without modifications.

Modifications:

* If an element is not defined the value from the option *undef* is assigned to the element.
* If an element holds an empty string the value from the option *empty* is assigned to the element.
* Tab characters in elements are replaces with a space.

  $element =~ s/\t/ /g;
* Vertical spaces in elements are squashed to two spaces.

  $element =~ s/\v+/\ \ /g;
* Code points from the ranges of control, surrogate and noncharacter are removed.

  $element =~ s/[\p{Cc}\p{Noncharacter\_Code\_Point}\p{Cs}]//g;
* If the length (print columns) of an element is greater than the width of the screen the element is cut and three dots are attached.

# OPTIONS

Options which expect a number as their value expect integers.

### alignment

0 - elements ordered in columns are aligned to the left (default)

1 - elements ordered in columns are aligned to the right

2 - elements ordered in columns are centered

### beep

0 - off (default)

1 - on

### clear-screen

0 - off

1 - clears the screen before printing the choices (default)

### color

If enabled, SRG ANSI escape sequences can be used to color the screen output.

0 - off (default)

1 - on (current selected element not colored)

2 - on (current selected element colored)

### default

With the option *default* it can be selected an element, which will be highlighted as the default instead of the first element.

*default* expects a zero indexed value, so e.g. to highlight the third element the value would be *2*.

If the passed value is greater than the index of the last array element, the first element is highlighted.

Allowed values: 0 or greater

(default: 0)

### empty

Sets the string displayed on the screen instead of an empty string.

(default: "")

### footer

Add a string in the bottom line.

If a footer string is passed with this option, the option page is automatically set to `2`.

(default: undefined)

### hide-cursor

0 - keep the terminals highlighting of the cursor position

1 - hide the terminals highlighting of the cursor position (default)

### index

0 - off (default)

1 - return the indices of the chosen elements instead of the chosen elements.

This option has no meaning for `pause`.

### info

Expects as its value a string. The string is printed above the prompt string.

### keep

*keep* prevents that all the terminal rows are used by the prompt lines.

Setting *keep* ensures that at least *keep* terminal rows are available for printing "list"-rows.

If the terminal height is less than *keep*, *keep* is set to the terminal height.

Allowed values: 1 or greater

(default: 5)

### layout

From broad to narrow: 0 > 1 > 2

* 0 - layout off

  ```
  .-------------------.   .-------------------.   .-------------------.   .-------------------.
  | .. .. .. .. .. .. |   | .. .. .. .. .. .. |   | .. .. .. .. .. .. |   | .. .. .. .. .. .. |
  |                   |   | .. .. .. .. .. .. |   | .. .. .. .. .. .. |   | .. .. .. .. .. .. |
  |                   |   |                   |   | .. .. .. ..       |   | .. .. .. .. .. .. |
  |                   |   |                   |   |                   |   | .. .. .. .. .. .. |
  |                   |   |                   |   |                   |   | .. .. .. .. .. .. |
  |                   |   |                   |   |                   |   | .. .. .. .. .. .. |
  '-------------------'   '--- ---------------'   '-------------------'   '-------------------'

  ```
* 1 - (default)

  ```
  .-------------------.   .-------------------.   .-------------------.   .-------------------.
  | .. .. .. .. .. .. |   | .. .. .. ..       |   | .. .. .. .. ..    |   | .. .. .. .. .. .. |
  |                   |   | .. .. .. ..       |   | .. .. .. .. ..    |   | .. .. .. .. .. .. |
  |                   |   | .. ..             |   | .. .. .. .. ..    |   | .. .. .. .. .. .. |
  |                   |   |                   |   | .. .. .. .. ..    |   | .. .. .. .. .. .. |
  |                   |   |                   |   | .. .. ..          |   | .. .. .. .. .. .. |
  |                   |   |                   |   |                   |   | .. .. .. .. .. .. |
  '-------------------'   '-------------------'   '-------------------'   '-------------------'

  ```
* 2 - all in a single column

  ```
  .-------------------.   .-------------------.   .-------------------.   .-------------------.
  | ..                |   | ..                |   | ..                |   | ..                |
  | ..                |   | ..                |   | ..                |   | ..                |
  | ..                |   | ..                |   | ..                |   | ..                |
  |                   |   | ..                |   | ..                |   | ..                |
  |                   |   |                   |   | ..                |   | ..                |
  |                   |   |                   |   |                   |   | ..                |
  '-------------------'   '-------------------'   '-------------------'   '-------------------'

  ```

### margin

The option *margin* allows one to set a margin on all four sides.

*margin* expects a list of four elements in the following order:

* top margin (number of terminal lines)
* right margin (number of terminal columns)
* botton margin (number of terminal lines)
* left margin (number of terminal columns)

See also [tabs-info](#tabs-info) and [tabs-prompt](#tabs-prompt).

Allowed values: 0 or greater. Elements beyond the fourth are ignored.

(default: undefined)

### max-cols

Limit the number of item columns to *max-cols*.

Allowed values: 1 or greater

(default: undefined)

### max-height

If defined sets the maximal number of rows used for printing list items.

If the available height is less than *max-height*, *max-height* is set to the available height.

Height in this context means number of print rows.

*max-height* overwrites *keep* if *max-height* is set to a value less than *keep*.

Allowed values: 1 or greater

(default: undefined)

### max-width

If defined, sets the maximal output width to *max-width* if the terminal width is greater than *max-width*.

To prevent the "auto-format" to use a width less than *max-width* set *layout* to `0`.

Width refers here to the number of print columns.

Allowed values: 2 or greater

(default: undefined)

### mouse

0 - no mouse (default)

1 - mouse enabled

### order

If the output has more than one row and more than one column:

0 - elements are ordered horizontally

1 - elements are ordered vertically (default)

### pad

Sets the number of whitespaces between columns. (default: 2)

Allowed values: 0 or greater

### page

0 - off

1 - print the page number on the bottom of the screen. If all the choices fit into one page, the page number is not displayed. (default)

2 - the page number is always displayed even with only one page. Setting page to 2 automatically enables the option clear-screen.

### prompt

If *prompt* is undefined, a default prompt-string will be shown.

If the *prompt* value is an empty string (""), no prompt-line will be shown.

(default: undefined)

### save-screen

0 - off (default)

1 - use the alternate screen

### search

Set the behavior of Ctrl-F.

0 - off

1 - case-insensitive search (default)

2 - case-sensitive search

### tabs-info

The option *tabs-info* allows one to insert spaces at beginning and the end of *info* lines.

*tabs-info* expects a list with one to three elements:

* the first element (initial tab) sets the number of spaces inserted at beginning of paragraphs
* the second element (subsequent tab) sets the number of spaces inserted at the beginning of all broken lines apart from the beginning of paragraphs
* the third element sets the number of spaces used as a right margin.

Allowed values: 0 or greater. Elements beyond the third are ignored.

default: If *margin* is set, the initial-tab and the subsequent-tab are set to left-*margin* and the right margin is set to right-*margin*. If *margin* is not defined, the default is undefined.

### tabs-prompt

The option *tabs-prompt* allows one to insert spaces at beginning and the end of *prompt* lines.

*tabs-prompt* expects a list with one to three elements:

* the first element (initial tab) sets the number of spaces inserted at beginning of paragraphs
* the second element (subsequent tab) sets the number of spaces inserted at the beginning of all broken lines apart from the beginning of paragraphs
* the third element sets the number of spaces used as a right margin.

Allowed values: 0 or greater. Elements beyond the third are ignored.

default: If *margin* is set, the initial-tab and the subsequent-tab are set to left-*margin* and the right margin is set to right-*margin*. If *margin* is not defined, the default is undefined.

### undef

Sets the string displayed on the screen instead of an undefined element.

(default: "")

## options choose-multi

### include-highlighted

0 - `choose-multi` returns the items marked with the SpaceBar. (default)

1 - `choose-multi` returns the items marked with the SpaceBar plus the highlighted item.

2 - `choose-multi` returns the items marked with the SpaceBar. If no items are marked with the SpaceBar, the highlighted item is returned.

### mark

*mark* expects as its value a list of indexes (integers). `choose-multi` preselects the list-elements correlating to these indexes.

(default: undefined)

### meta-items

*meta-items* expects as its value a list of indexes (integers). List-elements correlating to these indexes can not be marked with the SpaceBar or with the right mouse key but if one of these elements is the highlighted item it is added to the chosen items when Return is pressed.

Elements greater than the last index of the list are ignored.

(default: undefined)

### no-spacebar

*no-spacebar* expects as its value an list. The elements of the list are indexes of choices which should not be markable with the SpaceBar or with the right mouse key. If an element is preselected with the option *mark* and also marked as not selectable with the option *no-spacebar*, the user can not remove the preselection of this element.

(default: undefined)

# MULTITHREADING

`Term::Choose` uses multithreading when preparing the list for the output; the number of threads to use can be set with the environment variable `TC_NUM_THREADS`.

# REQUIREMENTS

## Escape sequences

The control of the cursor location, the highlighting of the cursor position and the marked elements and other options on the terminal is done via escape sequences.

By default `Term::Choose` uses `tput` to get the appropriate escape sequences. If the environment variable `TC_ANSI_ESCAPES` is set to a true value, hardcoded ANSI escape sequences are used directly without calling `tput`.

The escape sequences to enable the *mouse* mode and the escape sequence to get the cursor position are always hardcoded.

If the environment variable `TERM` is not set to a true value, `vt100` is used instead as the terminal type for `tput`.

## Monospaced font

It is required a terminal that uses a monospaced font which supports the printed characters.

## Ambiguous width characters

By default ambiguous width characters are treated as half width. If the environment variable `TC_AMBIGUOUS_WIDTH_IS_WIDE` is set to a true value, ambiguous width characters are treated as full width.

The support for the old variable name `TC_AMBIGUOUS_WIDE` will be removed.

## Restrictions

Term::Choose is not installable on Windows.

# AUTHOR

Matthäus Kiem [cuer2s@gmail.com](mailto:cuer2s@gmail.com)

# CREDITS

Based on the `choose` function from the [Term::Clui](https://metacpan.org/pod/Term::Clui) module.

Thanks to the people from [Perl-Community.de](http://www.perl-community.de), from [stackoverflow](http://stackoverflow.com) and from #perl6 on irc.freenode.net for the help.

# LICENSE AND COPYRIGHT

Copyright (C) 2016-2025 Matthäus Kiem.

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


## dist_cpan-GARLANDG-Constants-Net-If.md
# NAME

Constants::Net::If - Constants found in net/if.h

# SYNOPSIS

```
use Constants::Net::If;

```

# DESCRIPTION

Constants::Net::If contains many enumerated values that are implemented as #define directives in <net/if.h> file on unix-like operating systems.

This module should be compatible with windows, macos, linux, netbsd, freebsd, openbsd, and dragonflybsd. Each platform will receive a slightly different enumerations.

Based on C headers found on official sites and unofficial mirrors of source trees.

# AUTHOR

Travis Gibson [TGib.Travis@protonmail.com](mailto:TGib.Travis@protonmail.com)

# COPYRIGHT AND LICENSE

Copyright 2019 Travis Gibson

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


## token.md
token

Combined from primary sources listed below.

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

See primary documentation
[in context](/language/grammars#Named_Regexes)
for **Named Regexes**.

The main ingredient of grammars is named [regexes](/language/regexes). While the syntax of [Raku Regexes](/language/regexes) is outside the scope of this document, *named* regexes have a special syntax, similar to subroutine definitions: [[1]](#fn1)

```raku
my regex number { \d+ [ \. \d+ ]? }

```

In this case, we have to specify that the regex is lexically scoped using the `my` keyword, because named regexes are normally used within grammars.

Being named gives us the advantage of being able to easily reuse the regex elsewhere:

```raku
say so "32.51" ~~ &number;                         # OUTPUT: «True␤»
say so "15 + 4.5" ~~ /<number>\s* '+' \s*<number>/ # OUTPUT: «True␤»

```

**`regex`** isn't the only declarator for named regexes. In fact, it's the least common. Most of the time, the **`token`** or **`rule`** declarators are used. These are both *ratcheting*, which means that the match engine won't back up and try again if it fails to match something. This will usually do what you want, but isn't appropriate for all cases:

```raku
my regex works-but-slow { .+ q }
my token fails-but-fast { .+ q }
my $s = 'Tokens won\'t backtrack, which makes them fail quicker!';
say so $s ~~ &works-but-slow; # OUTPUT: «True␤»
say so $s ~~ &fails-but-fast; # OUTPUT: «False␤»
                              # the entire string is taken by the .+

```

Note that non-backtracking works on terms, that is, as the example below, if you have matched something, then you will never backtrack. But when you fail to match, if there is another candidate introduced by `|` or `||`, you will retry to match again.

```raku
my token tok-a { .* d  };
my token tok-b { .* d | bd };
say so "bd" ~~ &tok-a;        # OUTPUT: «False␤»
say so "bd" ~~ &tok-b;        # OUTPUT: «True␤»

```


## dist_cpan-MELEZHIK-Sparrowdo-VSTS-YAML-Update-Azure-SSL.md
# Sparrowdo::VSTS::YAML::Update::Azure::SSL

Sparrowdo module to generate VSTS yaml build definitions to update Azure ssl certs.

```
$ cat sparrowfile

module_run "VSTS::YAML::Update::Azure::SSL", %(
  build-dir => ".build",
  subscription => "Dev01", # Azure subscription,
  keyvault-name => "app-01-02", # the name of keyvault holding certificates
  cert-name => "app-dev", # certificate name in keyvault
  domain => "foo.bar", # web application domain name
  app-service => "foo-bar", # azure app service name ( a.k web application )
  resource-group => "rg0102" , # azure resource group
);

$ sparrowdo --local_mode --no_sudo

```

# Agent capabilities

This is the list of required tool should be installed on VSTS agent:

* Perl
* Az cli

# Author

Alexey Melezhik


## dist_cpan-MARTIMM-Auth-SCRAM.md
# Salted Challenge Response Authentication Mechanism (SCRAM)

[![Build Status](https://travis-ci.org/MARTIMM/Auth-SCRAM.svg?branch=master)](https://travis-ci.org/MARTIMM/Auth-SCRAM)

[![License](http://martimm.github.io/label/License-label.svg)](http://www.perlfoundation.org/artistic_license_2_0)

This package implements secure authentication mechanism.

## Synopsis

```
# Example from rfc (C = client, s = server)
# C: n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL
# S: r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,i=4096
# C: c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,
#    p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts=
# S: v=rmF9pqV8S7suAoZWja4dJRkFsKQ=
#
class MyClient {

  # Send client first message to server and return server response
  method client-first ( Str:D $client-first-message --> Str ) {

    # Send $client-first-message to server;

    # Get server response, this is the server first message
    'r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,i=4096';
  }

  # Send client final message to server and return server response
  method client-final ( Str:D $client-final-message --> Str ) {

    # Send $client-final-message to server.

    # Server response is server final message
    'v=rmF9pqV8S7suAoZWja4dJRkFsKQ=';
  }

  method error ( Str:D $message --> Str ) {
    # Errors? nah ... (Famous last words!)
  }
}

my Auth::SCRAM $sc .= new(
  :username<user>,
  :password<pencil>,
  :client-side(MyClient.new),
);

$sc.c-nonce-size = 24;
$sc.c-nonce = 'fyko+d2lbbFgONRv9qkxdawL';

my $error = $sc.start-scram;

```

## Documentation

* [SCRAM](https://github.com/MARTIMM/Auth-SCRAM/blob/master/doc/SCRAM.pdf)
* [SCRAM::Client](https://github.com/MARTIMM/Auth-SCRAM/blob/master/doc/Client.pdf)
* [SCRAM::Server](https://github.com/MARTIMM/Auth-SCRAM/blob/master/doc/Server.pdf)

Change log

* [Release notes](https://github.com/MARTIMM/Auth-SCRAM/blob/master/doc/CHANGES.md)

Bugs, todo and known limitations

* [Bugs, todo](https://github.com/MARTIMM/Auth-SCRAM/blob/master/doc/TODO.md)

## Installing

Use zef to install the package like so.

```
$ zef install Auth-SCRAM

```

## Versions of Raku using moarvm

This project is tested with latest Rakudo built on MoarVM implementing Perl v6.d.

## Authors

```
Marcel Timmerman (MARTIMM on github)

```


## dist_zef-rbt-Test-Differences.md
# Test::Differences

Test complex data structures and output the differences between them in
diagnostics. This is helpful for spotting minor changes over a large dataset.

## SYNOPSIS

```
   use Test;
   use Test::Differences;

   eq_or_diff $got,  "a\nb\nc\n",   "testing strings";
   eq_or_diff @got, [{foo => <a b c>}, 1, Nil], "testing compex structure";

```

## DESCRIPTION

When the code you're testing returns multiple lines, records or data
structures and they're just plain wrong, an equivalent to the Unix
C utility may be just what's needed. Here's output from an
example test script that checks two text documents and then two
(trivial) data structures:

```
# Failed test 'Differences in text'
# +---+----------------+----------------+
# | Ln|Got             |Expected        |
# +---+----------------+----------------+
# |  0|this is line 1  |this is line 1  |
# *  1|this is line 2  |this is line b  *
# |  2|this is line 3  |this is line 3  |
# +---+----------------+----------------+
not ok 1 - Differences in text
#
# Failed test 'Differences in whitespace'
# +---+--------------+--------------+
# | Ln|Got           |Expected      |
# +---+--------------+--------------+
# |  0|    indented  |    indented  |
# *  1|indented      |indented      *
# |  2|    indented  |    indented  |
# +---+--------------+--------------+
not ok 2 - Differences in whitespace
#
# Failed test 'Differences in structure'
# +---+-----------------------------------+---+---------------------------+
# | Ln|Got                                | Ln|Expected                   |
# +---+-----------------------------------+---+---------------------------+
# *  0|{                                  *  0|[                          *
# *  1|ITEM => "Dry humourless message",  *  1|"ITEM",                    *
# *  2|}                                  *  2|"Dry humourless message",  *
# |   |                                   *  3|]                          *
# +---+-----------------------------------+---+---------------------------+
not ok 3 - Differences in structure
#
# You failed 3 tests of 3

```

eq\_or\_diff() compares two strings or (limited) data structures and
either emits an ok indication or a side-by-side diff. Test::Differences
is designed to be used with Test.

### eq-or-diff

```
eq_or_diff $got, $want, $test-title, OutputStyle :output-style = Table, :context-lines = 5, :dump-overrides => {};

```

* `output-style` may be any OutputStyle supported by [Text::Diff](https://github.com/rbt/raku-Text-Diff).
* `context-lines` is the number of lines above/below within the formatted output around
  the change to present.
* `dump-overrides` is a set of overrides to default [Data::Dump](https://github.com/tony-o/perl6-data-dump)
  styling.

## COPYRIGHT

Copyright Barrie Slaymaker, Curtis "Ovid" Poe, and David Cantrell.

Ported, with non-trivial restructuring, to Raku by Rod Taylor.

## LICENSE

You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.


## nude.md
nude

Combined from primary sources listed below.

# [In role Rational](#___top "go to top of document")[§](#(role_Rational)_method_nude "direct link")

See primary documentation
[in context](/type/Rational#method_nude)
for **method nude**.

```raku
method nude(Rational:D: --> Positional)
```

Returns a list of the numerator and denominator.


## obsolete.md
class X::Obsolete

Compilation error due to use of obsolete syntax

```raku
class X::Obsolete does X::Comp { }
```

Syntax error thrown when the user is attempting to use constructs from other languages.

For example

```raku
m/abc/i

```

dies with

｢text｣ without highlighting

```

```

===SORRY!===
Unsupported use of /i; in Raku please use :i

```

```

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

## [method old](#class_X::Obsolete "go to top of document")[§](#method_old "direct link")

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

Returns a textual description of the obsolete syntax construct

## [method replacement](#class_X::Obsolete "go to top of document")[§](#method_replacement "direct link")

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

Describes what to use instead of the obsolete syntax.

## [method when](#class_X::Obsolete "go to top of document")[§](#method_when "direct link")

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

Returns a string describing the state of the language (usually `" in Raku"`).


## dist_cpan-TITSUKI-Algorithm-SetUnion.md
[![Build Status](https://travis-ci.org/titsuki/p6-Algorithm-SetUnion.svg?branch=master)](https://travis-ci.org/titsuki/p6-Algorithm-SetUnion)

# NAME

Algorithm::SetUnion - a perl6 implementation for solving the disjoint set union problem (a.k.a. Union-Find Tree)

# SYNOPSIS

```
use Algorithm::SetUnion;

my $set-union = Algorithm::SetUnion.new(size => 4);
$set-union.union(0,1);
$set-union.union(1,2);

my $root = $set-union.find(0);

```

# DESCRIPTION

Algorithm::SetUnion is a perl6 implementation for solving the disjoint set union problem (a.k.a. Union-Find Tree).

## CONSTRUCTOR

```
my $set-union = Algorithm::SetUnion.new(%options);

```

### OPTIONS

* `size => $size`

Sets the number of disjoint sets.

## METHODS

### find(Int $index --> Int:D)

```
my $root = $set-union.find($index);

```

Returns the name(i.e. root) of the set containing element `$index`.

### union(Int $left-index, Int $right-index --> Bool:D)

```
$set-union.union($left-index, $right-index);

```

Unites sets containing element `$left-index` and `$right-index`. If sets are equal, it returns False otherwise True.

# AUTHOR

titsuki [titsuki@cpan.org](mailto:titsuki@cpan.org)

# COPYRIGHT AND LICENSE

Copyright 2016 titsuki

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

This algorithm is from Tarjan, Robert Endre. "A class of algorithms which require nonlinear time to maintain disjoint sets." Journal of computer and system sciences 18.2 (1979): 110-127.


## dist_github-sergot-DateTime-Parse.md
# DateTime::Parse

DateTime parser.

[![test](https://github.com/sergot/datetime-parse/actions/workflows/test.yml/badge.svg)](https://github.com/sergot/datetime-parse/actions/workflows/test.yml)

# Synopsis

```
    my $rfc1123 = DateTime::Parse.new('Sun, 06 Nov 1994 08:49:37 GMT');
    say $rfc1123.Date;

    say DateTime::Parse.new('Sun', :rule<wkday>) + 1; # 7th day of week

```

# Description

* new( $format, $rule )
  * $format : String with DateTime to be parsed
  * $rule : Rule to run


## dist_cpan-LEMBARK-FileSystem-Parent.md
# NAME

FileSystem::Parent - Return Seq of elements above a given point in the filesystem.

# SYNOPSIS

```
use FileSystem::Parent;

# list of dirs at or above the executable's directory.

my $found   = scan-up;

# the Seq is evaluated lazily, or can be converted to
# a list on return.

say '#Found: ', $found.join( "\n#\t" );

my @dirz    = $found.eager;

# return the list of dirs above a given directory or
# a file:

my $found   = scan-up from => '~/sandbox';
my $found   = scan-up :from( $*PROGRAM-NAME  );

# or use a file as the starting point:

my $found   = scan-up :from( 'SYS$USER:[sandbox]foo.c;3' );
my $found   = scan-up :from( 'c:\\run\\foo.bat' );

# resolve any symbolic links in the input path once
# before tracing up the directory tree.

my $found   = scan-up :resolve;
my $found   = scan-up :resolve, :from( $some_file );

# append 'lib' or a multi-part relatvie path to each
# of the directories reported using the proper syntax
# for the filesystem.

my $found   = scan-up append => 'lib';
my $found   = scan-up append => 'etc/config.yaml';

# or append a file basename, or a subdir.

my $found   = scan-up append => 'etc/config.yaml';

# usually not all tha useful to scan root dir's for
# Perly modules. skip-root avoids procesing the root
# (e.g., '/') directory. in this case, the list will
# not include any of "/lib" or "c:\lib", or
# USER$SANDBOX:[lib].

my $found   = scan-up append => 'lib', :skip-root;

# default filter is 'all'.
# also available: dir, file, exists.

my $found   = scan-up append => 'lib', filter => 'dir';
my $found   = scan-up append => 'etc', filter => 'dir';

my $found   = scan-up append => 'config.yaml', filter => 'file';
my $found   = scan-up append => '.gitignore',  filter => 'exist';

# roll your own filter. basically, grep on the file tree
# above your executable for whatever you like.
# filter value anything that can smart match with an IO:
# string, regex, block...

my $from    = '~/sandbox/project/cleanup';
my $append  = 'etc/cleanup.confg.yaml';
my $filter  = -> IO $path { $path ~~ :s && $path ~~ :r };

my $found   = scan-up :$from, :$append, :$filter;

# do it verbosely: Reporting all wanted or skipped dirs
# and getting report from FindBin for a default start dir.

my $verbose = True;
my $found   = scan-up :$verbose;

```

# DESCRIPTION

FileSystem::Parent scans up the filetree from a given file or directory searching and filtering for specific items. Unlike scandir(3) or File::scan-up it returns a short list -- at most the depth of the file tree at the starting point.

It's use is in locating direcories or files for library inclusion or configuration based on an executable's location in the filesystem.

The default behavior simply returns the absolute, possibly resolved, path of each directory above the starting point. Supplying a relative path via "append" allows searching for sub-dirs or configuration files relative to the executable; adding a filter locates usable items along the path.

One example is the use via FindBin::libs to append => 'lib', filter => 'dir' and effectively '-I' the existing dir's below /lib at compile time based on the executable's location in the filesystem. Another is using append => "etc/$name.config.yaml", filter => 'file' and locating usable configuration files at increasing distances.

The canned filter are listed below; a user-supplied filter is compared by smart-matching each path element as an IO to the argument, allowing regexen or blocks to perform any actions they require (including initializing the paths if necessary via a block).

## Parameters

All parameters are named (i.e., no positionals). All have defaults.

* from The first directory derived from this point in the filesystem, either a directory or a file's parent. Values can be whatever works on the filesystem in use:

  c:\foo\bar\bletch.ext
  USER$SANDBOX:[some.path.to.your.sandbox]
  /var/tmp/foobar

are all valid in appropriate places. So long as Perl6 IO can successfully check that it exists, is a directory, and take the parent of a non-dir it'll work.

This is affected by the "resolve": starting from a symlink executable may leave the file tree completely outside of where the running executable lives.

Default is FindBin::Bin (which may simply be the current working directory for in interactive invocation).

* :append This is a relative path appended to each directory found from start to the root. It may be a directory, file, or mutiple dir's leading up to a file:

  :append( 'lib' ) generate for 'lib' subirs.
  :append( 'config.yaml' ) append a file basename.
  :append( 'etc/foo.bar' ) append a directory and basename.
  :append( 'etc/foo/bar.cfg' ) sub-directory and basename.

Depding on your value of append, different filters may be meaningless (e.g., 'dir' with a config file basename).

Defaults is '' (i.e., append nothing).

* :filter This can be a string to use a canned filter or anything that can be smart-matched with an IO. Canned filters include: "all", "dir", "file", and "exists" (i.e., True, :d, :f, :e).

Non-string values can include regexen, blocks... anything for which

```
$path.IO ~~ $filter

```

is valid.

A block should take an IO as argument and return a Boolean. For example, to return ./etc dirs which contain "config.yaml" files for the current executable:

```
my $filter  = -> IO $path
{
    $path.add( 'config.yaml' ) ~~ :e
};

my $dirz    = scan-up append => 'etc', :$filter;

```

this will leave $dirz as a sequence of 'etc' dir's which do contain the requested basename -- not a lise of valid config files.

Default is Stringy 'all', which takes everything.

* skip-root This boolean tells scan-up to avoid processing the root directory (e.g., "/", "c:", "FOO$BAR:[]"). It is normally used with append when the result of appending to the root is useless (e.g., few modules appear in "/lib"):

  my $lib\_dirz = scan-up append => 'lib', filter => dir, :skip-root;

will not return "/lib" on \*NIX.

This saves the caller from having to convert the lazy list to an array in order to 'pop' the last item or find some way to avoid processing the last item returned from the seq.

Default: False (i.e., include the root in processing).

* :resolve This calls "resolve" on the starting point after converting it to an absolute path.

Defaults to False.

* :verbose Passed to Bin also used to display a list of dir's taken or skipped by the filter.

Defaults to False.

## Notes:

# SEE ALSO

* FindBin

Describes behavior of Bin used for default start along with its use of verbose & resolve.

# AUTHOR

Steven Lembark [lembark@wrkhors.com](mailto:lembark@wrkhors.com)

# COPYRIGHT AND LICENSE

Copyright 2019 Steven Lembark

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


## confused.md
class X::Syntax::Confused

Compilation error due to unrecognized syntax

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

```

The most general syntax error, if no more specific error message can be given.

For example

```raku
1∞

```

dies with

｢text｣ without highlighting

```

```

===SORRY!===
Confused

```

```


## thread.md
class Thread

Concurrent execution of code (low-level)

```raku
class Thread {}
```

A [thread](https://en.wikipedia.org/wiki/Thread_%28computing%29) is a sequence of instructions that can (potentially) run in parallel to others. Class `Thread` provides a bit of abstraction over threads provided by the underlying virtual machines (which in turn might or might not be operating system threads).

Since threads are fairly low-level, most applications should use other primitives, like [`start`](/type/Promise#method_start), which also runs in parallel and returns a [`Promise`](/type/Promise).

```raku
my @threads = (^10).map: {
    Thread.start(
        name => "Sleepsorter $_",
        sub {
            my $rand = (^10).pick;
            sleep $rand;
            say $rand;
        },
    );
}

.finish for @threads;

```

The current thread is available in the dynamic variable `$*THREAD`.

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

## [method new](#class_Thread "go to top of document")[§](#method_new "direct link")

```raku
method new(:&code!, Bool :$app_lifetime = False, Str :$name = '<anon>' --> Thread:D)
```

Creates and returns a new `Thread`, without starting it yet. `&code` is the code that will be run in a separate thread.

`$name` is a user-specified string that identifies the thread.

If `$app_lifetime` is set to `True`, then the thread is killed when the main thread of the process terminates. If set to `False`, the process will only terminate when the thread has finished.

## [method start](#class_Thread "go to top of document")[§](#method_start "direct link")

```raku
method start(Thread:U: &code, Bool :$app_lifetime = False, Str :$name = '<anon>' --> Thread:D)
```

Creates, runs and returns a new `Thread`. Note that it can (and often does) return before the thread's code has finished running.

## [method run](#class_Thread "go to top of document")[§](#method_run "direct link")

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

## [method id](#class_Thread "go to top of document")[§](#method_id "direct link")

```raku
method id(Thread:D: --> Int:D)
```

Returns a numeric, unique thread identifier.

## [method finish](#class_Thread "go to top of document")[§](#method_finish "direct link")

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

Waits for the thread to finish. This is called [join](#method_join) in other programming systems.

## [method join](#class_Thread "go to top of document")[§](#method_join "direct link")

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

Waits for the thread to finish.

## [method yield](#class_Thread "go to top of document")[§](#method_yield "direct link")

```raku
method yield(Thread:U:)
```

Tells the scheduler to prefer another thread for now.

```raku
Thread.yield;
```

## [method app\_lifetime](#class_Thread "go to top of document")[§](#method_app_lifetime "direct link")

```raku
method app_lifetime(Thread:D: --> Bool:D)
```

Returns `False` unless the named parameter `:app_lifetime` is specifically set to `True` during object creation. If the method returns `False` it means that the process will only terminate when the thread has finished while `True` means that the thread will be killed when the main thread of the process terminates.

```raku
my $t1 = Thread.new(code => { for 1..5 -> $v { say $v }});
my $t2 = Thread.new(code => { for 1..5 -> $v { say $v }}, :app_lifetime);

say $t1.app_lifetime;                 # OUTPUT: «False␤»
say $t2.app_lifetime;                 # OUTPUT: «True␤»
```

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

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

Returns the user defined string, which can optionally be set during object creation in order to identify the `Thread`, or `'<anon>'` if no such string was specified.

```raku
my $t1 = Thread.new(code => { for 1..5 -> $v { say $v }});
my $t2 = Thread.new(code => { for 1..5 -> $v { say $v }}, name => 'my thread');

say $t1.name;                 # OUTPUT: «<anon>␤»
say $t2.name;                 # OUTPUT: «my thread␤»
```

## [method Numeric](#class_Thread "go to top of document")[§](#method_Numeric "direct link")

```raku
method Numeric(Thread:D: --> Int:D)
```

Returns a numeric, unique thread identifier, i.e. the same as [id](#method_id).

## [method Str](#class_Thread "go to top of document")[§](#method_Str "direct link")

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

Returns a string which contains the invocants [thread id](#method_id) and [name](#method_name).

```raku
my $t = Thread.new(code => { for 1..5 -> $v { say $v }}, name => 'calc thread');
say $t.Str;                           # OUTPUT: «Thread<3>(calc thread)␤»
```

## [method is-initial-thread](#class_Thread "go to top of document")[§](#method_is-initial-thread "direct link")

```raku
method is-initial-thread(--> Bool)
```

Returns a Bool indicating whether the current thread (if called as a class method) or the Thread object on which it is called, is the initial thread the program started on.

```raku
say Thread.is-initial-thread;    # True if this is the initial thread
say $*THREAD.is-initial-thread;  # True if $*THREAD is the initial thread
```

Please note there is no guarantee that this is actually the main thread from the OS's point of view. Also note that if you need this other than from a pure introspection / debugging point of view, that there are probably better ways to achieve what you're trying to achieve.

# [Routines](#class_Thread "go to top of document")[§](#Routines "direct link")

## [sub full-barrier](#class_Thread "go to top of document")[§](#sub_full-barrier "direct link")

```raku
sub full-barrier()
```

Performs a full memory barrier, preventing re-ordering of reads/writes. Required for implementing some lock-free data structures and algorithms.

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

Type relations for `Thread`

raku-type-graph

Thread
Thread

Any
Any

Thread->Any

Mu
Mu

Any->Mu

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