## dist_github-Skarsnik-App-GPTrixie.md
# GPTrixie (The Great and Powerful Trixie)

A tool to generate NativeCall code from C headers

You will need gccxml and gcc/g++ 4.9 or castxml (it's based on clang/llvm)
By default GPTrixie use GCCXML.
Beware some distributions provide gccxml as castxml and it's bad, you will need to change the code to use gccxml.real
or make sure the gccxml executable is gccxml if you want to use gccxml.
To use castxml you will need to use the --castxml option and give it the standard option castxml need to use (it's the --std option of castxml, c99 or c11 should work fine on recent version)

# Usage

`Usage: gptrixie [--all] [--define-enum=<Str>] [--ooc=<Str>] [--enums] [--functions] [--structs] [--externs] [--list-types] <header-file> [<gccoptions> ...]`

gccoptions can be stuff like -I /another/include/path

The --define-enum option allows you to generate an enum from #define, it takes a starting string like `MSQL_TYPE`

The --list-types option is mainly for debugging, it lists all the C types found.

You can do a 'dry' run without options, to have an idea of the lenght of the output. It can be useful
to know what to expect. This is an example with one of a libxml2 headers:

```
Number of things founds
-Types: 972
-Structures: 80
-Unions: 12
-Enums: 31
-Functions: 1068
-Variables: 45
-Files: 52

```

Most GPTrixie messages are in stderr, allowing you to redirect the generated perl6 code into a file.

More options and other specific generators will come in the future.

# Limitations

The default generator is not smart. It can't really make sense of how the type is used; some arbitrary
choice is made for you. You will probably have to adjust the generated code.

char \* and const char \* become Str

void \* and const void \* are Pointer

Typedef defined on top of a fundamental C type are left as is. You will have to complete the missing
definition for the type. This choice is based on stuff like sqlite\_int64 where is up to you to either
replace with int64 or define a `constant sqlite_int64 = int64`

## C++ Support

C++ support is planned

# Example

(The display can change)

t@testperl6:~/piko/gptrixie# perl6 -I lib bin/gptrixie --all /usr/local/include/gumbo.h

```
## Enumerations
enum GumboNamespaceEnum is export (
   GUMBO_NAMESPACE_HTML => 0,
   GUMBO_NAMESPACE_SVG => 1,
   GUMBO_NAMESPACE_MATHML => 2
);
enum GumboParseFlags is export (
   GUMBO_INSERTION_NORMAL => 0,
   GUMBO_INSERTION_BY_PARSER => 1,
   GUMBO_INSERTION_IMPLICIT_END_TAG => 2,
   GUMBO_INSERTION_IMPLIED => 8,
   GUMBO_INSERTION_CONVERTED_FROM_END_TAG => 16,
   GUMBO_INSERTION_FROM_ISINDEX => 32,
   GUMBO_INSERTION_FROM_IMAGE => 64,
   GUMBO_INSERTION_RECONSTRUCTED_FORMATTING_ELEMENT => 128,
   GUMBO_INSERTION_ADOPTION_AGENCY_CLONED => 256,
   GUMBO_INSERTION_ADOPTION_AGENCY_MOVED => 512,
   GUMBO_INSERTION_FOSTER_PARENTED => 1024
);

enum GumboQuirksModeEnum is export (
   GUMBO_DOCTYPE_NO_QUIRKS => 0,
   GUMBO_DOCTYPE_QUIRKS => 1,
   GUMBO_DOCTYPE_LIMITED_QUIRKS => 2
);
enum GumboAttributeNamespaceEnum is export (
   GUMBO_ATTR_NAMESPACE_NONE => 0,
   GUMBO_ATTR_NAMESPACE_XLINK => 1,
   GUMBO_ATTR_NAMESPACE_XML => 2,
   GUMBO_ATTR_NAMESPACE_XMLNS => 3
);
enum GumboNodeType is export (
   GUMBO_NODE_DOCUMENT => 0,
   GUMBO_NODE_ELEMENT => 1,
   GUMBO_NODE_TEXT => 2,
   GUMBO_NODE_CDATA => 3,
   GUMBO_NODE_COMMENT => 4,
   GUMBO_NODE_WHITESPACE => 5,
   GUMBO_NODE_TEMPLATE => 6
);
## Structures
class GumboSourcePosition is repr('CStruct') is export {
        has uint32                        $.line; # unsigned int line
        has uint32                        $.column; # unsigned int column
        has uint32                        $.offset; # unsigned int offset
}
class GumboStringPiece is repr('CStruct') is export {
        has Str                           $.data; # const char* data
        has size_t                        $.length; # Typedef(size_t)->|unsigned int| length
}
class GumboVector is repr('CStruct') is export {
        has Pointer[Pointer]              $.data; # void** data
        has uint32                        $.length; # unsigned int length
        has uint32                        $.capacity; # unsigned int capacity
}
class GumboAttribute is repr('CStruct') is export {
        has int32                         $.attr_namespace; # GumboAttributeNamespaceEnum attr_namespace
        has Str                           $.name; # const char* name
        HAS GumboStringPiece              $.original_name; # GumboStringPiece original_name
        has Str                           $.value; # const char* value
        HAS GumboStringPiece              $.original_value; # GumboStringPiece original_value
        HAS GumboSourcePosition           $.name_start; # GumboSourcePosition name_start
        HAS GumboSourcePosition           $.name_end; # GumboSourcePosition name_end
        HAS GumboSourcePosition           $.value_start; # GumboSourcePosition value_start
        HAS GumboSourcePosition           $.value_end; # GumboSourcePosition value_end
}
class GumboDocument is repr('CStruct') is export {
        HAS GumboVector                   $.children; # GumboVector children
        has bool                          $.has_doctype; # bool has_doctype
        has Str                           $.name; # const char* name
        has Str                           $.public_identifier; # const char* public_identifier
        has Str                           $.system_identifier; # const char* system_identifier
        has int32                         $.doc_type_quirks_mode; # GumboQuirksModeEnum doc_type_quirks_mode
}
class GumboText is repr('CStruct') is export {
        has Str                           $.text; # const char* text
        HAS GumboStringPiece              $.original_text; # GumboStringPiece original_text
        HAS GumboSourcePosition           $.start_pos; # GumboSourcePosition start_pos
}
class GumboElement is repr('CStruct') is export {
        HAS GumboVector                   $.children; # GumboVector children
        has int32                         $.tag; # GumboTag tag
        has int32                         $.tag_namespace; # GumboNamespaceEnum tag_namespace
        HAS GumboStringPiece              $.original_tag; # GumboStringPiece original_tag
        HAS GumboStringPiece              $.original_end_tag; # GumboStringPiece original_end_tag
        HAS GumboSourcePosition           $.start_pos; # GumboSourcePosition start_pos
        HAS GumboSourcePosition           $.end_pos; # GumboSourcePosition end_pos
        HAS GumboVector                   $.attributes; # GumboVector attributes
}
class GumboInternalNode_v_Union is repr('CUnion') is export {
        HAS GumboDocument                 $.document; # GumboDocument document
        HAS GumboElement                  $.element; # GumboElement element
        HAS GumboText                     $.text; # GumboText text
}
class GumboInternalNode is repr('CStruct') is export {
        has int32                         $.type; # GumboNodeType type
        has Pointer[GumboInternalNode]    $.parent; # Typedef(GumboNode)->|GumboInternalNode|* parent
        has size_t                        $.index_within_parent; # Typedef(size_t)->|unsigned int| index_within_parent
        has int32                         $.parse_flags; # GumboParseFlags parse_flags
        HAS GumboInternalNode_v_Union     $.v; # Union v
}
class GumboInternalOptions is repr('CStruct') is export {
        has Pointer[PtrFunc]              $.allocator; # Typedef(GumboAllocatorFunction)->|PtrFunc*| allocator
        has Pointer[PtrFunc]              $.deallocator; # Typedef(GumboDeallocatorFunction)->|PtrFunc*| deallocator
        has Pointer                       $.userdata; # void* userdata
        has int32                         $.tab_stop; # int tab_stop
        has bool                          $.stop_on_first_error; # bool stop_on_first_error
        has int32                         $.max_errors; # int max_errors
        has int32                         $.fragment_context; # GumboTag fragment_context
        has int32                         $.fragment_namespace; # GumboNamespaceEnum fragment_namespace
}
class GumboInternalOutput is repr('CStruct') is export {
        has Pointer[GumboInternalNode]    $.document; # Typedef(GumboNode)->|GumboInternalNode|* document
        has Pointer[GumboInternalNode]    $.root; # Typedef(GumboNode)->|GumboInternalNode|* root
        HAS GumboVector                   $.errors; # GumboVector errors
}
## Extras stuff
constant GumboOutput is export := GumboInternalOutput;
constant GumboOptions is export := GumboInternalOptions;
constant GumboNode is export := GumboInternalNode;
## Functions
sub gumbo_get_attribute(Pointer[GumboVector] $attrs, Str $name) is native(LIB) returns Pointer[GumboAttribute] is export { * }
sub gumbo_normalized_tagname(int32 $tag) is native(LIB) returns Str is export { * }
sub gumbo_parse(Str $buffer) is native(LIB) returns Pointer[GumboInternalOutput] is export { * }
sub gumbo_string_equals_ignore_case(Pointer[GumboStringPiece] $str1, Pointer[GumboStringPiece] $str2) is native(LIB) returns bool is export { * }
sub gumbo_tag_from_original_text(Pointer[GumboStringPiece] $text) is native(LIB)  is export { * }
sub gumbo_vector_index_of(Pointer[GumboVector] $vector, Pointer $element) is native(LIB) returns int32 is export { * }
sub gumbo_tagn_enum(Str $tagname, uint32 $length) is native(LIB) returns int32 is export { * }
sub gumbo_destroy_output(Pointer[GumboInternalOptions] $options, Pointer[GumboInternalOutput] $output) is native(LIB)  is export { * }
sub gumbo_string_equals(Pointer[GumboStringPiece] $str1, Pointer[GumboStringPiece] $str2) is native(LIB) returns bool is export { * }
sub gumbo_normalize_svg_tagname(Pointer[GumboStringPiece] $tagname) is native(LIB) returns Str is export { * }
sub gumbo_parse_with_options(Pointer[GumboInternalOptions] $options, Str $buffer, size_t $buffer_length) is native(LIB) returns Pointer[GumboInternalOutput] is export { * }
sub gumbo_tag_enum(Str $tagname) is native(LIB) returns int32 is export { * }
## Externs
our GumboInternalOptions $kGumboDefaultOptions is export = cglobals(LIB, "kGumboDefaultOptions", GumboInternalOptions);
our GumboStringPiece $kGumboEmptyString is export = cglobals(LIB, "kGumboEmptyString", GumboStringPiece);
our GumboVector $kGumboEmptyVector is export = cglobals(LIB, "kGumboEmptyVector", GumboVector);
our GumboSourcePosition $kGumboEmptySourcePosition is export = cglobals(LIB, "kGumboEmptySourcePosition", GumboSourcePosition);

```

# Reporting bugs and errors

Use the github issue tracker. Try to give the name of the headers

# Licence

This software is under the same licence as Rakudo. See the LICENCE file


## dist_zef-jjmerelo-Test-Script-Output.md
[![Test-install and cache deps](https://github.com/JJ/raku-test-script-output/actions/workflows/test.yaml/badge.svg)](https://github.com/JJ/raku-test-script-output/actions/workflows/test.yaml)

# NAME

Test::Script::Output - Tests the output of scripts using special comments

# SYNOPSIS

```
# in the tested file, file.p6
say "Hello";
=output
Hello

```

The test file for this will be:

```
use Test::Script::Output;
output-ok( "file.p6", "script runs OK")

```

In another file:

```
# Another tested file, regex.p6
say "Time now is ", now;
=output
/^^Time now/

```

Can be tested with:

```
output-ok( "regex.p6", "script tested via regex runs OK")

```

# DESCRIPTION

`Test::Script::Output` tests the output of scripts. Desired output must be included aas an `=output` pod section with the literal output that should be expected from it. If that changes, a regular expression can be used.

You can either set the output explicitly

```
=output
First line
Second line

```

Or match the whole output via a regex, which can be used when the output is variable

```
=output
/^^ Start /

```

The scripts can include external compunits as long as they're available, and you take care of including all relevant paths via `use lib`.

If you want to check out how this works, the biggest collection of examples is at <https://github.com/JJ/perl6-quick-reference-apress>.

Provided is also a Dockerfile you can use directly for your tests; check it out at <https://cloud.docker.com/repository/docker/jjmerelo/perl6-test-script-output/>

Use this `.travis.yml` for testing your scripts (or something like that, changing the name of the directory)

```
language: minimal

services:
  - docker

install:
  - docker pull jjmerelo/perl6-test-script-output
  - mkdir t && echo "use Test::Script::Output;for <Chapter7 Chapter8 Chapter9 Chapter10> -> \$d { dir-ok( \$d.IO , 'Scripts in dir ' ~ \$d ~ ' are OK') }" > t/0.t

script: docker run -t -v  $TRAVIS_BUILD_DIR:/test jjmerelo/perl6-test-script-output

```

# Methods

## output-ok( $file, $msg)

The argument can be either the name of an existing file, or a IO handle for that same file; the `$msg` is the test message.

## dir-ok( $dir, $msg)

Takes the files with the extension "\*.p6" from a dir, and tests them, the test will be OK if all of the files check out.

## \_get\_output( $f )

This is the routine doing the real work of extracting the expected and actual output from the file. It's not exported by default.

# AUTHOR

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

# Note

This test module was created originally to test the scripts for the book
["Perl 6 Quick Reference"](<https://link.springer.com/book/10.1007/978-1-4842>
-4956-7), published by Apress.

# 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-tony-o-Log-Reader.md
# log reader

this is a log reader with a basic interface.

## current features

supports a grammar/action parse, currently implemented with the extended log format (you can read about it from w3c).

## usage

```
use Log::Reader;

my %data = parse-log('your-log'.IO.slurp);

# do something with %data<directives> and %data<rows> here

```

easy peasy.

have your own grammar/actions?

```
use Log::Reader;
use Custom::Grammar;
use Custom::Actions;

my $parser = Log::Reader.new(:parser(Custom::Grammar), :actions(Custom::Actions));

$parser.parse('some-file'.IO.slurp);

```

## todo

* support streams for i/o

## authors

tony-o


## dir.md
dir

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/IO/Path#routine_dir)
for **routine dir**.

```raku
multi  dir(*%_)
multi  dir(IO::Path:D $path, |c)
multi  dir(IO()       $path, |c)
method dir(IO::Path:D: Mu :$test = $*SPEC.curupdir)
```

Returns a lazy list of `IO::Path` objects corresponding to the entries in a directory, optionally filtered by [smartmatching](/language/operators#infix_~~) their names *as strings* per the `:test` parameter. The order in which the filesystem returns entries determines the order of the entries/objects in the list. Objects corresponding to special directory entries `.` and `..` are not included. `$path` determines whether the objects' paths are absolute or relative.

Since the tests are performed against [`Str`](/type/Str) arguments, not [`IO`](/type/IO), the tests are executed in the `$*CWD`, instead of the target directory. When testing against file test operators, this won't work:

```raku
dir('mydir', test => { .IO.d })
```

while this will:

```raku
dir('mydir', test => { "mydir/$_".IO.d })
```

**NOTE:** a `dir` call opens a directory for reading, which counts towards maximum per-process open files for your program. Be sure to exhaust returned [`Seq`](/type/Seq) before doing something like recursively performing more `dir` calls. You can exhaust it by assigning to an `@-`sigiled variable or simply looping over it. Note how examples below push further dirs to look through into an [`Array`](/type/Array), rather than immediately calling `dir` on them. See also [`IO::Dir` module](https://raku.land/zef:raku-community-modules/IO::Dir) that gives you finer control over closing dir handles.

Examples:

```raku
# To iterate over the contents of the current directory:
for dir() -> $file {
    say $file;
}

# As before, but include even '.' and '..' which are filtered out by
# the default :test matcher:
for dir(test => *) -> $file {
    say $file;
}

# To get the names of all .jpg and .jpeg files in the home directory of the current user:
my @jpegs = $*HOME.dir: test => /:i '.' jpe?g $/;
```

An example program that lists all files and directories recursively:

```raku
sub MAIN($dir = '.') {
    my @todo = $dir.IO;
    while @todo {
        for @todo.pop.dir -> $path {
            say $path.Str;
            @todo.push: $path if $path.d;
        }
    }
}
```

A lazy way to find the first three files ending in ".raku" recursively starting from the current directory:

```raku
my @stack = '.'.IO;
my $raku-files = gather while @stack {
    with @stack.pop {
        when :d { @stack.append: .dir }
        .take when .extension.lc eq 'raku'
    }
}
.put for $raku-files[^3];

```


## dist_zef-tony-o-Data-Dump.md
# Data::Dump

## for perl6

that's right folks, here's a quicky for your data dump needs. if you have Terminal::ANSIColor installed then the output will be so colorful your eyes might bleed.

feel free to submit bugs or make suggestions, if you submit a bug please provide a concise example that replicates the problem and i'll add some tests and make this thing better.

## options

all of these options can be overridden in the `DATA_DUMP` environment variable in the format: `indent=4,color=false`

### `indent`

default: `2`

```
<...>
say Dump({ some => object }, :indent(4));
<...>

```

### `max-recursion`

default: `50`

```
<...>
say Dump({ some => object }, :max-recursion(3));
<...>

```

### `color`

default: `True`

This will override the default decision to use color on the output if `Terminal::ANSIColor` is installed. Passing a value of `False` will ensure that the output is vanilla.

```
<...>
say Dump({ some => object }, :color(False));
<...>

```

### `gist`

default: `False`

This will override the default object determination and output and use the output of `.gist`

```
<...>
say Dump({ some => object}, :gist);
<...>

```

### `no-postfix`

default: `False`

This will shorten `Str|Int|Rat|Numeric` output from `5.Int|"H".Str` to simply `5|"H"`

### `skip-methods`

default: `False`

This will skip the methods if you dump custom classes.

```
<...>
say Dump($object, :skip-methods(True));
<...>

```

### `overrides`

default: `{}`

This will allow you to override how DD dumps certain types of objects.

```
Dump($object, overrides => {
  Int => sub ($int) { return $int * 2; },
  Str => sub ($str) { return "'$str'"; },
  # etc.
});

```

## usage

```
use Data::Dump;

say Dump(%(
  key1 => 'value1',
  key256 => 1,
));

```

output:

```
{
  key1   => "value1".Str,
  key256 => 1.Int,
}

```

note: if you have Terminal::ANSIColor installed then it's going to be amazing. so, prepare yourself.

## oh you want to `Dump` your custom class?

here you go, dude

```
use Data::Dump;

class E {
  has $.public;
  has Int $!private = 5;
  method r(Str $a) { };
  method s($b, :$named? = 5) { };
  method e returns Int { say $!private; };
};

say Dump(E.new);

```

output:

```
E :: (
  $!private => 5.Int,
  $!public  => (Any),

  method e () returns Int {...},
  method public () returns Mu {...},
  method r (Str $a) returns Mu {...},
  method s (Any $b, Any :named($named) = 5) returns Mu {...},
)

```


## dist_zef-jonathanstowe-AWS-SNS-Notification.md
# AWS::SNS::Notification

Description of an AWS Simple Notification Service message.

[![CI](https://github.com/jonathanstowe/AWS-SNS-Notification/actions/workflows/main.yml/badge.svg)](https://github.com/jonathanstowe/AWS-SNS-Notification/actions/workflows/main.yml)

## Synopsis

```
use Cro::HTTP::Router;
use Cro::HTTP::Server;
use AWS::SNS::Notification;

my $app = route {
    post -> 'sns-message' {
        # The SNS message has a content-type of 'text/plain' so this will be raw JSON
        request-body -> $json {
            my $notification = AWS::SNS::Notification.from-json($json);
            # Check this is a valid notification
            if $notification.verify-signature {
               if $notification.is-notification {
                   # Do something with the $notification.message
                   # The format of which depends on the source - an S3 notification will be a JSON String for instance
               }
               else {
                   # This is subscribe or unsubscribe confirmation request
                   # so perform the confirmation
                   $notification.respond;
               }
            }
            else {
                bad-request 'text/plain', 'Fake notification';
            }
        }
    }
};

my Cro::Service $service = Cro::HTTP::Server.new(:host<127.0.0.1>, :port<7798>, application => $app);

$service.start;

react  { whenever signal(SIGINT) { $service.stop; exit; } }

```

Alternatively you can derive a body parser using [Cro::HTTP::BodyParser::JSONClass](https://github.com/jonathanstowe/Cro-HTTP-BodyParser-JSONClass) :

```
use Cro::HTTP::Router;
use Cro::HTTP::Server;
use AWS::SNS::Notification;
use Cro::HTTP::BodyParser::JSONClass;

class SNSBodyParser does Cro::HTTP::BodyParser::JSONClass[AWS::SNS::Notification] {
	use Cro::HTTP::Message;
    method is-applicable(Cro::HTTP::Message $message --> Bool ) {
        $message.header('x-amz-sns-message-type').defined && $message.header('x-amz-sns-message-id').defined;
    }
}

my $app = route {
    body-parser SNSBodyParser;
    post -> 'sns-message' {
        request-body -> $notification {
            # Check this is a valid notification
            if $notification.verify-signature {
               if $notification.is-notification {
                   # Do something with the $notification.message
                   # The format of which depends on the source - an S3 notification will be a JSON String for instance
               }
               else {
                   # This is subscribe or unsubscribe confirmation request
                   # so perform the confirmation
                   $notification.respond;
               }
            }
            else {
                bad-request 'text/plain', 'Fake notification';
            }
        }
    }
};

my Cro::Service $service = Cro::HTTP::Server.new(:host<127.0.0.1>, :port<7798>, application => $app);

$service.start;

react  { whenever signal(SIGINT) { $service.stop; exit; } }

```

## Description

This class describes an [AWS Simple Notification Service](https://aws.amazon.com/sns/) message that may be delivered by HTTPS or by a message queue or somesuch.

The class provides for parsing the JSON payload for the message, verifying the signature of the message against the signing key and responding if necessary to a Subscribe or Unsubscribe confirmation.

The actual message sent by the source application is accessed through the `.message` accessor - so for instance in the case of an S3 notification this will be a JSON string which will need to be decoded for further processing.

## Installation

Assuming you have a working rakudo installation you can install this with *zef* :

```
 zef install AWS::SNS::Notification

```

Or from a local clone of the distribution

```
 zef install AWS::SNS::Notification

```

## Support

If you have an feedback/suggestions/patches please send them via [Github](https://github.com/jonathanstowe/AWS-SNS-Notification/issues)

## Licence and Copyright

This library is free software. Please see the <LICENCE> file in the distribution for details.

© Jonathan Stowe 2021


## dist_zef-Marcool04-Mac-Battery-Alerter.md
# GETTING STARTED

To install the script run:

```
$ zef install Mac::Battery::Alerter

```

Then test it to see it is functioning properly:

```
$ /raku/install/path/bin/battery_alerter.raku --debug

```

Now, to run the script on a regular basis and get spoken to when the mac's battery is low, you can use a plist file similar to this one:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>KeepAlive</key>
	<false/>
	<key>Label</key>
	<string>batteryAlert</string>
	<key>LowPriorityIO</key>
	<true/>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/battery_script.raku</string>
    <!-- <string>--debug</string>
    <string>--warn=60</string>
    <string>--panic=58</string> -->
  </array>
  <!-- <key>StandardOutPath</key>
  <string>/tmp/battery_script.txt</string>
  <key>StandardErrorPath</key>
  <string>/tmp/battery_script.txt</string>-->
	<key>RunAtLoad</key>
	<true/>
	<key>StartInterval</key>
	<integer>30</integer>
	<key>EnvironmentVariables</key>
  <dict>
      <key>PATH</key>
      <string>/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin</string>
  </dict>
</dict>
</plist>

```

This should be placed in `~/Library/LaunchAgents/` (for instance) and started using:

```
launchctl enable batteryAlert
launchctl start batteryAlert

```

See <https://www.launchd.info/> for more information

**Note:** there are commented out entries in this plist which allow you to debug the service should it not appear to be working. Simply uncomment those parts, reload the service, and check the /tmp/battery\_script.txt file for errors.

# DESCRIPTION

This is a small script that interfaces with macOS system utilities to analyse what the current battery status is, and uses speech (macOS `say` utility) to warn when the battery is getting low. This is in response to the fact that there is no audible feedback when the "Low battery" dialog is shown, which is rather late (4% battery) and will give you little time to intervene and plug the mac in should you be looking away at that moment.
It is inspired by this post: <https://hints.macworld.com/article.php?story=20110219013713667>, credit goes to Mac OSX Hints user `Toggi3` for formulating the problem so well and outlining this solution.

# AUTHOR

Mark Collins (<https://gitlab.com/Marcool04>)

# COPYRIGHT AND LICENCE

Copyright 2020 Mark Collins

This work is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See the LICENCE file for (almost no) more details.


## kernel.md
class Kernel

Kernel related information

```raku
class Kernel does Systemic { }
```

Built-in class for providing kernel related information. Usually accessed through the [`$*KERNEL`](/language/variables#Dynamic_variables) dynamic variable.

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

## [method arch](#class_Kernel "go to top of document")[§](#method_arch "direct link")

```raku
method arch
```

Instance method returning the "arch" (as in "architecture") information of the Kernel object. Dies if the "arch" could not be established.

## [method archname](#class_Kernel "go to top of document")[§](#method_archname "direct link")

```raku
method archname
```

Instance method returning the concatenation of [hardware](/routine/hardware) and [name](/routine/name).

## [method bits](#class_Kernel "go to top of document")[§](#method_bits "direct link")

```raku
method bits
```

Instance method returning the number of bits used in the architecture of the processor. Usually **32** or **64**.

## [method cpu-cores](#class_Kernel "go to top of document")[§](#method_cpu-cores "direct link")

```raku
method cpu-cores(--> Int)
```

Instance / Class method returning the number of CPU cores that are available.

```raku
say $*KERNEL.cpu-cores; # OUTPUT: «8␤»
```

## [method cpu-usage](#class_Kernel "go to top of document")[§](#method_cpu-usage "direct link")

```raku
method cpu-usage(--> Int)
```

Instance / Class method returning the amount of CPU uses since the start of the program (in microseconds).

## [method free-memory](#class_Kernel "go to top of document")[§](#method_free-memory "direct link")

```raku
method free-memory(--> Int)
```

Instance / Class method returning the available memory on the system. When using the JVM, this returns the available memory to the JVM instead. This method is only available in release v2019.06 and later.

## [method total-memory](#class_Kernel "go to top of document")[§](#method_total-memory "direct link")

```raku
method total-memory(--> Int)
```

Instance / Class method returning the total memory available to the system. When using the JVM, this returns the total memory available to the JVM instead. This method is only available in release v2019.06 and later.

## [method endian](#class_Kernel "go to top of document")[§](#method_endian "direct link")

```raku
method endian(--> Endian:D)
```

Class method that returns the [`Endian`](/type/Endian) object associated with the kernel architecture (either `LittleEndian` or `BigEndian`).

## [method hardware](#class_Kernel "go to top of document")[§](#method_hardware "direct link")

```raku
method hardware
```

Instance method returning the hardware information of the Kernel object. Dies if the hardware information could not be established.

```raku
say $*KERNEL.hardware; # OUTPUT: «x86_64␤»
```

## [method hostname](#class_Kernel "go to top of document")[§](#method_hostname "direct link")

```raku
method hostname
```

Instance method returning the hostname of the Kernel object.

## [method release](#class_Kernel "go to top of document")[§](#method_release "direct link")

```raku
method release
```

Instance method returning the release information of the Kernel object. Dies if the release information could not be established.

## [method signal](#class_Kernel "go to top of document")[§](#method_signal "direct link")

```raku
multi method signal(Kernel:D: Str:D $signal --> Int:D)
multi method signal(Kernel:D: Signal:D \signal --> Int:D)
multi method signal(Kernel:D: Int:D \signal --> Int:D)
```

Instance method returning the `Signal` numeric code for a given name for the Kernel object.

```raku
say $*KERNEL.signal("INT"); # OUTPUT: «2␤»
```

## [method signals](#class_Kernel "go to top of document")[§](#method_signals "direct link")

Instance method returning a list of `Signal`s that are supported by the kernel represented by the Kernel object.

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

Type relations for `Kernel`

raku-type-graph

Kernel
Kernel

Any
Any

Kernel->Any

Mu
Mu

Any->Mu

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


## dist_github-gfldex-Operator-defined-alternation.md
# Operator::defined-alternation

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

Perl 6 provides control statements and operators to test for definedness instead of trueness, to provide ease of typing and a clear statement of intend from the programmer. Sadly there is currently no way to define your own ternary operators with Rakudo. However, we can emulate operators with 3 arguments with a chain of 2 infix operators, as long as we provide a type for the 2nd infix to handle dispatch properly.

## Usage:

```
use v6;
use Operator::defined-alternation;

my $falsish = 2 but False;
say $falsish ?// 'defined' !! 'undefined';
# OUTPUT: defined
# What is equivalent to:
say $falsish.defined ?? 'defined' !! 'undefined';
# OUTPUT: defined
# But opposed to:
say $falsish ?? 'true' !! 'false';
# OUTPUT: false

```

## License

(c) Wenzel P. P. Peppmeyer, Released under Artistic License 2.0.


## dist_zef-thundergnat-String-Splice.md
[![Actions Status](https://github.com/thundergnat/String-Splice/actions/workflows/test.yml/badge.svg)](https://github.com/thundergnat/String-Splice/actions)

# Name

String::Splice - splice, but for Strings instead of Arrays

# Synopsis

```
use String::Splice;

say 'Perl 6 is awesome'.&splice(0, 6, 'Raku');
# Raku is awesome

say splice('This is Rakudo', *-2, 2);
# This is Raku

say "Tonight I'm gonna party like it's 1999"
  .&splice(18, 5, 'program').&splice(*-4, 2, 20);
# Tonight I'm gonna program like it's 2099

```

# Description

String::Splice is intended to give a simple interface to slicing and dicing Strings much in the same way that CORE Array.splice makes it easy to slice and dice Arrays.

Works very similarly on strings as the CORE splice works on Arrays.

Available as both a Role `Splice` which may be used as a mixin, or to augment strings, and as a subroutine (that primarily operates on strings).

```
multi sub splice($String:D, $start, $chars?, $replacement = '' --> Str)

```

The splice routine may be called with either three or four parameters.

Need to supply a defined string to operate on, a starting point (in chars), optionally the number of chars to affect, and an optional replacement string (defaults to ''). The starting point may be a positive integer, any Real numeric value that can be coerced to a positive integer, or a WhateverCode that will offset from the string end.

Use a WhateverCode if you want to modify a string some set offset from the end of an unknown length string rather than from the start.

`'Be home by 6:00PM'.&splice(*-2, 1, 'A')` `# Be home by 6:00AM`

You may supply a start point larger than the string and the string will be padded with spaces to achieve that starting point.

`splice('Raku', 9, 'rocks')` is valid, as is `splice('Raku', *+5, 'rocks')`

The major difference in how String.splice differs from Array.splice is in that the starting position does not default to zero. It must be given.

Three parameter splice is mostly useful as an "insert" operation. You supply a receiving string, an "insert position" and a string to insert. The returned string will be the receiving string with the insertion string added at the start position. Technically, you could do a two argument splice, supplying a receiving string and a start position, and it will then insert a blank string at the start position, but that's kind-of pointless.

Four parameter splice is useful for remove or replace operations. You supply a receiving string, an "insert position", the number of characters to replace, and a string to insert. Remove portions of the string by replacing the substring with a blank, or change the string by replacing the substring with a different string.

The replace parameter does not necessarily need to be a string. Anything that may be coerced to a string may be supplied and will likely work as expected. When using 3 parameter splice: (String, start, insert), insert *must* be a string to disambiguify the signature to the dispatcher. You can always use the four parameter form with a 0 chars parameter to get the automatic coercion.

# Off topic musings

I debated whether it was a good idea call this method/routine splice as splice is already used in core. The existing splice only works on Arrays and Bufs though, so there isn't much likelihood of confusion. I kicked around a few other name options (slice? dice?, nah, slice is already in use and not a very similar operation. dice maybe, but no historical corollation, and I really like the strange consistency between Array splice and String splice.)

Honestly, I am slightly surprised that something like this does not already exist in CORE what with Perls reputation as a text wrangling utility. I would be quite willing to contribute the idea and code if there were interest in folding it in. Better to start out as a module though to prove it out.

# Author

Steve Schulze (thundergnat)

# Copyright and License

Copyright 2020 Steve Schulze

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


## dist_github-alabamenhu-Intl-Fluent.md
# Introduction

A Perl 6 / Raku module that implements Mozilla's Project Fluent. This is an
implementation based on the design documents, but it is not actually a port.
The idea is to provide both an interface and code that is maintainable, usable,
and Raku-ish.

**Note: This module is currently undergoing a top-to-bottom rewrite. It should be used with caution at the moment. Features should work, but if you supply specific options for number formatting (significant figures, etc) they may be slightly off.**

## Basic Usage

```
    use Fluent;
    add-localization-basepath('localization');
    add-localization-languages('en', 'es');
    say localized('helloworld');   #   ↪ "Hello World!" (if system set to English)
    say localized 'helloworld';    #   ↪ "¡Hola mundo!" (if system set to Spanish)

```

If you store the result of a `localized` call, you’ll get a Hashy `Str`. That
means you can use it like a `Str` (because it is one), but if the message
has attributes, you can access it via the normal associative ways:

```
    my  $translation = localized 'greeting';
    say $translation;          #   ↪ "Hello!"
    say $translation<foo>;     #   ↪ "some related text"
    say $translation{'bar'};   #   ↪ "some other related text"

```

## Subroutines

When load the module, Fluent will export a handful of useful subroutines. You
don't *have* to use them, but they implement an entire localization framework
that only under rare circumstances would you want or need to handle manually.

* **localized**(Str *$message-id*, Str *:$domain?*, *:$language?*, *:@languages?*, :*%variables?*, *%slurp-vars*) returns **Str**
  The function that you will use most often. In common use, you will only need to
  specify the `$message-id`, and maybe the `$domain` if your project uses them.
  If you need to pass variables, you can use the
  `%variables` named parameter, or alternative, specify the variables as
  additional named parameters (using `%variables` is only required if the
  name of the variable is one of the extant named parameters. If you do not pass
  any languages (which should be either `Str` or `LanguageTag`), the default
  languages will be used.
* **add-localization-basepath**(Str *$path*, Str *:$domain?*, Bool *:$resource* = False, Bool, *:$lazy* = True)
  Adds the given path (directories need to end in `/`!) to the list of locations
  where `.ftl` files can be found. If used in a module, then pass the `:resource`
  adverb to have it search in the module’s resource folder. Lazy loading is
  enabled by default. Turning it off is mainly useful if you want to preparse
  everything during a precompilation phase.
* **add-localization-basepaths**(Str *@paths*, Str *:$domain?*, Bool *:$resource* = False, Bool, *:$lazy* = True)
  Same as previous, but acts on a list of basepaths.
* **add-localization-language**(*$language-tag*, Str *:$domain?*)
  Adds the given language to the list of languages supported (this cannot be
  automated because `%*RESOURCES` does not allow introspection of files). If
  any eager (non-lazy) basepaths were previously added, their associated `.ftl`
  files will be loaded immediately. The `$language-tag` may be either a `Str`
  in valid BCP47 format or a `LanguageTag` (available in the `Intl::BCP47`
  package)
* **add-localization-language**(*@language-tags*, Str *:$domain?*)
  Same as previous, but acts on a list of language tags.
* **set-localization-fallback**(Callable *&fallback*)
  If a localization cannot be found, the callable is called with two positional
  parameters: (1) the message ID and (2) the domain if applicable. Fluent will
  pass the correct number of parameters, so if you don't use domains, feel free
  to just use a single `Whatever` to make your life easy. You can also pass a
  `Str` if you want a static message.
* **reset-localization-fallback**()
  Resets the fall back to the default.
* **load-localization**(Str *$fluent-document*, *$language-tag*, Str *$domain?*)
  Loads the specified Fluent data (note: *not* a filename) for the given language
  tag (as a BCP47 `Str` or a `LanguageTag`), optionally in the given domain. Most
  useful for testing, not as useful in actual production.
* **with-args**(*|c*)
  This function is mixes in the arguments into anything. Its primary use is for
  the `NUMBER` and `DATETIME` functions to pass complex formatting information
  in an easy to read manner.

# Formatting and organization

The file format is described on the [Project Fluent page](https://projectfluent.org).
To use localization files, just provide the root path of the files which can
be in your resources folder or locally stored on a disk. If you're writing a
module, structure it like this:

```
lib/
resources/
    localization/
        ast.ftl
        en.ftl
        es-ES.ftl     ⬅ These two are bad design,
        es-MX.ftl     ⬅   see usage notes.
        zh-Hant.ftl
        zh-Hans.ftl
t/
LICENSE
META6.json
README.md

```

To let Fluent know where the files are, give it the base file path onto
which it will add language codes (which may end in a `/` or not, but I find it
easiest to keep them all in a folder, but you may want them prefixed elsewise).

```
    add-localization-basepath('localization/', :resources);

```

The `:resources` adverb lets the module know to look in the `%*RESOURCES`
variable for the file. If the file is on the hard drive, don't use it,
and just reference the file path as you would any other. For example, in another
project where we've named files 'ui\_en.ftl', 'ui\_es-ES.ftl', etc, we might say:

```
    add-localization-basepath('data/l10n/ui_');

```

You also have an additional option to group the terms into various *domains*.
This may be useful if you plan to handle several different
sites/services/etc at once, and each one may have different texts for the same
message id. So, imagining I had an HTTP server and a website called Fruitopia
all about fruits, and another called Vegitania all about vegetables, with vastly
different sets of text, we could load (and access them) by using the `:domain`
argument:

```
    add-localization-basepath($root ~ 'fruitopia/text/email/', :domain('fruit') );
    add-localization-basepath($root ~ 'fruitopia/text/ui/',    :domain('fruit') );
    add-localization-basepath($root ~ 'fruitopia/text/store/', :domain('veggie'));
    add-localization-basepath($root ~ 'fruitopia/text/ui/',    :domain('veggie'));

```

With this set up, using `localized('sitename', :domain('fruit'))` contained in the `ui/`
directory would return something like **Fruitopia** but by changing the domain
`veggie` we might get **Vegitania**. But because Fruitopia doesn't have any
text for a store loaded, if we called `localized('buynow', :domain('fruit'))`,
the text returned would be that defined by the fallback option.

To define the fallback text, you can use either a string, some combination of
strings and WhateverCode (`*`), or some other callable. If you use a `Callable`
you might consider using two Whatevers or positional parameters to capture
the domain as well. Using the previous example, here's the text that
would be returned based on different fall back text:

```
    set-localization-fallback('[No Localization Present]');
    localized('buynow', :domain('fruit'));
    # ↪ [No Localization Present]

    set-localization-fallback('[MessageID:' ~ * ~ ']');
    localized('buynow', :domain('fruit'));
    # ↪ [MessageID:buynow]

    set-localization-fallback('[﹖ ' ~ * ~ ' ← ' ~ *.uc ']');
    localized('buynow', :domain('fruit'));
    # ↪ [﹖ buynow ← FRUIT]

    set-localization-fallback( { '[$^b:$^a??]' };
    localized('buynow', :domain('fruit'));
    # ↪ [fruit:buynow??]

```

Be aware that the order of positional arguments is first the Message ID,
second the domain (which is '' if no domain is specified). If the arity is
greater than 2 then all other parameters will be passed a blank string, although
the third one *may* in the future also receive a hash of variables being passed.

# Language Usage Notes

If the first thing you do with Fluent is pass a base file, Fluent won't do
much of anything with it. Fluent also needs to know which languages you intend
to support. Because the `resources` directory in modules is not able to be
queried for files available, I made the decision to have the programmer tell
Fluent which languages are available. To enable a language, simply pass it or
various to the `add-localization-language` (single) or `add-localization-languages`
(convenience, calls `add-localization-language` for each passed language)
functions which take *either* a LanguageTag *or* a Str representing a valid BCP47 language tag. For the hypothetical module listed previously, we'd say:

```
    add-localization-languages('ast', 'en', 'es-ES', 'es-MX', 'zh-Hant', 'zh-Hans');

```

Once both languages and file paths have been loaded, only once there is a need
for a language's localization files to be read will the `.ftl` be loaded and
parsed. However, if you want the files to be read into memory immediately,
you can use the `:!lazy` adverb:

```
    add-localization-basepath('foo/') :!lazy; # FTL files for all enabled languages
                                              # will be loaded immediately, and will
                                              # load immediately for any languages
                                              # added in the future

```

This option is best suited when precompilation is beneficial so that the FTL
files will be loaded once.

To determine the best fit language, Fluent uses the match algorithm in the
`Intl::BCP47` module on a *per message/term* basis. This means you can set a
base English translation in the `en.ftl` file, and override specific terms or
messages in an `en-GB` or `en-NZ` file. If the user prioritizes `en-NZ`, then
Fluent will first look there. If the message is not there, then it will look
in `en`, failing that, it will look (if enabled) the project default language
and finally, failing all other options, provide the fall back text described
above.

Note that this means it is a *bad idea* to only include regional language tags
without a base one. In the module example, there is a tag for `es-ES` and
`es-MX`. For a user requesting `es-GT`, Fluent will not find any Guatemalan
Spanish files, and so then will try `es`. But it *also* won't find that! At
that point, it will just go to the next best choice (or the default or, worst
case, the fallback). This is a result of the RFC4647 lookup method that BCP47
implements.

# Perl 6 implementation details

This module makes use of mixins to match features of other implementations in a
clean and intuitive manner. There are two main areas where they are used:

## The Hashy Str

The `localized` routine always returns a `Str`, but if the message also has
attributes, they are mixed in in a `Hash`-like manner and can be accessed as if
the result were a `Hash`;

```
    my  $translation = localized('greeting');
    say $translation;          #   ↪ "Hello!"
    say $translation<foo>;     #   ↪ "some related text"
    say $translation{'bar'};   #   ↪ "some other related text"

```

## Who doesn't like `but`s?

To take advantage of the partial arguments, you can use the function `with-args`
after a `but`. Functions that take arguments can then access them in addition
to the localizer’s arguments. For example:

```
my $weight = 5 but with-args(:3minimum-fraction-digits);
localized 'kilograms', :$weight; #   ↪ "It weighs 5.000 kg"

```

It can be done in one fell swoop, and actually ends up a bit cleaner (IMO) than
the Javascript version (with only two parentheses at the end, rather than two
parentheses and two brackets):

```
FluentBundle.format('proportion', {amount: FluentNumber(5, {minimumFractionDigits: 3, style: 'percent'})})

```

```
localized 'proportion', :amount( 5 but with-args(:3minimum-fraction-digits, :style<percent>) );

```

(You may even want to do a quick `&format = &with-args` so you can make your
code even prettier, *with-args* was chosen to be as generic as possible.)

## camelCase vs. kebab-case

Fluent's built in functions `NUMBER` and `DATETIME` take arguments in camelCase.
Because those aren't as natural to Perl 6 programmers (and aren’t what Intl::CLDR
uses), you can *also* use kebab-case arguments. This *only* applies to
arguments supplied code-side. Any arguments from the `.ftl` *must* use
camelCase to ensure compatibility with other implementations.

# Version history

* 0.8.1
  * Minor adjustments for dependency chain changes.
* 0.8 “Alcovy”
  * Added support for the `NUMBER` function (currency formatting will be available when Intl::CLDR supports it)
  * Improved handling for functions in general, including the ability for programs to add their own functions.
  * Updated test files.
* 0.7 “Cheaha”
  * Updated documents substantially
  * Fixed a bug in inline block text
  * Fixed major bugs in variable references and term references
  * Corrected term attribute usage, particularly evident in selectors
  * Moved the CLDR Plural logic into a separate module (Intl::CLDR) where it is better suited.
  * Added an experimental feature Variable Term References which is not currently part of the standard to demonstrate proof of concept
* 0.6 “Blackjack”
  * First reasonably usable version (missing NUMBER/DATE functions)
  * Localization file structure added
  * Messages/Terms are now tested based on `Intl::BCP47`'s lookup.
  * API should be mostly frozen at this point.
* 0.5
  * First semi working version

# Licensing and rights information

This module is released under the Artistic License 2.0.
The social media image (resources/logo.png) is released under CC-by 4.0, and incorporates
the pieces (<https://commons.wikimedia.org/wiki/File:Adonis_Blue_Butterfly.jpg>, licensed under CC0 1.0)
and


## resolve.md
resolve

Combined from primary sources listed below.

# [In CompUnit::Repository::Installation](#___top "go to top of document")[§](#(CompUnit::Repository::Installation)_method_resolve "direct link")

See primary documentation
[in context](/type/CompUnit/Repository/Installation#method_resolve)
for **method resolve**.

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

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

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

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

```raku
method resolve(IO::Path:D: :$completely --> IO::Path)
```

Returns a new `IO::Path` object with all symbolic links and references to the parent directory (`..`) resolved. This means that the filesystem is examined for each directory in the path, and any symlinks found are followed.

```raku
# bar is a symlink pointing to "/baz"
my $io = "foo/./bar/..".IO.resolve;      # now "/" (the parent of "/baz")
```

If `:$completely`, which defaults to `False`, is set to a true value, the method will [`fail`](/routine/fail) with `X::IO::Resolve` if it cannot completely resolve the path, otherwise, it will resolve as much as possible, and will merely perform [`cleanup`](/routine/cleanup) of the rest of the path. The last part of the path does **NOT** have to exist to `:$completely` resolve the path.

NOTE: Currently (April 2017) this method doesn't work correctly on all platforms, e.g. Windows, since `resolve` assumes POSIX semantics.

# [In role CompUnit::Repository](#___top "go to top of document")[§](#(role_CompUnit::Repository)_method_resolve "direct link")

See primary documentation
[in context](/type/CompUnit/Repository#method_resolve)
for **method resolve**.

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

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

# [In CompUnit::Repository::FileSystem](#___top "go to top of document")[§](#(CompUnit::Repository::FileSystem)_method_resolve "direct link")

See primary documentation
[in context](/type/CompUnit/Repository/FileSystem#method_resolve)
for **method resolve**.

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

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


## experimental.md
Experimental features

Preview of upcoming new language features available for user evaluation

During Raku development, new features are often made available for users as experimental before their design is completed. Eventually these features may be made part of the Raku specification. To use these features, one uses the `experimental` pragma in program source code, for example, like this:

```raku
use experimental :macros;
```

These are the features that, for the time being, are experimental.

## [**pack**](#Experimental_features "go to top of document")[§](#pack "direct link")

Pack is a feature that allows binary serialization of general data structures, and is inherited from [Perl's pack](http://perldoc.perl.org/functions/pack.html). The `pack` order creates a [`Buf`](/type/Buf) by packing data structures in a certain way given by a *packing string* with the options shown [in the description of `unpack`](/type/Blob#routine_unpack). You turn it on by inserting this pragma at the beginning of your program:

```raku
use experimental :pack;
```

For instance, we can pack numbers interpreting them as hexadecimal (`H`) with the pattern repeating until there are no more elements (`*`):

```raku
use experimental :pack;
say pack("H*", "414243").contents;#  OUTPUT: «(65 66 67)␤»

```

There is a corresponding `unpack` routine that does exactly the opposite.

```raku
use experimental :pack;
my $buf=Buf.new(65,66,67);
say $buf.unpack("H*"); # OUTPUT: «414243␤»

```

Not all of the symbols above are guaranteed to be implemented, and the roadmap does not include a fixed date for getting out of that stage.

Please see also documentation for [`pack`](/type/Blob#sub_pack) and [`unpack`](/type/Blob#routine_unpack) in the [`Blob`](/type/Blob) page.

## [**macros**](#Experimental_features "go to top of document")[§](#macros "direct link")

[Macros](https://en.wikipedia.org/wiki/Macro_(computer_science)) are code-generating routines, that generate code in compile time, before the program is executed. In Raku its use is still experimental and it needs to be turned on via the pragma

```raku
use experimental :macros;
```

Macro processing happens during parsing time. A macro generates an abstract syntax tree, which is grafted into the program syntax tree. `quasi` is the routine that performs this task.

```raku
use experimental :macros;
macro does-nothing() {
    quasi {}
};
does-nothing; # OUTPUT: «»

```

Macros are a kind of routine, so they can take arguments in exactly the same way, and act also in almost the same way.

```raku
use experimental :macros;
macro is-mighty( $who ) {
    quasi { "$who is mighty!"}
};
say is-mighty "Freija"; # OUTPUT: « "Freija" is mighty!␤»

```

"Almost" accounts for the fact that the argument is inserted as a literal, including the quotes. Please note that we can also eliminate the parentheses for a macro call, following the same rules as a routine. You can use the unquoting construct `{{{}}}` to get rid of this kind of thing:

```raku
use experimental :macros;
macro is-mighty( $who ) {
    quasi { {{{$who}}} ~ " is mighty!"}
};
say is-mighty "Freija";  # OUTPUT: «Freija is mighty!␤»

```

Since macro expansion happens at parse time, care must be taken when using external variables in them:

```raku
use experimental :macros;
my $called;
macro called() {
    $called++;
    quasi { "Called" }
};
say called() ~ " $called times";
say called() ~ " $called times"; # OUTPUT: «Called 2 times␤Called 2 times␤»

```

Since macros are expanded at parse time, `$called` will be the result when runtime starts, which is already `2`, as printed. Initializing `$called` with 0, however, will make this print `Called 0 times` since that initialization is run *after* the parse phase, when the macros are expanded.

Macros are terribly useful when complicated, computed initializations need to be done. However, they are still in the *experimental* nursery for a good reason. Although the features shown above are not very likely to change, anything, even their very presence, might change at any one time depending in necessities, so it would be best to keep them away from production code. Meanwhile, taking a look at [this article by Masak](https://perl6advent.wordpress.com/2012/12/23/day-23-macros/) as well as [`007`](https://github.com/masak/007), a new macro language, might provide a glimpse into the things to come.

## [**cached**](#Experimental_features "go to top of document")[§](#cached "direct link")

The following pragma:

```raku
use experimental :cached;
```

turns on the `is cached` trait, which stores the result of a routine call, returning the same value if called with the same arguments.

It can be used when heavy calculations are involved, as in this sample that uses [amicable numbers](https://perl6advent.wordpress.com/2018/12/25/calling-numbers-names/#more-7528), taken from the 2018 Advent Calendar:

```raku
use experimental :cached;

sub aliquot-parts( $number ) is cached {
    (^$number).grep: $number %% *;
}

sub infix:<amic>( $m, $n ) {
    $m == aliquot-parts($n).sum &&
    $n == aliquot-parts($m).sum;
}

# Taken from https://en.wikipedia.org/wiki/Amicable_numbers
my @numbers = [2620, 2924, 5020, 5564, 6232, 6368, 66928, 66992];

say "Aliquot parts of $_ are ", aliquot-parts $_ for @numbers;

for @numbers X @numbers -> @pair {
    say "@pair[0] and @pair[1] are ",
        @pair[0] amic @pair[1]??" "!!"not ", "amicable";
}

```

This code caches the computation of the *aliquot parts*, so that when the `amic` operator is called, it's only computed once; as a matter of fact, the first loop which prints these aliquot parts will be the only one that actually perform the computation.

See also [the description of the trait](/routine/is%20cached) for additional information and examples.

**Note**: This feature is not thread-safe.

## [**rakuast**](#Experimental_features "go to top of document")[§](#rakuast "direct link")

The pragma:

```raku
use experimental :rakuast;
```

makes the [`RakuAST`](/type/RakuAST) package and its classes available for use in language versions **before** `6.e`.


## dist_github-azawawi-Memoize.md
# Memoize

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

This make a Perl 6 routine faster by caching its results. This means it trades
more memory space used to get less execution time on cache hits. This means it
is faster on routines that return a result such the following:

* An expensive calculation (CPU)
* A slow database query (I/O)

This is a totally-experimental-at-the-moment module to create a subroutine trait
similar to the currently experimental `is cached`.

## Plan

* Add None to strategy to disable cache eviction and cache size limitation
* Determine tunable cache size statistics
* Add a pluggable architecture to cache expiry.

> perlpilot: it would be interesting if you could pass the thing that handles the caching as a parameter, but perhaps only as an academic exercise.

## Example

```
use v6;
use Memoize;

sub get-slowed-result(Int $n where $_ >= 0) is memoized {
  sleep $n / 10;
  return 1 if $n <= 1;
  return get-slowed-result($n - 1) * $n;
}

say sprintf("get-slowed-result(%d) is %d", $_, get-slowed-result($_)) for 0..10;

```

## Memoize vs `is-cached`

* `is-cached` is currently marked as experimental as per a [#perl6 discussion](http://irclog.perlgeek.de/perl6/2016-02-28#i_12114511).

Here is an example for `is cached` for the sake of completeness:

```
#!/usr/bin/env perl6

use v6;
use experimental :cached;

sub get-slowed-result(Int $n where $_ >= 0) is cached {
  sleep $n / 10;
  return 1 if $n <= 1;
  return get-slowed-result($n - 1) * $n;
}

say sprintf("get-slowed-result(%d) is %d", $_, get-slowed-result($_)) for 0..10;

```

## See Also

* [Add memoize to Perl 6 Most Wanted](https://github.com/perl6/perl6-most-wanted/pull/20)
* [Memoize (CPAN)](https://metacpan.org/pod/Memoize)
* [Memoize::ExpireLRU (CPAN)](https://metacpan.org/pod/Memoize::ExpireLRU)
* [Perl 6 RFC 228 - Add memoize into the standard library](http://perl6.org/archive/rfc/228.html)
* [Design specification for `is cached` subroutine trait](http://design.perl6.org/S06.html#is_cached)
* [Perl 6 documentation for `is cached` subroutine trait](http://doc.perl6.org/routine/is%20cached)
* [Memoization on Wikipedia](https://en.wikipedia.org/wiki/Memoization)
* [Pure and impure functions on Wikipedia](https://en.wikipedia.org/wiki/Pure_function#Impure_functions)

## Author

Ahmad M. Zawawi, azawawi on #perl6, <https://github.com/azawawi/>

## License

MIT License


## dist_cpan-YNOTO-JSON-Path.md
# JSON::Path

A pure perl JSON path implementation for perl6.

## Usage

```
use JSON::Path;

my $jpath = '$.options';
my $json  = from-json( '{ "options": { "is-rad": true } }' );

# Get results from the json:
my $results = filter-json($jpath, $json);

#`[
[ { "is-rad" => True } ]
]

# Get paths from the json:
my $results = filter-json($jpath, $json, :want-path);

#`[
[ "options" ]
]

# Alter the json:
my $modifier = sub ($val is rw) {
  $val = !$val;
};
filter-json($jpath, $json, :assign($modifier));

#`[
$json before: {"options":{"is-rad":true}}
 $json after: {"options":{"is-rad":false}}
]

```


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

# An Object-Oriented XML Framework for Raku

## Introduction

XML (originally called Exemel) is a full fledged XML library for Raku.

It handles parsing, generating, manipulating and querying XML. It supports element queries, parent element information, namespaces, and an extendable interface.

It supports every major kind of XML Node (XML::Node):

```
* Document (XML::Document)

* Element (XML::Element)

* Text (XML::Text)

* Comment (XML::Comment)

* PI (XML::PI)

* CDATA (XML::CDATA)

```

You can easily serialize the objects back to XML text by using any XML::Node object in a string context.

## Documentation

### XML

A *module* that provides a few simple subroutines.

#### from-xml(Str $string --> XML::Document)

Parse the string as XML, and return an XML::Document object.

#### from-xml-stream(IO $input --> XML::Document)

Slurp the IO, parse the contents, and return an XML::Document object.

#### from-xml-file(IO::Path() $file --> XML::Document)

Return an XML::Document object representing the specified file. You will be able to call $xml.save(); to save back to the original file.

#### open-xml(Str|IO::Path|IO::Handle $src)

A multi sub that picks the right way to open `$src` . If a `Str` is given it defaults to a filename. If such file is found it assumes a `Str` containing XML.

#### make-xml(Str $name, ... --> XML::Element)

See the *XML::Element.craft()* function for details on how this works.

### XML::Node

A *role* used by the rest of the XML Node classes.

#### $.parent [rw]

The XML::Element or XML::Document to which this Node belongs. Only an XML::Document will have an undefined *$.parent* property.

#### remove()

Removes the Node from its parent element.

#### reparent(XML::Element $newparent)

Removes the Node from its existing parent (if any) and sets the specified node as its *$.parent* property.

#### previousSibling()

Returns the Node that exists in the parent just before this one. Returns Nil if there is none.

#### nextSibling()

Returns the Node that exists in the parent just after this one. Returns Nil if there is none.

#### cloneNode()

This is a polymorphic method that exists in all XML::Node objects, and does what is needed to return a clone of the desired Node.

#### ownerDocument()

Returns the top-level XML::Document that this Node belongs to.

### XML::Document [XML::Node]

A Node representing an XML document. You can use array access syntax on it to access children of the root node. You can use hash access syntax on it to access attributes of the root node.

#### $.version

The XML version. Default: '1.0'

#### $.encoding

The text encoding, if specified in the XML declarator.

#### %.doctype

Has two keys, *'type'* represents the document type, *'value'* represents the rest of the DOCTYPE declaration (if applicable.)

#### $.root

The root XML::Element of the document. This also proxies many of the useful XML::Element methods, so that they can be called directly from the XML::Document object.

#### $.filename

If an XML::Document represents a file on the file-system, this is the path to that file.

#### new(Str $xml, :$filename)

Parse the passed XML and return an XML::Document. If the *$filename* variable is passed, the *$.filename* property will be set on the object.

#### new(XML::Element $root)

Create a new XML::Document object, with the specified XML::Element as its root element.

#### load(Str $filename)

Create a new XML::Document object, representing the specified file. The *$.filename* property will be set.

#### save(Str $filename?, Bool :$copy)

Save the XML back into a file. If the *$filename* parameter is not passed, we use the *$.filename* property (if it is set, otherwise we return False.)

If the *:copy* option is true, we don't re-set the *$.filename* property.

#### .elems()

See XML::Element.elems() for details, but this basically tells you how many child nodes (whether Element nodes or otherwise) the root node has.

### XML::Element [XML::Node]

A Node representing an individual XML element. You can use array access syntax to access child nodes, and hash access syntax to access or set attributes.

#### $.name [rw]

The tag name of the element.

#### @.nodes

Any child nodes that may exist. All members of *@.nodes* MUST be an object that does the XML::Node role.

Unless you are doing something that requires direct access of the *@.nodes* property, it's probably easier (and less noisy) to use the array access syntax.

#### %.attribs

XML attributes for the current node. We expect the keys and values to be strings, but you can use numeric values if you want. Remember on emitting or parsing, all values will be strings, even if you set it as a number.

It is recommended that you do not use *%.attribs* directly to set values. Use the *set()* method or the hash access syntax to set attribute values, and use the *unset()* method to delete attributes.

#### $.idattr [rw, default: 'id']

Specifies what attribute will be used as the XML Id when using the *getElementById()* method. This defaults to *'id'* which is used in (X)HTML and thus the most common.

#### new(Str $xml)

Return a new XML::Element object representing the specified XML string.

#### insert(XML::Node $node)

Insert an XML::Node at the beginning of our *@.nodes* list.

#### insert(Str $name, ...)

Create a new XML::Element with the given name, and insert it to the beginning of our nodes list. Uses *craft()* to build the element.

Any named parameters will be used as attributes, any positional parameters will be used as child nodes.

Positional parameters can be one of the following:

```
* An XML::Node object. Will be added as is.

* A String. Will be included as an XML::Text node.

* A Capture. Calls *craft()* using the Capture as the signature.

* Anything else, will be stringified, and added as an XML::Text node.

```

#### append(XML::Node $node)

Append an XML::Node to the bottom of our *@.nodes* list.

#### append(Str $name, ...)

See *insert (Str $name, ...)* but at the bottom.

#### before(XML::Node $existing, XML::Node $new)

Insert the *$new* Node before the *$existing* Node. It only works if the *$existing* node is actually found in our *@.nodes* list.

#### before(XML::Node $node)

Only works if our *$.parent* is an XML::Element. Inserts the Node before the current one.

#### before(Str $name, ...)

See *insert (Str $name, ...)* and *before(XML::Node $node)* and figure it out.

#### after(XML::Node $existing, XML::Node $new)

Like *before($existing, $new)* but put the node after the *$existing* one.

#### after(XML::Node $node)

Like *before(XML::Node $node)* but put the node after the current one.

#### after(Str $name, ...)

As per the others.

#### insert-xml(Str $xml)

Insert to top, a new XML::Element representing the given XML string.

#### append-xml(Str $xml)

Append to bottom, a new XML::Element representing the given XML string.

#### before-xml(Str $xml)

Insert a new XML::Element for the XML string, before the current element.

#### after-xml(Str $xml)

Insert a new XML::Element for the XML string, after the current element.

#### insertBefore(XML::Node $new, XML::Node $existing)

An alternative to *before($existing, $new)* using DOM semantics.

#### insertAfter(XML::Node $new, XML::Node $existing)

An alternative to *after($existing, $new)* using DOM-like semantics.

#### replace(XML::Node $existing, XML::Node $new)

If the *$existing* node is found, replace it with *$new* , otherwise, we return False.

#### replaceChild(XML::Node $new, XML::Node $existing)

An alternative to *replace()* with DOM semantics.

#### removeChild (XML::Node $node)

Removes the *$node* from our child *@.nodes* if it exists. If it doesn't we return False.

#### firstChild()

Return our first child node.

#### lastChild()

Return our last child node.

#### index-of($find)

Pass it a smart match rule, and it will return array index of the first matching node.

#### craft(Str $name, ...)

Create and return a new XML::Element object with the given name. Named and positional parameters are handled as with *insert(Str $name, ...)*

#### set(Str $name, $value)

Set an attribute with the given *$name* to the specified *$value* . If the *$value* is a Str or Numeric is is added directly. If it is Bool and True, the value will be set to the same as the *$name* . If it is Bool and False, the attribute will be deleted.

Any other value will be stringified using the *.Str* method.

#### set(...)

A *set()* call containing no positional paramters, will pass all named parameters to the above *set()* as key/value pairs.

#### unset($name, ...)

Each positional parameter passed will be assumed to be the name of an attribute to delete.

#### unset(:$name, ...)

We assume the key of each named parameter passed to be the name of an attribute to delete. The value means absolutely nothing and is in fact ignored entirely.

#### is-bool($attrib)

Returns True if the given attribute exists, and has the same value as its name (the definition of an XML boolean.)

#### add-values (Str $attrib, Set $values)

For the attribute with the given *$name* , perform the set-wise union, *(|)* , of the set of *$values* passed to the method and the existing values of the attribute. The results are converted back to a string value and stored in the attribute. For example:

```
my $xml = from-xml('<test><folks we = "Al Barb Carl"/></test>');
say $xml[0]; # <folks we="Al Barb Carl"/>

$xml[0].add-values("we", <Carl Dave Ellie>.Set);
say $xml[0]; # <folks we="Al Barb Carl Dave Ellie"/>

```

#### delete-values (Str $attrib, Set $values)

For the attribute with the given *$name* , perform the set-wise difference, *(-)* , of the existing values of the attribute and the *$values* passed to the method. The results are converted back to a string value and stored in the attribute. For example:

```
my $xml = from-xml('<test><folks we = "Al Barb Carl Dave Ellie"/></test>');
say $xml[0]; # <folks we="Al Barb Carl Dave Ellie"/>

$xml[0].delete-values("we", <Al Ellie Zack>.Set);
say $xml[0]; # <folks we="Barb Carl Dave"/>

```

#### test-values (Str $attrib, @tests)

For the attribute with the given *$name* , test each value in @tests for membership in the set of existing values of the attribute. Returns a hash that has the test values as keys and the boolean results of the membership test as values. For example:

```
my $xml = from-xml('<test><folks we = "Barb Carl Dave"/></test>');
say $xml[0]; # <folks we="Barb Carl Dave"/>

my %test-results = $xml[0].test-values("we", <Al Carl Zack>.Array);
say %test-results; # "Al" => Bool::False, "Carl" => Bool::True, "Zack" => Bool::False

```

#### elements()

Return all child XML::Elements.

#### elements(...)

Specify a query of named parameters. Special processing parameters are used:

```
* TAG

```

If set, elements must match the given tag name.

```
* NS

```

If set, elements must match the given namespace prefix.

```
* URI

```

If set, elements must match the given namespace URI.

```
* RECURSE

```

If set to a non-zero digit, child elements will also be searched for elements matching the queries. The recursion will traverse a tree depth of the value set to this parameter.

```
* NEST

```

Used with *RECURSE* if this is set to True, this will recurse even child elements that matched the query.

```
* SINGLE

```

If this is set to True, we will return the first matched value. If no values match, we will return False. If *SINGLE* is not specified, or is set to False, we return an Array of all matches (this may be empty if no nodes matched.)

```
* OBJECT

```

If this is set to True, instead of returning an Array of results, we will return a XML::Element object with the same name as the original input object, with its nodes set to the matched elements.

```
* POS

```

If set to an Int, the element must be the nth child to match. If set to a Range, the element's position must be within the range. If set to a Whatever match rule (e.g. \* > 2) the rule must match.

If this is set to an Int, and RECURSE is not a positive value, then the SINGLE rule will be set to True.

```
* NOTPOS

```

Set to an Int, then we match if the element is not the nth child.

```
* FIRST

```

Match only if the element is the first child.

If RECURSE is not a positive value, then SINGLE will be set to True.

```
* !FIRST

```

Don't include the first child in the results.

```
* LAST

```

Match only if the element is the last child.

If RECURSE is not a positive value, then SINGLE will be set to True.

```
* !LAST

```

Don't include the last child in the results.

```
* EVEN

```

Match even child nodes. By default this is based on natural position (i.e. the second child element is even) see BYINDEX for details.

```
* ODD

```

Match odd child nodes. By default this is based on natural position (i.e. the first child element is odd) see BYINDEX for details.

```
* BYINDEX

```

If set to True, then the EVEN and ODD rules match against the array index value rather than the natural position. Therefore, the first element will be even, since it is in position 0.

Any other named paramters not in the above list, will be assumed to be attributes that must match. You can match by value, regular expression, or whatever code matches.

```
  my $head = $html.elements(:TAG<head>, :SINGLE);
  my @stylesheets = $head.elements(:TAG<link>, :rel<stylesheet>);
  my @middle = $table.elements(:!FIRST, :!LAST);
  my @not-red = $div.elements(:class(* ne 'red'));
  my @elms-by-class-name = $html.elements(:RECURSE(Inf), :class('your-class-name')); # find all elements by class name

```

#### lookfor(...)

A shortcut for elements(..., :RECURSE)

#### getElementById($id)

Return the XML::Element with the given id.

#### getElementsByTagName($name, :$object?)

Return an array of XML::Elements with the given tag name.

If the boolean $object named parameter is true, then the 'OBJECT' rule will be applied to the query sent to elements().

#### nsPrefix(Str $uri)

Return the XML Namespace prefix.

If no prefix is found, it returns an undefined value. If the URI is the default namespace, it returns ''.

#### nsURI(Str $prefix?)

Returns the URI associated with a given XML Namespace prefix. If the *$prefix* is not specified, return the default namespace.

Returns an undefined value if there is no XML Namespace URI assigned.

#### setNamespace($uri, $prefix?)

Associated the given XML Namespace prefix with the given URI. If no *$prefix* is specified, it sets the default Namespace.

#### comments()

Return an array of all XML::Comment child nodes.

#### cdata()

Returns an array of all XML::CDATA child nodes.

#### instructions()

Returns an array of all XML::PI child nodes.

#### contents()

Returns an array of all XML::Text child nodes.

#### .elems()

XML and Raku have quite different meanings for the word "element". In XML, an Element is a , whereas in Raku, it's a single element in a one-dimensional list/array.

The TL;DR is that .elements() uses the XML meaning, whereas .elems() uses the Raku meaning.

The slightly longer version is that, since XML::Element does Positional, it has to have a .elems() method that supports the Raku meaning. So .elems will tell you how many children the node has, not the number of XML::Element children (since there will likely be some text nodes and things in there as well).

### XML::Text [XML::Node]

A Node representing a portion of plain text.

#### $.text

The raw text, with no whitespace chopped out.

#### Str(XML::Entity :$decode, Bool :$min, Bool :$strip, Bool :$chomp, Bool :numeric)

Return the text, with various modifications depending on what was passed. If :decode is set, we decode XML entities using the XML::Entity object. If :min is set, we replace multiple whitespace characters with a single space. If :strip is set, we trim off leading and trailing whitespace. If :chomp is set, we remove the trailing newline. The :numeric value is passed to the decoder specified in :decode.

#### string(XML::Entity $decode=XML::Entity.new)

An alias for Str(:$decode, :min, :strip, :chomp, :numeric);

Basically, make the text node easier to read for humans.

The default $decode value is a new instance of XML::Entity.

### XML::Comment [XML::Node]

Represents an XML Comment

```
  <!-- comment here -->

```

#### $.data

Contains the string data of the content.

### XML::PI [XML::Node]

Represents an XML processing instruction.

```
  <?blort?>

```

#### $.data

Contains the string text of the processing instruction.

### XML::CDATA [XML::Node]

Represents an XML CDATA structure.

```
  <![CDATA[ random cdata content here ]]>

```

#### $.data

Contains the string text of the CDATA.

### XML::Entity

#### decode(Str $input, Bool :$numeric)

Decode XML entities found in the string.

#### encode(Str $input, Bool :$hex, ...)

Encode known XML entities, plus any numeric values passed as extra parameters. Any additional parameters should be the regular base10 integer values of the additional characters that should be encoded.

If :hex is true we encode using hexidecimal entities instead of decimal.

#### add (Str $name, Str $value)

Add a new custom entity named $name with the replacement value $value.

#### add (Pair $pair)

An alias for self.add($pair.key, $pair.value);

## Examples

A quick example, for more, see the tests in the 't/' folder.

### test.xml

```
<test>
  <greeting en="hello">world</greeting>
  <for>
    <item>Yes</item>
    <item>No</item>
    <item>Maybe</item>
    <item>Who cares?</item>
  </for>
</test>

```

### test.raku

```
use XML;

my $xml = from-xml-file('test.xml');

say $xml[1]<en> ~ $xml[1][0]; ## "hello world"
say $xml[3][5][0]; ## "Maybe"

$xml[3].append('item', 'Never mind');

say $xml[3][9]; ## <item>Never mind</item>

```

## Author

Timothy Totten, supernovus on #raku, <https://github.com/supernovus/>

### Note

The XML::Grammar library was originally based on the now defunct [XML::Grammar::Document](http://github.com/krunen/xml) library, but modified to work with Rakudo 'ng' and later 'nom', with other changes specific to this library.

## License

[Artistic License 2.0](http://www.perlfoundation.org/artistic_license_2_0)


## dist_zef-martimm-Gnome-Gsk4.md
![](https://martimm.github.io/gnome-gtk3/content-docs/images/gtk-perl6.png)

# Gnome Gsk - Scene Graph Kit

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

# Description

GTK Scene Graph Kit (GSK) is the rendering and scene graph API for GTK introduced with version 3.90. GSK lies between the graphical control elements (widgets) and the rendering.

## Documentation

* [🔗 Website, entry point for all documents and blogs](https://martimm.github.io/)
* [🔗 License document](https://www.perlfoundation.org/artistic_license_2_0)
* [🔗 Release notes of all the packages in `:api<2>`](https://github.com/MARTIMM/gnome-source-skim-tool/blob/main/CHANGES.md)
* [🔗 Issues of all the packages in `:api<2>`](https://github.com/MARTIMM/gnome-source-skim-tool/issues)

# Installation

Do not install this package on its own. Instead install `Gnome::Gtk4` newest api.

`zef install Gnome::Gtk4:api<2>`

# Author

Name: **Marcel Timmerman**
Github account name: **MARTIMM**

# Issues

There are always some problems! If you find one please help by filing an issue at [my github project](https://github.com/MARTIMM/gnome-source-skim-tool/issues).

# Attribution

* The inventors of Raku, formerly known as Perl 6, of course and the writers of the documentation which helped me out every time again and again.
* The builders of all the Gnome libraries and the documentation.
* Other helpful modules for their insight and use.


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

Date::Calendar::Julian - Conversions from / to the Julian calendar

# SYNOPSIS

What is the peculiarity of 15 February for people using the Julian
calendar? And can you please print it in, say, Dutch?

```
use Date::Calendar::Julian;

my Date $feb15-grg;
my Date::Calendar::Julian $palindrome-jul;

$feb15-grg      .= new(2020, 2, 15);
$palindrome-jul .= new-from-date($feb15-grg);

say $palindrome-jul;
# --> 2020-02-02
$palindrome-jul.locale = 'nl';
say $palindrome-jul.strftime("%A %e %B %Y");
# --> zaterdag  2 februari 2020

my Str $s1 = $palindrome-jul.strftime("%Y%m%d");
if $s1 eq $s1.flip {
  say "$s1 is a palindrome in YYYYMMDD format!";
}
$s1 = $palindrome-jul.strftime("%d%m%Y");
if $s1 eq $s1.flip {
  say "$s1 is a palindrome in DDMMYYYY format!";
}
$s1 = $palindrome-jul.strftime("%m%d%Y");
if $s1 eq $s1.flip {
  say "$s1 is a palindrome in MMDDYYYY format!";
}

```

The Perl & Raku Conference was scheduled to end on 1st August when
using the Julian calendar. What is the corresponding Gregorian date?

```
use Date::Calendar::Julian;
my Date::Calendar::Julian $TPRC-Amsterdam-jul;
my Date                   $TPRC-Amsterdam-grg;

$TPRC-Amsterdam-jul .= new(year  => 2020
                         , month =>    8
                         , day   =>    1);
$TPRC-Amsterdam-grg = $TPRC-Amsterdam-jul.to-date;

say $TPRC-Amsterdam-grg;
# --> 2020-08-14

```

# INSTALLATION

```
zef install Date::Calendar::Julian

```

or

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

```

# DESCRIPTION

Date::Calendar::Julian is a class representing dates in the Julian
calendar. It allows you to convert an Julian date into Gregorian (or
possibly other) calendar and the other way.

With class Date::Calendar::Julian::AUC, you can count the years since
the founding of Rome.

# AUTHOR

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

# COPYRIGHT AND LICENSE

Copyright © 2020, 2021 Jean Forget

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


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

# NAME

Raku port of Perl's ref() built-in

# SYNOPSIS

```
use P5ref; # exports ref()

my @a;
say ref @a;  # ARRAY

my %h;
say ref %h;  # HASH

sub &a { };
say ref &a;  # CODE

my $r = /foo/;
say ref $r;  # Regexp

my $v = v6.c;
say ref $v;  # VSTRING

my $i = 42;
say ref $i;  # Int

```

# DESCRIPTION

This module tries to mimic the behaviour of Perl's `ref` built-in as closely as possible in the Raku Programming Language.

# HEAD1

ORIGINAL PERL 5 DOCUMENTATION

```
ref EXPR
ref     Returns a non-empty string if EXPR is a reference, the empty
        string otherwise. If EXPR is not specified, $_ will be used. The
        value returned depends on the type of thing the reference is a
        reference to.

        Builtin types include:

            SCALAR
            ARRAY
            HASH
            CODE
            REF
            GLOB
            LVALUE
            FORMAT
            IO
            VSTRING
            Regexp

        You can think of "ref" as a "typeof" operator.

            if (ref($r) eq "HASH") {
                print "r is a reference to a hash.\n";
            }
            unless (ref($r)) {
                print "r is not a reference at all.\n";
            }

        The return value "LVALUE" indicates a reference to an lvalue that
        is not a variable. You get this from taking the reference of
        function calls like "pos()" or "substr()". "VSTRING" is returned
        if the reference points to a version string.

        The result "Regexp" indicates that the argument is a regular
        expression resulting from "qr//".

        If the referenced object has been blessed into a package, then
        that package name is returned instead. But don't use that, as it's
        now considered "bad practice". For one reason, an object could be
        using a class called "Regexp" or "IO", or even "HASH". Also, "ref"
        doesn't take into account subclasses, like "isa" does.

        Instead, use "blessed" (in the Scalar::Util module) for boolean
        checks, "isa" for specific class checks and "reftype" (also from
        Scalar::Util) for type checks. (See perlobj for details and a
        "blessed/isa" example.)

        See also perlref.

```

# PORTING CAVEATS

## Types not supported

The following strings are currently never returned by `ref` because they have no sensible equivalent in Raku: `REF`, `GLOB`, `LVALUE`, `FORMAT`, `IO`.

Also, since everything in Raku is a (blessed) object, you can only get the `SCALAR` response if you managed to put a Scalar container into another Scalar container (which is pretty hard), or you somehow have gotten ahold of a Proxy object. On all other cases, a Scalar container will be ignored and instead the contents of the container will be used.

## $\_ no longer accessible from caller's scope

In future language versions of Raku, it will become impossible to access the `$_` variable of the caller's scope, because it will not have been marked as a dynamic variable. So please consider changing:

```
ref;

```

to either:

```
ref($_);

```

or, using the subroutine as a method syntax, with the prefix `.` shortcut to use that scope's `$_` as the invocant:

```
.&ref;

```

# AUTHOR

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

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!

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

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021, 2023 Elizabeth Mattijsen

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

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


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

# NAME

Raku port of Perl's Tie::StdHash module

# SYNOPSIS

```
use Tie::StdHash;

```

# DESCRIPTION

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

Tie::StdHash is a module intended to be subclassed by classes using the [P5tie](tie()) interface. It uses the standard `Hash` implementation as its "backend".

# SEE ALSO

<P5tie>, Tie::StdHash

# AUTHOR

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

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

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021 Elizabeth Mattijsen

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

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


## dist_zef-codesections-_.md
# `_`

`_` (pronounced "lowbar") is a meta utility package for the [Raku](https://raku.org) programming
language. Being *meta* means that `_` is comprised of independent sub-packages, each with their own
documentation and tests. Being a *utility* package means that each of `_`'s sub-packages is
provides some helper functionality — the type of functionality that, if it weren't in `_`, might
live in a `./utils` directory or in a tiny module that would bloat your dependency tree.

`_`'s goal is to provide you with utilities that are [correct by
inspection](https://proofwiki.org/wiki/ProofWiki:Jokes#Proof_by_Inspection): that is, with code so
simple that you can look at it and *tell* that it is correct. To achieve this goal, each `_`
sub-package will always be:

1. **A single file** (not counting tests/docs)
2. **with zero dependencies** (not counting other `_` files or [core
   modules](https://docs.raku.org/language/modules-core))
3. **with no more than 70 lines**

This means that you or any other Raku programmer can evaluate any `_` sub-package by opening a
single file and reading a page of code. If you have questions or concerns about any `_`
sub-packages, I encourage you to do just that.

However, just because you can doesn't mean that you must: each `_` sub-package is also documented in
the accompanying `README` file located in its directory. Similarly, as valuable as "proof by
inspection" my be, it's no substitute for tests. (Recall [Knuth's
warning to a colleague](https://www-cs-faculty.stanford.edu/~knuth/faq.html): "Beware of bugs in the above code; I
have only proved it correct, not tried it."). Accordingly, each sub-package also has its own tests.

**NOTE**: Once `_` has a production release, it will guarantee backwards compatibility. However,
`_` is currently beta software and does **not promise backwards compatibility**.

For more information about `_`'s goals and plans, please see the [announcement blog
post](https://raku-advent.blog/unix_philosophy_without_leftpad_part2).

## Installation

Install `_` with `$ zef install _:auth<github:codesections>`.

## Usage

To use `_`, you can import all of `_`'s non-test functions with `use _`, all of its test functions
with `use _ :Test`, or both sets with `use _ :ALL`. This style of importing is intended for
prototyping/experimentation when you are not which `_` functions you may use.

Alternatively, you can selectively import exported functions (or other symbols) by passing their
name to the `use _` statement. For example, here's how you could import the `&dbg` function from
the `Print::Dbg` sub-package and the `&wrap-words` function from the `Text::Wrap` sub-package using
a fully-qualified use statement:

```
use _:ver<0.0.1>:auth<fez:codesections> <&dbg &wrap-words>;

```

This style of imports is intended for later in the development process/when you want to pin to an
exact `_` version and ensure that `_` does not cause unexpected name clashes.

## sub-packages

`_` includes the following sub-packages. You can find more information about each one in
the `README` file in its directory.

* `Pattern::Match` - pattern match with Raku's full destructuring from signature
  binding. [README](lib/Pattern/Match/README.md); [src](lib/Pattern/Match/Match.rakumod)
* `Print::Dbg` - better print-line debugging than `.raku` or
  `dd`. [README](lib/Print/Dbg/README.md); [src](lib/Print/Dbg/Dbg.rakumod)
* `Self::Recursion` - provides `&_` as an alias for `&?ROUTINE` for anonymous self-recursion.
  [README](lib/Self/Recursion/README.md); [src](lib/Self/Recursion/Recursion.rakumod)
* `Text::Paragraphs` - provides a `paragraphs` function similar to
  [`lines`](https://docs.raku.org/routine/lines) except that it breaks text up into paragraphs
  rather than lines. [README](lib/Text/Paragraphs/README.md); [src](lib/Text/Paragraphs/Paragraphs.rakumod)
* `Text::Wrap` - provides a `wrap-words` function that wraps text to a specified line length (a
  better alternative to Rakudo's private `naive-word-wrapper`). [README](lib/Text/Wrap/README.md);
  [src](lib/Text/Wrap/Wrap.rakumod)
* `Test::Doctest::Markdown` - tests Raku code blocks from `README`s or other markdown files and,
  optionally, compares their output to `# OUTPUT: «…»`
  comments. [README](lib/Test/Doctest/Markdown/README.md); [src](lib/Test/Doctest/Markdown/Markdown.md)
* `Test::Fluent` - A thin wrapper over [Test](https://docs.raku.org/type/Test) that lets you
  describe tests in [declarator
  comments](https://docs.raku.org/language/pod#index-entry-declarator_blocks_%23=) (`#|`) and to
  more fluently chain test methods.[README](lib/Test/Fluent/README.md); [src](lib/Test/Fluent/Fluent.md)

## Contributing

You would be welcome to contribute to `_`'s development; you can help in any of the following ways:

* by opening an issue
  * to report a section of the documentation that you found unclear
  * to report a bug in an existing sub-package
  * to suggest a feature for an existing sub-package
  * to suggest a new sub-package
  * to discuss future plans for `_`/and of the
    [questions from the announcement
    post](https://raku-advent.blog/unix_philosophy_without_leftpad_part2#future_plans)
* by opening a pull request
  * to improve the documentation
  * to add tests for an exiting sub-package
  * to fix a bug
  * to add a feature for a sub-package
  * to add a new sub-package

(For the last two, it'd probably be a good idea to mention your idea in an issue first; that's not
a requirement, but it might prevent you spending time of a feature that isn't a great fit for `_`).

All `_` contributors agree to abide by the [Raku Code of
Conduct](https://raku.github.io/Raku-Steering-Council/papers/CoC).

## Roadmap

My initial goal for `_` is to get it to a 1.0.0/stable release as soon as possible in order to
provide guarantees regarding backwards compatibility. To that end, my priority is to decide what
`_`'s overall approach to versioning will be and to implement that system. The [announcement blog
post](https://raku-advent.blog/unix_philosophy_without_leftpad_part2#versioning) has additional
details about the versioning considerations.

Once `_` has a stable release, the plan is to focus on growing `_` to address other needs in the
Raku ecosystem.