## dist_github-grondilu-Clifford.md
# Geometric Algebra in Raku

[![Build Status](https://travis-ci.org/grondilu/clifford.svg)](https://travis-ci.org/grondilu/clifford)
![Sparky](https://sparky.sparrowhub.io/badge/grondilu-clifford?foo=bar)

The `MultiVector` module in this repository is an attempt to implement basic
[Geometric Algebra](http://en.wikipedia.org/wiki/Geometric_Algebra) in Raku.

With this module you can create vectors of arbitrary, albeit countable
dimension. You can then add and substract them, as well as multiplying them by
real scalars as you would do with any vectors, but you can also multiply and
divide them as made possible by the geometric algebra.

The module exports three array constants `@e`, `@i` and `@o`
which serve as normed bases for three orthogonal spaces respectively
Euclidean, anti-Euclidean and null.

In addition to the usual overloading of arithmetic operators, the module also
defines the infix operators `∧` and `·` (vim digraphs "AN" and ".M") as the
outer and scalar products. The scalar product is defined only on vectors (i.e.
multivectors of grade one).

## Synopsis

```
use MultiVector;

say @e[0];         # e₀
say @e[1]*@e[0];   # -e₀∧e₁
say 1 + @e[4];     # 1+e₄
say @i[3]∧@e[2];   # -e₂∧i₃
say @o[2]∧@i[2];   # -i₂∧o₂

say @e[1]²;      # 1
say @i[1]²;      # -1
say @o[1]²;      # 0

say @o[0](@e[1] + 2*@o[0]);  # 2

```

## External links

* [Geometric Algebra for Computer science](http://www.geometricalgebra.net) : a
  website and a book that helped for this project ;
* [Versor](https://github.com/wolftype/versor), a C++ implementation of the
  above reference.
* [Eric Lengyel's page on Geometric Algebra](https://projectivegeometricalgebra.org/),
  with links to his wikis on the subject. Dr Eric Lengyel is the person who
  first suggested the use of the symbol `⟑`.
* [Bivector.net](https://bivector.net/), some kind of a GA community hub.


## dist_github-fayland-Lingua-Unihan.md
# Lingua::Unihan

[![Build Status](https://travis-ci.org/fayland/perl6-Lingua-Unihan.svg?branch=master)](https://travis-ci.org/fayland/perl6-Lingua-Unihan)

```
    use Lingua::Unihan;

    my $codepoint = unihan_codepoint('你'); # 4f60

    my $mandarin = unihan_query('kMandarin', '林'); # 'lín'
    my $strokes  = unihan_query('kTotalStrokes', '林'); # 8

```

## Supported Filed Type

* kCangjie
* kCantonese
* kCheungBauer
* kCihaiT
* kDefinition
* kFenn
* kFourCornerCode
* kFrequency
* kGradeLevel
* kHDZRadBreak
* kHKGlyph
* kHangul
* kHanyuPinlu
* kHanyuPinyin
* kJapaneseKun
* kJapaneseOn
* kKorean
* kMandarin
* kPhonetic
* kTang
* kTotalStrokes
* kVietnamese
* kXHC1983


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

# NAME

Proc::InvokeEditor - Edit strings in an external editor.

# SYNOPSIS

```
use Proc::InvokeEditor;

my $editor = Proc::InvokeEditor.new( :editors( [ "/usr/bin/emacs" ] ) );
my $text = $editor->edit( "Edit text below\n" );

```

# DESCRIPTION

Proc::InvokeEditor is a port of the Perl5 module of the same name. The API is intended to be as close as possible to the original. Later versions of the module will add additional functionality

# METHODS

## new( :editors )

Create a new Proc::InvokeEditor object, takes an optional list of paths to editors to attempt to use. Note: currently all paths given must be complete paths, the system doesn't attempt an checking of the path environment for files.

Editor strings can include command line arguments to pass and should expect to take a filename as there final argument.

## editors()

Getter / Setter for the array of editors accepts a postional arguments or an postitional and sets the list of editors to that. If called with no values gives the current list in the order they will be checked.

Can be called as a getter as a class method but will error if you try and set the editors as a class method.

## editors\_env( @editors )

Object method only, given an array (or positional arguments) of Str keys will prepend to the editors array the value for that key in ENV (if one is defined).

Returns the current list of editors.

Fails if called as a class method.

## editors\_prepend( @editors )

Object method only, given an array (or positional arguments) of Str values will prepend them to the editor list.

Returns the current list of editors.

Fails if called as a class method.

## first\_usable()

Class or object method. Returns an array of executable path string and then optional parameters for the editor the system will use when edit() is called.

## edit( $string )

Class or object method, takes a string or list of strings. Fires up the external editor specifed by first\_usable() and waits for it to complete then returns the updated result.

# TODO

* Windows support.
* Check PATH for possibles
* Addtional Perl6-isms including Async editting allowing background processes.

# NOTE

The original Perl5 module includes methods to turn off auto cleanup of temp files and to reuse the same file. This functionality is not planned for this version of the module, if required please raise a ticket.

# AUTHOR

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

Original Perl5 Module Authored by Micheal Stevens

# COPYRIGHT AND LICENSE

Copyright 2018 Simon Proctor

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


## dist_cpan-JMERELO-Git-Blame.md
[![Build Status](https://travis-ci.org/JJ/perl6-git-blame.svg?branch=master)](https://travis-ci.org/JJ/perl6-git-blame)

# NAME

Git::Blame - Examine who's worked on a file

# SYNOPSIS

```
use Git::Blame;

my $blamer = Git::Blame.new( "t/01-basic.t" );
say "Lines ",  $git-blame.lines();
say "Chunks ", $git-blame.chunks();
for $git-blame.SHAs.keys -> $k {
    say $git-blame.SHAs{$k}<email>, " → ",  $git-blame.SHAs{$k}<range>;
}

```

# DESCRIPTION

Git::Blame is a module that uses `git blame` to extract information from a single file in a repository and process it in a number of ways. It's mainly geared to tally contributions via lines changed, but it can also be modified and used to do some repository mining.

```
It works, for the time being, with single files.

```

# METHODS

## lines()

Returns an Array with all the lines in the file

## chunks()

Returns an array of hashes, every one of them with a chunk with range, author email and sha1 of the commit involved.

## SHAs()

Returns a hash that uses as keys the sha1 of the commit, and as values arrays of all chunks changed in that commit

## author-lines()

Returns a hash that uses the author emails as keys and the number of lines done in the current version as value.

# AUTHOR

JJ Merelo [jjmerelo@gmail.com](mailto:jjmerelo@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2019 JJ Merelo

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


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

# NAME

RakudoPrereq - Specify minimum required versions of Rakudo

# SYNOPSIS

```
use RakudoPrereq v2021.04; # specify minimum Rakudo version 2021.04

# specify minimum Rakudo version 2021.04, with custom message
# when user's Rakudo is too old
use RakudoPrereq v2021.04, 'Your Raku is way too old, bruh!';

# specify minimum Rakudo version 2021.04, use default message and die
# when non-Rakudo compiler is used
use RakudoPrereq v2021.04, '', 'rakudo-only';

# specify minimum Rakudo version 2021.04, use custom message and die
# when non-Rakudo compiler is used
use RakudoPrereq v2021.04, 'your compiler is no good', 'rakudo-only';

# specify minimum Rakudo version 2021.04, use default message and die
# when non-Rakudo compiler is used and don't print location of `use`
use RakudoPrereq v2021.04, '', 'rakudo-only no-where';

```

# DESCRIPTION

Need to black-list non-Rakudo compilers or some Rakudo versions that implement the same language version? This module is for you!

If the program is run on a Rakudo that's too old, the module will print a message and exit with status `1`

# USAGE

The entire API is via the arguments specified on the `use RakudoPrereq` line.

## Minimum Rakudo version

The first argument is required and is the [`Version`](https://docs.raku.org/type/Version) object specifying the minimum required Rakudo version.

## Custom message

By default, the module will print a generic message before exiting, you can specify a custom message here. Default message will be printed if the specified custom message is an empty string.

## String with options

Space-separated string of options:

### rakudo-only

By default, the module would not fail if the compiler is not Rakudo. Specify this option if you want to fail for non-Rakudo compilers as well, regardless of their version.

### no-where

Both the default and custom message will have the location of where the `use RakudoPrereq` that caused failure is at. Specify this argument if you want to surpress that information.

# AUTHOR

Zoffix Znet

# COPYRIGHT AND LICENSE

Copyright 2017 Zoffix Znet

Copyright 2018 - 2022 Raku Community

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


## dist_cpan-JFORGET-Date-Calendar-MayaAztec.md
# NAME

Date::Calendar::MayaAztec - conversions from / to the Maya calendar and from / to the Aztec calendar

# SYNOPSIS

When was the last time the end of the universe happened?

```
use Date::Calendar::Maya;
my Date::Calendar::Maya
        $d-maya  .= new(long-count => '13.0.0.0.0');
my Date $d-greg   = $d-maya.to-date('Date');
say $d-greg;
# --> 2012-12-21 (for 21st December 2012)

```

The Perl and Raku conference in North America was scheduled to take
place in Houston, starting on 2020-06-20. What does the southern
neighbours call this date?

```
use Date::Calendar::Maya;
use Date::Calendar::Aztec;
my Date                  $d-greg  .= new(2020, 6, 20);
my Date::Calendar::Aztec $d-aztec .= new-from-date($d-greg);
my Date::Calendar::Maya  $d-maya  .= new-from-date($d-greg);

say "{.tzolkin} {.haab} {.long-count}" with $d-maya;
# --> 12 Etznab 1 Tzec 13.0.7.10.18
$d-maya.locale = 'en';
say "{.tzolkin} {.haab}" with $d-maya;
# --> 12 Flint 1 Skull

say "{.tonalpohualli} {.xiuhpohualli}" with $d-aztec;
# --> 12 Tecpatl 20 Teotleco
$d-aztec.locale = 'en';
say "{.tonalpohualli} {.xiuhpohualli}" with $d-aztec;
# --> 12 Flint 20 God arrives

```

# DESCRIPTION

Date::Calendar::MayaAztec is a distribution with two main classes,
Date::Calendar::Maya implementing the Maya calendars (long count, Haab
and Tzolkin) and Date::Calendar::Aztec implementing the Aztec
calendars (tonalpohualli and xiuhpohualli).

# INSTALLATION

```
zef install Date::Calendar::MayaAztec

```

or

```
git clone https://github.com/jforget/raku-Date-Calendar-MayaAztec.git
cd raku-Date-Calendar-MayaAztec
zef install .

```

# AUTHOR

Jean Forget [JFORGET@cpan.org](mailto:JFORGET@cpan.org)

# COPYRIGHT AND LICENSE

Copyright © 2020 Jean Forget

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


## next.md
role CX::Next

Next control exception

```raku
role CX::Next does X::Control { }
```

A [control exception](/language/exceptions#Control_exceptions) that is triggered when `next` is called.

```raku
for ^10 {
    CONTROL {
      when CX::Next { say "We're next" };
    }
    next if $_ %% 2;
    say "We're in $_";
}

```

This will print:

｢text｣ without highlighting

```

```

We're next
We're in 1
We're next
We're in 3
We're next
We're in 5
We're next
We're in 7
We're next
We're in 9

```

```

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

## [method message](#role_CX::Next "go to top of document")[§](#method_message "direct link")

```raku
method message()
```

Returns `'<next control exception>'`.


## dist_cpan-MARTIMM-MongoDB.md
# Leaf MongoDB Driver for Raku

![T](https://travis-ci.com/MARTIMM/raku-mongodb-driver.svg?branch=master) ![A](https://ci.appveyor.com/api/projects/status/github/MARTIMM/raku-mongodb-driver?branch=master&passingText=Windows%20-%20OK&failingText=Windows%20-%20FAIL&pendingText=Windows%20-%20pending&svg=true) ![L](https://martimm.github.io/label/License-label.svg)

## Documentation

* [🔗 Website](https://martimm.github.io/raku-mongodb-driver/)
* [🔗 License document](https://www.perlfoundation.org/artistic_license_2_0)
* [🔗 Release notes](https://martimm.github.io/raku-mongodb-driver/content-docs/about/release-notes.html)
* [🔗 Issues](https://github.com/MARTIMM/raku-mongodb-driver/issues)

## INSTALLING THE MODULES

Use zef to install the package.

```
zef install MongoDB

```

## AUTHORS

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

## Contributors

* Dan Zwell (lefth on github)
* David Golden, who has pointed me to important documents he has developed together with a MongoDB team. It's about guide lines for server discovery and building up a topology of the servers seeded from the url.


## nativetype.md
class X::Bind::NativeType

Compilation error due to binding to a natively typed variable

```raku
class X::Bind::NativeType does X::Comp { }
```

Compile-time error thrown when trying to bind to a natively typed variable.

Since native variables explicitly don't have the concept of a container at runtime, it does not make sense to support both binding and assignment; Raku supports only assignment (which makes more sense, because native types are value types).

For example the code

```raku
my int $x := 3;

```

dies with

｢text｣ without highlighting

```

```

Cannot bind to natively typed variable '$x'; use assignment instead

```

```

and can be fixed by writing it as

```raku
my int $x = 3;
```

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

## [method name](#class_X::Bind::NativeType "go to top of document")[§](#method_name "direct link")

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

Returns the name of the variable.


## dist_cpan-CHLOEKEK-Template-Classic.md
```
Template engine which allows embedding of arbitrary Raku code and features
escaping with HTML entities.

See lib/Template/Classic.pm6 for usage.

```


## dist_zef-avuserow-SQL-Builder.md
[![Actions Status](https://github.com/avuserow/raku-sql-builder/actions/workflows/test.yml/badge.svg)](https://github.com/avuserow/raku-sql-builder/actions)

# NAME

SQL::Builder - build SQL statements

# SYNOPSIS

```
use SQL::Builder;

my $sql = SQL::Builder.new;

# all SELECT queries start with from
my $q1 = $sql.from('users').select(<name address>).where(['email', '=', 'foo@example.com']);
my $statement = $q1.build;
# $statement.sql: SELECT name, address FROM users WHERE email = ?
# $db.execute($statement.sql, |$statement.bind);

# many SQL fragments are supported:
my $q2 = $sql.from('songs').
    select(['album', :albumlength(Fn.new('SUM', 'length'))]).
    where([:online(True), ['year', '>=', 2020]]).
    group-by('album').
    order-by('album');

# subselects too:
my $q3 = $sql.from($q2, :as<inner>).select(Fn.new('MAX', 'inner.albumlength'));

# joins:
my $q4 = $sql.from('songs').
    join(:left, 'ratings', :using('song-id')).
    select(<title artist album rating>);

```

# DESCRIPTION

SQL::Builder generates SQL statements using an approach modeled after the 'builder' pattern. This allows us to support a wide variety of SQL syntax, including sub-queries, while allowing each option to remain intuitive.

This module is partially inspired by Python's SQLAlchemy Core as well as Perl 5's `SQL::Abstract`. This module forgoes an ORM in favor of generating raw SQL, giving you the power to build complex queries and not lose execution speed.

This module also prioritizes safety. Each option has rules on how it handles an untyped string, and it defaults to either a quoted `Identifier` or a `Placeholder`, depending on the ergonomics of each function.

SQL::Builder can represent a large amount of SQL statements, and is best suited for statements of medium complexity with reasonably high amounts of runtime changes (e.g. where clause, optional joins or sub-selects).

# TYPE SYSTEM

SQL::Builder has a basic type system to ensure the right behavior when a value is provided. Each builder option has a default way to handle a string, typically either as either Identifier or Placeholder and each method documents its expectations.

These are all subclasses of `SQLSyntax` and are:

* `Identifier`: used for table and column names, and will be split into pieces and quoted. See `Identifier` below for full details.
* `Placeholder`: always generates a single `?` placeholder and puts its value into the list of bind values.
* `Value`: used for a string value when `Placeholder` is not an option. Always fully quoted.
* `Raw`: this is a raw fragment of SQL. Use `Raw.fmt` to safely write raw fragments.
* `Fn`: used to help write function calls. The first argument is unquoted. Subsequent arguments default to `Identifier`, and are put in a parenthesized list.

## Identifier

The `Identifier` type is the most common way to handle untyped input. It is used to represent tables and columns, with an optional type cast. If a dotted value is specified (e.g. `table.column`), then this is split into two bits before quoting. Additionally, if it ends with `::`, then that suffix is allowed as a PostgreSQL-style type cast.

Example input and output for the SQL portion:

* `Identifier.new("foo")` -> `"foo"`
* `Identifier.new("foo.bar")` -> `"foo"."bar"`
* `Identifier.new("foo::int")` -> `"foo"::int`
* `Identifier.new("foo.bar::uuid[]")` -> `"foo"."bar"::uuid[]`

## Placeholder

This is a simple SQL placeholder. It is used as in the right-hand side of various conditionals. The resulting fragment is always a single `?`, and the value is put in the bind list.

No conversion is done to the value, so you can pass in values of type `Str`, `Int`, `DateTime`, `Bool`, as well as `Array`. Currently, Arrays do not have any special logic to create additional placeholders or otherwise flatten the array. See the Cookbook section to see how to handle this.

## Value

The value is escaped and wrapped in single quotes.

## Raw

No escaping is performed. The `Raw.fmt` method provides a safer way to use this.

## Raw.fmt(Str $template, SQLSyntax $a, $b, ...)

The `fmt` method lets you safely build bits of SQL by providing a template containing `{}` sequences that are replaced by the following arguments. You must have the same number of `{}` replacements as arguments, and all arguments must be one of the types in this section (e.g. subclasses of `SQLSyntax`).

Examples:

```
Raw.fmt('COUNT({}) AS {}', Identifier.new("artist"), Identifier.new("artistcount"));
# sql: COUNT("artist") AS "artistcount"
# bind: []

Raw.fmt('unnest({}::uuid[]) WITH ORDINALITY t(id, ord)', Placeholder.new([1, 2, 3]));
# sql: unnest(?::uuid[]) WITH ORDINALITY t(id, ord)
# bind: [@ids,]

Raw.fmt('date_trunc({}, {})', Value.new('day'), Identifier.new('song-start'));
# sql: date_trunc('day', "song-start")
# bind: []

```

## Fn

Fn (function) is a helper to make function calls. The first item is taken as a Raw value, and all following items default to Identifiers. This can be used for any function-like syntax in SQL, not just real functions.

Examples:

```
Fn.new('COUNT', 'artists');
# sql: COUNT("artists")
# bind: []

Fn.new('ANY', my @stuff);
# sql: ANY(?)
# bind: [@my-stuff,]

```

# SELECT QUERIES

Select queries are created with the `from` method on the `SQL::Builder` object. All other options can be passed in any order. All options except `join` overwrite the current value. Each option returns the SelectBuilder instance, allowing for a chain style: `$sql.from('foo').select('bar').group-by('baz')`

Multiple tables in the `from` clause are not yet supported. Use `join` instead.

Select queries support the following options:

## from(Str $table)

Creates a `SelectBuilder` from the given table.

## from(SQLStatement, :$as!)

Creates a subselect from the provided SQLStatement, aliased to the value of `$as`. Contrived example:

```
my $inner-q = $sql.from('foo').select('bar');
my $q = $sql.from($inner-q, :as<inner>).select('bar');
# SELECT "bar" FROM (SELECT "bar" FROM "foo") AS "inner"

```

## select(:all)

Emits a `SELECT *`.

## select(\*@columns)

Specifies the list of values to return. Each column defaults to `Identifier`.

A column may be aliased with the use of a Capture in the form `\("column-name", :as<alias>)`.

```
# Preferred form: using a capture explicitly:
$sql.from('table').select(\("bar", :as<foo>));
# sql: SELECT "bar" AS "foo" FROM "table"

```

Note that due to Raku's handling of Pairs, if you mix Positional and non-Positional arguments, the Pairs will always be at the end. You can avoid this by passing an Array, or parenthesizing the Pairs:

```
$sql.from('table').select(<foo bar>, :a<b>, :c<d>);
# SELECT "foo", "bar", "b" AS "a", "d" AS "c" FROM table

$sql.from('table').select(:a<b>, <foo bar>, :c<d>);
# SELECT "foo", "bar", "b" AS "a", "d" AS "c" FROM table

# Instead, pass all values as positional elements, in any of the following ways:
$sql.from('table').select([:a<b>, "foo", "bar", :c<d>]);
$sql.from('table').select([:a<b>, <foo bar>.flat, :c<d>]);
$sql.from('table').select((:a<b>), "foo", "bar", (:c<d>));
# SELECT "b" AS "a", "foo", "bar", "d" AS "c" FROM table

```

## where(@where)

Provide a `WHERE` clause with one or more values. These clauses are combined with `AND` logic by default. The values are used as a `ConditionClause`, see the documentation below for the details.

```
$sql.from('users').select('email').where(:username<ak>);
# sql: SELECT "email" FROM "users" WHERE "username" = ?
# bind: ["ak",]

$sql.from('users').select('email').where(["username", "=", "ak"]);
# sql: SELECT "email" FROM "users" WHERE "username" = ?
# bind: ["ak",]

$sql.from('users').select('email').where([["email", "LIKE", "%gmail.com"], ["email", "LIKE", "ak%"]]);
# sql: SELECT "email" FROM "users" WHERE "email" LIKE ? AND "email" LIKE ?
# bind: ["%gmail.com", "ak%"]

# Use a Capture to make a sub-group to switch to OR logic:
$sql.from('users').select('email').where(\(:or[["email", "LIKE", "%gmail.com"], ["email", "LIKE", "%googlemail.com"]]));
# sql: SELECT "email" FROM "users" WHERE ("email" LIKE ? OR "email" LIKE ?)
# bind: ["%gmail.com", "%googlemail.com"]

```

## join($table, :@on, :$using, Str :$as, :$inner/:$left/:$right/:$full)

Provides a `JOIN` clause to this query. `$table` should be either the name of a table (treated as an Identifier), or a `SelectBuilder` to use a sub-query.

Exactly one of `:$using` or `:@on` must be specified, which determines how to join the table. `:$using` is for when the columns match exactly. `:@on` is passed to `ConditionClause` and lets you fully control the join logic. See the `ConditionClause` documentation below. These correspond to the `USING(column)` and `ON expr` portions of the SQL join expression, respectively.

The `:$as` parameter is optional which controls the join expression's alias. This is needed if you use a sub-query or the same table is joined multiple times. This is treated as an Identifier.

Finally, one of `:$inner/:$left/:$right/:$full` may be specified to control the type of JOIN. This is optional.

Multiple JOINs are supported and are processed in the order they are added.

There is currently no way to clear the list of JOINs from a query.

Examples:

```
$sql.from('t1').join('t2', :using<id>).select(<t1.foo t2.bar>);
# sql: SELECT "t1"."foo", "t2"."bar" FROM "t1" JOIN "t2" USING("id")

my $inner = $sql.from('t1').select(:bar<foo>, 'id');
$sql.from('t2').
    join(:left, $inner, :as<inner>, :on['inner.id', '=', Identifier.new('t2.id')]).
    select(<t1.foo t2.bar>);
# sql: SELECT "t1"."foo", "t2"."bar" FROM "t2" LEFT JOIN (SELECT "id", "foo" AS "bar" FROM "t1") AS "inner" ON "inner"."id" = "t2"."id"

$sql.from('t1').
    join('t2', :on(["t1.id", "=", Identifier.new("t2.id")], ["t1.foo", "<", "t2.foo"])).
    select(<t1.foo t2.bar>);
# sql: SELECT "t1"."foo", "t2"."bar" FROM "t1" JOIN "t2" ON "t1.id" = "t2.id" AND "t1"."foo" < "t2"."foo"

```

## limit(Int $n)

Provides a `LIMIT` clause (with the specified value as a placeholder):

```
$sql.from('table').select(<foo bar>).limit(1);
# sql: SELECT "foo", "bar" FROM "table" LIMIT ?
# bind: 1

```

## offset(Int $n)

Provides a `OFFSET` clause (with the specified value as a placeholder):

```
$sql.from('table').select(<foo bar>).limit(1).offset(2);
# sql: SELECT "foo", "bar" FROM "table" LIMIT ? OFFSET ?
# bind: [1, 2]

```

## group-by(\*@columns)

Provides a `GROUP BY` clause on the specified columns:

```
$sql.from('songs').select(Fn.new('SUM', 'length'), 'artist', 'year').group-by('artist', 'year');
# SELECT SUM("length"), "artist", "year" FROM songs GROUP BY "artist", "year"

```

## having(@having)

Provides a `HAVING` clause. This is handled identical to a `WHERE` clause, see the documentation above.

## order-by(\*@columns)

Provides an `ORDER BY` clause on the specified columns. Each value is interpreted as an `Identifier`, though you may specify another subclass of `SQLSyntax` to use an expression instead:

```
# pick 10 shortest shortest songs
$sql.from('songs').select('title').order-by('length').limit(10);
# sql: SELECT "title" FROM "songs" ORDER BY "length" limit ?
# bind: 10

# pick 10 random items
$sql.from('songs').select('title').order-by(Fn.new('RANDOM')).limit(10);
# sql: SELECT "title" FROM "songs" ORDER BY RANDOM() limit ?
# bind: 10

```

A `Capture` may be specified to use descending order, by providing the column name (or expression) and `:desc`. `:asc` is also supported if you wish to be explicit about ascending order.

```
# pick 10 longest songs
$sql.from('songs').select('title').order-by(\("length", :desc)).limit(10);
# sql: SELECT "title" FROM "songs" ORDER BY "length" DESC limit ?
# bind: 10

```

## build(:$pretty=False)

Converts this `SelectBuilder` into an `SQLFragment` that has `.sql` and `.bind` methods. This method may be called more than once, but it is not recommended. The SQL and bind values may not appear in the same order across invocations.

If `$pretty` is true, then the resulting SQL will be (minimally) pretty-printed.

## clone()

Returns a new `SelectBuilder` in the same state. Useful if you want to have a common set of options, and then use many times. (Note that if you do not clone, then the original builder would be modified, which may not be what you want.)

```
sub getuser {
    state $q = $sql.from('users').select(<username email address>);
    $q.clone;
}

# multiple times later:
my $username = "whoever";
my $st2 = getuser().where(:$username).build;
# $db.query($st2.sql, |$st2.bind);

```

# INSERT QUERIES

Insert queries are created with the `insert-into` method on the `SQL::Builder` object. All other options can be passed in any order. All options overwrite the current value. Each option returns the InsertBuilder instance, allowing for a chain style:

```
$sql.insert-into("table").values([:a(1), :b(2)])
# INSERT INTO "table" ("a", "b") VALUES (?, ?)

```

The Insert query requires some values to insert. You may specify this with the `values` clause to provide values verbatim, or the combination of `columns` and `query` to get values from a subquery (typically a sub-select).

## new(Str $table)

Creates a `InsertBuilder` for the given table.

## values(@values)

Set the data to be inserted. The data is a List of Pairs, where the key is the column name (as an `Identifier`), and the value is the value (interpreted as a `Placeholder`). This may be passed in a variety of styles, all equivalent:

```
$sql.insert-into("table").values([:a(1), :b(2)])
$sql.insert-into("table").values(:a(1), :b(2))
$sql.insert-into("table").values([:a(1)], :b(2))
# sql: INSERT INTO "table" ("a", "b") VALUES (?, ?)
# bind: [1, 2]

```

This only supports inserting a single row.

## columns(@columns)

Sets the columns to insert, as a List of columns (interpreted as `Identifier`s). Used in combination with `query`, see below for an example.

## query(SQLStatement $query)

Provides the values to insert from the result of a query. This query is typically a Select statement but may be other queries depending on database support.

```
my $inner = $sql.from("t1").select("a", "b").order-by("a").limit(1);
$sql.insert-into("t2").columns("c", "d").query($inner);
# INSERT INTO "t2" ("c", "d") SELECT "a", "b" FROM "t1" ORDER BY "a" LIMIT 1

```

## returning(@columns)

Provides a `RETURNING` clause, with list of columns (or other expressions) to return. This works identically to the `select` clause of a Select query, see that documentation above.

```
$sql.insert-into("table").values(:a(1), :b(2), :c(3)).returning("b", Fn.new("LOWER", "c"))
# INSERT INTO "table" WHERE "a" = ? RETURNING "b", LOWER("c")

```

## build(:$pretty=False)

Converts this `InsertBuilder` into an `SQLFragment` that has `.sql` and `.bind` methods. This method may be called more than once, but it is not recommended. The SQL and bind values may not appear in the same order across invocations.

If `$pretty` is true, then the resulting SQL will be (minimally) pretty-printed.

# UPDATE QUERIES

Update queries are created with the `update` method on the `SQL::Builder` object. All other options can be passed in any order. All options overwrite the current value. Each option returns the UpdateBuilder instance, allowing for a chain style:

```
$sql.update("table").set(:a(1)).where(["b", "=", 2])
# UPDATE "table" SET a = ? WHERE "a" = ?

```

## new(Str $table)

Creates a `UpdateBuilder` for the given table.

## set(@values)

Set the data to be updated. The data is a List of Pairs, where the key is the column name (as an `Identifier`), and the value is the value (interpreted as a `Placeholder`). This may be passed in a variety of styles, all equivalent:

```
$sql.update("table").set([:a(1), :b(2)]).where(:c(3))
$sql.update("table").set(:a(1), :b(2)).where(:c(3))
$sql.update("table").set([:a(1)], :b(2)).where(:c(3))
# sql: UPDATE "table" SET "a" = ?, "b" = ? WHERE "c" = ?
# bind: [1, 2, 3]

```

If you want to provide an expression for a column, use a `Fn` or `Raw` value:

```
my $fn = Fn.new("MAX", "a", "d");
my $expr = Raw.fmt('{} + {}', Identifier.new("c"), Placeholder.new(1234));
$sql.update("table").set([:a($fn), :b($expr)]).where(:c(3))
# sql: UPDATE "table" SET "a" = MAX("a", "d"), "b" = "c" + ? WHERE "c" = ?
# bind: [1234, 3]

```

## where($where) / where(@where)

Provides a `WHERE` clause with one or more values. This works identically to `where` for Select queries, and is used to make a ConditionClause. See documentation for `where` above, and on `ConditionClause` below.

Unlike Select queries, this is required, even if you want to update all rows in a table.

## returning(@columns)

Provides a `RETURNING` clause, with list of columns (or other expressions) to return. This works identically to the `select` clause of a Select query, see that documentation above.

## build(:$pretty=False)

Converts this `UpdateBuilder` into an `SQLFragment` that has `.sql` and `.bind` methods. This method may be called more than once, but it is not recommended. The SQL and bind values may not appear in the same order across invocations.

If `$pretty` is true, then the resulting SQL will be (minimally) pretty-printed.

# DELETE QUERIES

Delete queries are created with the `delete-from` method on the `SQL::Builder` object. All other options can be passed in any order. All options overwrite the current value. Each option returns the DeleteBuilder instance, allowing for a chain style:

```
$sql.delete-from("table").where(["a", "=", 1])
# DELETE FROM "table" WHERE "a" = ?

```

## new(Str $table)

Creates a `DeleteBuilder` for the given table.

## where($where) / where(@where)

Provides a `WHERE` clause with one or more values. This works identically to `where` for Select queries, and is used to make a ConditionClause. See documentation for `where` above, and on `ConditionClause` below.

Unlike Select queries, this is required, even if you want to delete all rows in a table.

## returning(@columns)

Provides a `RETURNING` clause, with list of columns (or other expressions) to return. This works identically to the `select` clause of a Select query, see that documentation above.

```
$sql.delete-from("table").where(["a", "=", 1]).returning("b", Fn.new("LOWER", "c"))
# DELETE FROM "table" WHERE "a" = ? RETURNING "b", LOWER("c")

```

## build(:$pretty=False)

Converts this `DeleteBuilder` into an `SQLFragment` that has `.sql` and `.bind` methods. This method may be called more than once, but it is not recommended. The SQL and bind values may not appear in the same order across invocations.

If `$pretty` is true, then the resulting SQL will be (minimally) pretty-printed.

# ConditionClause

The `ConditionClause` syntax is how `SQL::Builder` encodes the options of the `WHERE` clause, the `HAVING` clause, and the `JOIN ... ON` clause.

Multiple items are combined with `AND` logic. To use `OR` logic, use a sub-group (Capture), documented below.

At its core, this syntax is a list of items. Each item can be one of three values:

## 3-Valued List

The main item is a list of exactly three items, typically a column (`Identifier`), an operator (`Raw`), and a `Placeholder` value.

```
$q.where(["a", "=", 1]);
# sql: ... WHERE a = ?
# bind: [1,]

```

Any of these three can be replaced by an explicit type from the "Type System" section above:

```
$q.where([Fn.new("lower", "a"), "=", Fn.new("lower", "b")]);
# sql: ... WHERE lower("a") = lower("b")

$q.where(["b", ">=", Raw.fmt('{} / 2.0', Placeholder.new(3))]);
# sql: ... WHERE "b" >= ? / 2.0
# bind: [3,]

```

## Pair

As a convenience, a Pair is used for equality.

```
$q.where([:a(1)]);
# sql: ... WHERE "a" = ?
# bind: [1,]

my $a = 1;
$q.where([:$a]);
# sql: ... WHERE "a" = ?
# bind: [$a,]

```

If the value is exactly `Nil`, then `IS NULL` is used instead. `Nil` is the only undefined value with this special treatment:

```
$q.where([:a(Nil)]);
# sql: ... WHERE "a" IS NULL

# other values are not special:
$q.where([:a(Any)]);
# sql: ... WHERE "a" = ?
# bind: [Any,]

```

## Sub-group (Capture)

To represent a parenthesized sub-group, use a `Capture` with the `\(...)` syntax. This Capture must contain a single Pair, with the key of `and` or `or`, depending on which you want, and the value is another list that creates another `ConditionClause`.

```
$q.where([:a<b>, \(:or[
    :c<d>, :e<f>
])]);
# sql: ... WHERE "a" = ? AND (c = ? OR e = ?)
# bind: ["b", "d", "f"]

```

This syntax is chosen to avoid difficulties with flattening of lists in Raku. It also avoids some confusion between Pairs and single-item Hashes.

Subgroups also provide a way to switch from `AND` to `OR` logic:

```
$q.where(\(:or[
    :c<d>, :e<f>
]));
# sql: ... WHERE (c = ? OR e = ?)
# bind: ["d", "f"]

```

# COMPATIBILITY

The author primarily uses this module with PostgeSQL, however it should work fine for most database engines. Some syntax may not be readily accessible outside of the `Raw.fmt` syntax.

# AUTHOR

Adrian Kreher [avuserow@gmail.com](mailto:avuserow@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2022 - 2024 Adrian Kreher

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


## dist_zef-samy-Sys-OsRelease.md
# NAME

Sys::OsRelease - Read OS info from system os-release file

# SYNOPSIS

```
use Sys::OsRelease;

my %osinfo = os-release;

```

# DESCRIPTION

Sys::OsRelease is a module that provides the `os-release` function, which reads your system's os-release file and returns a hash of the data found in the file.

The os-release file is a text file found on many modern \*NIX systems that conveniently details operating system identification data, such as the OS name and version. More information can be found in the [official standard](https://www.freedesktop.org/software/systemd/man/latest/os-release.html) by freedesktop.org.

By default, `os-release` will try to locate and read one of the following files in descending order of priority:

```
/etc/os-release
/usr/lib/os-release

```

`os-release`'s signature:

```
Str  :$path = get_os-release_path(),
Bool :$defaults = False,
Bool :$strict = True,
Bool :$standard-only = True,
--> Hash

```

* **path**

  Path to the os-release file.

  By default, searches for os-release file in the standard locations which were mentioned above.
* **defaults**

  Initialize hash with default values, which are the following:

  ```
  NAME         => "Linux",
  ID           => "linux",
  PRETTY_NAME  => "Linux",
  SYSEXT_SCOPE => "system portable",

  ```

  Defaults to `False`.
* **strict**

  Toggle strict file reading. When `True`, `os-release` will do basic sanity checks on read data and die on invalid lines. When `False`, `os-release` will just ignore invalid lines and odd data.

  Defaults to `True`.
* **standard-only**

  Determines whether `os-release` should ignore non-standard parameters (those not listed in the official freedesktop.org standard).

  Defaults to `True`.

# AUTHOR

Written by Samuel Young, [samyoung12788@gmail.com](mailto:samyoung12788@gmail.com).

# COPYRIGHT

Copyright 2024, Samuel Young

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

# SEE ALSO

[os-release](https://www.freedesktop.org/software/systemd/man/latest/os-release.html)


## dist_github-retupmoca-Net-POP3.md
# P6-Net-POP3

A pure-perl implementation of a POP3 client.

## Example Usage

```
####
# raw interface
####
my $pop = Net::POP3.new(:server("your.server.here"), :port(110), :debug, :raw);
$pop.get-response # +OK

$pop.apop-login("username", "password");
# or (less secure)
$pop.user("username");
$pop.pass("password");

my $message-list = $pop.list; # +OK 2 messages\r\n1 120\r\n...
say $pop.retr(1); # +OK \r\nFrom:...
$pop.dele(1);
$pop.quit;

####
# simple interface
####
my $pop = Net::POP3.new(:server("your.server.here"), :port(110), :debug);
$pop.auth("username", "password"); # tries apop, then falls back to user/pass
my $count = $pop.message-count;
my @messages = $pop.get-messages;
for @messages {
    my $unique-id = .uid;
    my $raw-data = .data;
    my $email-mime = .mime; # returns Email::MIME object
                            # (requires Email::MIME installed to work)
    .delete;
}
$pop.quit;

```

## Simple mode methods

Note that all of these methods should return a true value (or a valid false response,
such as '0' from message-count) on success or a Failure object on failure.

* `new(:$server!, :$port, :$debug, :$socket, :$ssl, :$starttls, :$plain)`

  Creates a new POP3 client and opens a connection to the server.

  `$port` defaults to 110.

  `$debug` will print the network traffic to $\*ERR if set.

  `$socket` allows you to use a class other than IO::Socket::INET for
  network communication. If you pass in a defined object, Net::POP3 will assume
  it is an already connected socket.
* `auth($username, $password)`

  Authenticates with the server. Attempts APOP first, and if the server doesn't
  support APOP or if the APOP login fails, will attempt a USER + PASS plain text
  login.
* `message-count()`

  Returns the number of messages in your mailbox.
* `get-message(:$sid, :$uid)`

  Returns a Net::POP3::Message object that refers to the message with the specified
  session id ($sid, the standard POP3 message number) or unique id ($uid, as returned
  from UIDL. NYI)
* `get-messages()`

  Returns a list of Net::POP3::Message objects, one for each message in the current
  mailstore.
* `quit()`

  Commits any message deletions and closes the connection to the server.

### Net::POP3::Message Methods

This class contains the actual message from the POP3 server.

* `size()`

  Returns the size of the message, in octets.
* `uid()`

  Returns the unique id of the message (as returned by UIDL)
* `delete()`

  Deletes this message from the POP3 server. Will not take effect until .quit is
  called on the main object.
* `data()`

  Returns the raw email message as a string.
* `mime()`

  Returns the email message as an Email::MIME object. Note that this will fail
  if Email::MIME is not installed.


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

# NAME

hide-methods - hide methods of classes during runtime

# SYNOPSIS

```
use hide-methods;

class A {
    method foo() { say "foo" }
}

A.foo;  # foo

hide-methods(A,"foo");
A.foo;  # X::Method::NotFound

class B {
    method bar() { say "bar" }
}

B.bar;  # bar

my $vault = B.&hide-methods("bar");
B.bar;  # X::Method::NotFound

$vault.unhide-methods("bar");
B.bar;  # bar

```

# DESCRIPTION

`hide-methods` is a module that exports a single subroutine called `hide-methods`. Calling this subroutine with a class and one or more method names, will hide the indicated methods from execution, resulting in either having a `X::Method::NotFound` exception thrown, or a method with the same name called from a parent class (if that doesn't happen to be hidden as well, of course).

Handles standard method call dispatch and the `.can` method on classes. Does **not** affect dispatch through `.?`, `.+` or `.*`, or listing with the `.^methods` method.

# SUBROUTINES

## hide-methods

```
hide-methods(A,<foo bar baz>);   # hide "foo","bar","baz" methods in A
A.&hide-methods(<foo bar baz>);  # same, using method syntax

my $vault = hide-methods(B,"zippo");  # allow unhiding

$vault.unhide-methods("zippo");  # make B.zippo available again

```

The `hide-methods` subroutine takes a class as the first parameter, and one or more names of methods to hide. It returns a `Vault` object that supports a `unhide-methods` method, that takes the names of the methods that should become available again.

# AUTHOR

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

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

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

# COPYRIGHT AND LICENSE

Copyright 2020, 2021, 2024 Elizabeth Mattijsen

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


## dist_zef-lucs-Debugging-Tool.md
[![Actions Status](https://github.com/lucs/Debugging-Tool/actions/workflows/test.yml/badge.svg)](https://github.com/lucs/Debugging-Tool/actions)

# NAME

```
Debugging::Tool - To print debugging info during development

```

## DESCRIPTION

Brian Kernighan observed in "Unix for Beginners" (1979) that "The most effective debugging tool is still careful thought, coupled with judiciously placed print statements.".

`Debugging::Tool` instances help placing those print statements, but the careful thought part is left up to you. A `Debugging::Tool` instance's printing methods can print a message you want, mentioning by default on which line of which file the method was called.

## SUMMARY

### Constructor

The constructor specifies where to print and how to format the messages you print:

```
    method new (
        $destination?,
        Block $formatter?,
    )

```

Valid values for `$destination` are:

```
    1             : $*OUT
    2             : $*ERR
    'wut.debug'   : some arbitrary file name
    '/tmp/baz'    : some other arbitrary file name
    '/dev/pts/8'  : some arbitrary terminal

```

If `$destination` is not specified or is `Any`, the program will check to see if the `DEBUGGING_TOOL_TO` envvar is set. If it is, it will use that value, otherwise the instance's printing methods will do nothing.

Setting `DEBUGGING_TOOL_TO` to a given terminal may be the most useful way to use this module, as your debugging messages won't be interleaved with your program's actual output.

The `$formatter` block may be applied to the message that is to be printed. If not specified but needed, the default one will be used, resulting in strings that look like this:

```
    «L-⟨line number⟩ ‹⟨message⟩› …/⟨file⟩»

```

### Printing methods

The basic printing methods are:

```
    put putf putn putfn
    say sayf sayn sayfn

```

All have the same structure and build a message to print from their `@elems` argument:

```
    method ⟨as above, and more⟩ (
        *@elems,
        Real :s($sleep) where * >= 0,
    ) {⋯}

```

Half of the printing method names start with 'put', and half with 'say'. Before using `@elems` to build the message to print, those that start with 'put' will apply `.Str` to all its elements, and those that start with 'say' will apply `.gist`.

Plain `put` and `say` simply concatenate the `@elems` elements and make that the message that they will display. Note that a newline will be appended to the printed string in both cases.

If 'f' is added to the name, the method will instead interpret `@elems` as a list of arguments (after applying `.Str` or `.gist` n'est-ce pas) to be passed to `sprintf()` to build the message to display.

If 'n' is added to the name, no newline will be added to what is to be printed.

Both 'f' and 'n' can be added (in that order) to either 'put' or 'say' to obtain both effects.

There are also variations of the basic printing methods where their name can be changed by either, or both:

* Prepending an underscore: The method will print nothing. For example: `_put(⋯)`, `_sayf(⋯)`. This is an easy way to "comment out" such a debugging invocation, and it makes it easy to search for in code too.
* Appending an underscore: The `$formatter` attribute block will not be applied. For example: `sayn_(⋯)`, `put_(⋯)`.
* Both can be combined (and nothing gets printed): `_putfn_(⋯)`, `_say_(⋯)`.

If a printing method fails for some reason, a `Debugging::Tool::XCantPrint` exception will be raised.

### Other methods

```
    method pause    # Printing methods will do nothing until resume() is called.
    method resume   # Resume the printing.

```

### The `$formatter()` attribute

This attribute is a `Block` that may be invoked by the printing methods. Its default implementation will build a line that looks like this:

```
    «L-⟨line number⟩ ‹⟨message⟩› …/⟨file⟩»

```

You can supply your own `$formatter` to the constructor. The `Block` must be declared as taking two arguments and when it gets invoked by the printing methods, the arguments that will be passed to it are the message that was constructed from the printing method's `@elems` and a callframe corresponding to where the printing method was called.

If your formatter is not interested in using either or both of those arguments, just declare them as `Any`. Here are a few illustrations:

```
        This formatter just returns the message without changing
        anything. It's like if no formatter was being applied or like
        if only methods whose name ends with an underscore were being
        invoked.
    Debugging::Tool.new: 1, -> $msg, Any { $msg }

        This one ignores the message argument and just returns a
        number that increments each time a printing method is called.
        Not really useful, but there it is.
    Debugging::Tool.new: 1, -> Any, Any { state $n = 1; $n++ }

        This one uppercases any message that contains the string
        'error' matched case insensitively.
    Debugging::Tool.new(
        1,
        sub ($msg is copy, Any) {
            $msg .= uc if $msg ~~ m:i/ 'error' /;
            return $msg;
        }
    )

        This is the code of the default formatter.
    sub ($msg, $callframe) {
            The callframe 'file' annotation sometimes
            appends the parenthesized name of the module to
            the file name, so we remove it here.
        (my $filename = $callframe.file) ~~ s/ \s+ '(' \S+ ')' $//;
        sprintf(
            "L-%-5d ‹%s› …/%s",
            $callframe.line,
            $msg,
            $filename.IO.basename,
        );
    }

```

## Examples

This first example presumes that the `DEBUGGING_TOOL_TO` envvar is set to `/dev/pts/8` and that the code is in a file named `wip.raku`:

```
    use Debugging::Tool;
    my $dt = Debugging::Tool.new;

        # Prints this line in the ‹/dev/pts/8› terminal window:
        # «L-6   ‹The value of $x is 42› …/wip.raku␤»
    $dt.put: 'The value of $x is ', 6 * 7;

```

This one makes the printing methods output to STDOUT and uses a `$formatter` that uppercases the message to print. It will print a message built with `sprintf()`:

```
    use Debugging::Tool;
    my $dt = Debugging::Tool.new:
        1,
        :formatter(sub ($msg, Any) {return $msg.uc}),
    ;

        # Will print «ABC - 023␤» to STDOUT.
    $dt.putf: "%s - %03d", 'abc', 23;

```

This last example will print to STDERR a message without applying the `$formatter` and will sleep a bit after printing it:

```
    use Debugging::Tool;
    my $dt = Debugging::Tool.new: 2;

        # Prints «Hiya.␤» to STDERR, then sleeps for 1.5 seconds.
    $dt.put_: :s(1.5), 'Hiya.';

```

# AUTHOR

Luc St-Louis [lucs@pobox.com](mailto:lucs@pobox.com)

# COPYRIGHT AND LICENSE

Copyright 2024 Luc St-Louis

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


## push.md
push

Combined from primary sources listed below.

# [In role Buf](#___top "go to top of document")[§](#(role_Buf)_method_push "direct link")

See primary documentation
[in context](/type/Buf#method_push)
for **method push**.

```raku
method push( $elems )
```

Adds elements at the end of the buffer.

```raku
my $bú = Buf.new( 1, 1, 2, 3, 5 );
$bú.push( 8 );
say $bú.raku; # OUTPUT: «Buf.new(1,1,2,3,5,8)␤»
```

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

See primary documentation
[in context](/type/IterationBuffer#method_push)
for **method push**.

```raku
method push(IterationBuffer:D: Mu \value)
```

Adds the given value at the end of the `IterationBuffer` and returns the given value.

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

See primary documentation
[in context](/type/Array#method_push)
for **method push**.

```raku
multi method push(Array:D: **@values is raw --> Array:D)
multi method push(Array:D: \value --> Array:D)
multi method push(Array:D: Slip \values --> Array:D)
```

Adds the provided value or values to the end of the array, and returns the modified array. If any argument is a [`Slip`](/type/Slip), method `push` will add the values produced by the argument's [iterator](/routine/iterator). It throws if the invocant array or a [`Slip`](/type/Slip) [is lazy](/routine/is-lazy).

Example:

```raku
my @foo = <a b c>;
@foo.push: 'd';
say @foo;                   # OUTPUT: «[a b c d]␤»
```

Note that `push` does not attempt to flatten its argument list. If you pass an array or list as the thing to push, it becomes one additional element:

```raku
my @a = <a b c>;
my @b = <d e f>;
@a.push: @b;
say @a.elems;               # OUTPUT: «4␤»
say @a[3].join;             # OUTPUT: «def␤»
```

Multiple values are added to the array only if you supply them as separate arguments or in a [`Slip`](/type/Slip):

```raku
my @a = '1';
say @a.push: 'a', 'b';       # OUTPUT: «[1 a b]␤»
my @c = <E F>;
say @a.push: @c.Slip;        # OUTPUT: «[1 a b E F]␤»
```

See [method append](/type/Array#method_append) if you want to append multiple values that are produced by a single non-slipping [`Iterable`](/type/Iterable).

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

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

```raku
multi method push(Any:U \SELF: |values --> Positional:D)
```

The method push is defined for undefined invocants and allows for autovivifying undefined to an empty [`Array`](/type/Array), unless the undefined value implements [`Positional`](/type/Positional) already. The argument provided will then be pushed into the newly created Array.

```raku
my %h;
say %h<a>;     # OUTPUT: «(Any)␤»      <-- Undefined
%h<a>.push(1); # .push on Any
say %h;        # OUTPUT: «{a => [1]}␤» <-- Note the Array
```

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

See primary documentation
[in context](/type/Nil#method_push)
for **method push**.

```raku
method push(*@)
```

Warns the user that they tried to push onto a `Nil` or derived type object.

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

See primary documentation
[in context](/type/Hash#method_push)
for **method push**.

```raku
method push(Hash:D: +new)
```

Adds the `new` elements to the hash with the same semantics as hash assignment, but with three exceptions:

* The hash isn't emptied first, i.e. old pairs are not deleted.
* If a key already exists in the hash, and the corresponding value is an [`Array`](/type/Array), the new value is pushed onto the array (instead of replacing it).
* If a key already exists in the hash, and the corresponding value is not an [`Array`](/type/Array), old and new value are both placed into an array in the place of the old value.

Example:

```raku
my %h  = a => 1;
%h.push: (a => 1);              # a => [1,1]
%h.push: (a => 1) xx 3 ;        # a => [1,1,1,1,1]
%h.push: (b => 3);              # a => [1,1,1,1,1], b => 3
%h.push('c' => 4);              # a => [1,1,1,1,1], b => 3, c => 4
push %h, 'd' => 5;              # a => [1,1,1,1,1], b => 3, c => 4, d => 5
```

Please note that literal pairs in the argument list may be interpreted as [named arguments](/type/Capture) and as such won't end up in the `Hash`:

```raku
my %h .= push(e => 6);
say %h.raku; # OUTPUT: «{}␤»
```

Use the corresponding [subroutine](/type/independent-routines#sub_push) to catch this kind of mistake:

```raku
push my %h, f => 7;
CATCH { default { put .message } };
# OUTPUT: «Unexpected named argument 'f' passed␤»
```

Also note that push can be used as a replacement for assignment during hash initialization very useful ways. Take for instance the case of an inverted index:

```raku
my %wc = 'hash' => 323, 'pair' => 322, 'pipe' => 323;
(my %inv).push: %wc.invert;
say %inv;                     # OUTPUT: «{322 => pair, 323 => [pipe hash]}␤»
```

Note that such an initialization could also be written as

```raku
my %wc = 'hash' => 323, 'pair' => 322, 'pipe' => 323;
my %inv .= push: %wc.invert;
```

**Note:** Compared to [`append`](/routine/append), `push` will add the given value as is, whereas `append` will [`slip`](/routine/slip) it in:

```raku
my %ha = :a[42, ]; %ha.push: "a" => <a b c a>;
say %ha; # OUTPUT: «{a => [42 (a b c a)]}␤»

my %hb = :a[42, ]; %hb.append: "a" => <a b c a>;
say %hb; # OUTPUT: «{a => [42 a b c a]}␤»
```

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

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

```raku
multi push(\a, **@b is raw)
multi push(\a, \b)
```

Calls method `push` on the first argument, passing the remaining arguments. Method `push` is supposed to add the provided values to the end of the collection or parts thereof. See the documentation of the [`Hash` method](/routine/push#(Hash)_method_push) for an example where indirection via this subroutine can be helpful.

The `push` method is supposed to flatten all arguments of type [`Slip`](/type/Slip). Therefore, if you want to implement a conforming method for a new collection type, it should behave as if its signature was just:

```raku
multi method push(::?CLASS:D: **@values is raw --> ::?CLASS:D)
```

Autovivification to an instance of the new type is [provided by the default base class](/routine/append#(Any)_method_append) if the new type implements the [`Positional`](/type/Positional) role. If the new type is not [`Positional`](/type/Positional), autovivification can be supported by adding a multi method with a signature like

```raku
multi method push(::?CLASS:U: **@values is raw --> ::?CLASS:D)
```


## clone.md
clone

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Match#method_clone)
for **method clone**.

```raku
method clone()
```

Clones the `Match` object.

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

See primary documentation
[in context](/type/Array#method_clone)
for **method clone**.

```raku
method clone(Array:D: --> Array:D)
```

Clones the original `Array`. Modifications of elements in the clone are not propagated to the original and vice-versa:

```raku
my @a = <a b c>; my @b = @a.clone;
@b[1] = 42; @a.push: 72;
say @b; # OUTPUT: «[a 42 c]␤»
say @a; # OUTPUT: «[a b c 72]␤»
```

However, note that the reifier *is* shared between the two Arrays, so both Arrays will have the same elements even when each is randomly-generated on reification and each element will be reified just once, regardless of whether the reification was done by the clone or the original Array. **Note:** just as reifying an Array from multiple threads is not safe, so is, for example, reifying the clone from one thread while reifying the original from another thread is not safe.

```raku
my @a = 1, {rand} … ∞; my @b = @a.clone;
say @b[^3]; # OUTPUT: «(1 0.0216426755282736 0.567660896142156)␤»
say @a[^3]; # OUTPUT: «(1 0.0216426755282736 0.567660896142156)␤»
```

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

See primary documentation
[in context](/type/Mu#method_clone)
for **method clone**.

```raku
multi method clone(Mu:U: *%twiddles)
multi method clone(Mu:D: *%twiddles)
```

This method will clone type objects, or die if it's invoked with any argument.

```raku
say Num.clone( :yes )
# OUTPUT: «(exit code 1) Cannot set attribute values when cloning a type object␤  in block <unit>␤␤»

```

If invoked with value objects, it creates a shallow clone of the invocant, including shallow cloning of private attributes. Alternative values for *public* attributes can be provided via named arguments with names matching the attributes' names.

```raku
class Point2D {
    has ($.x, $.y);
    multi method gist(Point2D:D:) {
        "Point($.x, $.y)";
    }
}

my $p = Point2D.new(x => 2, y => 3);

say $p;                     # OUTPUT: «Point(2, 3)␤»
say $p.clone(y => -5);      # OUTPUT: «Point(2, -5)␤»

```

Note that `.clone` does not go the extra mile to shallow-copy `@.` and `%.` sigiled attributes and, if modified, the modifications will still be available in the original object:

```raku
class Foo {
    has $.foo is rw = 42;
    has &.boo is rw = { say "Hi" };
    has @.bar       = <a b>;
    has %.baz       = <a b c d>;
}

my $o1 = Foo.new;
with my $o2 = $o1.clone {
    .foo = 70;
    .bar = <Z Y>;
    .baz = <Z Y X W>;
    .boo = { say "Bye" };
}

# Hash and Array attribute modifications in clone appear in original as well:
say $o1;
# OUTPUT: «Foo.new(foo => 42, bar => ["Z", "Y"], baz => {:X("W"), :Z("Y")}, …␤»
say $o2;
# OUTPUT: «Foo.new(foo => 70, bar => ["Z", "Y"], baz => {:X("W"), :Z("Y")}, …␤»
$o1.boo.(); # OUTPUT: «Hi␤»
$o2.boo.(); # OUTPUT: «Bye␤»

```

To clone those, you could implement your own `.clone` that clones the appropriate attributes and passes the new values to `Mu.clone`, for example, via [`nextwith`](/language/functions#sub_nextwith).

```raku
class Bar {
    has $.quux;
    has @.foo = <a b>;
    has %.bar = <a b c d>;
    method clone { nextwith :foo(@!foo.clone), :bar(%!bar.clone), |%_  }
}

my $o1 = Bar.new( :42quux );
with my $o2 = $o1.clone {
    .foo = <Z Y>;
    .bar = <Z Y X W>;
}

# Hash and Array attribute modifications in clone do not affect original:
say $o1;
# OUTPUT: «Bar.new(quux => 42, foo => ["a", "b"], bar => {:a("b"), :c("d")})␤»
say $o2;
# OUTPUT: «Bar.new(quux => 42, foo => ["Z", "Y"], bar => {:X("W"), :Z("Y")})␤»

```

The `|%_` is needed to slurp the rest of the attributes that would have been copied via shallow copy.

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

See primary documentation
[in context](/type/DateTime#method_clone)
for **method clone**.

```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␤»
```

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

See primary documentation
[in context](/type/Date#method_clone)
for **method clone**.

```raku
method clone(Date:D: :$year, :$month, :$day, :&formatter)
```

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

```raku
say Date.new('2015-11-24').clone(month => 12);    # OUTPUT: «2015-12-24␤»
```


## dist_cpan-UZLUISF-Ranker.md
# NAME

Ranker - a module to rank a list of elements.

# DESCRIPTION

This is a module for ranking a list/array of scorable elements using various ranking strategies written in Raku.

It's mostly based on [Ilya Scharrenbroich's Ruby library](https://github.com/quidproquo/ranker) by the same name.

# INSTALLATION

Either:

* from CPAN:

  * `zef install Ranker`
* from local directory:

  * `git clone git@gitlab.com:uzluisf/ranker.git` or [download it](https://gitlab.com/uzluisf/ranker)
  * `zef install path/to/ranker/`

# SYNOPSIS

## Default Ranking

Default ranking will assume values are numeric and rank them in their descending order. For example, a score of 100 is higher than a score of 50 and thus appears before as in `[100, 50]`.

```
use Ranker;

my @scores = 1, 1, 2, 3, 3, 1, 4, 4, 5, 6, 8, 1, 0, 8;

my $rankings = Ranker::rank(@scores);
put $rankings.elems; #=> 8

my $ranking = $rankings[0];
given $ranking {
    .rank       .put; #=> 1
    .score      .put; #=> 8
    .rankables  .put; #=> [8, 8]
    .percentile .put; #=> 100
    .z-score    .put; #=> 1.83921346366645
}

```

## Custom Ranking by Block

Custom ranking allows for ranking of objects by using an anonymous subroutine which can created with `sub`, with a pointy block or with a block.

```
class Player {
    has Int $.score;
}

my @players = (0, 100, 1000, 25).map: Player.new(score => *);
my (&score, $rankings);

# Explicit:
&score = -> $player { $player.score };
$rankings = Ranker::rank(@players, by => &score);

# Still more explicit:
&score = sub( Player:D $player ) { $player.score };
$rankings = Ranker::rank(@players, by => &score);

# Same thing but more succint:
$rankings = Ranker::rank(@players, by => { $^player.score });

```

In some cases, objects need to be ranked by score in ascending order. For instance, if you were ranking golf players. In this case, 75 is higher than a score of 100 and thus appears before as in `[75, 100]`.

```
class GolfPlayer is Player { }

my @golfplayers = (72, 100, 138, 54).map: GolfPlayer.new(score => *);
my $rankings = Ranker::rank(
    @golfplayers,              # Rankable values
    by => -> gp { $gp.score }, # Block to rank by
    :asc                       # Use ascending order
);

```

## Ranking Strategies

Ranker provides several ranking strategies, which are mostly based on the Wikipedia entry for [ranking](http://en.wikipedia.org/wiki/Ranking). Strategies can be passed in as an option to the `Ranker::rank` subroutine.

```
my $rankings = Ranker::rank(
    @players,
    by       => { $^p.score },
    strategy => 'ordinal',
);

```

The possible string values for the default strategies are: `'standard'`, `'modified'`, `'ordinal'`, `'dense'`, and `'fractional'`.

### **Standard Competition Ranking ("1224" ranking)**

This is the default ranking strategy used by `Ranker`. For more info, see the Wikipedia entry on [Standard Competition Ranking](https://en.wikipedia.org/wiki/Ranking#Standard_competition_ranking_(%221224%22_ranking)).

```
my $rankings = Ranker::rank(
    @players,
    by       => { $^p.score },
    strategy => 'standard',
);

```

### **Modified Competition Ranking ("1334" ranking)**

For more info, see the Wikipedia entry on [Modified Competition Ranking](https://en.wikipedia.org/wiki/Ranking#Modified_competition_ranking_(%221334%22_ranking)).

```
my $rankings = Ranker::rank(
    @players,
    by       => { $^p.score },
    strategy => 'modified',
);

```

### **Dense Ranking ("1223" ranking)**

For more info, see the Wikipedia entry on [Dense Ranking](https://en.wikipedia.org/wiki/Ranking#Dense_ranking_(%221223%22_ranking))

```
my $rankings = Ranker::rank(
    @players,
    by       => { $^p.score },
    strategy => 'dense',
);

```

### **Ordinal Ranking ("1234" ranking)**

For more info, see the Wikipedia entry on [Ordinal Ranking](https://en.wikipedia.org/wiki/Ranking#Ordinal_ranking_(%221234%22_ranking)).

```
my $rankings = Ranker::rank(
    @players,
    by       => { $^p.score },
    strategy => 'ordinal',
);

```

### **Fractional Ranking ("1 2.5 2.5 4" ranking)**

For more info, see the Wikipedia entry on [Fractional Ranking](https://en.wikipedia.org/wiki/Ranking#Fractional_ranking_(%221_2.5_2.5_4%22_ranking)).

```
my $rankings = Ranker::rank(
    @players,
    by       => { $^p.score },
    strategy => 'fractional',
);

```

## Custom Strategies

`Ranker` allows you to write your own strategies and supply them to the `Ranker::rank` subroutine. To do this, you must compose the `Strategy` role into a class and use [`::()`](https://docs.perl6.org/language/packages#Interpolating_into_names) to interpolate the class name into a package or variable name. `Strategy` is the role from which the default «Strategy» classes are composed.

```
use Ranker;
use Ranker::Strategies;

# Composing Strategy into a class
class MyCustomStrategy does Strategy {

  method execute {
    # You must implement this method ;-)
  }

}

my $rankings = Ranker::rank(
    @players,
    by       => -> $p { $p.score },
    strategy => ::('MyCustomStrategy') # Passing the package-interpolated class name
);

```

By default, only the `Strategy` role is exported with `use Ranker::Strategies`, which must be composed before it's used. To export a default strategy, you must specify it with a `use` statement. For instance, `use Ranker::Strategies :dense` exports `Strategies::Dense` which can then be instantiated:

```
use Ranker::Strategies :dense;

my @scores = 44, 42, 42, 43;
my $ds = Dense.new: rankables => @scores, options => { :asc };

```

# ROUTINES

### `Ranker`

* `Ranker::rank(@rankables, *%options)`

  * `@rankables` - list of elements to be ranked
  * `%options` - key-value pairs to specify a custom ranking with `by` (e.g., `by => { $^value }`), a sorting order with `asc` (e.g., `asc => True`) and strategy to be used with `strategy` (e.g., `strategy => 'dense'`).

By default, values are assumed to be numeric and ranked in descending order using the standard-competition ranking strategy. Thus, the following two calls achieve the same thing:

* `Ranker::rank(@values);`
* `Ranker::rank(@values, :by({ $^value }), :asc(False), :strategy('standard'));`

### Others

Run `p6doc` on `Ranker::Ranking`, `Ranker::Rankings` and `Ranker::Strategies` to get the methods made available by `Ranking`, `Rankings` and `Strategy` respectively.

# AUTHOR

Luis F. Uceta

# LICENSE

Artistic License 2.0


## dist_github-codesections-Pod-Tangle.md
[![Actions Status](https://github.com/codesections/pod-tangle/workflows/test/badge.svg)](https://github.com/codesections/pod-tangle/actions)

# NAME

Pod::Tangle - Tangle code from Raku source

# SYNOPSIS

Installation (assuming you already have Raku and [zef](https://github.com/ugexe/zef) installed):

```
zef install Pod::Tangle

```

You can use Pod::Tangle as a library:

```
use Pod::Tangle
tangle($filename.IO);

```

You can also use it through it's command line tool

```
pod-tangle $source.raku > $source-without-pod.raku

```

# DESCRIPTION

Pod::Tangle strips all Pod documentation from a Raku source file, leaving it as a "tangled" file. The goal of doing so is to support basic [literate programming](https://en.wikipedia.org/wiki/Literate_programming) in Raku.

For additional details, please see the announcement blog post: [www.codesections.com/blog/weaving-raku](https://www.codesections.com/blog/weaving-raku).

# AUTHOR

codesections [daniel@codesections.com](mailto:daniel@codesections.com)

# COPYRIGHT AND LICENSE

ⓒ 2020 Daniel Sockwell

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


## hashmap.md
Hashes and maps

Working with associative arrays/dictionaries/hashes

# [The associative role and associative classes](#Hashes_and_maps "go to top of document")[§](#The_associative_role_and_associative_classes "direct link")

The [`Associative`](/type/Associative) role underlies hashes and maps, as well as other classes such as [`MixHash`](/type/MixHash). It defines the two types that will be used in associative classes; by default, you can use anything (literally, since any class that subclasses [`Any`](/type/Any) can be used) [as a key](#Non-string_keys_(object_hash)), although it will be coerced to a string, and any object as value. You can access these types using the `of` and `keyof` methods.

By default, any object declared with the `%` sigil will get the Associative role, and will by default behave like a hash, but this role will only provide the two methods above, as well as the default Hash behavior.

```raku
say (%).^name ; # OUTPUT: «Hash␤»
```

Inversely, you cannot use the `%` sigil if the [`Associative`](/type/Associative) role is not mixed in, but since this role does not have any associated properties, you will have to redefine the behavior of the [hash subscript operator](/language/operators#postcircumfix_{_}). In order to do that, there are several functions you will have to override:

```raku
class Logger does Associative[Cool,DateTime] {
    has %.store;

    method log( Cool $event ) {
        %.store{ DateTime.new( now ) } = $event;
    }

    multi method AT-KEY ( ::?CLASS:D: $key) {
        my @keys = %.store.keys.grep( /$key/ );
        %.store{ @keys };
    }

    multi method EXISTS-KEY (::?CLASS:D: $key) {
        %.store.keys.grep( /$key/ )??True!!False;
    }

    multi method DELETE-KEY (::?CLASS:D: $key) {
        X::Assignment::RO.new.throw;
    }

    multi method ASSIGN-KEY (::?CLASS:D: $key, $new) {
        X::Assignment::RO.new.throw;
    }

    multi method BIND-KEY (::?CLASS:D: $key, \new){
        X::Assignment::RO.new.throw;
    }
}
say Logger.of;                   # OUTPUT: «(Cool)␤»
my %logger := Logger.new;
say %logger.of;                  # OUTPUT: «(Cool)␤»

%logger.log( "Stuff" );
%logger.log( "More stuff");

say %logger<2018-05-26>;         # OUTPUT: «(More stuff Stuff)␤»
say %logger<2018-04-22>:exists;  # OUTPUT: «False␤»

```

In this case, we are defining a logger with Associative semantics that will be able to use dates (or a part of them) as keys. Since we are parameterizing [`Associative`](/type/Associative) to those particular classes, `of` will return the value type we have used, [`Cool`](/type/Cool) in this case (we can log lists or strings only). Mixing the [`Associative`](/type/Associative) role gives it the right to use the `%` sigil; binding is needed in the definition since `%`-sigiled variables get by default the [`Hash`](/type/Hash) type.

This log is going to be append-only, which is why we escape the associative array metaphor to use a `log` method to add new events to the log. Once they have been added, however, we can retrieve them by date or check if they exist. For the first we have to override the `AT-KEY` multi method, for the latter `EXIST-KEY`. In the last two statements, we show how the subscript operation invokes `AT-KEY`, while the `:exists` adverb invokes `EXISTS-KEY`.

We override `DELETE-KEY`, `ASSIGN-KEY` and `BIND-KEY`, but only to throw an exception. Attempting to assign, delete, or bind a value to a key will result in a `Cannot modify an immutable Str (value)` exception thrown.

Making classes associative provides a very convenient way of using and working with them using hashes; an example can be seen in [Cro](https://cro.services/docs/reference/cro-http-client#Setting_the_request_body), which uses it extensively for the convenience of using hashes to define structured requests and express its response.

# [Mutable hashes and immutable maps](#Hashes_and_maps "go to top of document")[§](#Mutable_hashes_and_immutable_maps "direct link")

A [`Hash`](/type/Hash) is a mutable mapping from keys to values (called *dictionary*, *hash table* or *map* in other programming languages). The values are all scalar containers, which means you can assign to them. [`Map`](/type/Map)s are, on the other hand, immutable. Once a key has been paired with a value, this pairing cannot be changed.

Maps and hashes are usually stored in variables with the percent `%` sigil, which is used to indicate they are Associative.

Hash and map elements are accessed by key via the `{ }` postcircumfix operator:

```raku
say %*ENV{'HOME', 'PATH'}.raku;
# OUTPUT: «("/home/camelia", "/usr/bin:/sbin:/bin")␤»
```

The general [Subscript](/language/subscripts) rules apply providing shortcuts for lists of literal strings, with and without interpolation.

```raku
my %h = oranges => 'round', bananas => 'bendy';
say %h<oranges bananas>;
# OUTPUT: «(round bendy)␤»

my $fruit = 'bananas';
say %h«oranges "$fruit"»;
# OUTPUT: «(round bendy)␤»
```

You can add new pairs simply by assigning to an unused key:

```raku
my %h;
%h{'new key'} = 'new value';
```

# [Hash assignment](#Hashes_and_maps "go to top of document")[§](#Hash_assignment "direct link")

Assigning a list of elements to a hash variable first empties the variable, and then iterates the elements of the right-hand side (which must contain an even number of elements). Note that hash keys are always coerced to be strings even if they are unquoted, but keys with spaces in their names must be quoted. For example, using the common [`Pair`](/type/Pair) syntax:

```raku
my %h = 1 => 'a', b => 2, '1 2' => 3;
say %h.keys.sort.raku;       # OUTPUT: «("1", "1 2", "b").Seq␤»
say %h.values.sort.raku      # OUTPUT: «(2, 3, "a").Seq␤»
```

The stringification of the keys can lead to surprising results. For example, the Raku module `CSV::Parser` in one mode returns a CSV data line as a hash of `{UInt => 'value'}` pairs which can look like this fragment of a 20-field line:

```raku
my %csv = '2' => 'a', '10' => 'b';
say %csv.keys.sort.raku;           # OUTPUT: «("10", "2").Seq␤»
```

The sort result is not what one would normally want. We can use the power of Raku to coerce the string values into integers for the sort. There are several ways that can be done but this method may present the least "line noise" to novices or non-Raku viewers:

```raku
say %csv.keys.map(+*).sort.raku;   # OUTPUT: «(2, 10).Seq␤»

```

In a hash constructor list the [`Pair`](/type/Pair) syntax doesn't have to be used, or it may be intermixed with ordinary list values as long as the list has an even number of elements in total as well as between [`Pair`](/type/Pair)s. If an element is a [`Pair`](/type/Pair) type (e.g., 'a => 1'), its key is taken as a new hash key, and its value as the new hash value for that key. Otherwise the value is coerced to [`Str`](/type/Str) and used as a hash key, while the next element of the list is taken as the corresponding value.

```raku
my %h = 'a', 'b', c => 'd', 'e', 'f';
```

Same as

```raku
my %h = a => 'b', c => 'd', e => 'f';
```

or

```raku
my %h = <a b c d e f>;
```

or even

```raku
my %h = %( a => 'b', c => 'd', e => 'f' );
```

If you have an odd number of elements using most constructors you will see an error:

```raku
my %h = <a b c>; # OUTPUT: «hash initializer expected...␤»
```

There are two other valid ways of constructing a hash, but the user should be wary:

```raku
my %h = [ a => 'b', c => 'd', e => 'f' ]; # This format is NOT recommended.
                                          # It cannot be a constant and there
                                          # will be problems with nested hashes
```

or

```raku
my $h = { a => 'b', c => 'd', e => 'f'};
```

Please note that curly braces are used only in the case that we are not assigning it to a `%`-sigiled variable; in case we use it for a `%`-sigiled variable we will get an error of `Potential difficulties:␤ Useless use of hash composer on right side of hash assignment; did you mean := instead?`. As this error indicates, however, we can use curly braces as long as we use also binding:

```raku
my %h := { a => 'b', c => 'd', e => 'f'};
say %h; # OUTPUT: «{a => b, c => d, e => f}␤»
```

Nested hashes can also be defined using the same syntax:

```raku
my %h =  e => f => 'g';
say %h<e><f>; # OUTPUT: «g␤»
```

However, what you are defining here is a key pointing to a [`Pair`](/type/Pair), which is fine if that is what you want and your nested hash has a single key. But `%h<e>` will point to a [`Pair`](/type/Pair) which will have these consequences:

```raku
my %h =  e => f => 'g';
%h<e><q> = 'k';
# OUTPUT: «Pair␤Cannot modify an immutable Str (Nil)␤  in block <unit>»

```

This, however, will effectively define a nested hash:

```raku
my %h =  e => { f => 'g' };
say %h<e>.^name;  # OUTPUT: «Hash␤»
say %h<e><f>;     # OUTPUT: «g␤»
```

If a [`Pair`](/type/Pair) is encountered where a value is expected, it is used as a hash value:

```raku
my %h = 'a', 'b' => 'c';
say %h<a>.^name;            # OUTPUT: «Pair␤»
say %h<a>.key;              # OUTPUT: «b␤»
```

If the same key appears more than once, the value associated with its last occurrence is stored in the hash:

```raku
my %h = a => 1, a => 2;
say %h<a>;                  # OUTPUT: «2␤»
```

To assign a hash to a variable which does not have the `%` sigil, you may use the `%()` hash constructor:

```raku
my $h = %( a => 1, b => 2 );
say $h.^name;               # OUTPUT: «Hash␤»
say $h<a>;                  # OUTPUT: «1␤»
```

If one or more values reference the topic variable, `$_`, the right-hand side of the assignment will be interpreted as a [`Block`](/type/Block), not a Hash:

```raku
my @people = [
    %( id => "1A", firstName => "Andy", lastName => "Adams" ),
    %( id => "2B", firstName => "Beth", lastName => "Burke" ),
    # ...
];

sub lookup-user (Hash $h) { #`(Do something...) $h }

my @names = map {
    # While this creates a hash:
    my  $query = { name => "$person<firstName> $person<lastName>" };
    say $query.^name;      # OUTPUT: «Hash␤»

    # Doing this will create a Block. Oh no!
    my  $query2 = { name => "$_<firstName> $_<lastName>" };
    say $query2.^name;       # OUTPUT: «Block␤»
    say $query2<name>;       # fails

    CATCH { default { put .^name, ': ', .Str } };
    # OUTPUT: «X::AdHoc: Type Block does not support associative indexing.␤»
    lookup-user($query);
    # Type check failed in binding $h; expected Hash but got Block
}, @people;

```

This would have been avoided if you had used the `%()` hash constructor. Only use curly braces for creating Blocks.

## [Hash slices](#Hashes_and_maps "go to top of document")[§](#Hash_slices "direct link")

You can assign to multiple keys at the same time with a slice.

```raku
my %h; %h<a b c> = 2 xx *; %h.raku.say;  # OUTPUT: «{:a(2), :b(2), :c(2)}␤»
my %h; %h<a b c> = ^3;     %h.raku.say;  # OUTPUT: «{:a(0), :b(1), :c(2)}␤»
```

## [Non-string keys (object hash)](#Hashes_and_maps "go to top of document")[§](#Non-string_keys_(object_hash) "direct link")

By default keys in `{ }` are forced to strings. To compose a hash with non-string keys, use a colon prefix:

```raku
my $when = :{ (now) => "Instant", (DateTime.now) => "DateTime" };
```

Note that with objects as keys, you often cannot use the `<...>` construct for key lookup, as it creates only strings and [allomorphs](/language/glossary#Allomorph). Use the `{...}` instead:

```raku
:{  0  => 42 }<0>.say;   # Int    as key, IntStr in lookup; OUTPUT: «(Any)␤»
:{  0  => 42 }{0}.say;   # Int    as key, Int    in lookup; OUTPUT: «42␤»
:{ '0' => 42 }<0>.say;   # Str    as key, IntStr in lookup; OUTPUT: «(Any)␤»
:{ '0' => 42 }{'0'}.say; # Str    as key, Str    in lookup; OUTPUT: «42␤»
:{ <0> => 42 }<0>.say;   # IntStr as key, IntStr in lookup; OUTPUT: «42␤»
```

*Note*: Rakudo implementation currently erroneously applies [the same rules](/routine/{ }#(Operators)_term_{_}) for `:{ }` as it does for `{ }` and can construct a [`Block`](/type/Block) in certain circumstances. To avoid that, you can instantiate a parameterized Hash directly. Parameterization of `%`-sigiled variables is also supported:

```raku
my Num %foo1      = "0" => 0e0; # Str keys and Num values
my     %foo2{Int} =  0  => "x"; # Int keys and Any values
my Num %foo3{Int} =  0  => 0e0; # Int keys and Num values
Hash[Num,Int].new: 0, 0e0;      # Int keys and Num values
```

Now if you want to define a hash to preserve the objects you are using as keys *as the **exact** objects you are providing to the hash to use as keys*, then object hashes are what you are looking for.

```raku
my %intervals{Instant};
my $first-instant = now;
%intervals{ $first-instant } = "Our first milestone.";
sleep 1;
my $second-instant = now;
%intervals{ $second-instant } = "Logging this Instant for spurious raisins.";
for %intervals.sort -> (:$key, :$value) {
    state $last-instant //= $key;
    say "We noted '$value' at $key, with an interval of {$key - $last-instant}";
    $last-instant = $key;
}

```

This example uses an object hash that only accepts keys of type [`Instant`](/type/Instant) to implement a rudimentary, yet type-safe, logging mechanism. We utilize a named [state](/language/variables#The_state_declarator) variable for keeping track of the previous [`Instant`](/type/Instant) so that we can provide an interval.

The whole point of object hashes is to keep keys as objects-in-themselves. Currently object hashes utilize the [WHICH](/routine/WHICH) method of an object, which returns a unique identifier for every mutable object. This is the keystone upon which the object identity operator ([===](/routine/===)) rests. Order and containers really matter here as the order of `.keys` is undefined and one anonymous list is never [===](/routine/===) to another.

```raku
my %intervals{Instant};
my $first-instant = now;
%intervals{ $first-instant } = "Our first milestone.";
sleep 1;
my $second-instant = now;
%intervals{ $second-instant } = "Logging this Instant for spurious raisins.";
say ($first-instant, $second-instant) ~~ %intervals.keys;       # OUTPUT: «False␤»
say ($first-instant, $second-instant) ~~ %intervals.keys.sort;  # OUTPUT: «True␤»
say ($first-instant, $second-instant) === %intervals.keys.sort; # OUTPUT: «False␤»
say $first-instant === %intervals.keys.sort[0];                 # OUTPUT: «True␤»

```

Since [`Instant`](/type/Instant) defines its own comparison methods, in our example a sort according to [cmp](/routine/cmp) will always provide the earliest instant object as the first element in the [`List`](/type/List) it returns.

If you would like to accept any object whatsoever in your hash, you can use [`Any`](/type/Any)!

```raku
my %h{Any};
%h{(now)} = "This is an Instant";
%h{(DateTime.now)} = "This is a DateTime, which is not an Instant";
%h{"completely different"} = "Monty Python references are neither DateTimes nor Instants";
```

There is a more concise syntax which uses binding.

```raku
my %h := :{ (now) => "Instant", (DateTime.now) => "DateTime" };
```

The binding is necessary because an object hash is about very solid, specific objects, which is something that binding is great at keeping track of but about which assignment doesn't concern itself much.

Since 6.d was released, [`Junction`s](/type/Junction) can also be used as hash keys. The result will also be a [`Junction`](/type/Junction) of the same type used as key.

```raku
my %hash = %( a => 1, b => 2, c=> 3);
say %hash{"a"|"c"};   # OUTPUT: «any(1, 3)␤»
say %hash{"b"^"c"};   # OUTPUT: «one(2, 3)␤»
say %hash{"a" & "c"}; # OUTPUT: «all(1, 3)␤»
```

If a Junction of any kind is used to define a key, it will have the same effect of defining elements of the [`Junction`](/type/Junction) as separate keys:

```raku
my %hash = %( "a"|"b" => 1, c => 2 );
say %hash{"b"|"c"};       # OUTPUT: «any(1, 2)␤»

```

## [Constraint value types](#Hashes_and_maps "go to top of document")[§](#Constraint_value_types "direct link")

Place a type object in-between the declarator and the name to constrain the type of all values of a [`Hash`](/type/Hash).

```raku
my Int %h;
put %h<Goku>   = 900;

try {
    %h<Vegeta> = "string";
    CATCH { when X::TypeCheck::Binding { .message.put } }
}

# OUTPUT:
# 9001
# Type check failed in assignment to %h; expected Int but got Str ("string")
```

You can do the same by a more readable syntax.

```raku
my %h of Int; # the same as my Int %h
```

If you want to constraint the type of all keys of a [`Hash`](/type/Hash), add `{Type}` following the name of variable.

```raku
my %h{Int};
```

Even put these two constraints together.

```raku
my %h{Int} of Int;
put %h{21} = 42;

try {
    %h{0} = "String";
    CATCH { when X::TypeCheck::Binding { .message.put } }
}

try {
    %h<string> = 42;
    CATCH { when X::TypeCheck::Binding { .message.put } }
}

try {
    %h<string> = "String";
    CATCH { when X::TypeCheck::Binding { .message.put } }
}

# OUTPUT:
# 42
# Type check failed in binding to parameter 'assignval'; expected Int but got Str ("String")
# Type check failed in binding to parameter 'key'; expected Int but got Str ("string")
# Type check failed in binding to parameter 'key'; expected Int but got Str ("string")
```

# [Looping over hash keys and values](#Hashes_and_maps "go to top of document")[§](#Looping_over_hash_keys_and_values "direct link")

A common idiom for processing the elements in a hash is to loop over the keys and values, for instance,

```raku
my %vowels = 'a' => 1, 'e' => 2, 'i' => 3, 'o' => 4, 'u' => 5;
for %vowels.kv -> $vowel, $index {
  "$vowel: $index".say;
}
```

gives output similar to this:

｢output｣ without highlighting

```

```

a: 1
e: 2
o: 4
u: 5
i: 3

```

```

where we have used the `kv` method to extract the keys and their respective values from the hash, so that we can pass these values into the loop.

Note that the order of the keys and values printed cannot be relied upon; the elements of a hash are not always stored the same way in memory for different runs of the same program. In fact, since version 2018.05, the order is guaranteed to be different in every invocation. Sometimes one wishes to process the elements sorted on, e.g., the keys of the hash. If one wishes to print the list of vowels in alphabetical order then one would write

```raku
my %vowels = 'a' => 1, 'e' => 2, 'i' => 3, 'o' => 4, 'u' => 5;
for %vowels.sort(*.key)>>.kv -> ($vowel, $index) {
  "$vowel: $index".say;
}
```

which prints

｢output｣ without highlighting

```

```

a: 1
e: 2
i: 3
o: 4
u: 5

```

```

in alphabetical order as desired. To achieve this result, we sorted the hash of vowels by key (`%vowels.sort(*.key)`) which we then ask for its keys and values by applying the `.kv` method to each element via the unary `>>` hyperoperator resulting in a [`List`](/type/List) of key/value lists. To extract the key/value the variables thus need to be wrapped in parentheses.

An alternative solution is to flatten the resulting list. Then the key/value pairs can be accessed in the same way as with plain `.kv`:

```raku
my %vowels = 'a' => 1, 'e' => 2, 'i' => 3, 'o' => 4, 'u' => 5;
for %vowels.sort(*.key)>>.kv.flat -> $vowel, $index {
  "$vowel: $index".say;
}
```

You can also loop over a [`Hash`](/type/Hash) using [destructuring](/language/signatures#Destructuring_arguments).

## [In place editing of values](#Hashes_and_maps "go to top of document")[§](#In_place_editing_of_values "direct link")

There may be times when you would like to modify the values of a hash while iterating over them.

```raku
my %answers = illuminatus => 23, hitchhikers => 42;
# OUTPUT: «hitchhikers => 42, illuminatus => 23»
for %answers.values -> $v { $v += 10 }; # Fails
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::AdHoc: Cannot assign to a readonly variable or a value␤»
```

This is traditionally accomplished by sending both the key and the value as follows.

```raku
my %answers = illuminatus => 23, hitchhikers => 42;
for %answers.kv -> $k,$v { %answers{$k} = $v + 10 };
```

However, it is possible to leverage the signature of the block in order to specify that you would like read-write access to the values.

```raku
my %answers = illuminatus => 23, hitchhikers => 42;
for %answers.values -> $v is rw { $v += 10 };
```

It is not possible directly to do in-place editing of hash keys, even in the case of object hashes; however, a key can be deleted and a new key/value pair added to achieve the same results. For example, given this hash:

```raku
my %h = a => 1, b => 2;
for %h.keys.sort -> $k {
    # use sort to ease output comparisons
    print "$k => {%h{$k}}; ";
}
say ''; # OUTPUT: «a => 1; b => 2; ␤»

```

replace key 'b' with 'bb' but retain 'b's value as the new key's value:

```raku
for %h.keys -> $k {
    if $k eq 'b' {
        %h<bb> = %h{$k}:delete;
    }
}
for %h.keys.sort -> $k {
    print "$k => {%h{$k}}; ";
}
say ''; # OUTPUT: «a => 1; bb => 2; ␤»

```


## dist_github-MattOates-Text-Homoglyph.md
# Text::Homoglyph

Perl6 package for mapping ASCII characters to unicode homoglyphs (similar looking characters)

# Data

The data was pinched and modified from the super evil <https://github.com/reinderien/mimic>
Several gaps were filled in with <http://shapecatcher.com> please feel free to extend and improve the character mapping. Some obvious improvements can be made by completing full ranges like the maths letters. More work needs to be done on curating the "best" looking unicode homoglyph as the first in the list.

N.b. the very first character returned is the ASCII character

# Example Use

```
#!/usr/bin/env perl6
use v6;

use Text::Homoglyph;

say "Woohoo this is some nice text".comb.map({(rand > 0.8)?? $_ !! homoglyphs($_)[1] }).join;

```

> Ꮃοοһοo 𝗍һiѕ іs ѕοⅿе niϲе 𝗍eх𝗍


## chdir.md
chdir

Combined from primary sources listed below.

# [In IO::Path](#___top "go to top of document")[§](#(IO::Path)_method_chdir "direct link")

See primary documentation
[in context](/type/IO/Path#method_chdir)
for **method chdir**.

```raku
multi method chdir(IO::Path:D: IO $path, |c)
multi method chdir(IO::Path:D: Str() $path, :$d = True, :$r, :$w, :$x)
```

Contrary to the name, the `.chdir` method does not change any directories, but merely concatenates the given `$path` to the invocant and returns the resultant `IO::Path`. Optional file tests can be performed by providing `:d`, `:r`, `:w`, or `:x` [`Bool`](/type/Bool) named arguments; when set to `True`, they'll perform [`.d`](/routine/d), [`.r`](/routine/r), [`.w`](/routine/w), and [`.x`](/routine/x) tests respectively. By default, only `:d` is set to `True`.

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

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

```raku
sub chdir(IO() $path, :$d = True, :$r, :$w, :$x --> IO::Path:D)
```

Changes value of `$*CWD` variable to the provided `$path`, optionally ensuring the new path passes several file tests. **NOTE:** that this routine does *NOT* alter the process's current directory (see [`&*chdir`](/routine/&*chdir)).

Returns [`IO::Path`](/type/IO/Path) representing new `$*CWD` on success. On failure, returns [`Failure`](/type/Failure) and leaves `$*CWD` untouched. The `$path` can be any object with an IO method that returns an [`IO::Path`](/type/IO/Path) object. The available file tests are:

* `:d` — check [`.d`](/routine/d) returns `True`
* `:r` — check [`.r`](/routine/r) returns `True`
* `:w` — check [`.w`](/routine/w) returns `True`
* `:x` — check [`.x`](/routine/x) returns `True`

By default, only `:d` test is performed.

```raku
chdir         '/tmp'; # change $*CWD to '/tmp' and check its .d is True
chdir :r, :w, '/tmp'; # … check its .r and .w are True
chdir '/not-there';   # returns Failure

```

Note that the following construct is a mistake:

```raku
# WRONG! DO NOT DO THIS!
my $*CWD = chdir '/tmp/';

```

Use [`indir`](/routine/indir) instead.


## dist_zef-nine-Spreadsheet-ODS.md
[![Actions Status](https://github.com/niner/Spreadsheet-ODS/workflows/test/badge.svg)](https://github.com/niner/Spreadsheet-ODS/actions)

# NAME

Spreadsheet::ODS - Work with Open Document (ODS) spreadsheets.

# SYNOPSIS

```
use Spreadsheet::ODS;

```

# DESCRIPTION

Spreadsheet::ODS is ...

# AUTHOR

Stefan Seifert [nine@detonation.org](mailto:nine@detonation.org)

### has Hash $!archive

Map of files in the decompressed archive we read from, if any.

### multi method load

```
multi method load(
    Str $file
) returns Spreadsheet::ODS

```

Load an ODS workbook from the file path identified by the given string.

### multi method load

```
multi method load(
    IO::Path $file
) returns Spreadsheet::ODS

```

Load an ODS workbook in the specified file.

### multi method load

```
multi method load(
    Blob $content
) returns Spreadsheet::ODS

```

Load an ODS workbook from the specified blob. This is useful in the case it was sent over the network, and so never written to disk.

# COPYRIGHT AND LICENSE

Copyright 2022 Stefan Seifert

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


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

# NAME

POFile - manipulating data in gettext PO files

# SYNOPSIS

```
use POFile;
my $po = POFile.load('foo.po');

say $po.obsolete-messages; # list of obsolete messages
say $po[0]; # POFile::Entry object at 0 index
say $po{'Splash text'}; # POFile::Entry object with msgid C<Splash textC<
for @$po -> $item {
    say $item.reference; # 'finddialog.cpp:38'
    say $item.msgstr; # msgstr value
    $item.msgstr = update($item.msgstr); # Do some update
}
$po.save('foo-updated.po');

```

# DESCRIPTION

The `.po` file as a whole is represented by the `POFile` class, which holds a `POFile::Entry` object per entry in the PO file.

## POFile::Entry

The `POFile::Entry` class represents a single record in PO file, and has its fields as attributes: `msgid`, `msgid-plural`, `msgstr`, `msgctxt`, `reference` (reference comment), `extracted` (extracted comment), `comment` (translator comment), `format-style`, `fuzzy-msgid`, `fuzzy-msgctxt`. All these attributes are set read/write.

You can create a single `POFile::Entry` object from a `Str` using the `POFile::Entry.parse($str)` method.

The `msgid` and `msgstr` accessors always provided unquoted values; the methods `msgid-quoted` and `msgstr-quoted` are present to provide access to the quoted messages.

The value of `msgstr` attribute might be either `Str` or `Array`, and is based on value of `msgid-plural` attribute:

```
with $po.msgid-plural {
    say $po.msgid; # Singular form
    say $_; # Plural form
    for $po.msgstr -> $form {
        say $form; # Every plural form of end language
    }
}

```

You can serialize an entry with `Str` method or its `~` shortcut:

```
my $po-entry = $po[1]; # Get second entry
say ~$po-entry;    # Serialized 1
say $po-entry.Str; # Serialized 2

```

Note that **no line wrapping** is done by the module.

## POFile

`POFile` provides access to `POFile::Entry` objects using either index (position in original file) or key (msgid value).

It must be noted that this module provides hash-like access by msgid, which might **not** be unique. Please consider that *only array access* is stable in this case. Use hash access you know *for sure* there are no items with the same `msgid`, yet different `msgctxt`.

The `POFile` object also contains all obsolete messages, which cani be accessed using `obsolete-messages` attribute.

You can create from scratch a new `POFile` object and populate it with entries, as well as delete entries by id or by key:

```
my $po = POFile.new;
@$po.push(POFile::Entry.parse(...));
@$po.push(POFile::Entry.parse(...));
$po[0]:delete;
$po{'my msgid'}:delete;

```

As well as `POFile::Entry`, you can serialize a `POFile` object calling `Str` method on it.

## Escaping

Additionally, two routines are available to escape and unescape strings accordingly to rules described for PO format.

```
use POFile :quoting;

say po-unquote(｢\t\"\\\n｣); # ｢\t"\\n｣      <- unquoting
say po-quote(｢\t"\\n\｣);    # ｢\t\"\\\n\\｣  <- quoting

```

# AUTHORS

* Alexander Kiryuhin
* Jonathan Worthington

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

# COPYRIGHT AND LICENSE

Copyright 2018 - 2020 Edument AB

Copyright 2024 The Raku Community

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