## dist_github-yowcow-WebService-SOP.md
[![Build Status](https://travis-ci.org/yowcow/p6-WebService-SOP.svg?branch=master)](https://travis-ci.org/yowcow/p6-WebService-SOP)

# NAME

WebService::SOP - SOP API request creator and validator

# DESCRIPTION

WebService::SOP is API authenticatable request creator and validator. Currently supporting **SOP v1.1** API authentication.

# SEE ALSO

WebService::SOP::V1\_1

# AUTHOR

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

# COPYRIGHT AND LICENSE

Copyright 2016 yowcow

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


## dist_zef-CIAvash-GtkLayerShell.md
# NAME

GtkLayerShell - A [Raku](https://www.raku-lang.ir/en) module for interfacing with `Gtk Layer Shell`

# DESCRIPTION

Provides a Raku interface for [Gtk Layer Shell](https://github.com/wmww/gtk-layer-shell), a library for creating panels and other desktop components for Wayland, using the Layer Shell protocol.

# SYNOPSIS

```
use GtkLayerShell:auth<zef:CIAvash>:api<0.9.2>;

# With Gnome::Gtk3 module
use Gnome::Gtk3::Main;
use Gnome::Gtk3::Window;
use Gnome::Gtk3::Box;
use Gnome::Gtk3::Label;

my Gnome::Gtk3::Main   $m          .= new;
my Gnome::Gtk3::Window $gtk_window .= new;

my $window = $gtk_window.get-native-object;

my GtkLayerShell $layer_surface .= new: :$window, :init,
                                        :layer(LAYER_OVERLAY)
                                        :anchors(:EDGE_LEFT, :EDGE_TOP),
                                        :margins(:EDGE_TOP(5), :EDGE_LEFT(10)),
                                        :exclusive_zone(50);

# Or
my $layer_surface = GtkLayerShell.new: :$window;
$layer_surface.init;
$layer_surface.set: :layer(LAYER_OVERLAY),
                    :anchors(:EDGE_LEFT, :EDGE_TOP),
                    :margins(:EDGE_TOP(5), :EDGE_LEFT(10)),
                    :name_space<panel>,
                    :auto_exclusive_zone

# Or
my $layer_surface = GtkLayerShell.new: :$window, :init;
$layer_surface.set_layer:  LAYER_OVERLAY;
$layer_surface.set_anchor: EDGE_TOP,  True;
$layer_surface.set_anchor: EDGE_LEFT, True;
$layer_surface.set_margin: EDGE_TOP,  10;
$layer_surface.set_margin: EDGE_LEFT, 10;

my $box = Gnome::Gtk3::Box.new;
$box.add: Gnome::Gtk3::Label.new: :text('Gtk Layer Shell!');

$gtk_window.add: $box;

$gtk_window.show-all;

$m.gtk-main;

# With GTK::Simple
use GTK::Simple;
use GTK::Simple::App;

my GTK::Simple::App $app .= new;

my GtkLayerShell $layer_surface .= new: :window($app.WIDGET), :init, :anchors(:EDGE_RIGHT, :EDGE_BOTTOM);

$app.set-content: GTK::Simple::HBox.new: GTK::Simple::Label.new: text => 'Gtk Layer Shell!';

$app.run;

```

# INSTALLATION

You need to have [Gtk Layer Shell](https://github.com/wmww/gtk-layer-shell) and a Wayland compositor that works with it, [Raku](https://www.raku-lang.ir/en) and [zef](https://github.com/ugexe/zef), then run:

```
zef install "GtkLayerShell:auth<zef:CIAvash>:api<0.9.2>"

```

or if you have've cloned the repo:

```
zef install .

```

# TESTING

```
prove -ve 'raku -I.' --ext rakutest

```

# ATTRIBUTES

## has GtkLayerShell::DefinedWindow $.window

A layer surface. `Pointer` to `Gtk.Window`.

## has Bool:D $.init

Whether to initialize layer for `window` on instantiation

# METHODS

## method major\_version

```
method major_version() returns Int:D

```

Returns the major version number of the GTK Layer Shell library

## method minor\_version

```
method minor_version() returns Int:D

```

Returns the minor version number of the GTK Layer Shell library

## method micro\_version

```
method micro_version() returns Int:D

```

Returns the micro/patch version number of the GTK Layer Shell library

## method is\_supported

```
method is_supported() returns Bool

```

Returns `True` if the platform is Wayland and Wayland compositor supports the zwlr\_layer\_shell\_v1 protocol. May block for a Wayland roundtrip the first time it's called.

## method protocol\_version

```
method protocol_version() returns Int:D

```

Returns version of the zwlr\_layer\_shell\_v1 protocol supported by the compositor or 0 if the protocol is not supported. May block for a Wayland roundtrip the first time it's called.

## method init

```
method init() returns Mu

```

Sets the `window` up to be a layer surface once it is mapped. This must be called before the `window` is realized.

## method set

```
method set(
    LayerShellLayer :$layer,
    Str :$name_space,
    GtkLayerShell::Native::Monitor :$monitor,
    :@anchors where .all ~~ Anchor,
    :@margins where .all ~~ Margin,
    Int :$exclusive_zone,
    Bool :$auto_exclusive_zone,
    LayerShellKeyboardMode :$keyboard_mode
) returns Mu

```

Sets multiple properties of the layer surface at once

### PARAMETERS

#### Enum LayerShellLayer :$layer

The `LayerShellLayer` on which this surface appears

#### Str :$name\_space

The namespace of this layer surface

#### GtkLayerShell::Native::Monitor :$monitor

The output(`Pointer` to `Gdk.Monitor`) this layer surface will be placed on (`Any` to let the compositor decide)

#### :@anchors where .all ~~ Anchor

Pairs of `LayerShellEdge`, `Int` to set margins of this layer suface's edges

#### :@margins where .all ~~ Anchor

Pairs of `LayerShellEdge`, `Bool` this layer suface may be anchored to

#### Int :$exclusive\_zone

The size of the exclusive zone for this layer surface

#### Bool :$auto\_exclusive\_zone

Automatically set the size of exclusive zone for this layer surface

#### Enum LayerShellKeyboardMode :$keyboard\_mode

The type of keyboard interactivity requested

## method is\_layer\_window

```
method is_layer_window() returns Bool

```

Returns if `window` has been initialized as a layer surface.

## method zwlr\_layer\_surface\_v1

```
method zwlr_layer_surface_v1() returns GtkLayerShell::Native::ZwlrLayerSurfaceV1

```

Returns The underlying layer surface Wayland object

## method set\_namespace

```
method set_namespace(
    Str:D $name_space
) returns Mu

```

Sets the `namespace` of the surface. No one is quite sure what this is for, but it probably should be something generic ("panel", "osk", etc). If the window is currently mapped, it will get remapped so the change can take effect.

### PARAMETERS

#### Str:D $name\_space

The namespace of this layer surface

## method get\_namespace

```
method get_namespace() returns Str:D

```

Returns the namespace property. If namespace is unset, returns the default namespace ("gtk-layer-shell")

## method set\_layer

```
method set_layer(
    LayerShellLayer:D $layer
) returns Mu

```

Sets the "layer" on which the surface appears (controls if it is over top of or below other surfaces). The layer may be changed on-the-fly in the current version of the layer shell protocol, but on compositors that only support an older version, the `window` is remapped so the change can take effect.

Default is `LAYER_TOP`

### PARAMETERS

#### LayerShellLayer:D $layer

The layer on which this surface appears

## method get\_layer

```
method get_layer() returns LayerShellLayer:D

```

Returns the current layer

## method set\_monitor

```
method set_monitor(
    GtkLayerShell::Native::Monitor $monitor
) returns Mu

```

Sets the output for the window to be placed on, or `Pointer` type object to let the compositor choose. If the window is currently mapped, it will get remapped so the change can take effect.

Default behavior is to let the compositor choose

### PARAMETERS

#### GtkLayerShell::Native::Monitor:D $monitor

The output(`Pointer` to `Gdk.Monitor`) this layer surface will be placed on

## method get\_monitor

```
method get_monitor() returns GtkLayerShell::Native::Monitor

```

Returns the monitor(`Pointer` to `Gdk.Monitor`) this surface will/has requested to be on, can be `Pointer` type object.

NOTE: To get which monitor the surface is actually on, use `gdk_get_monitor_at_window` from a Gdk module.

## method set\_anchor

```
method set_anchor(
    LayerShellEdge:D $edge,
    Bool:D $anchor_to_edge
) returns Mu

```

Sets whether `window` should be anchored to `edge`.

* If two perpendicular edges are anchored, the surface with be anchored to that corner
* If two opposite edges are anchored, the window will be stretched across the screen in that direction Default is `False` for each `LayerShellEdge`

### PARAMETERS

#### Enum LayerShellEdge:D $edge

A `LayerShellEdge` this layer suface may be anchored to

#### Bool:D $anchor\_to\_edge

Whether or not to anchor this layer surface to `edge`

## method get\_anchor

```
method get_anchor(
    LayerShellEdge:D $edge
) returns Bool

```

Returns if this surface is anchored to the given edge
`LayerShellEdge`

## method set\_margin

```
method set_margin(
    LayerShellEdge:D $edge,
    Int:D $margin_size
) returns Mu

```

Sets the margin for a specific `edge` of a `window`. Effects both surface's distance from the edge and its exclusive zone size (if auto exclusive zone enabled). Default is 0 for each `LayerShellEdge`

### PARAMETERS

#### Enum LayerShellEdge:D $edge

The `LayerShellEdge` for which to set the margin

#### Int:D $margin\_size

The margin for `edge` to be set

## method get\_margin

```
method get_margin(
    LayerShellEdge:D $edge
) returns Int:D

```

Returns the size of the margin for the given edge
`LayerShellEdge`

## method set\_exclusive\_zone

```
method set_exclusive_zone(
    Int $exclusive_zone
) returns Mu

```

Has no effect unless the surface is anchored to an edge. Requests that the compositor does not place other surfaces within the given exclusive zone of the anchored edge.

For example, a panel can request to not be covered by maximized windows. See wlr-layer-shell-unstable-v1.xml for details. Default is 0

### PARAMETERS

#### Int $exclusive\_zone

The size of the exclusive zone

## method get\_exclusive\_zone

```
method get_exclusive_zone() returns Int:D

```

Returns the window's exclusive zone (which may have been set manually or automatically)

## method enable\_auto\_exclusive\_zone

```
method enable_auto_exclusive_zone() returns Mu

```

When auto exclusive zone is enabled, exclusive zone is automatically set to the size of the `window` + relevant margin. To disable auto exclusive zone, just set the exclusive zone to 0 or any other fixed value.

NOTE: you can control the auto exclusive zone by changing the margin on the non-anchored edge. This behavior is specific to gtk-layer-shell and not part of the underlying protocol

## method is\_auto\_exclusive\_zone\_enabled

```
method is_auto_exclusive_zone_enabled() returns Bool

```

Returns if the surface's exclusive zone is set to change based on the window's size

## method set\_keyboard\_mode

```
method set_keyboard_mode(
    LayerShellKeyboardMode:D $mode
) returns Mu

```

Sets if/when `window` should receive keyboard events from the compositor, see `LayerShellKeyboardMode` for details. Default is `KEYBOARD_MODE_NONE`

### PARAMETERS

#### Enum LayerShellKeyboardMode:D $mode

The type of keyboard interactivity requested

## method get\_keyboard\_mode

```
method get_keyboard_mode() returns LayerShellKeyboardMode:D

```

Returns current keyboard interactivity mode for `window`

# REPOSITORY

<https://codeberg.org/CIAvash/GtkLayerShell/>

# BUG

<https://codeberg.org/CIAvash/GtkLayerShell/issues>

# AUTHOR

Siavash Askari Nasr - <https://siavash.askari-nasr.com>

# COPYRIGHT

Copyright © 2021 Siavash Askari Nasr

# LICENSE

This file is part of GtkLayerShell.

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

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

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


## dist_zef-antononcube-LLM-RetrievalAugmentedGeneration.md
# LLM::RetrievalAugmentedGeneration

[![Actions Status](https://github.com/antononcube/Raku-LLM-RetrievalAugmentedGeneration/actions/workflows/linux.yml/badge.svg)](https://github.com/antononcube/Raku-LLM-RetrievalAugmentedGeneration/actions)
[![Actions Status](https://github.com/antononcube/Raku-LLM-RetrievalAugmentedGeneration/actions/workflows/macos.yml/badge.svg)](https://github.com/antononcube/Raku-LLM-RetrievalAugmentedGeneration/actions)

[![](https://raku.land/zef:antononcube/LLM::RetrievalAugmentedGeneration/badges/version)](https://raku.land/zef:antononcube/LLM::RetrievalAugmentedGeneration)
[![](https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg)](https://opensource.org/licenses/Artistic-2.0)

Raku package for doing LLM Retrieval Augment Generation (RAG).

---

## Motivation and general procedure

Assume we have a large (or largish) collection of (Markdown) documents and we want
to interact with it as if a certain LLM model has been specially trained with that collection.

Here is one way to achieve this:

1. The "data wrangling problem" is the conversion of the a collection of documents into Markdown files, and then partitioning those files into text chunks.
   * There are several packages and functions that can do the conversion.
   * It is not trivial to partition texts into reasonable text chunks.
     * Certain text paragraphs might too big for certain LLMs to make embeddings for.
2. Each of the text chunks is "vectorized" via LLM embedding.
3. Then the vectors are put in a vector database or "just" into a "nearest neighbors" finding function object.
   * A large nearest neighbors finding object can be made with ["Math::Nearest"](https://raku.land/zef:antononcube/Math::Nearest), [AAp6].
   * Alternatively, a recommender system can be used like ["ML::StreamsBlendingRecommender"](https://github.com/antononcube/Raku-ML-StreamsBlendingRecommender), [AAp8].
4. When a user query is given:
   * The LLM embedding vector is being found.
   * The closest text chunk vectors are found.
5. The corresponding closest text chunks are given to the LLM to formulate a response to user's query.

---

## Workflow

Here is the Retrieval Augmented Generation (RAG) workflow we consider:

* The document collection is ingested.
* The documents are split into chunks of relevant sizes.
  * LLM embedding models have token limit that have to be respected.
  * It might be beneficial or desirable to split into "meaningful" chunks.
    * I.e. complete sentences or paragraphs.
* Large Language Model (LLM) embedding vectors are obtained for all chunks.
* A vector database is created with these embedding vectors and stored locally. Multiple local databases can be created.
* A relevant local database is imported for use.
* An input query is provided to a retrieval system.
* The retrieval system retrieves relevant documents based on the query.
* The top K documents are selected for further processing.
* The model is fine-tuned using the selected documents.
* The fine-tuned model generates an answer based on the query.
* The output answer is presented to the user.

### Component diagram

Here is a Mermaid-JS component diagram that shows the components of performing the Retrieval Augmented Generation (RAG) workflow:

```
flowchart TD
    subgraph LocalVDB[Local Folder]
        A(Vector Database 1)
        B(Vector Database 2)
        C(Vector Database N)
    end
    ID[Ingest document collection]
    SD[Split Documents]
    EV[Get LLM Embedding Vectors]
    CD[Create Vector Database]
    ID --> SD --> EV --> CD

    EV <-.-> LLMs

    CD -.- CArray[[CArray<br>representation]]

    CD -.-> |export| LocalVDB

    subgraph Creation
        ID
        SD
        EV
        CD
    end

    LocalVDB -.- JSON[[JSON<br>representation]]

    LocalVDB -.-> |import|D[Ingest Vector Database]

    D -.- CArray
    F -.- |nearest neighbors<br>distance function|CArray
    D --> E
    E[/User Query/] --> F[Retrieval]
    F --> G[Document Selection]
    G -->|Top K documents| H(Model Fine-tuning)
    H --> I[[Generation]]
    I <-.-> LLMs
    I -->J[/Output Answer/]
    G -->|Top K passages| K(Model Fine-tuning)
    K --> I

    subgraph RAG[Retrieval Augmented Generation]
        D
        E
        F
        G
        H
        I
        J
        K
    end

    subgraph LLMs
        direction LR
        OpenAI{{OpenAI}}
        Gemini{{Gemini}}
        MistralAI{{MistralAI}}
        LLaMA{{LLaMA}}
    end

```

In this diagram:

* Document collections are ingested, processed, and corresponding vector databases are made.
  * LLM embedding models are used for obtain the vectors.
* There are multiple local vector databases that are stored and maintained locally.
* A vector database from the local collection is selected and ingested.
* An input query provided by the user initiates the RAG workflow.
* The workflow then proceeds with:
  * retrieval
  * document selection
  * model fine-tuning
  * answer generation
  * presenting the final output

---

## Implementation notes

### Fast nearest neighbors

* Since Vector DataBases (VDBs) are slow and "expensive" to compute, their stored in local directory.
  * By default `XDG_DATA_HOME` is used; for example, `~/.local/share/raku/LLM/SemanticSearchIndex`.
* LLM embeddings produce large, dense vectors, hence nearest neighbors finding algorithms like
  [K-d Tree](https://en.wikipedia.org/wiki/K-d_tree#Degradation_in_performance_with_high-dimensional_data) do not apply.
  (Although, those algorithms perform well in low-dimensions.)
  * For example we can have 500 vectors each with dimension 1536.
* Hence, fast C-implementations of the common distance functions were made; see [AAp7].

### Smaller export files, faster imports

* Exporting VDBs files in JSON format produces large files.
  * For example:
    * Latest LLaMA models make vectors with dimension 4096
    * So the transcript of "normal" ≈ 3.5 hours long podcast would produce ≈ 55 MB JSON file size
    * It takes ≈ 13 seconds to JSON-import that file.
* Hence, a format for smaller file size and faster import should be investigated.
* I investigated the use of [CBOR](https://cbor.io) via ["CBOR::Simple"](https://raku.land/zef:japhb/CBOR::Simple).
* In order to facilitate the use of CBOR:
  * The VDB class `.export` method takes `:format` argument.
  * The `.import` method uses the file extension to determine with which format to import with.
  * The package "Math::DistanceFunctions::Native:ver<0.1.1>" works with `num64` (`double`) and `num32` (`float`) C-arrays.
  * There is (working) precision attribute `$num-type` in the VDB class that can be `num32` or `num64`.
* Using CBOR instead of JSON to export/import VDB objects:
  * Produces ≈ 2 times smaller files using `num64`; ≈ 3 times with `num32`
  * Exporting is 30% faster with CBOR
  * Importing VDB CBOR files is ≈ 3.5 times faster
  * Importing `num32` CBOR exported files is problematic
  * Importing using CBOR is "too slow" to make VDBs summaries (done with regexes over JSON text blobs)

---

## TODO

* TODO Implementation
  * DONE "Short file spec"
  * TODO Weak and strong equivalence of VDBs
* TODO Unit testing
  * DONE Ingest VDB
  * DONE Joining VDBs
  * DONE Using `vector-database-objects`
  * DONE Round trip export and import with CBOR and JSON formats
  * TODO Expected "correct" nearest neighbors tests
* TODO Documentation
  * DONE VDB creation notebook
  * DONE VDB ingestion and RAG notebook
  * DONE Raku-RAG demo notebook and video
  * TODO Review (and complete if needed)
  * TODO Overview blog post
* TODO Applications and workflows
  * DONE Simple RAG demos
  * DONE Making nearest neighbor graphs
  * TODO Using a recommender system
    * I.e. ["ML::StreamsBlendingRecommender"](https://github.com/antononcube/Raku-ML-StreamsBlendingRecommender)
  * TODO Complete RAG workflow over a real life, largish Raku package
  * TODO RAG over "App::Rak"
  * TODO RAG over docs.raku.org

---

## References

### Packages

[AAp1] Anton Antonov,
[WWW::OpenAI Raku package](https://github.com/antononcube/Raku-WWW-OpenAI),
(2023),
[GitHub/antononcube](https://github.com/antononcube).

[AAp2] Anton Antonov,
[WWW::PaLM Raku package](https://github.com/antononcube/Raku-WWW-PaLM),
(2023),
[GitHub/antononcube](https://github.com/antononcube).

[AAp3] Anton Antonov,
[LLM::Functions Raku package](https://github.com/antononcube/Raku-LLM-Functions),
(2023-2024),
[GitHub/antononcube](https://github.com/antononcube).

[AAp4] Anton Antonov,
[LLM::Prompts Raku package](https://github.com/antononcube/Raku-LLM-Prompts),
(2023-2024),
[GitHub/antononcube](https://github.com/antononcube).

[AAp5] Anton Antonov,
[ML::FindTextualAnswer Raku package](https://github.com/antononcube/Raku-ML-FindTextualAnswer),
(2023-2024),
[GitHub/antononcube](https://github.com/antononcube).

[AAp6] Anton Antonov,
[Math::Nearest Raku package](https://github.com/antononcube/Raku-Math-Nearest),
(2024),
[GitHub/antononcube](https://github.com/antononcube).

[AAp7] Anton Antonov,
[Math::DistanceFunctions::Native Raku package](https://github.com/antononcube/Raku-Math-DistanceFunctions-Native),
(2024),
[GitHub/antononcube](https://github.com/antononcube).

[AAp8] Anton Antonov,
[ML::StreamsBlendingRecommender Raku package](https://github.com/antononcube/Raku-ML-StreamsBlendingRecommender),
(2021-2023),
[GitHub/antononcube](https://github.com/antononcube).


## signature.md
class Signature

Parameter list pattern

```raku
class Signature { }
```

A signature is a static description of the [parameter](/type/Parameter) list of a code object. That is, it describes what and how many arguments you need to pass to the code or function in order to call it.

Passing arguments to a signature *binds* the arguments, contained in a [`Capture`](/type/Capture), to the signature.

For information on signature literals, see [here](/language/signatures).

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

## [method params](#class_Signature "go to top of document")[§](#method_params "direct link")

```raku
method params(Signature:D: --> Positional)
```

Returns the list of [`Parameter`](/type/Parameter) objects that make up the signature.

## [method arity](#class_Signature "go to top of document")[§](#method_arity "direct link")

```raku
method arity(Signature:D: --> Int:D)
```

Returns the *minimal* number of positional arguments required to satisfy the signature.

## [method count](#class_Signature "go to top of document")[§](#method_count "direct link")

```raku
method count(Signature:D: --> Real:D)
```

Returns the *maximal* number of positional arguments which can be bound to the signature. Returns `Inf` if there is a slurpy positional parameter.

## [method returns](#class_Signature "go to top of document")[§](#method_returns "direct link")

Whatever the Signature's return constraint is:

```raku
:($a, $b --> Int).returns # OUTPUT: «(Int)»
```

## [method ACCEPTS](#class_Signature "go to top of document")[§](#method_ACCEPTS "direct link")

```raku
multi method ACCEPTS(Signature:D: Signature $topic)
multi method ACCEPTS(Signature:D: Capture $topic)
multi method ACCEPTS(Signature:D: Mu \topic)
```

If `$topic` is a `Signature` returns `True` if anything accepted by `$topic` would also be accepted by the invocant, otherwise returns `False`:

```raku
:($a, $b) ~~ :($foo, $bar, $baz?);   # OUTPUT: «True»
:(Int $n) ~~ :(Str);                 # OUTPUT: «False»
```

The `$topic` is a [`Capture`](/type/Capture), returns `True` if it can be bound to the invocant, i.e., if a function with invocant's `Signature` would be able to be called with the `$topic`:

```raku
\(1, 2, :foo) ~~ :($a, $b, :foo($bar)); # OUTPUT: «True»
\(1, :bar)    ~~ :($a);                 # OUTPUT: «False»
```

Lastly, the candidate with `Mu \topic` converts `topic` to [`Capture`](/type/Capture) and follows the same semantics as [`Capture`](/type/Capture) `$topic`:

```raku
<a b c d>  ~~ :(Int $a);      # OUTPUT: «False»
42         ~~ :(Int);         # OUTPUT: «False» (Int.Capture throws)
set(<a b>) ~~ :(:$a, :$b);    # OUTPUT: «True»
```

Since [`where` clauses](/language/signatures#index-entry-where_clause) are not introspectable, the method cannot determine whether two signatures [ACCEPTS](/type/Signature#method_ACCEPTS) the same sort of `where`-constrained parameters. Such comparisons will return `False`. This includes signatures with literals, which are just sugar for the `where`-constraints:

```raku
say :(42) ~~ :($ where 42)    # OUTPUT: «False␤»
```

## [method Capture](#class_Signature "go to top of document")[§](#method_Capture "direct link")

```raku
method Capture()
```

Throws [`X::Cannot::Capture`](/type/X/Cannot/Capture).

# [Runtime creation of Signature objects (6.d, 2019.03 and later)](#class_Signature "go to top of document")[§](#Runtime_creation_of_Signature_objects_(6.d,_2019.03_and_later) "direct link")

```raku
Signature.new(params => (...), returns => Type, arity => 1, count => 1.Num)

```

In some situations, specifically when working with the MetaObject Protocol, it makes sense to create `Signature` objects programmatically. For this purpose, you can call the `new` method with the following named parameters:

* params

A list of [`Parameter`](/type/Parameter) objects for this signature.

* returns

Any constraint the return value should match. Defaults to [`Mu`](/type/Mu), which effectively implies no return value constraint check.

* arity

The *minimal* number of positional arguments required to satisfy the signature. Defaults to the number of [`Parameter`](/type/Parameter) objects given with the `params` parameter.

* count

The *maximal* number of positional arguments which can be bound to the signature. Defaults to the `arity` if not specified. Specify `Inf` if there is a slurpy positional parameter.

*Warning*: although the logical type of the `count` parameter is integer, the value assigned to it must explicitly be of type [`Num`](/type/Num). If any other type is used, the `new` method silently fails and returns an empty signature. The same trouble occurs when the value assigned to the `arity` parameter is not of type [`Int`](/type/Int).

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

Type relations for `Signature`

raku-type-graph

Signature
Signature

Any
Any

Signature->Any

Mu
Mu

Any->Mu

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


## dist_zef-Kaiepi-annotations.md
![Build Status](https://github.com/Kaiepi/ra-annotations/actions/workflows/test.yml/badge.svg)

# NAME

annotations - Thread-safe static buffer

# SYNOPSIS

```
use v6.e.PREVIEW;

my constant LATIN = 'a'..'z';

module Upper {
    use annotations <declare symbolic class>;
    # We may now declare a class with a symbolic object buffer associated with
    # it. This can be retrieved by parameterizing ANN with our type object,
    # which is typically knowable at compile-time.

    role Alphabet[@LOOKUP is raw] is repr<Uninstantiable> {
        # The annotated operator makes some allocations in an annotation's ANN
        # buffer eagerly given some Str-coercive objects. These become IntStr:D
        # symbols, which is to say they're a name and a position in the buffer
        # for this mixin. Because we take care of this immediately, this can
        # act as our compile-time check for whether or not we really are
        # composing an annotation. Such allocating in ANN is thread-safe.
        my @SYMBOLS := $?CLASS annotate @LOOKUP;

        # The bare slots can be fetched by ANN's list method given these
        # symbols. Because these carry containers regardless of whether or not
        # a value is being stored, this can always be assigned to dynamically.
        method alphabet(::?CLASS: --> List:D) {
            ANN[$?CLASS].list: :of(@SYMBOLS)
        }

        # Likewise, these symbols can form the keys of a map by the ANN's hash
        # method.
        method dictionary(::?CLASS: --> Map:D) {
            ANN[$?CLASS].hash: :of(@SYMBOLS)
        }

        # This will find a letter given the key of a booked symbol.
        method translate(::?CLASS: Str:D --> Str) { ... }
    }

    annotation Half does Alphabet[LATIN] is repr<Uninstantiable> {
        CHECK $?CLASS.alphabet = 'A'..'Z';

        my %DICTIONARY := $?CLASS.dictionary;

        method translate(::?CLASS: Str:D $letter --> Str) {
            %DICTIONARY.AT-KEY: $letter
        }
    }

    annotation Full does Alphabet[LATIN] is repr<Uninstantiable> {
        CHECK $?CLASS.alphabet = 'Ａ'..'Ｚ';

        my %DICTIONARY := $?CLASS.dictionary;

        method translate(::?CLASS: Str:D $letter --> Str) {
            %DICTIONARY.AT-KEY: $letter
        }
    }
}

# Despite the inner alphabet list being static, public, mutable state by
# technicality, its inner Binder slots each only respects its first assignment.
put Upper::Full.alphabet = Upper::Half.alphabet; # OUTPUT:
# Ａ Ｂ Ｃ Ｄ Ｅ Ｆ Ｇ Ｈ Ｉ Ｊ Ｋ Ｌ Ｍ Ｎ Ｏ Ｐ Ｑ Ｒ Ｓ Ｔ Ｕ Ｖ Ｗ Ｘ Ｙ Ｚ
put Upper::Full.translate: 'a'; # OUTPUT:
# Ａ

# But because we can achieve all this with static input alone, we can write a
# cheaper annotation.
module LowerPsychUpper {
    use annotations <declare direct class>;
    # Now the ANN buffer is purely a buffer. Direct annotations' ANN buffer is
    # a lower level construct compared to before; because we get references
    # over symbols, we generally need to track any value bound ourselves.

    annotation Full is repr<Uninstantiable> {
        # Note the RW array this time around.
        my constant @ALPHABET = $?CLASS annotate ['ａ'..'ｚ'];

        my constant %DICTIONARY = Map.new: LATIN Z=> @ALPHABET;

        method alphabet(::?CLASS: --> List:D) {
            @ALPHABET
        }

        method dictionary(::?CLASS: --> Map:D) {
            %DICTIONARY
        }

        method translate(::?CLASS: Str:D $letter --> Str) {
            %DICTIONARY{$letter}
        }
    }
}

# Unlike before, the RW containers provided by the RW array we annotated are
# preserved, so an assignment will carry through.
put LowerPsychUpper::Full.alphabet = Upper::Full.alphabet; # OUTPUT:
# Ａ Ｂ Ｃ Ｄ Ｅ Ｆ Ｇ Ｈ Ｉ Ｊ Ｋ Ｌ Ｍ Ｎ Ｏ Ｐ Ｑ Ｒ Ｓ Ｔ Ｕ Ｖ Ｗ Ｘ Ｙ Ｚ
put LowerPsychUpper::Full.translate: 'z'; # OUTPUT:
# Ｚ

# In this example, we have code resembling what's possible to write with OUR.
# Unlike a Stash in a WHO or a PseudoStash, ANN errs more toward order and
# immutability, but deconts of a Scalar are cheaper than those of a wrapper
# Proxy. An OUR-scoped value skips a call we need otherwise on top of this, and
# would thus be more efficient if the WHO Stash's inherent mutability is OK.

```

# DESCRIPTION

`annotations` is a collection of containers in a package trench coat. Through `MetamodelX::AnnotationHOW`, a `Positional` or `Associative` container may be associated with any kind of type, regardless of whether or not it actually can support stashing. These can be retrieved with `ANN`, and appended to via the infix `=`, `annotate`, and `graffiti` operators (see `t/02-direct.t` for an example of `graffiti`).

Importing `annotations` can either create an `annotation` declarator with `<declare>` or override another (e.g. `<role>`) with `<supersede>` (though this produces an erroneous deprecation warning as of v2020.07). As demonstrated, the `<direct>` and `<symbolic>` arguments determine the mode of assignment to a package's `ANN`. Finally, a package declarator must be provided in order to retrieve its HOW.

# AUTHOR

Ben Davies (Kaiepi)

# COPYRIGHT AND LICENSE

Copyright 2022 Ben Davies

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


## snapper.md
snapper

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Telemetry#routine_snapper)
for **routine snapper**.

```raku
sub snapper($sleep = 0.1, :$stop, :$reset --> Nil)
```

The `snapper` routine starts a separate thread that will call `snap` repeatedly until the end of program. It is exported by default.

By default, it will call `snap` every **0.1** second. The only positional parameter is taken to be the delay between `snap`s.

Please see the [snapper module](#module_snapper) for externally starting a snapper without having to change the code. Simply adding `-Msnapper` as a command line parameter, will then start a snapper for you.


## dist_zef-jjmerelo-IO-String.md
# IO::String [Test in a Raku container](https://github.com/JJ/raku-io-string/actions/workflows/test.yaml)

*This is a fork of the original
[IO::String](https://github.com/hoelzro/p6-io-string), which was archived, with
the intention of maintaining and releasing it again into the ecosystem*

## SYNOPSIS

```
        use IO::String;

        my $buffer = IO::String.new;
        {
            my $*OUT = $buffer;
            say "hello";
        }
        say ~$buffer; # hello

```

## DESCRIPTION

Sometimes you want to use code that deals with files (or other file-like
objects), but you don't want to mess around with creating temporary files. This
includes uses like APIs that for some reason don't accept strings as well as
files as targets, mocking I/O, or capturing output written to the
terminal. That's why this module exists. Loosely based on Perl 5's IO::String.

## TODO

* Input as well as output
* Handle encodings

## LICENSE

(c) `hoelzro`, 2017. Released under the MIT [license](LICENSE)


## dist_cpan-MELEZHIK-Sparrowdo-VSTS-YAML-MsBuild.md
# Sparrowdo::VSTS::YAML:MsBuild

Sparrowdo module to generate VSTS yaml steps for msbuild tool.

```
$ cat sparrowfile

module_run "VSTS::YAML::MsBuild", %(
  build-dir => "cicd/build",
  project   => "Database.sqlproj", # Relative path from repo root of the project(s) or solution(s) to run.
  configuration => "debug",  # Build configuration, default value
  platform => "any cpu", # Build platform, default value
  display-name => "Build app.csproj", # optional
);

$ sparrowdo --local_mode --no_sudo

```

# Parameters

## project

Relative path from repo root of the project(s) or solution(s) to run. Wildcards can be used. For example, \*\*/\*.csproj for all csproj files in all sub folders.

## configuration

Build configuration

## platform

Build platform

# See also

* Sparrowdo::VSTS::YAML::Solution
* Sparrowdo::VSTS::YAML::DotNet

# Author

Alexey Melezhik


## datetime.md
class DateTime

Calendar date with time

```raku
class DateTime does Dateish {}
```

For handling points in civil time, a `DateTime` object stores year, month, day, hour, minute (all [`Int`](/type/Int)), second (potentially fractional) and a time zone.

It provides methods for calculating with date (for the Gregorian calendar) and time.

`DateTime` methods are immutable; if you are tempted to modify one, create a modified copy instead.

Time zones are handled as [`Int`](/type/Int)s in **seconds** offset from UTC, not by time zone name.

```raku
my $dt = DateTime.new(
    year    => 2015,
    month   => 11,
    day     => 21,
    hour    => 16,
    minute  => 1,
);

say $dt;                            # OUTPUT: «2015-11-21T16:01:00Z␤»
say $dt.later(days => 20);          # OUTPUT: «2015-12-11T16:01:00Z␤»
say $dt.truncated-to('hour');       # OUTPUT: «2015-11-21T16:00:00Z␤»
say $dt.in-timezone(-8 * 3600);     # OUTPUT: «2015-11-21T08:01:00-0800␤»

my $now = DateTime.now(formatter => { sprintf "%02d:%02d", .hour, .minute });
say $now;                           # 12:45 (or something like that)

```

Since version 6.d, using synthetic codepoints such as 7̈ will result in an error.

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

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

```raku
multi method new(Int :$year!, Int :$month = 1, Int :$day = 1,
                 Int :$hour = 0, Int :$minute = 0, :$second = 0,
                 Int :$timezone = 0, :&formatter)
multi method new(Date :$date!,
                 Int :$hour = 0, Int :$minute = 0, :$second = 0,
                 Int :$timezone = 0, :&formatter)
multi method new(Int() $year, Int() $month, Int() $day,
                 Int() $hour, Int $minute, $second,
                 Int() :$timezone = 0, :&formatter)
multi method new(Instant:D $i,  :$timezone=0, :&formatter)
multi method new(Numeric:D $posix,  :$timezone=0, :&formatter)
multi method new(Str:D $format, :$timezone=0, :&formatter)

```

Creates a new `DateTime` object. One option for creating a new DateTime object is from the components (year, month, day, hour, ...) separately. Another is to pass a [`Date`](/type/Date) object for the date component, and specify the time component-wise. Yet another is to obtain the time from an [`Instant`](/type/Instant), and only supply the time zone and formatter. Or instead of an Instant you can supply a [`Numeric`](/type/Numeric) as a UNIX timestamp.

You can also supply a [`Str`](/type/Str) formatted in ISO 8601 timestamp notation or as a full [RFC 3339](https://tools.ietf.org/html/rfc3339) date and time. Strings should be formatted as `yyyy-mm-ddThh:mm:ssZ` or `yyyy-mm-ddThh:mm:ss+0100`. We are somewhat less restrictive than the ISO 8601 standard, as we allow Unicode digits and mixing of condensed and extended time formats.

An invalid input string throws an exception of type [`X::Temporal::InvalidFormat`](/type/X/Temporal/InvalidFormat). If you supply a string that includes a time zone and supply the `timezone` named argument, an exception of type [`X::DateTime::TimezoneClash`](/type/X/DateTime/TimezoneClash) is thrown.

```raku
my $datetime = DateTime.new(year => 2015,
                            month => 1,
                            day => 1,
                            hour => 1,
                            minute => 1,
                            second => 1,
                            timezone => 1);
$datetime = DateTime.new(date => Date.new('2015-12-24'),
                         hour => 1,
                         minute => 1,
                         second => 1,
                         timezone => 1);
$datetime = DateTime.new(2015, 1, 1, # First January of 2015
                         1, 1, 1);   # Hour, minute, second with default time zone
$datetime = DateTime.new(now);                       # Instant.
# from a Unix timestamp
say $datetime = DateTime.new(1470853583.3);          # OUTPUT: «2016-08-10T18:26:23.300000Z␤»
$datetime = DateTime.new("2015-01-01T03:17:30+0500") # Formatted string
```

Since Rakudo release 2022.03, the `day` parameter can be a [`Callable`](/type/Callable), with `*` returning the last day in the month, and `*-n` returning the last but `n`.

Since Rakudo release 2022.07, it is also possible to just specify a "YYYY-MM-DD" string to indicate midnight on the given date.

```raku
say DateTime.new("2023-03-04");  # OUTPUT: «2023-03-04T00:00:00Z␤»
```

## [method now](#class_DateTime "go to top of document")[§](#method_now "direct link")

```raku
method now(:$timezone = $*TZ, :&formatter --> DateTime:D)
```

Creates a new `DateTime` object from the current system time. A custom [formatter](/routine/formatter) and [timezone](/routine/timezone) can be provided. The `:$timezone` is the offset **in seconds** from [GMT](https://en.wikipedia.org/wiki/Greenwich_Mean_Time) and defaults to the value of [`$*TZ` variable](/language/variables#index-entry-%24*TZ).

```raku
say DateTime.now; # OUTPUT: «2018-01-08T13:05:32.703292-06:00␤»
```

Note that one may use the methods shown below chained to the `.now` to easily express current values, e.g.,

```raku
say DateTime.now.year; # OUTPUT: «2018␤»
```

## [method clone](#class_DateTime "go to top of document")[§](#method_clone "direct link")

```raku
method clone(DateTime:D: :$year, :$month, :$day, :$hour, :$minute, :$second, :$timezone, :&formatter)
```

Creates a new `DateTime` object based on the invocant, but with the given arguments overriding the values from the invocant.

```raku
say DateTime.new('2015-12-24T12:23:00Z').clone(hour => 0);
# OUTPUT: «2015-12-24T00:23:00Z␤»
```

Note that this can lead to invalid dates in some circumstances:

```raku
say DateTime.new("2012-02-29T12:34:56Z").clone(year => 2015);
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::OutOfRange: Day out of range. Is: 29, should be in 1..28␤»
```

## [method hh-mm-ss](#class_DateTime "go to top of document")[§](#method_hh-mm-ss "direct link")

```raku
method hh-mm-ss(DateTime:D: --> Str:D)
```

Returns the time represented by the object as a string in 24-hour HH:MM:SS format:

```raku
say DateTime.new("2052-02-29T22:34:56Z").hh-mm-ss;
# OUTPUT: «22:34:56␤»
```

## [method hour](#class_DateTime "go to top of document")[§](#method_hour "direct link")

```raku
method hour(DateTime:D: --> Int:D)
```

Returns the hour component.

```raku
say DateTime.new('2012-02-29T12:34:56Z').hour;      # OUTPUT: «12␤»
```

## [method minute](#class_DateTime "go to top of document")[§](#method_minute "direct link")

```raku
method minute(DateTime:D: --> Int:D)
```

Returns the minute component.

```raku
say DateTime.new('2012-02-29T12:34:56Z').minute;     # OUTPUT: «34␤»
```

## [method second](#class_DateTime "go to top of document")[§](#method_second "direct link")

```raku
method second(DateTime:D:)
```

Returns the second component, including potentially fractional seconds.

```raku
say DateTime.new('2012-02-29T12:34:56Z').second;     # OUTPUT: «56␤»
say DateTime.new('2012-02-29T12:34:56.789Z').second; # OUTPUT: «56.789␤»
say DateTime.new('2012-02-29T12:34:56,789Z').second; # comma also ok
```

## [method whole-second](#class_DateTime "go to top of document")[§](#method_whole-second "direct link")

```raku
method whole-second(DateTime:D:)
```

Returns the second component, rounded down to an [`Int`](/type/Int).

```raku
say DateTime.new('2012-02-29T12:34:56.789Z').whole-second;      # OUTPUT: «56␤»
```

## [method timezone](#class_DateTime "go to top of document")[§](#method_timezone "direct link")

```raku
method timezone(DateTime:D: --> Int:D)
```

Returns the time zone **in seconds** as an offset from UTC.

```raku
say DateTime.new('2015-12-24T12:23:00+0200').timezone;          # OUTPUT: «7200␤»
```

## [method offset](#class_DateTime "go to top of document")[§](#method_offset "direct link")

```raku
method offset(DateTime:D: --> Int:D)
```

Returns the time zone **in seconds** as an offset from UTC. This is an alias for [method timezone](#method_timezone).

```raku
say DateTime.new('2015-12-24T12:23:00+0200').offset;            # OUTPUT: «7200␤»
```

## [method offset-in-minutes](#class_DateTime "go to top of document")[§](#method_offset-in-minutes "direct link")

```raku
method offset-in-minutes(DateTime:D: --> Real:D)
```

Returns the time zone in minutes as an offset from UTC.

```raku
say DateTime.new('2015-12-24T12:23:00+0200').offset-in-minutes; # OUTPUT: «120␤»
```

## [method offset-in-hours](#class_DateTime "go to top of document")[§](#method_offset-in-hours "direct link")

```raku
method offset-in-hours(DateTime:D: --> Real:D)
```

Returns the time zone in hours as an offset from UTC.

```raku
say DateTime.new('2015-12-24T12:23:00+0200').offset-in-hours;   # OUTPUT: «2␤»

```

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

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

Returns a string representation of the invocant, as done by [the formatter](/type/Dateish#method_formatter). If no formatter was specified, an ISO 8601 timestamp will be returned.

```raku
say DateTime.new('2015-12-24T12:23:00+0200').Str;
# OUTPUT: «2015-12-24T12:23:00+02:00␤»

```

## [method Instant](#class_DateTime "go to top of document")[§](#method_Instant "direct link")

```raku
method Instant(DateTime:D: --> Instant:D)
```

Returns an [`Instant`](/type/Instant) object based on the invocant.

```raku
say DateTime.new('2015-12-24T12:23:00+0200').Instant; # OUTPUT: «Instant:1450952616␤»
```

## [method Real](#class_DateTime "go to top of document")[§](#method_Real "direct link")

```raku
multi method Real(DateTime:D: --> Instant:D)
```

Converts the invocant to [`Instant`](/type/Instant). The same value can be obtained with the [`Instant`](/type/Instant) method.

Available as of release 2023.02 of the Rakudo compiler.

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

```raku
multi method Numeric(DateTime:D: --> Instant:D)
```

Available as of the 2021.09 release of the Rakudo compiler.

Converts the invocant to [`Instant`](/type/Instant). The same value can be obtained with the [`Instant`](/type/Instant) method. This allows `DateTime` objects to be used directly in arithmetic operations.

## [method day-fraction](#class_DateTime "go to top of document")[§](#method_day-fraction "direct link")

```raku
method day-fraction(DateTime:D: --> Real:D)
```

Returns the instant's time as a fraction of a 24-hour day.

```raku
say DateTime.new('2021-12-24T12:23:00.43Z').day-fraction; # OUTPUT: «0.5159772␤»
```

Notice the `day-fraction` value is the same as the fractional part of the `modified-julian-date` for the same instant.

Available as of the 2021.04 Rakudo compiler release.

## [method julian-date](#class_DateTime "go to top of document")[§](#method_julian-date "direct link")

```raku
method julian-date(DateTime:D: --> Real:D)
```

Returns the [Julian date](https://en.wikipedia.org/wiki/Julian_day) (JD) for the UTC date and time.

```raku
say DateTime.new('2021-12-24T12:23:00.43Z').julian-date; # OUTPUT: «2459573.0159772␤»
```

The `julian-date` starts at zero at the epoch of noon UTC on *November 24, 4714 B.C.* on the [proleptic](https://en.m.wiktionary.org/wiki/proleptic) Gregorian calendar (the calendar in use in much of the world and in international commerce and travel). The JD is used in astronomy to define times of celestial objects transiting the Earth's Prime Meridian. For any instant, it is the sum of the number of whole days and the fraction of a day from that epoch to that instant.

Available as of the 2021.04 Rakudo compiler release.

## [method modified-julian-date](#class_DateTime "go to top of document")[§](#method_modified-julian-date "direct link")

```raku
method modified-julian-date(DateTime:D: --> Real:D)
```

Returns the [Modified Julian Date](https://en.wikipedia.org/wiki/Julian_day) (MJD) for the UTC date and time.

```raku
say DateTime.new('2021-12-24T12:23:00.43Z').modified-julian-date; # OUTPUT: «59572.5159772␤»
```

Notice the fractional part of the `modified-julian-date` is same value as the `day-fraction` for the same instant. Likewise, the integral part of the *MJD* is the same value as the `daycount` for the same instant since they reference the same epoch (November 17, 1858). The MJD is obtained by subtracting the constant `2_400_000.5` from the *Julian Date* and is used to simplify transformations between civil and astronomical time systems.

Available as of the 2021.04 Rakudo compiler release.

## [method posix](#class_DateTime "go to top of document")[§](#method_posix "direct link")

```raku
method posix(Bool:D: $ignore-timezone = False --> Int:D)
```

Returns the date and time as a POSIX/UNIX timestamp (integral seconds since the POSIX epoch, 1970-01-01T00:00:00Z).

If `$ignore-timezone` is `True`, the `DateTime` object will be treated as if the time zone offset is zero.

```raku
method posix(Bool:D: $ignore-timezone = False, :$real --> Num:D)
```

As of release 2022.06 of the Rakudo compiler, it is also possible to specify a `:real` named argument. If specified with a true value, a [`Num`](/type/Num) will be returned, allowing for sub-second accuracy of the number of seconds since the POSIX epoch.

```raku
say DateTime.new('2015-12-24T12:23:00Z').posix;           # OUTPUT: «1450959780␤»
say DateTime.new('2022-06-21T12:23:00.5Z').posix;         # OUTPUT: «1655814180␤»
say DateTime.new('2022-06-21T12:23:00.5Z').posix(:real);  # OUTPUT: «1655814180.5␤»

```

## [method truncated-to](#class_DateTime "go to top of document")[§](#method_truncated-to "direct link")

```raku
method truncated-to(DateTime:D: Cool $unit)
```

Returns a copy of the invocant, with everything smaller than the specified unit truncated to the smallest possible value.

```raku
my $d = DateTime.new("2012-02-29T12:34:56.946314Z");
say $d.truncated-to('second');      # OUTPUT: «2012-02-29T12:34:56Z␤»
say $d.truncated-to('minute');      # OUTPUT: «2012-02-29T12:34:00Z␤»
say $d.truncated-to('hour');        # OUTPUT: «2012-02-29T12:00:00Z␤»
say $d.truncated-to('day');         # OUTPUT: «2012-02-29T00:00:00Z␤»
say $d.truncated-to('month');       # OUTPUT: «2012-02-01T00:00:00Z␤»
say $d.truncated-to('year');        # OUTPUT: «2012-01-01T00:00:00Z␤»
```

DateTimes with fractional seconds can be truncated to whole seconds with `.truncated-to('second')`.

## [method Date](#class_DateTime "go to top of document")[§](#method_Date "direct link")

```raku
multi method Date(DateTime:U --> Date:U)
multi method Date(DateTime:D --> Date:D)
```

Converts the invocant to [`Date`](/type/Date).

```raku
say DateTime.new("2012-02-29T12:34:56.946314Z").Date; # OUTPUT: «2012-02-29␤»
say DateTime.Date;                                    # OUTPUT: «(Date)␤»

```

## [method DateTime](#class_DateTime "go to top of document")[§](#method_DateTime "direct link")

```raku
method DateTime(--> DateTime)
```

Returns the invocant.

```raku
say DateTime.new("2012-02-29T12:34:56.946314Z").DateTime;
# OUTPUT: «2012-02-29T12:34:56.946314Z␤»
say DateTime.DateTime;
# OUTPUT: «(DateTime)␤»
```

## [method utc](#class_DateTime "go to top of document")[§](#method_utc "direct link")

```raku
method utc(DateTime:D: --> DateTime:D)
```

Returns a DateTime object for the same time, but in time zone UTC.

```raku
say DateTime.new('2015-12-24T12:23:00+0200').utc;
# OUTPUT: «2015-12-24T10:23:00Z␤»
```

## [method in-timezone](#class_DateTime "go to top of document")[§](#method_in-timezone "direct link")

```raku
method in-timezone(DateTime:D: Int(Cool) $timezone = 0 --> DateTime:D)
```

Returns a DateTime object for the same time, but in the specified `$timezone`, which is the offset **in seconds** from [GMT](https://en.wikipedia.org/wiki/Greenwich_Mean_Time).

```raku
say DateTime.new('2015-12-24T12:23:00Z').in-timezone(3600 + 1800); # OUTPUT: «2015-12-24T13:53:00+0130␤»
```

Per [RFC 7164](https://tools.ietf.org/html/rfc7164#section-3), leap seconds do not respect local time and always occur at the end of the *UTC* day:

```raku
say DateTime.new: '2017-01-01T00:59:60+01:00'
# OUTPUT: «2017-01-01T00:59:60+01:00␤»
```

## [method local](#class_DateTime "go to top of document")[§](#method_local "direct link")

```raku
method local(DateTime:D: --> DateTime:D)
```

Returns a DateTime object for the same time, but in the local time zone ([`$*TZ`](/language/variables#index-entry-%24*TZ)).

```raku
my $*TZ = -3600;
say DateTime.new('2015-12-24T12:23:00+0200').local; # OUTPUT: «2015-12-24T09:23:00-0100␤»
```

## [sub infix:<->](#class_DateTime "go to top of document")[§](#sub_infix:<-> "direct link")

```raku
multi infix:<-> (DateTime:D, Duration:D --> DateTime:D)
multi infix:<-> (DateTime:D, DateTime:D --> Duration:D)
```

Takes a `DateTime` to subtract from and either a [`Duration`](/type/Duration) or another `DateTime` object. Returns a new `DateTime` object or the [`Duration`](/type/Duration) between the two dates, respectively. When subtracting [`Duration`](/type/Duration), time zone of the original `DateTime` is preserved in the returned `DateTime` object.

```raku
say raku DateTime.new(:2016year) - DateTime.new(:2015year):;
# OUTPUT: «Duration.new(31536001.0)␤»
say DateTime.new(:2016year, :3600timezone) - Duration.new(31536001.0);
# OUTPUT: «2015-01-01T00:00:00+01:00␤»
```

## [sub infix:<+>](#class_DateTime "go to top of document")[§](#sub_infix:<+> "direct link")

```raku
multi infix:<+> (DateTime:D, Duration:D --> DateTime:D)
multi infix:<+> (Duration:D, DateTime:D --> DateTime:D)
```

Takes a `DateTime` and increases it by the given [`Duration`](/type/Duration), preserving the time zone.

```raku
say DateTime.new(:2015year) + Duration.new(31536001.0);
# OUTPUT: «2016-01-01T00:00:00Z␤»
say Duration.new(42) + DateTime.new(:2015year, :3600timezone);
# OUTPUT: «2015-01-01T00:00:42+01:00␤»
```

## [sub infix:<cmp>](#class_DateTime "go to top of document")[§](#sub_infix:<cmp> "direct link")

```raku
multi infix:<cmp>(DateTime:D \a, DateTime:D \b --> Order:D)
```

Compares the equivalent instant, returns the Order.

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

Type relations for `DateTime`

raku-type-graph

DateTime
DateTime

Any
Any

DateTime->Any

Dateish
Dateish

DateTime->Dateish

Mu
Mu

Any->Mu

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


## dist_cpan-ALOREN-App-FindSource.md
# perl6-app-findsource

Find your source file easily.

# USAGE

```
$ fs -h
Usage:
/home/*/.perl6/bin/fs [add|list|remove] [-l=<array>] [-w=<array>] [-a=<array>] [-i] [-no=<array>] [-only=<string>] [-d|--debug] <directory>

-l=<array>     load specify config, available config are < perl make cpp cfg >.

-w=<array>     match whole filename.

-a=<array>     addition extension list.

-i             enable ignore case mode.

-no=<array>    exclude file category.

-only=<string> only search given category.

-d|--debug     print debug message.

```

## config

The config use json format, it contain the option will add categories to command line.
In the config, you also can append value to `-w` or `-a`.

### cpp.json

```
{
	"option" : [
		{
			"short" : "c",
			"value" : [ "c" ],
			"annotation" : "c source file extension list. "
		},
		{
			"short" : "h",
			"value" : [ "h" ],
			"annotation" : "c/c++ header file extension list. "
		}
	]
}

```

`short` is the category option will added.

`value` is the default value of the category, it will append the value to the category if the category exists.

## load the config

Use `-l cpp` to load the config, it will add `-h=<array>` and `-c=<array>` to `fs` command line.

```
$ fs -l cpp -h
Usage:
/home/*/.perl6/bin/fs [add|list|remove] [-l=<array>] [-w=<array>] [-a=<array>] [-i] [-no=<array>] [-only=<string>] [-d|--debug] [-c=<array>] [-cpp=<array>] [-h=<array>] <directory>

-l=<array>     load specify config, available config are < perl make cpp cfg >.

-w=<array>     match whole filename.

-a=<array>     addition extension list.

-i             enable ignore case mode.

-no=<array>    exclude file category.

-only=<string> only search given category.

-d|--debug     print debug message.

-c=<array>     c source file extension list. [c]

-h=<array>     c/c++ header file extension list. [h]

```

## do search

Add an argument specify the directory you want searched.

```
$ fs ../rakudo/tmp/rakudo/src/vm -l cpp
"../rakudo/tmp/rakudo/src/vm/moar/ops/perl6_ops.c"
"../rakudo/tmp/rakudo/src/vm/moar/ops/container.h"
"../rakudo/tmp/rakudo/src/vm/moar/ops/container.c"

```

## add extension to category

You can add additional file extension to category.

```
$ fs ../rakudo/tmp/rakudo/src/vm -l cpp -a java
"../rakudo/tmp/rakudo/src/vm/moar/ops/perl6_ops.c"
"../rakudo/tmp/rakudo/src/vm/moar/ops/container.h"
"../rakudo/tmp/rakudo/src/vm/moar/ops/container.c"
"../rakudo/tmp/rakudo/src/vm/jvm/runtime/org/perl6/rakudo/RakudoContainerSpec.java"
"../rakudo/tmp/rakudo/src/vm/jvm/runtime/org/perl6/rakudo/RakudoContainerConfigurer.java"
"../rakudo/tmp/rakudo/src/vm/jvm/runtime/org/perl6/rakudo/RakOps.java"
"../rakudo/tmp/rakudo/src/vm/jvm/runtime/org/perl6/rakudo/RakudoJavaInterop.java"
"../rakudo/tmp/rakudo/src/vm/jvm/runtime/org/perl6/rakudo/RakudoEvalServer.java"
"../rakudo/tmp/rakudo/src/vm/jvm/runtime/org/perl6/rakudo/Binder.java"

```

## add | remove | list config

You can add your own config to configuration directory.

List current configuration file:

```
$ fs list
cfg.json
perl.json
cpp.json
make.json

```

# Installation

`zef install App::FindSource`

# License

GPL

# Author

araraloren (blackcatoverwall#gmail.com)


## dist_github-arnsholt-Net-ZMQ.md
# Net::ZMQ

Net::ZMQ is a Perl 6 library that may be used to interact with ZeroMQ
library.

```
use Net::ZMQ4;            # Your main import
use Net::ZMQ4::Constants; # Basic constants

my Net::ZMQ4::Context $ctx .= new;

my Net::ZMQ4::Socket $Rize .= new($ctx, ZMQ_PULL);
$Rize.bind("tcp://127.0.0.1:2910");
my Net::ZMQ4::Socket $Sharo .= new($ctx, ZMQ_PUSH);
$Sharo.connect("tcp://127.0.0.1:2910");

# Single message
$Sharo.send('Kuru Kuru');
# Splitted message
$Sharo.sendmore('Cats', 'Dogs', 'Rabbits');

my $msg = $Rize.receive; # Pure ZMQ message
say $msg.data;           # bytes
say $msg.data-str;       # 'Kuru Kuru'
$msg.close;              # Don't forget to close your messages!

# Multi-receive
loop {
    my $msg = $Rize.receive(0); # Can take flags as arguments, 0 is default
    say $msg.data-str;
    $msg.close;
    unless $Rize.getopt(ZMQ_RCVMORE) == 1 {
        last; # If there are no pieces
    }
}
# Says:
# Cats
# Dogs
# Rabbits

```

# Supported version

Main supported ZMQ version is 4.1. Support of 4.2 is planned.

# Issues

If you noticed a bug, have a desire to see some feature implemented,
feel free to open a ticket on github's
[issues](https://github.com/arnsholt/Net-ZMQ/issues) page of the
project.

# Authors

The library was written by Arne
Skjærholt([arnsholt](https://github.com/arnsholt) on github) with a
help of many others(see
[Contributors](https://github.com/arnsholt/Net-ZMQ/graphs/contributors)
page).

[Altai-man](https://github.com/Altai-man) made small cosmetic changes
too.

# Contributing

The project is still relatively unstable and thus wants some love. :)
All new issues and pull requests are welcome.

Efforts may be spend on:

* Want to support a legacy version? Write a compatibility layer for
  the version you want as, for example, ZMQX::Compat, where `X` can be
  desired version.
* If you feel like a strong mage, you can try your luck with improving
  library's stability. Catch segfaults, fix memory leaks - any
  improvements in this difficult field will be greatly appreciated.
* Want to help project while writing Perl 6? Contribute examples!
* Spotted a typo in this README? Want to write more documentation?
  Feel free to pull request additional docs!


## sampler.md
class Telemetry::Sampler

Telemetry instrument pod

```raku
class Telemetry::Sampler { }

```

**Note:**  This class is a Rakudo-specific feature and not standard Raku.

```raku
use Telemetry;
$*SAMPLER.set-instruments(<Usage ThreadPool>); # default setting

```

One usually does not create any `Telemetry::Sampler` objects: when the [`Telemetry`](/type/Telemetry) module is loaded, a `Telemetry::Sampler` object is automatically created in the `$*SAMPLER` dynamic variable.

An object of the `Telemetry::Sampler` class knows about which instruments to use when making a snapshot.

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

```raku
method new(Telemetry::Sampler: @instruments --> Telemetry::Sampler:D)

```

The `new` method takes a list of instruments. If no instruments are specified, then it will look at the `RAKUDO_TELEMETRY_INSTRUMENTS` environment variable to find specification of instruments. If that is not available either, then [`Telemetry::Instrument::Usage`](/type/Telemetry/Instrument/Usage) and [`Telemetry::Instrument::ThreadPool`](/type/Telemetry/Instrument/ThreadPool) will be assumed.

Instruments can be specified by either the type object of the instrument class (e.g. [`Telemetry::Instrument::Usage`](/type/Telemetry/Instrument/Usage)) or by a string, in which case it will be automatically prefixed with "Telemetry::Instrument::", so "Usage" would be the same as [`Telemetry::Instrument::Usage`](/type/Telemetry/Instrument/Usage).

## [method set-instruments](#class_Telemetry::Sampler "go to top of document")[§](#method_set-instruments "direct link")

```raku
method set-instruments(Telemetry::Sampler:D @instruments --> Nil)

```

Allows one to change the instruments on an existing `Instrument::Sampler` object. Generally only used by calling it on the `$*SAMPLER` dynamic variable. Takes the same parameters as [new](/routine/new), except that specifying **no** instruments will actually remove all of the instruments, effectively blocking any snap taking.


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

# NAME

Backtrace::Files - turn backtrace into list of files / lines

# SYNOPSIS

```
use Backtrace::Files;

.say for backtrace-files($backtrace, :context(2));

say normalize-backtrace-filename("SETTING::src/core.c/Cool.rakumod");

.say for add-source-lines(@backtrace);

```

# DESCRIPTION

Backtrace::Files attempts to provide an abstract interface to backtraces and the files and line numbers in those backtraces, with the `backtrace-files` subroutine. Backtraces can be given as a string, or as an `Exception` object.

It also provides two helper subroutines: one for normalizing filenames to a local system installation (with references to the Rakudo core, and references to installed modules) called `normalize-backtrace-filename`.

And another called `add-source-lines` that will fetch the source lines of a given list of filename / line-numbers pairs, with potential context lines added.

# SELECTIVE IMPORTING

```
use Backtrace::Files <backtrace-files>;  # only export sub backtrace-files

```

By default all subroutines are exported. But you can limit this to the functions you actually need by specifying the names in the `use` statement.

To prevent name collisions and/or import any subroutine with a more memorable name, one can use the "original-name:known-as" syntax. A semi-colon in a specified string indicates the name by which the subroutine is known in this distribution, followed by the name with which it will be known in the lexical context in which the `use` command is executed.

```
# export "backtrace-files" as "btf"
use Backtrace::Files <backtrace-files:btf>;

.say for btf($backtrace, :context(2));

```

# EXPORTED SUBROUTINES

## backtrace-files

```
# show file / linenrs of given backtrace
for backtrace-files($backtrace) -> (:key($file), :value(@lines)) {
    say "$file: @lines.join(',')";
}

# show file / linenrs / actual lines of given backtrace
for backtrace-files($backtrace, :source) -> (:key($file), :value(@lines)) {
    say "$file:";
    for @lines -> (:key($linenr), :value($line)) {
        say "$linenr: $line";
    }
    say "";
}

```

The `backtrace-files` subroutine accepts a single positional argument, the source of the backtrace information. This can either be an `Exception`, a `IO::Handle` object, an `IO::Path` object, or a string.

By default, the `backtrace-files` subroutine produces a list of `Pair`s of which the key is the absolute filename, and the value is a list of line numbers of consecutive frames within the same file. Please note that the same filename can occur more than once, if not all calls to code in a file where consecutive in the backtrace.

The following optional named arguments can be specified to include the actual source of the lines as well:

### :source

Indicates whether the actual source of the lines referred to in the backtrace, should be included as well. If specified with a true value, then each line number will be converted into a `Pair` with the line number as the key, and the actual line as the value (or an empty string if the line could not be obtained for whatever reason).

### :context(N)

Indicates whether extra source lines should be added before and after the actual line number of the backtrace. Only makes sense if `:source` has been specified with a true value. If specified, indicates the number of lines that should be added before and after, as additional `Pair`s in the array keyed to the filename. Defaults to no lines being added.

### :before-context(N)

Indicates whether extra source lines should be added **before** the actual line number of the backtrace. Only makes sense if `:source` has been specified with a true value. If specified, indicates the number of lines that should be added before, as additional `Pair`s in the array keyed to the filename. Defaults to whatever was (implicitely) specified with `:context`.

### :after-context(N)

Indicates whether extra source lines should be added **after** the actual line number of the backtrace. Only makes sense if `:source` has been specified with a true value. If specified, indicates the number of lines that should be added after, as additional `Pair`s in the array keyed to the filename. Defaults to whatever was (implicitely) specified with `:context`.

### :in-backtrace(Type)

Indicates the actual type that should be used to create `Pair`s of line number and actual source for lines that actually occurred in the backtrace. Only makes sense if `:source` has been specified with a true value. Defaults to `Pair`.

### :added-context(Type)

Indicates the actual type that should be used to create `Pair`s of line number and actual source for lines that actually occurred in the backtrace. Only makes sense if `:source` has been specified with a true value. Defaults to `Pair`.

## normalize-backtrace-filename

```
say normalize-backtrace-filename("SETTING::src/core.c/Cool.rakumod");

```

The `normalize-backtrace-filename` subroutine is a utility subroutine that accepts a string consisting of a filename from a backtrace, and converts this to an actual filename if the file mentioned was a conceptual filename or a filename known to have missing information.

It is intended for situations where e.g. a `CATCH` block would look at the backtrace to produce a list of actual filenames.

## add-source-lines

```
for add-source-lines($file, (10, 20)) -> (:key($file), :value(@pairs)) {
    say $file;
    for @pairs -> (:key($linenr), :value($source)) {
        say "$linenr:$source"
    }
}

```

The `add-source-lines` subroutine is a utility subroutine that will fetch the source lines indicated by pair(s) of filename and line number lists. It either accepts a filename and a list of line numbers, or a `Pair` consisting of a filename as key and a list of line numbers as value, or it accepts a list of `Pair`s with filename a list of line numbers.

It also accepts the `:context`, `:before-context`, `:after-context`, `:in-backtrace` and `:added-context` named arguments, with the same defaults as documented with the `backtrace-files` subroutine.

# AUTHOR

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

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

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

# COPYRIGHT AND LICENSE

Copyright 2022, 2024 Elizabeth Mattijsen

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


## dist_cpan-AZAWAWI-Wkhtmltox.md
# Wkhtmltox

[![Build Status](https://travis-ci.org/azawawi/perl6-wkhtmltox.svg?branch=master)](https://travis-ci.org/azawawi/perl6-wkhtmltox) [![Build status](https://ci.appveyor.com/api/projects/status/github/azawawi/perl6-wkhtmltox?svg=true)](https://ci.appveyor.com/project/azawawi/perl6-wkhtmltox/branch/master)

This modules converts HTML code to PDF or Image files using [`libwkhtmltox`](https://wkhtmltopdf.org/libwkhtmltox/) (aka `wkhtmltopdf`, `wkhtmltoimage`). It does not run `wkhtmltopdf` or `wkhtmltoimage` binaries thus
no extra CPU/memory cost for each conversion operation. It is suitable for batch
HTML to PDF/Image conversions.

**Note: This is currently experimental and API may change. Please DO NOT use in
a production environment.**

## Example

```
# Print library version
my $version = Wkhtmltox::PDF.version;
say "wkhtmltopdf version: $version";

# Create pdf object
my $pdf = Wkhtmltox::PDF.new;

# Print global setting values
say $pdf.get-global-setting("size.pageSize");

# Set global settings values
$pdf.set-global-setting("size.pageSize", "A4");

# Convert HTML to PDF
my $html = "Perl 6 rocks!";
my $pdf-blob = $pdf.render($html);
"sample.pdf".IO.spurt($pdf-blob) if $pdf-blob.defined;

# Call only once to cleanup resources
$pdf.destroy;

```

## Installation

* Please [download](https://wkhtmltopdf.org/downloads.html) & install
  `libwkhtmltox` binaries.
* Install this module using [zef](https://github.com/ugexe/zef):

```
$ zef install Wkhtmltox

```

## Testing

* To run tests:

```
$ prove -ve "perl6 -Ilib"

```

* To run all tests including author tests (Please make sure
  [Test::Meta](https://github.com/jonathanstowe/Test-META) is installed):

```
$ zef install Test::META
$ AUTHOR_TESTING=1 prove -e "perl6 -Ilib"

```

## Author

Ahmad M. Zawawi, [azawawi](https://github.com/azawawi/) on #perl6

## License

MIT License


## repository.md
role CompUnit::Repository

CompUnit::Repository

The `CompUnit::Repository` role defines the interface of the implementation of CompUnit::Repositories such as [`CompUnit::Repository::Installation`](/type/CompUnit/Repository/Installation) and [`CompUnit::Repository::FileSystem`](/type/CompUnit/Repository/FileSystem).

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

## [method resolve](#role_CompUnit::Repository "go to top of document")[§](#method_resolve "direct link")

```raku
method resolve(CompUnit::DependencySpecification $spec --> CompUnit:D)
```

Returns a [`CompUnit`](/type/CompUnit) mapped to the highest version distribution matching `$spec` from the first repository in the repository chain that contains any version of a distribution matching `$spec`.

## [method need](#role_CompUnit::Repository "go to top of document")[§](#method_need "direct link")

Loads and returns a [`CompUnit`](/type/CompUnit) which is mapped to the highest version distribution matching `$spec` from the first repository in the repository chain that contains any version of a distribution matching `$spec`.

## [method load](#role_CompUnit::Repository "go to top of document")[§](#method_load "direct link")

```raku
method load(IO::Path:D $file --> CompUnit:D)
```

Load the `$file` and return a [`CompUnit`](/type/CompUnit) object representing it.

## [method loaded](#role_CompUnit::Repository "go to top of document")[§](#method_loaded "direct link")

```raku
method loaded(--> Iterable:D)
```

Returns all [`CompUnit`](/type/CompUnit)s this repository has loaded.


## socket.md
role IO::Socket

Network socket

```raku
role IO::Socket { ... }
```

`IO::Socket` contains read and write methods for sockets. It is usually used through [`IO::Socket::INET`](/type/IO/Socket/INET).

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

## [method recv](#role_IO::Socket "go to top of document")[§](#method_recv "direct link")

```raku
method recv(IO::Socket:D: Cool $elems = Inf, :$bin)
```

Receive a packet and return it, either as a [`Blob`](/type/Blob) if `:bin` was passed, or a [`Str`](/type/Str) if not. Receives up to `$elems` or `65535` (whichever is smaller) bytes or characters.

If the socket has previously been read from in non-`:bin` mode, it's not always safe to read from it in `:bin` mode again. Depending on the decoder it's possible for the `:bin` read to skip over bytes that the decoder has read ahead messing up the order of bytes and chars. This effect can occur with the UTF-8 decoder and if the previously decoded char could still receive combiners.

In Rakudo versions prior to 2024.07 mixing of binary and non-binary reads is unsupported.

Fails if the socket is not connected.

## [method read](#role_IO::Socket "go to top of document")[§](#method_read "direct link")

```raku
method read(IO::Socket:D: Int(Cool) $bytes)
```

Reads `$bytes` bytes from the socket and returns them in a [`Blob`](/type/Blob).

The same caveat of mixed binary and non-binary reads described in [method recv](#method_recv) applies.

Fails if the socket is not connected.

## [routine get](#role_IO::Socket "go to top of document")[§](#routine_get "direct link")

```raku
method get(IO::Socket:D: --> Str:D)
```

Reads a single line of input from the socket, removing the trailing newline characters (as set by [`.nl-in`](/routine/nl-in)). Returns [`Nil`](/type/Nil), if no more input is available.

Fails if the socket is not connected.

## [method print](#role_IO::Socket "go to top of document")[§](#method_print "direct link")

```raku
method print(IO::Socket:D: Str(Cool) $string)
```

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

Fails if the socket is not connected.

## [method write](#role_IO::Socket "go to top of document")[§](#method_write "direct link")

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

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

Fails if the socket is not connected.

## [method put](#role_IO::Socket "go to top of document")[§](#method_put "direct link")

```raku
method put(IO::Socket:D: Str(Cool) $string)
```

Writes the supplied string, with a `\n` appended to it, to the socket, thus sending it to other end of the connection.

Fails if the socket is not connected.

## [method close](#role_IO::Socket "go to top of document")[§](#method_close "direct link")

```raku
method close(IO::Socket:D)
```

Closes the socket.

Fails if the socket is not connected.

## [method native-descriptor](#role_IO::Socket "go to top of document")[§](#method_native-descriptor "direct link")

```raku
method native-descriptor()
```

This returns a value that the operating system would understand as a "socket descriptor" and is suitable for passing to a native function that requires a socket descriptor as an argument such as `setsockopt`.


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

# NAME

App::Browser - OS independent interface to a browser

# SYNOPSIS

```
use App::Browser;

browse('raku.org');             # visit the Raku web site with default browser

browse('raku.org', 'firefox');  # visit the Raku web site with Firefox

```

# DESCRIPTION

App::Browser provides a simple generic interface to starting a browser for a given URL. It exports the `browse` function that takes a `URL` as the first parameter, and an optional browser identification as a second parameter (which defaults to the `APP_BROWSER` environment variable).

The `browse` function returns a `Proc` object, or `Nil` if something went wrong. Whether it makes sense to do something with that object, is unsure.

It also exports a command line script `browse` that will take a `URL` and an optional browser identifier (e.g. `chrome`, `firefox`, `safari`).

```
$ browse raku.org

$ APP_BROWSER=chrome browse raku.org

$ browse raku.org firefox

```

# WORK IN PROGRESS

Please note that this is a continuing work in progress. At the moment of this writing, only `MacOS` is supported. Specifically the different ways of opening browsers on `Windows` and the various tastes of `Linux` will need some experienced users to get this right.

# AUTHOR

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

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

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


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

# NAME

Concurrent::Trie - A lock-free concurrent trie (Text Retrieval) data structure

# SYNOPSIS

```
use Concurrent::Trie;

my $trie = Concurrent::Trie.new;
say $trie.contains('brie');  # False
say so $trie;                # False
say $trie.elems;             # 0

$trie.insert('brie');
say $trie.contains('brie');  # True
say so $trie;                # True
say $trie.elems;             # 1

$trie.insert('babybel');
$trie.insert('gorgonzola');
say $trie.elems;             # 3
say $trie.entries();         # (gorgonzola babybel brie)
say $trie.entries('b');      # (babybel brie)

```

# DESCRIPTION

A trie stores strings as a tree, with each level in the tree representing a character in the string (so the tree's maximum depth is equal to the number of characters in the longest entry). A trie is especially useful for prefix searches, where all entries with a given prefix are required, since this is obtained simply by walking the tree according to the prefix, and then visiting all nodes below that point to find entries.

This is a lock-free trie. Checking if the trie contains a particular string **never** blocks. Iterating the entries never blocks either, and will provide a snapshot of all the entries at the time the `entries`` method was called. An insertion uses optimistic concurrency control, building an updated tree and then trying to commit it. This offers a global progress bound: if one thread fails to insert, it's because another thread did a successful insert.

This data structure is well suited to auto-complete style features in concurrent applications, where new entries and lookups may occur when, for example, processing web requests in parallel.

# Methods

## insert(Str $value --> Nil)

Inserts the passed string value into the trie.

## contains(Str $value --> Bool:D)

Checks if the passed string value is in the trie. Returns `True` if so, and `False` otherwise.

## entries($prefix = '' --> Seq:D)

Returns a lazy iterator of all entries in the trie with the specified prefix. If no prefix is passed, the default is the empty prefix, meaning that a call like `$trie.entries()` will iterate **all** entries in the trie. The order of the results is not defined.

The results will be a snapshot of what was in the trie at the point `entries` was called; additions after that point will not be in the `entries` list.

## elems(--> Int:D)

Gets the number of entries in the trie. The data structure maintains a count, making this O(1) (as opposed to `$trie.entries.elems`, which would be O(n)).

## Bool(--> Bool:D)

Returns `True` if the number of entries in the trie is non-zero, and `False` otherwise.

# AUTHOR

Jonathan Worthington

# COPYRIGHT AND LICENSE

Copyright 2018 - 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.


## instant.md
class Instant

Specific moment in time

```raku
class Instant is Cool does Real { }
```

An `Instant` is a particular moment in time measured in atomic seconds, with fractions. It is not tied to or aware of any epoch.

An `Instant` can be used to create a [`DateTime`](/type/DateTime) object set to that `Instant`. The pseudo-constant `now` returns the current time as an `Instant`.

Basic math is defined for `Instant`s (as well as [`Duration`](/type/Duration)s). Adding an `Instant` to a [`Duration`](/type/Duration) returns another Instant. Subtracting two `Instant`s will yield a [`Duration`](/type/Duration). Adding two `Instant`s is explicitly disallowed. All other operations with Instants are undefined.

# [Future Leap Seconds](#class_Instant "go to top of document")[§](#Future_Leap_Seconds "direct link")

The methods that involve knowledge of leap seconds always assume that there will be no further leaps after the last leap second that the implementation knows about, which may not be the last leap second that has actually been scheduled. This means you can get different results, depending on the compiler version you're using. For example, the December 31, 2016 leap second was announced in July and shipped with Rakudo 2016.07, so 2016.06 and earlier releases won't know about it.

｢text｣ without highlighting

```

```

$ perl6-2016.06 -e 'say Instant.from-posix: 1485726595'
Instant:1485726631

$ perl6-2016.07 -e 'say Instant.from-posix: 1485726595'
Instant:1485726632

```

```

Since a Rakudo compiler always returns 0 for future leap seconds it doesn't know about, you can patch your old code when new leap seconds are announced, so it will give correct results, regardless of what version of the compiler it runs on:

｢text｣ without highlighting

```

```

$ perl6-2016.06 -e 'say ($*VM.version before v2016.07 ?? 1 !! 0) + Instant.from-posix: 1485726595'
Instant:1485726632

$ perl6-2016.07 -e 'say ($*VM.version before v2016.07 ?? 1 !! 0) + Instant.from-posix: 1485726595'
Instant:1485726632

```

```

*These examples require compilers that predate the rename, and so still refer to perl6.*

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

## [method from-posix](#class_Instant "go to top of document")[§](#method_from-posix "direct link")

```raku
method from-posix($posix, Bool $prefer-leap-second = False)
```

Converts the POSIX timestamp `$posix` to an Instant. If `$prefer-leap-second` is `True`, the return value will be the first of the two possible seconds in the case of a leap second.

```raku
say DateTime.new(Instant.from-posix(915148800, True));  # OUTPUT: «1998-12-31T23:59:60Z␤»
say DateTime.new(Instant.from-posix(915148800));        # OUTPUT: «1999-01-01T00:00:00Z␤»
```

## [method to-posix](#class_Instant "go to top of document")[§](#method_to-posix "direct link")

```raku
method to-posix()
```

Converts the invocant to a POSIX timestamp and returns a two element list containing the POSIX timestamp and a [`Bool`](/type/Bool). It is the inverse of [method from-posix](#method_from-posix), except that the second return value is `True` if \*and only if\* this Instant is in a leap second.

```raku
say DateTime.new("1999-01-01T00:00:00Z").Instant.to-posix; # OUTPUT: «(915148800 False)␤»
say DateTime.new('1998-12-31T23:59:60Z').Instant.to-posix; # OUTPUT: «(915148800 True)␤»
```

## [method Date](#class_Instant "go to top of document")[§](#method_Date "direct link")

```raku
method Date(Instant:D: --> Date:D)
```

Coerces the invocant to [`Date`](/type/Date).

```raku
my $i = "/etc/passwd".IO.modified;
say $i;             # OUTPUT: «Instant:1451489025.878018␤»
say $i.Date;        # OUTPUT: «2015-12-30␤»
```

## [method DateTime](#class_Instant "go to top of document")[§](#method_DateTime "direct link")

```raku
method DateTime(Instant:D: --> DateTime:D)
```

Coerces the invocant to [`DateTime`](/type/DateTime).

```raku
say now.DateTime;  # OUTPUT: «2017-05-09T14:02:58.147165Z␤»
```

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

Type relations for `Instant`

raku-type-graph

Instant
Instant

Cool
Cool

Instant->Cool

Real
Real

Instant->Real

Mu
Mu

Any
Any

Any->Mu

Cool->Any

Numeric
Numeric

Real->Numeric

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


## mainline.md
class X::Placeholder::Mainline

Compilation error due to a placeholder in the mainline

```raku
class X::Placeholder::Mainline is X::Placeholder::Block { }
```

Thrown when a placeholder variable is used in the mainline, i.e. outside of any explicit block.

For example

```raku
$^x;

```

dies with

｢text｣ without highlighting

```

```

===SORRY!===
Cannot use placeholder parameter $^x outside of a sub or block

```

```

Note that this error can also occur when you think something is a block, but it really is a [postcircumfix:<{ }>](/routine/{ }), for example

```raku
my %h;
say %h{ $^x };
#     ^^^^^^^  not a block, so $^x is part of the mainline

```


## dist_cpan-LYX-Test-Diehard.md
NAME
Test::Diehard

AUTHOR
Mose Schmiedel [mose.schmiedel@web.de](mailto:mose.schmiedel@web.de)

VERSION
0.0.0

Description

Test suite for PRNGs.

Installation

Install this module through zef:

```
zef install Test::Diehard

```

License

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


## dist_zef-martimm-BSON.md
# Face BSON support

Implements [BSON specification](http://bsonspec.org/).

![L](https://martimm.github.io/label/License-label.svg)

## Synopsis

The main entry point is **BSON::Document**. This structure is a Hash like object but will keep the order of its keys and because of that there is no need for cumbersome operations. At the moment it is much slower than the hashed variant even with the encoding happening in the background and parallel.

```
use BSON::Document;

my BSON::Javascript $js .= new(:javascript('function(x){return x;}'));
my BSON::Javascript $js-scope .= new(
  :javascript('function(x){return x;}'),
  :scope(BSON::Document.new: (nn => 10, a1 => 2))
);

my BSON::Binary $bin .= new(:data(Buf,new(... some binary data ...));
my BSON::Regex $rex .= new( :regex('abc|def'), :options<is>);

my BSON::Document $d .= new: ( 'a number' => 10, 'some text' => 'bla die bla');
$d<oid> = BSON::ObjectId.new;
$d<javascript> = $js;
$d<js-scope> = $js-scope;
$d<datetime> = DateTime.now;
$d<bin> = $bin;
$d<rex> = $rex;
$d<null> = Any;
$d<array> = [ 10, 'abc', 345];
$d<subdoc1> = a1 => 10, bb => 11;
$d<subdoc1><b1> = q => 255;

my Buf $enc-doc = $d.encode;

my BSON::Document $new-doc .= new;
$new-doc.decode($enc-doc);

```

## Documentation

BSON/Document.pod

* 🔗 Website
* [🔗 License document](https://www.perlfoundation.org/artistic_license_2_0)
* [🔗 Release notes](https://github.com/MARTIMM/BSON/blob/main/doc/CHANGES.md)
* [🔗 Issues](https://github.com/MARTIMM/BSON/issues)

## Installing BSON

Use zef to install the package like so.

```
$ zef install BSON

```

When installing MongoDB, BSON will be installed automatically as a dependency.

## Version of Raku and MoarVM

This module is tested using the latest 6.d Raku version on MoarVM

## Authors

Original creator of the modules is Pawel Pabian (2011-2015, v0.3)(bbkr on github).
Current maintainer Marcel Timmerman (2015-present)(MARTIMM on github).

## Contributors

Dan Zwell (lefth on github)


## dist_zef-jjmerelo-Test-Grammar.md
# Test::Grammar for Raku [Test in a Raku container - template](https://github.com/JJ/raku-test-grammar/actions/workflows/test.yaml)

Unit testing for grammars. Because testing is important.

## Installing

No dependencies, except `Test` which is a Rakudo core library, so the usual
`zef install Test::Grammar`.

## Running

> Copied from [the source](lib/Test/Grammar.pm6), version there is the single
> source of truth:

```
use Test::Grammar;

parses-ok Test-Grammar,"num", 3, "33 parses OK";

my $test-output = q:to/EOC/;
ok 1 - bailout parses OK
ok 2 - «bailout» extracts token
1..2
EOC

has-tokens Test-Grammar, "test", <nok num description>, $test-output,
    "Complete tests";

token-is Test-Grammar,"bailout", "explanation",
    "Bail out! FOOBAR",
    "FOOBAR",
    "«bailout» extracts token";

for <foo bar b3> {
    parses-nok Test-Grammar,"num", $_, "$_ not parsed";
}

```

## See also

There are very nice testing libraries out there:

* [T](https://raku.land/zef:CIAvash/T) emphasizes output and messages
* [Testo](https://raku.land/zef:raku-community-modules/Testo) is another
  opinionated test library.

## License

(c) JJ Merelo, [jj@raku.org](mailto:jj@raku.org), 2022

Licensed under the Artistic 2.0 License (the same as Raku itself).


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

# TITLE

ReadWriteLock -- A lock with shared/exclusive access modes

# SYNOPSIS

```
use ReadWriteLock;

my $l = ReadWriteLock.new;

my $thread-a = Thread.start({
    $l.lock-shared();
    for ^5 {
        sleep 1;
        say "thread A doing something under protection of the lock";
    }
    $l.unlock();
});

my $thread-b = Thread.start({
    $l.protect-shared({
        for ^5 {
            sleep 1;
            say "thread B doing something under protection of the lock";
        }
    });
});

my $thread-c = Thread.start({
    $l.protect-exclusive({
        for ^5 {
            sleep 1;
            say "thread C doing something under exclusive protection of the lock";
        }
    });
});

$thread-a.join;
$thread-b.join;
$thread-c.join;

```

# FEATURES

* Does what a basic `Lock` does, just slower and with more bugs ;)
* Reentrant: the lock can be taken again by a thread that is already holding it It needs to be unlocked the same number of times it was locked before it can be taken by another thread
* Fair in the sense of first-come-first-serve
* Shared access: multiple 'readers' can share the lock, yet access is mutually exclusive between 'readers' and 'writers'
* Lock Upgrade: you can upgrade a shared access mode to an exclusive without unlocking first, if no other thread is interferring. In this case you do not need to unlock twice.

# PLANNED FEATURES

* Read-for-write access mode that guarantees that a lock upgrade can be taken
* Async version that returns threads to the threadpool and returns a promise from lock()

# DESCRIPTION

This module implements a lock/mutex with shared and exclusive access modes, so a set of 'readers' could share the lock while 'writers' need exclusive access. The lock is reentrant, so can be taken multiple times by the same thread, and fair in the sense of come-first-server-first.

Please note that locks of whatever kind are a very low-level synchronisation mechanism and inherently difficult to use correctly, where possible higher-level mechanisms like a `Channel`, `Promise` or `Suppply` should be used.

# EXAMPLES

## Constructor

```
use ReadWriteLock;

my $l = ReadWriteLock.new;

```

Constructing a ReadWriteLock is very simple and takes no arguments.

## Protecting a Code segment

```
$l.protect-shared: {
    # code thunk
}

$l.protect-exclusive: {
    # code thunk
}

$l.protect: shared, {
    # code thunk
}

$l.protect: exclusive, {
    # code thunk
}

```

The `protect()` usage pattern has the distinct benefit that it automatically unlocks in case of e.g. exceptions or whenever the code block is being left. You can either use the 'long' form like `protect-shared()`, which is nice and implicit, or pass the access mode in as an argument, which allows determning it from a function and passing it around.

## Direct locking/unlocking

```
$l.lock-shared;

$l.lock-exclusive;

$l.lock(shared);

$l.lock(exclusive);

$l.unlock;

```

Alternatively you can also use stand-alone lock/unlock calls, which allows tricky usages like overhand locking etc, but requires more care to be safe. If you lock multiple times, you need to unlock a matching number of times before the lock becomes available again.

## Lock Upgrades

```
$l.lock-shared;

# do something

$l.lock-exclusive;

# do something else that requires exclusive access

$l.unlock;

```

You can upgrade a lock that you are holding in shared mode to an exclusive access, as long as no other thread was traying to do the same before (You will get an exception in that case). In this case you only need to unlock once, the lock has been upgraded not re-entered.

# AUTHORS

* Robert Lemmen (2018-2020)
* Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks) (2021-)

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

Copyright 2021, 2024, 2025 Elizabeth Mattijsen

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


## dist_github-gfldex-Git-Config.md
# Git::Config

[![Build Status](https://travis-ci.org/gfldex/perl6-git-config.svg?branch=master)](https://travis-ci.org/gfldex/perl6-git-config)

Read gitconfig and return a Hash of Hash.

# SYNOPSIS

```
use Git::Config;

my $git-user = git-config<user><name>;
my $remote-repo = git-config('.git/config'){'remote "origin"'}<url>;

for git-config().seach-path -> {
    say "looking for a git config in " ~ .Str;
}

say "found a git config at " ~ git-config().path;

```

# Subs

```
sub git-config(IO::Path $file? --> Hash)

```

The returned Hash got an anonymous role mixed in providing the method `path`
pointing to the location of the git config file that was read. The method
`search-path` that is returning a list of paths, containing the paths a git
config file was searched in.

# Grammars

```
grammar Config

```