## dist_zef-FCO-HTML-Component.md
[![Actions Status](https://github.com/FCO/HTML-Component/actions/workflows/test.yml/badge.svg)](https://github.com/FCO/HTML-Component/actions)

# Still very early stage of development

# NAME

`HTML::Component` - is the beginning of components (WiP)

# SYNOPSIS

```
# examples/todo/Todo.rakumod
use HTML::Component;
use HTML::Component::Endpoint;

unit class Todo does HTML::Component;

my @todos;

has UInt   $.id = ++$;
has Str()  $.description is required;
has Bool() $.done = False;

submethod TWEAK(|) {
  @todos[$!id - 1] := self;
}

method LOAD(UInt() :$id) {
  @todos[$id - 1]
}

multi method new($description) { self.new: :$description, |%_ }

method RENDER($_) {
  .li:
    :htmx-endpoint(self.toggle),
    :hx-swap<outerHTML>,
    :class<todo>,
    {
      .input-checkbox:
        :checked($!done),
      ;
      if $!done {
        .del: $!description
      } else {
        .add-child: $!description
      }
    }
  ;
}

method toggle is endpoint{ :return-component } {
  $!done .= not
}

```

```
# examples/todo/TodoList.rakumod
use HTML::Component::Endpoint;
use HTML::Component;
use HTML::Component::Boilerplate;
use HTML::Component::Traits;
use Todo;

unit class TodoList does HTML::Component;

method new(|)  { $ //= self.bless }
method LOAD(|) { self.new }

has UInt $.id = ++$;
has Todo @.todos;

method RENDER($_) {
  .ol: {
    .add-children: @!todos;
  }
  .form: self.new-todo;
}

method new-todo(
  Str :$description! is no-label, #= What should be done?
) is endpoint{ :verb<POST>, :redirect</> } {
  @!todos.push: Todo.new: :$description;
}

```

```
# examples/todo/App.rakumod
use TodoList;
use HTML::Component;
use HTML::Component::Boilerplate;
unit class App does HTML::Component;

method RENDER($) {
  boilerplate
    :title("My TODO list"),
    :body{
      .script: :src<https://unpkg.com/htmx.org@1.9.10>;
      .add-child: TodoList.new;
    }
  ;
}

```

```
# examples/todo/cro-todo.raku
use Cro::HTTP::Log::File;
use Cro::HTTP::Server;
use Cro::HTTP::Router;
use HTML::Component::CroRouter;
use Cro::HTTP::Log::File;
use lib "examples";
use App;

my $route = route {
    root-component App.new
}

my $app = Cro::HTTP::Server.new(
    host => '127.0.0.1',
    port => 10000,
    application => $route,
    after => [
        Cro::HTTP::Log::File.new(logs => $*OUT, errors => $*ERR)
    ],
  );

  $app.start;
  say "Listening at http://127.0.0.1:10000";

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

```

# DESCRIPTION

HTML::Component is coming...

# AUTHOR

Fernando Corrêa de Oliveira `fernandocorrea@gmail.com`

# COPYRIGHT AND LICENSE

Copyright 2023 Fernando Corrêa de Oliveira

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


## dist_zef-dwarring-CSS-TagSet.md
[[Raku CSS Project]](https://css-raku.github.io)
/ [[CSS::TagSet]](https://css-raku.github.io/CSS-TagSet-raku)

## CSS::TagSet

## Example

```
# interrogate styling rules for various XHTML tags and attributes
use CSS::TagSet::XHTML;
my CSS::TagSet::XHTML $tag-set .= new;

# show styling for various XHTML tags
say $tag-set.tag-style('i');  # font-style:italic;
say $tag-set.tag-style('b');  # font-weight:bolder;
say $tag-set.tag-side('th');  # display:table-cell;

# styling for <img width="200px" height="250px"/>
say $tag-set.tag-style('img', :width<200px>, :height<250px>);
# height:250px; width:200px;

```

## Description

This module implements document specific styling rules for several markup languages, including XHTML, Pango and Tagged-PDF.

TagSet classes perform the role CSS::TagSet and implement the follow methods, to
define how stylesheets are associated with documents and how CSS styling is
determined from document content, including the extraction of stylesheets
and applying styling to nodes in the document. The methods that need to
be implemented are:

| Method | Description |
| --- | --- |
| `stylesheet-content($doc)` | Extracts and returns stylesheets for a document |
| `tag-style(Str $tag, :$hidden, *%attrs)` | Computes styling for a node with a given tag-name and attributes |
| `inline-style-attribute()` | Returns inline styling attribute. Defaults to style |

In the case of XHTML (CSS::TagSet::XHTML):

* The `stylesheet-content($doc)` method extracts `<style>...</style>` tags or externally linked via `<link rel="stylesheet href=.../>` tags,
* for example `$.tag-style('b')` returns a CSS::Properties object `font-weight:bolder;`

The default styling for given tags can be adjusted via the `base-style` method:

```
say $tag-set.tag-style('small'); # font-size:0.83em;
$tag-set.base-style('small').font-size = '0.75em';
say $tag-set.tag-style('small'); # font-size:0.75em;

```

`base-style` can also be used to define styling for simple new tags:

```
$tag-set.base-style('shout').text-transform = 'upppercase';
say $tag-set.tag-style('shout');  # text-transform:upppercase;

```

## Classes

* [CSS::TagSet](https://css-raku.github.io/CSS-TagSet-raku/CSS/TagSet) - CSS TagSet Role
* [CSS::TagSet::XHTML](https://css-raku.github.io/CSS-TagSet-raku/CSS/TagSet/XHTML) - Implements XHTML specific styling
* [CSS::TagSet::Pango](https://css-raku.github.io/CSS-TagSet-raku/CSS/TagSet/Pango) - Implements Pango styling
* [CSS::TagSet::TaggedPDF](https://css-raku.github.io/CSS-TagSet-raku/CSS/TagSet/TaggedPDF) - (*UNDER CONSTRUCTION*) Implements Tagged PDF styling


## dist_zef-jonathanstowe-RedX-HashedPassword.md
# RedX::HashedPassword

A facility to allow the Red ORM to store and use hashed passwords in the database.

![Build Status](https://github.com/jonathanstowe/RedX-HashedPassword/workflows/CI/badge.svg)

## Synopsis

```

use Red;
use RedX::HashedPassword;

model User {
    has Int $.id        is serial;
    has Str $.username  is column;
    has Str $.password  is password handles <check-password>;
}

...

User.^create( username => 'user', password => 'password'); # password is saved as a hash

...

my User $user = User.^rs.first( *.username eq 'user' );

$user.check-password('password');  # True

```

## Description

This provides a mechanism for [Red](https://github.com/FCO/Red) to store a password
as a cryptographic hash in the database, such that someone who gains access to the
database cannot see the plain text password that may have been entered by a user.

The primary interface provided is the `is password` trait that should be
applied to the column attribute in your model definition that you want to store the
hashed password in, this takes care of hashing the password before it is stored in
the database, on retrieval ("inflation") it also applies a role that provides a method
`check-password` that checks a provided plaintext password against the stored hash.
You can make this appear to be a method of your (for example,) User model by applying
the `handles <check-password>` trait to your column attribute.

The hashing algorithm used will be the best one provided by
[Crypt::AnyPasswordHash](https://github.com/jonathanstowe/Crypt-AnyPasswordHash)
which has two implications, firstly the default provider is
[Crypt::Libcrypt](https://github.com/jonathanstowe/Crypt-Libcrypt) if no
other supported hashing module is installed, this will attempt to use the
mechanism suggested by the `libcrypt` but if this can't be determined,
it will fall back to SHA-512 which seems to be the best commonly provided
algorithm, except on `MacOS` where the `libcrypt` only appears to support
the "heritage" DES algorithm - which has been considered insecure for most
of this century, so you probably don't want to use this in production
on MacOS for the timebeing without installing one of the other modules
supported by `Crypt::AnyPasswordHash`. The second implication is that,
if you are going to access the hashed password from multiple hosts,
you should ensure that you have the same hashing module installed on
all the hosts in order that they can all verify the same methods.

## Installtion

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

```
 zef install RedX::HashedPassword

 # or from a local copy

 zef install .

```

The module requires at least v0.1.0 of [Crypt::Libcrypt](https://github.com/jonathanstowe/Crypt-Libcrypt)
so you may want to upgrade that first if you already have it installed.

## Support

Suggestions/patches are welcomed via github at:

<https://github.com/jonathanstowe/RedX-HashedPassword/issues>

Ideally there should be a better choice of hashing algorithm from those
provided by the OS and installed modules, this will come after the initial
release.

## Licence

This is free software.

Please see the <LICENCE> file in the distribution

© Jonathan Stowe 2019 - 2021


## dist_cpan-HOLLI-Operator-grandpa.md
[![Build Status](https://travis-ci.org/holli-holzer/Operator-grandpa.svg?branch=master)](https://travis-ci.org/holli-holzer/Operator-grandpa)

# NAME

Operator::grandpa - An object recursion operator

# VERSION

0.01

# SYNOPSIS

```
class Node {
  has $.name;
  has $.parent;
}

my $child = Node.new(
  :name("out"),
  :parent( Node.new(
    :name("mid"),
    :parent( Node.new(
      :name("inner"),
      :parent( Node.new( :name("root") ) )
    ))
  ))
);

my $root1 = $child :| { .parent }
my $root2 = $child 𝄇 -> $node { $node.parent }

```

# DESCRIPTION

```
multi sub prefix:<:|>(Any --> Callable:D)
multi sub prefix:<𝄇>(Any --> Callable:D)

```

The grandpa / object recursion operator *:|* and it's unicode counterpart *𝄇* (U+1D107) invoke the callable on the RHS recursively.

The callable gets initially invoked with the LHS as the argument, and then recursively invoked with its' respective previous return value as the argument.

It does that until the code block evaluates to `Any`, then returns the last good value.

Note, that if you assign to `$_` within the code block, this also changes the LHS of the operator. So, don't do that, unless it's what you want.

```
multi sub prefix:<|:>(Any --> Callable:D)
multi sub prefix:<𝄆>(Any --> Callable:D)

```

Alternatively you can use this version of the operator, which does the same as above but operates on a copy of the LHS, thus allowing assigning to `$_` safely.

# AUTHOR

```
holli.holzer@gmail.com

```

# COPYRIGHT AND LICENSE

Copyright © [holli.holzer@gmail.com](mailto:holli.holzer@gmail.com)

License: Artistic-2.0

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.


## dist_zef-sdondley-Distribution-Resources-Menu.md
[![Actions Status](https://github.com/sdondley/Distribution-Resources-Menu/actions/workflows/test.yml/badge.svg)](https://github.com/sdondley/Distribution-Resources-Menu/actions)

# NAME

Distribution::Resources::Menu - Navigate the files in the resources directory of your Raku distribution from the command line

# SYNOPSIS

Place something like the following code into a module in your distribution:

```
use Distribution::Resources::Menu;
unit module Your::Module;

my $rsm = ResourceMenu.new(
    distribution => $?DISTRIBUTION,
    resources    => %?RESOURCES);

sub execute-resource-menu is export {
    $rsm.execute;
}

```

And now you can execute the menu with something like this:

```
use Your::Module;

# Display a menu on the command line and prompt the user
# to select a file from the "resources" directory of the distribution
my $resource = execute-resource-menu();

say $resource.file-path;
say $resource.file-content;

```

# DESCRIPTION

Distribution::Resources::Menu generates and executes a menu for navigating and selecting files located in a distribution's `resources` directory.

# METHODS

## execute

Executes the interactive command-line menu for selecting a file from the resources directory of the distribution.

## file-content

Returns the string value of the content of the file.

## file-path

Returns the string value of the path to the file contained in the `$%RESOURCES` variable.

# AUTHOR

Steve Dondley [s@dondley.com](mailto:s@dondley.com)

# COPYRIGHT AND LICENSE

Copyright 2022 Steve Dondley

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


## dist_github-samgwise-Net-Osc.md
# [Build Status](https://travis-ci.org/samgwise/Net-OSC) Net::OSC

Open Sound Control for Perl6

Use the Net::OSC module to communicate with OSC applications and devices!

# SYNOPSIS

```
use Net::OSC;

my Net::OSC::Server::UDP $server .= new(
  :listening-address<localhost>
  :listening-port(7658)
  :send-to-address<localhost> # ← Optional but makes sending to a single host very easy!
  :send-to-port(7658)         # ↲
  :actions(
    action(
      "/hello",
      sub ($msg, $match) {
        if $msg.type-string eq 's' {
          say "Hello { $msg.args[0] }!";
        }
        else {
          say "Hello?";
        }
      }
    ),
  )
);

# Send some messages!
$server.send: '/hello', :args('world', );
$server.send: '/hello', :args('lamp', );
$server.send: '/hello';

# Our routing will ignore this message:
$server.send: '/hello/not-really';

# Send a message to someone else?
$server.send: '/hello', :args('out there', ), :address<192.168.1.1>, :port(54321);

#Allow some time for our messages to arrive
sleep 0.5;

# Give our server a chance to say good bye if it needs too.
$server.close;

```

# DESCRIPTION

Net::OSC distribution currently provides the following classes:

* Net::OSC
* Net::OSC::Types
* Net::OSC::Message
* Net::OSC::Server
* Net::OSC::Server::UDP
* Net::OSC::Transport::TCP

Classes planned for future releases include:

* Net::OSC::Bundle
* Net::OSC::Server::TCP

Net::OSC imports Net::OSC::Server::UDP and the action sub to the using name space. Net::OSC::Message provide a representation for OSC messages.

See reference section below for usage details.

# TODO

* Net::OSC::Server::TCP
* Additional OSC types

# CHANGES

|  |  |  |
| --- | --- | --- |
| Added type wrappers, helper functions and blobs | Compliant with core OSC 1.0 type specifications | 2020-03-20 |
| Compatibility updates for Numeric::Pack:ver<0.3.0> | Better portabilty as we're now pure perl all the way down | 2018-06-20 |
| Removed vestiges of the pack feature | Net::OSC will not be effected by the experimental status of pack in Rakudo | 2018-06-19 |
| TCP packing contributed | OSC messages can be sent over TCP connections | 2017-07-23 |
| Added Server role and UDP server | Sugar for sending, receiving and routing messages | 2016-12-08 |
| Updated to use Numeric::Pack | Faster and better tested Buf packing | 2016-08-30 |

# AUTHOR

Sam Gillespie [samgwise@gmail.com](mailto:samgwise@gmail.com)

# CONTRIBUTORS

```
TCP transport module contributed by Karl Yerkes <karl.yerkes@gmail.com>.

```

# COPYRIGHT AND LICENSE

Copyright 2016 Sam Gillespie

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

# Reference

## Net::OSC subroutines

### multi sub action

```
multi sub action(
    Regex $path,
    Callable $call-back
) returns Net::OSC::Types::EXPORT::DEFAULT::ActionTuple

```

Creates an action tuple for use in a server's actions list. The first argument is the path, which is checked when an OSC message is received. If the path of the message matches then the call back is executed. The call back is passed the Net::OSC::Message object and the match object from the regular expression comparison.

### multi sub action

```
multi sub action(
    Str $path where { ... },
    Callable $call-back
) returns Net::OSC::Types::EXPORT::DEFAULT::ActionTuple

```

Creates an action tuple for use in a server's actions list. The string must be a valid OSC path (currently we only check for a beginning '/' character). In the future this subroutine may translate OSC path meta characters to Perl6 regular expressions.

# NAME

Net::OSC::Bundle - Implements OSC message bundling and unbundling

# METHODS

```
method new(:@messages, :$time-stamp)

```

### method package

```
method package() returns Blob

```

Packages up a bundle into a Blob, ready for transport over a binary protocol. The pacakge contains the time-stamp and all messages of the Bundle object.

### method unpackage

```
method unpackage(
    Blob:D $bundle
) returns Net::OSC::Bundle

```

Unapackages a Blob into a bundle object. The blob must begin with #bundle0x00 as defined by the OSC spec.

# NAME

Net::OSC::Message - Implements OSC message packing and unpacking

# METHODS

```
method new(:$path = '/', :@args, :$!is64bit = True)

```

Set :is64bit to false to force messages to be packed to 32bit types this option may be required to talk to some versions of Max and other old OSC implementations.

### sub osc-message

```
sub osc-message(
    *@args
) returns Net::OSC::Message

```

Function for creating a new OSC Message. The list of arguments is infered according to the 32bit type map, since it is the most widely accepted. To define specific types (such as Doubles and Longs) use OSCType wrappers from Net::OSC::Types.

### sub osc-decode

```
sub osc-decode(
    Blob:D $buffer
) returns Net::OSC::Message

```

Function for unpacking an OSC message. Accepts a defined buffer and returns an Net::OSC::Message. Decoding errors are thrown as exceptions.

### method type-string

```
method type-string() returns Str

```

Returns the current type string of this messages content. See OSC types for possible values.

### method pick-osc-type

```
method pick-osc-type(
    $arg
) returns Str

```

Returns the character representing the OSC type $arg would be packed as by this Message object. If the argument is held in a wrapper from Net::OSC::Types then the wrapper's type will be used. Otherwise the type picker will try and infer a type according to the 32bit or 64 bit type map.

### method args

```
method args(
    *@new-args
) returns Seq

```

Adds any arguments as args to the object and returns the current message arguments. The OSC type of the argument will be determined according the the current OSC types map.

### method set-args

```
method set-args(
    *@new-args
) returns Mu

```

Clears the message args lists and sets it to the arguments provided. The OSC type of the argument will be determined according the the current OSC types map.

### method type-map

```
method type-map() returns Seq

```

Returns the current OSC type map of the message. This will change depending on the is64bit flag.

### method package

```
method package() returns Blob

```

Returns a Buf of the packed OSC message. See unpackage to turn a Buf into a Message object.

### method unpackage

```
method unpackage(
    Buf $packed-osc
) returns Net::OSC::Message

```

Returns a Net::OSC::Message from a Buf where the content of the Buf is an OSC message. Will die on unhandled OSC type and behaviour is currently undefined on non OSC message Bufs.

# NAME

Net::OSC::Server - A role to facilitate a convenient platform for OSC communication.

# METHODS

```
method new(:$!is64bit = True)

```

Set :is64bit to false to force messages to be packed to 32bit types this option may be required to talk to some versions of Max and other old OSC implementations.

### method actions

```
method actions() returns Seq

```

Lists the actions managed by this server. Actions are expressed as a list holding a Regex and a Callable object. Upon receiving a message the server tries to match the path of the OSC message with the Regex of an action. All actions with a matching Regex will be executed. the Callable element of an action is called with a Net::OSC::Message and a Match object.

### method add-action

```
method add-action(
    Regex $path,
    Callable $action
) returns Mu

```

Add an action for managing messages to the server. See the actions method description above for details and the add-actions method below for the plural expression.

### method add-actions

```
method add-actions(
    *@actions
) returns Mu

```

Add multiple actions for managing messages to the server. See the actions method description above for details.

### method send

```
method send(
    Str $path where { ... },
    *%params
) returns Mu

```

Send and OSC message. The to add arguments to the message pass :args(...), after the OSC path string. Implementing classes of the Server role may accept additional named parameters.

### method close

```
method close() returns Mu

```

Call the server's on-close method. This will call the server implementations on-close hook.

### method transmit-message

```
method transmit-message(
    Net::OSC::Message:D $message
) returns Mu

```

Transmit an OSC message. This method must be implemented by consuming classes. implementations may add additional signatures. Use this method to send a specific OSC message object instead of send (which creates one for you).

# NAME

Net::OSC::Server::UDP - A convenient platform for OSC communication over UDP.

```
Does Net::OSC::Server - look there for additional methods.

```

# METHODS

```
method new(
  Bool :$!is64bit = True,
  Str :listening-address,
  Int :listening-port,
  Str :send-to-address,
  Int :send-to-port,
)

```

Set :is64bit to false to force messages to be packed to 32bit types this option may be required to talk to some versions of Max and other old OSC implementations. The send-to-\* parameters are not required but allow for convenient semantics if you are only communicating with a single host.

### method send

```
method send(
    Str $path where { ... },
    *%params
) returns Mu

```

Send a UDP message to a specific host and port. This method extends the Net::OSC::Server version and adds the :address and :port Named arguments to support UDP message sending. If :address or :port are not provided the Server's relevant send-to-\* attribute will be used instead.

### multi method transmit-message

```
multi method transmit-message(
    Net::OSC::Message:D $message
) returns Mu

```

Transmit an OSC message. This implementation will send the provided message to the server's send-to-\* attributes.

### multi method transmit-message

```
multi method transmit-message(
    Net::OSC::Message:D $message,
    Str $address,
    Int $port
) returns Mu

```

Transmit an OSC message to a specified host and port. This implementation sends the provided message to the specified address and port.

# Net::OSC::Transport::TCP

TCP transport routines for Net::OSC.

There are a variety of methods for transmitting OSC over TCP. This module provides routines sending your OSC messages with Length-prefixed message framing and SLIP message framing. See the individual subroutine descriptions for more details.

## subroutines

### sub send-lp

```
sub send-lp(
    IO::Socket::INET $socket,
    Net::OSC::Message $message
) returns Mu

```

Sends an OSC message with Length-prefixed framing. This is known to be used in SuperCollider.

### sub recv-lp

```
sub recv-lp(
    IO::Socket::INET $socket
) returns Net::OSC::Message

```

A subroutine for receiving Length-prefixed messages. This routine blocks until it has recieved a complete message.

### sub send-slip

```
sub send-slip(
    IO::Socket::INET $socket,
    Net::OSC::Message $message
) returns Mu

```

Sends an OSC message with SLIP framing. This is known to be used in PureData.

### sub recv-slip

```
sub recv-slip(
    IO::Socket::INET $socket
) returns Net::OSC::Message

```

A subroutine for receiving SLIP messages. This routine blocks until it has recieved a complete message.

# Net::OSC::Types

Provides helper classes and subsets for dealing with OSC communications.

Type wrappers are provided for OSC 1.0 standard types.

## class -> ;; $\_? is raw { #`(Block|149465208) ... }

Tag Str values as OSC type 's'. Can be created via the osc-str function.

### method type-code

```
method type-code() returns Str

```

Tag Blob values as OSC type 'b'. Can be created via the osc-blob function.

### method type-code

```
method type-code() returns Str

```

Tag Int values as OSC type 'i'. Can be created via the osc-int32 function.

### method type-code

```
method type-code() returns Str

```

Tag Int values as OSC type 'h'. Can be created via the osc-int64 function.

### method type-code

```
method type-code() returns Str

```

Tag Rat values as OSC type 'f'. Can be created via the osc-float function.

### method type-code

```
method type-code() returns Str

```

Tag Rat values as OSC type 'd'. Can be created via the osc-double function.


## -circumflex-accentfff-circumflex-accent.md
^fff^

Combined from primary sources listed below.

# [In Operators](#___top "go to top of document")[§](#(Operators)_infix_^fff^ "direct link")

See primary documentation
[in context](/language/operators#infix_^fff^)
for **infix ^fff^**.

```raku
sub infix:<^fff^>(Mu $a, Mu $b)
```

Like [fff](/routine/fff), except it does not return true for matches to either the left or right argument.

```raku
my @list = <X A B C Y>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^fff^ /C/ for @list; # OUTPUT: «B␤»
```

For the non-sed version, see [`^ff^`](/routine/$CIRCUMFLEX_ACCENTff$CIRCUMFLEX_ACCENT).

This operator cannot be overloaded, as it's handled specially by the compiler.


## malformed.md
class X::Syntax::Malformed

Compilation error due to a malformed construct (usually a declarator)

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

The Raku compiler throws errors of type `X::Syntax::Malformed` when it knows what kind of declaration it is parsing, and encounters a syntax error, but can't give a more specific error message.

```raku
my Int a;   # throws an X::Syntax::Malformed

```

produces

｢text｣ without highlighting

```

```

===SORRY!===
Malformed my
at -e:1
------> my Int ⏏a

```

```

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

## [method what](#class_X::Syntax::Malformed "go to top of document")[§](#method_what "direct link")

```raku
method what(X::Syntax::Malformed:D: --> Str)
```

Returns a description of the thing that was being parsed.


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

# NAME

RedFactory - A factory for testing code using Red

# SYNOPSIS

```
# Your DB schema ---------------------------------------------------------
use Red;

model Post {...}

model Person {
   has UInt    $.id          is serial;
   has Str     $.first-name  is column;
   has Str     $.last-name   is column;
   has Str     $.email       is column;
   has Instant $.disabled-at is column{ :nullable };
   has Post    @.posts       is relationship(*.author-id, :model(Post));
}

model Post {
    has UInt    $.id         is serial;
    has Str     $.title      is column;
    has Str     $.body       is column;
    has UInt    $!author-id  is referencing(*.id, :model(Person));
    has Person  $.author     is relationship(*.author-id, :model(Person));
    has Instant $.created-at is column = now;
}

# Your factory configuration ---------------------------------------------
use RedFactory;

factory "person", :model(Person), {

   .first-name = "john";
   .last-name  = "doe";
   .email      = -> $_, :$number = .counter-by-model {
     "{ .first-name }{ $number }@domain.com"
   }

   .posts      = -> :$num-of-posts = 0 {
     factory-args $num-of-posts, "post"
   }

   trait "disabled", {
      .disabled-at = now
   }
}

factory "post", :model(Post), {

    .title = {
        "Post title { .counter-by-model }"
    }
    .body  = -> $_, :$title-repetition = 3 {
        (.title ~ "\n") x $title-repetition
    }
}

# Testing your imaginary controller helper -------------------------------
use Test;

my $*RED-DB = factory-db;

my &get-recent-author's-posts'-titles =
    get-controller's-help("get-recent-author's-posts'-titles");

# Create the needed person with posts
my $author = factory-create "person", :PARS{ :10num-of-posts };

my @posts = get-recent-author's-posts'-titles $author.id, 3;

is-deeply @posts, ["Post title 10", "Post title 9", "Post title 8"];

```

# DESCRIPTION

RedFactory is a easier way of testing code that uses Red

# AUTHOR

```
<fernandocorrea@gmail.com>

```

# COPYRIGHT AND LICENSE

Copyright 2021

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


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

# NAME

HexDump::Tiny - Generate hexadecimal dump

# SYNOPSIS

```
use HexDump::Tiny;

.say for hexdump(slurp("filename"));

```

# DESCRIPTION

HexDump::Tiny is module that exports a single subroutine `hexdump`, and installs a command-line interface to that called `hd`.

# SUBROUTINES

## hexdump

```
.say for hexdump($blob);                         # entire blob

.say for hexdump($blob, :skip(96));              # bytes after first 96 bytes

.say for hexdump($blob, :head(96));              # first 96 bytes

.say for hexdump($blob, :skip(96), :head(256));  # after 96 bytes for 256 bytes

```

The `hexdump` subroutine takes a value of which to create a hexadecimal dump (either as a `Blob` or `Buf`, or as a `Seq` or as anything else that can be coerced to a `Str`).

It returns a `Seq` of hexdump lines. It takes the following optional named arguments:

### skip

The named argument `:skip` specifies the number of bytes to skip before starting to generate the hexdump. The default is **0**.

### head

The named argument `:head` specifies the number of bytes to create a hexdump for. The default is all remaining bytes after bytes skipped.

### chunk-size

The named argument `:chunk-size` specifies the number of bytes per line of hexdump. The default is **16**.

# COMMAND-LINE INTERFACE

This module also installs a `hd` command-line interface that allows one to do a hexdump of a file, or the parameters on the command line, or from STDIN (if no parameters are specified.

It also accepts the same named arguments as the `hexdump` subroutine does.

# AUTHORS

Jonathan Scott Duff

Elizabeth Mattijsen

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

# COPYRIGHT AND LICENSE

Copyright 2015 - 2017 Jonathan Scott Duff

Copyright 2018 - 2022 Raku Community

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


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

# NAME

MoarVM::Remote - A library for working with the MoarVM remote debugging API

# SYNOPSIS

```
# see examples in the test-suite for now

```

# DESCRIPTION

A Raku library to interface with MoarVM's remote debugger protocol.

It's mostly a thin layer above the wire format, [documented in the MoarVM repository](https://github.com/MoarVM/MoarVM/blob/master/docs/debug-server-protocol.md)

It exposes commands as methods, responses as Promises, and events/event streams as Supplies.

You can use the debug protocol with the Raku module/program [App::MoarVM::Debug](https://raku.land/github:edumentab/App::MoarVM::Debug). Another application that supports the debug protocol is [Comma](commaide.com).

# MESSAGE TYPES

All messages defined here, unless stated otherwise, are supported in major version 1, minor version 0, of the protocol (also known as `1.0`).

All message types (basically a numeric ID, also exported as the `MessageType` enum) are described from the viewpoint of the client. Messages sent to the debug server are documented as "request", and messages coming back from the debug server are documented as "response".

When the term "user threads" is used, it means all threads apart from the spesh worker thread and the debug server thread itself.

### Message Type Not Understood (0)

Response indicating that a request was **not** understood, with the ID of the request that was not understood.

```
{
  type => 0,            # MT_MessageTypeNotUnderstood
  id   => $given-request-id
}

```

### Error Processing Message (1)

Response indicating that a problem occurred with the processing of a request, with the ID of the request that was not understood. The `reason` key should be a string explaining why.

```
{
  type   => 1,          # MT_ErrorProcessingMessage
  id     => $given-request-id,
  reason => $reason     # e.g. "Program already terminated"
}

```

### Operation Successful (2)

Response to acknowledge that a request was successfully performed (with ID of the request) when there is no further information to be given.

```
{
  type => 2,            # MT_OperationSuccessful
  id   => $given-request-id
}

```

### Is Execution Suspended Request (3)

Request to check whether execution of all user threads are currently suspended.

```
{
  type => 3,            # MT_IsExecutionSuspendedRequest
  id   => $new-request-id
}

```

### Is Execution Suspended Response (4)

Response indicating whether all user threads have been suspended, as observed by the `suspended` key being set to either `True` or `False`.

```
{
  type      => 4,       # MT_IsExecutionSuspendedResponse
  id        => $given-request-id,
  suspended => $suspended
}

```

### Suspend All (5)

Request to indicate that all user threads should be suspended. Response will always be "Operation Successful" regardless of whether the user threads had been suspended already or not.

```
{
  type => 5,            # MT_SuspendAll
  id   => $new-request-id
}

```

### Resume All (6)

Request to indicate that execution of all suspended threads should be resumed. Response will always be "Operation Successful" message regardless of whether the execution of user threads had been resumed already or not.

```
{
  type => 6,            # MT_ResumeAll
  id   => $new-request-id
}

```

### Suspend One (7)

Request to indicate that execution of a specific thread should be suspended, with the thread ID specified by the `thread` key.

Response will always be "Operation Successful" regardless of whether the execution of the indicated thread had been suspended already or not. If the thread ID was not recognized, then the response will be "Error Processing Message".

```
{
  type   => 7,          # MT_SuspendOne
  id     => $new-request-id,
  thread => $thread-id
}

```

### Resume One (8)

Request to indicate that execution of a specific thread should be resumed, with the thread ID specified by the `thread` key.

Response will always be "Operation Successful" regardless of whether the execution of the indicated thread had been resumed already or not. If the thread ID was not recognized, then the response will be "Error Processing Message".

```
{
  type   => 8,          # MT_ResumeOne
  id     => $new-request-id,
  thread => $thread-id
}

```

### Thread Started (9)

Unsolicited response whenever a new thread is started. The client can simply disregard it if it has no interest in this information.

The `thread` key contains the numeric thread ID that can be used in requests.

The `native_id` key contains the numeric thread ID that the OS has assigned to the thread.

The `app_lifetime` key contains `True` or `False`. `False` means that the process will only terminate when the thread has finished while `True` means that the thread will be killed when the main thread of the process terminates.

```
{
  type         => 9,    # MT_ThreadStarted
  id           => $an-even-id,
  thread       => $thread-id,
  native_id    => $OS_thread_id,
  app_lifetime => $app_lifetime
}

```

### Thread Ended (10)

Unsolicited response whenever a thread terminates. The client can simply disregard it if it has no interest in this information.

```
{
  type   => 10,         # MT_ThreadEnded
  id     => $an-even-id,
  thread => $thread-id
}

```

### Thread List Request (11)

Request a list of all threads, with some information about each one. This request may be sent at any time, whether or not the threads are suspended.

```
{
  type => 11,           # MT_ThreadListRequest
  id   => $new-request-id
}

```

### Thread List Response (12)

Response to a "Thread List Request". It contains an array of hashes, with one hash per running thread, providing information about that thread. It also contains an indication of whether the thread was suspended, and the number of locks it is currently holding.

The `name` key was added in version 1.2.

```
{
  type => 12,           # MT_ThreadListResponse
  id   => $given-request-id,
  threads => [
    {
      thread       => $thread-id      # e.g. 1
      native_id    => $OS_thread_id,  # e.g. 1010
      app_lifetime => $app_lifetime,  # e.g. True
      suspended    => $suspended      # e.g. True
      num_locks    => $num_locks,     # e.g. 1
      name         => $name           # e.g. "AffinityWorker"
    },
    {
      thread       => $thread-id      # e.g. 3
      native_id    => $OS_thread_id,  # e.g. 1020
      app_lifetime => $app_lifetime,  # e.g. True
      suspended    => $suspended      # e.g. False
      num_locks    => $num_locks,     # e.g. 0
      name         => $name           # e.g. "Supervisor"
    }
  ]
}

```

### Thread Stack Trace Request (13)

Request the stack trace of a thread. This is only allowed if that thread is suspended; an "Error Processing Message" response will be returned otherwise.

```
{
  type   => 13,         # MT_ThreadStackTraceRequest
  id     => $new-request-id,
  thread => $thread_id  # e.g. 3
}

```

### Thread Stack Trace Response (14)

Response to a "Thread Stack Trace Request". It contains an array of hashes, each representing a stack frame (topmost first) that are currently on the call stack of that thread.

The `bytecode_file` key will be either a string or `nil` if the bytecode only exists "in memory" (for example, due to an `EVAL`).

The `name` key will be an empty string in the case that the code for that frame has no name.

The `type` key is the debug name of the type of the code object, or `Nil` if there is none.

```
{
  type   => 14,           # MT_ThreadStackTraceResponse
  id     => $given-request-id,
  frames => [
    {
      file          => $file,          # e.g. "path/to/source/file"
      line          => $line,          # e.g. 22
      bytecode_file => $bytecode_file, # e.g. "path/to/bytecode/file"
      name          => $name,          # e.g. "some-method"
      type          => $type           # e.g. "Method"
    },
    {
      file          => $file,          # e.g. "path/to/source/file"
      line          => $line,          # e.g. 12
      bytecode_file => $bytecode_file, # e.g. "path/to/bytecode/file"
      name          => $name,          # e.g. "",
      type          => $type           # e.g. "Block"
    },
    {
      file          => $file,          # e.g. "path/to/another/source/file"
      line          => $line,          # e.g. 123
      bytecode_file => $bytecode_file, # e.g. "path/to/another/bytecode/file"
      name          => $name,          # e.g. "foo"
      type          => $type           # e.g. Nil
    }
  ]
}

```

### Set Breakpoint Request (15)

Request to set a breakpoint at the specified location, or the closest possible location to it.

The `file` key refers to the source file.

If the `suspend` key is set to `True` then execution of all threads will be suspended when the breakpoint is hit. In either case, the client will be notified. The use of non-suspend breakpoints is for counting the number of times a certain point is reached.

If the `stacktrace` key is set to `true` then a stack trace of the location where the breakpoint was hit will be included. This can be used both with and without `suspend`; with the `suspend` key set to `True` it can save an extra round-trip to request the stack location, while with `suspend` key set to `False` it can be useful for features like "capture a stack trace every time foo is called".

```
{
  type       => 15,     # MT_SetBreakpointRequest
  id         => $new-request-id,
  file       => $file,       # e.g. "path/to/source/file"
  line       => $line,       # e.g. 123
  suspend    => $suspend,    # e.g. True
  stacktrace => $stacktrace  # e.g. False
}

```

### Set Breakpoint Confirmation (16)

Response to confirm that a breakpoint has been set.

The `line` key indicates the actual line that the breakpoint was placed on, if there was no exactly annotation match. This message will be sent before any breakpoint notifications; the ID will match the ID specified in the breakpoint request.

```
{
  type => 16,           # MT_SetBreakpointConfirmation
  id   => $given-request-id,
  line => $line  # e.g. 16
}

```

### Breakpoint Notification (17)

Unsolicited response whenever a breakpoint is reached. The ID will match that of the breakpoint request.

The `frames` key will be `Nil` if the `stacktrace` key of the breakpoint request was `False`. Otherwise, it will contain an array of hashesh describing the stack frames, formatted as in the "Thread Stack Trace Response" message type.

```
{
  type   => 17,         # MT_BreakpointNotification
  id     => $given-request-id,
  thread => $thread-id, # e.g. 1
  frames => $frames     # Nil or [ ... ]
}

```

### Clear Breakpoint (18)

Request to clear a breakpoint. The line number must be the one the breakpoint was really set on (indicated in the "Set Breakpoint Confirmation" message). This will be followed by an "Operation Successful" response after clearing the breakpoint.

```
{
  type => 18,           # MT_ClearBreakpoint
  id   => $new-request-id,
  file => $file,  # e.g. "path/to/source/file",
  line => $line   # e.g. 123
}

```

### Clear All Breakpoints (19)

Request to clear all breakpoints that have been set. This will be followed by an "Operation Successful" response after clearing all breakpoints.

```
{
  type => 19,           # MT_ClearAllBreakpoints
  id   => $new-request-id
}

```

### Single Step (aka. Step Into) (20)

Request to run a suspended thread until the next program point, where program points are determined by either a change of frame or a change of line number in the bytecode annotation table.

The thread this is invoked on must be suspended, and will be returned to suspended state after the step has taken place, followed by a "Step Completed" response.

```
{
  type   => 20,         # MT_StepInto
  id     => $new-request-id,
  thread => $thread-id  # e.g. 1
}

```

### Step Over (21)

Request to run a suspended thread until the next program point either in the same frame or in a calling frame (but not in any called frames below this point), to return to suspended state after the steps have taken place, followed by a "Step Completed" response.

```
{
  type   => 21,         # MT_StepOver
  id     => $new-request-id,
  thread => $thread-id  # e.g. 1
}

```

### Step Out (22)

Request to run a suspended thread until the program returns into the specified frame. After which the thread will be returned to suspended state, followed by a "Step Completed" response.

```
{
  type   => 22,         # MT_StepOut
  id     => $new-request-id,
  thread => $thread-id  # e.g. 1
}

```

### Step Completed (23)

Response to acknowledge that a stepping operation was completed.

The `id` key matches the ID that of the step request.

The `frames` key contains an array of hashes that contains the stacktrace after stepping; the `file` and `line` keys will be of the current location in the topmost frame.

```
{
  type   => 23,         # MT_StepCompleted
  id     => $given-request-id,
  thread => $thread-id, # e.g. 1
  frames => [
    ...
  ]
}

```

### Release Handles (24)

Handles are integers that are mapped to an object living inside of the VM. For so long as the handle is alive, the object will be kept alive by being in the handles mapping table.

Therefore, it is important that, when using any instructions that involve handles, they are released afterwards when they are not needed anymore. Otherwise the client can induce a managed memory leak.

The `handles` key should be specified with an array of integers matching the handles to be released.

Responds with an "Operation Successful" message if all specified handles were successfully released.

```
{
  type    => 24,        # MT_ReleaseHandles
  id      => $id,
  handles => @array     #  e.g. [42, 100]
}

```

### Handle Result (25)

Response for requests that ask for an object handle. The ID will match that of the request. The value `0` represents the `VMNull` value.

```
{
  type   => 25,         # MT_HandleResult
  id     => $given-request-id,
  handle => $integer    # e.g. 42
}

```

### Context Handle (26)

Request to allocate a context object handle for the specified frame (indicated by the depth relative to the topmost frame on the callstack, which is frame 0) and thread.

This can only be used on a thread that is suspended. A context handle is just an object handle, where the object happens to have the `MVMContext` REPR.

Followed by a "Handle Result" response.

```
{
  type   => 26,         # MT_ContextHandle
  id     => $new-request-id,
  thread => $thread-id    # e.g. 1
  frame  => $frame-index  # e.g. 0
}

```

### Context Lexicals Request (27)

Request the values of lexicals in a given context, followed by a "Context Lexicals" response.

The `handle` key must be a context handle.

```
{
  type   => 27,         # MT_ContextLexicalsRequest
  id     => $new-request-id,
  handle => $handle-id  # e.g. 1234
}

```

### Context Lexicals Response (28)

Response containing the results of introspecting a context. The `lexicals` key contains a hash of hashes, in which the inner hash has information about the lexicals in that context, with the name of the lexical as the key.

For natively typed values, the value is included directly in the response.

For object lexicals, a new object handle will be allocated for each object encountered. This will allow for further introspection of the object (always make sure to release the associated handles if the object is no longer needed).

The debug name of the type is directly included in the `type` key, along with whether it's concrete (as opposed to a type object) and a container type that could be decontainerized.

The `kind` key may be one of "int", "num", or "str" (for native values) or "obj" for objects.

```
{
  type     => 28,       # MT_ContextLexicalsResponse
  id       => $given-request-id,
  lexicals => {
    '$x' => {
      kind      => "obj",
      handle    => $handle,    # e.g. 1234
      type      => $type,      # e.g. "Scalar"
      concrete  => $concrete,  # True or False
      container => $container  # True or False
    },
    '$i' => {
      kind  => "int",
      value => 42
    },
    '$s' => {
      kind  => "str",
      value => "Bibimbap"
    }
  }
}

```

### Outer Context Request (29)

Request a handle to the outer context of the context for which the handle is being passed, followed by a "Handle Result" response.

The null handle (`0`) will be given if there is no outer context.

```
{
  type   => 29,         # MT_OuterContextRequest
  id     => $new-request-id,
  handle => $handle     # e.g. 1234
}

```

### Caller Context Request (30)

Request to create a handle for the caller context of the context of which the handle is being passed, followed by a "Handle Result" response.

The null handle (`0`) will be given if there is no outer caller.

```
{
  type   => 30,         # MT_CallerContextRequest
  id     => $new-request-id,
  handle => $handle     # e.g. 1234
}

```

### Code Object Handle (31)

Request a handle for the code object of the specified frame (indicated by the depth relative to the topmost frame on the callstack, which is frame 0) and thread ID, followed by a "Handle Result" response.

This can only be used on a thread that is suspended.

If there is no high-level code object associated with the frame, then the null handle (`0`) will be given.

```
{
  type   => 31,         # MT_CodeObjectHandle
  id     => $new-request-id,
  thread => $thread-id,   # e.g. 1
  frame  => $frame-index  # e.g. 0
}

```

### Object Attributes Request (32)

Request information about the attributes of an object by its given handle, followed by an "Object Attributes" response.

```
{
  type   => 32,         # MT_ObjectAttributesRequest
  id     => $new-request-id,
  handle => $handle     # e.g. 1234
}

```

### Object Attributes Response (33)

Response containing the information about the attributes of an object (specified by its handle in a "Object Attributes" request).

The `attributes` key contains a list of hashes with the attribute information. If the object does not have any attributes, then the `attributes` key will be an empty array.

For natively typed attributes, the value is included directly in the response. For object attributes, an object handle will be allocated for each one. This will allow for further introspection of the object.

The debug name of the type is directly included, along with whether it's concrete (as opposed to a type object) and a container type that could be decontainerized.

The key may be one of "int", "num", or "str" for native values, or "obj" for objest. Since attributes with the same name may exist at multiple inheritance levels, an array is returned with the debug name of the class at that level with the `class` key.

```
{
  type       => 33,     # MT_ObjectAttributesResponse
  id         => $given-request-id,
  attributes => [
    {
      name      => '$!x',
      class     => $class,     # e.g. "FooBase"
      kind      => "obj",
      handle    => $handle,    # e.g. 1235
      type      => $type,      # e.g. "Scalar"
      concrete  => $concrete,  # True or False
      container => $container  # True or False
    },
    {
      name  => '$!i',
      class => $class,  # e.g. "Foo"
      kind  => "int",
      value => 42
    }
  ]
}

```

### Decontainerize Handle (34)

Request a handle for the decontainerized object indicated by its handle, followed by a "Handle Result" response.

Respond with an "Error Processing" response if the indicated object is not a container type, or if an exception occurred when trying to do the decontainerization.

A target thread to perform this operation on is required, since it may be required to run code (such as code inside a `Proxy` container). The thread must be suspended at the point the request made, and will be returned to suspended state again after the decontainerization has taken place and a new handle was created.

Note that breakpoints may be hit and will be fired during this operation.

```
{
  type   => 34,         # MT_DecontainerizeHandle
  id     => $new-request-id,
  thread => $thread-id, # e.g. 1
  handle => $handle     # e.g. 1234
}

```

### Invoke (36)

Request invocation of a code object (as indicated by its handle), followed by an "Invoke Result" response.

The `arguments` key should contain a (possibly empty) array of hashes, one for each argument.

Arguments may be native values or other objects specified by their `handle`. Named arguments require a `name` key with the name of the named argument.

A target thread to perform this operation on is required. The thread must be suspended at the point this request is made, and will be returned to suspended state again after the execution has taken place.

Note that breakpoints may be hit and will be fired during this operation.

```
{
  type      => 36,      # MT_Invoke
  id        => $new-request-id,
  thread    => $thread-id,   # e.g. 1
  handle    => $code-hande,  # e.g. 1235,
  arguments => [
    {
      kind   => "obj",
      handle => $handle  # e.g. 1234
    },
    {
      kind  => "str",
      name  => "frobnicate",
      value => "Bulgogi"
    }
  ]
}

```

### Invoke Result (37)

Response to an "Invoke" request with the result in the `result` key.

If the result was not a native value, then a handle to the object will be created and returned in the `handle` key.

If the invocation resulted in an exception, then the `crashed` key will be set to a true value: the `result` key will then be about the `Exception` object instead.

Object result example:

```
{
  type      => 37,      # MT_InvokeResult
  id        => $given-request-id,
  crashed   => False,
  kind      => "obj",
  handle    => $handle,    # e.g. 1256
  obj_type  => $obj_type,  # e.g. "Int",
  concrete  => $concrete,  # True or False
  container => $container  # True or False
}

```

Native int result example:

```
{
  type    => 37,        # MT_InvokeResult
  id      => $given-request-id,
  crashed => False,
  kind    => "int",
  value   => 42
}

```

Exception result:

```
{
  type      => 37,      # MT_InvokeResult
  id        => $given-request-id,
  crashed   => True,
  kind      => "obj",
  handle    => $handle,    # e.g. 1256
  obj_type  => "X::AdHoc",
  concrete  => True,
  container => False
}

```

### Unhandled Exception (38)

Unsollicited response when an unhandled exception occurs.

All threads will be suspended. A handle to the exception object is included in the `handle` key, together with the thread ID it occurred on and the stack trace of that thread.

The `frames` key contains an array of hashes with information of each frame, similar to the "Stack Trace" response.

The VM is expected toi still allow operations such as introspecting the context, decontainerizing values, and invoking code.

```
{
  type   => 38,         # MT_UnhandledException
  id     => $given-request-id,
  thread => $thread-id, # e.g. 1
  handle => $handle,    # 1278,
  frames => [
    {
      file          => "path/to/source/file",
      line          => 22,
      bytecode_file => "path/to/bytecode/file",
      name => "some-method",
      type => "Method"
    },
    {
      file          => "path/to/source/file",
      line          => 12,
      bytecode_file => "path/to/bytecode/file",
      name          => "",
      type          => "Block"
    }
  ]
}

```

### Object Metadata Request (40)

Request additional (meta-)information about an object (by its handle) that goes beyond its actual attributes, followed by a "Object Metadata" response.

Can include miscellaneous details from the REPRData and the object's internal state if it's concrete.

Additionally, all objects that have positional, associative, or attribute features will point that out in their response.

```
{
  type   => 40,         # MT_ObjectMetadataRequest
  id     => $new-request-id,
  handle => $handle     # e.g 1345
}

```

### Object Metadata Response (41)

Response to an "Object Metadata" request, with the results in the `metadata` key (which contains a hash).

The `reprname` key contains name of the REPR.

All concrete objects have `size` and `unmanaged_size` keys (in bytes).

The `positional_elems` and `associative_elems` keys contain the number of elements for objects that have `Positional` and/or associative features.

The `pos_features`, `ass_features`, and `attr_features` keys indicate which of the "Object Positionals Request (42)", "Object Associatives Request (44)"), or "Object Attributes Request (32)" will give useful results.

```
{
  type     => 41,       # MT_ObjectMetadataResponse
  id       => $given-request-id,
  metadata => {
    reprname       => "VMArray",
    size           => 128,
    unmanaged_size => 1024,

    vmarray_slot_type => "num32",
    vmarray_elem_size => 4,
    vmarray_allocated => 128,
    vmarray_start     => 40,

    positional_elems => 12,

    pos_features  => $pos_features,  # True or False
    ass_features  => $ass_features,  # True or False
    attr_features => $attr_features  # True or False
  }
}

```

### Object Positionals Request (42)

Request to obtain information about a `Positional` object (such as an array) indicated by its handle, followed by an "Object Positionals" response.

```
{
  type   => 42,         # MT_ObjectPositionalsRequest
  id     => $new-request-id,
  handle => $handle     # e.g. 12345
}

```

### Object Positionals Response (43)

Response to an "Object Positionals" request, with the `contents` key containing a list of native values, or a list of hashes.

The `kind` key contains "int", "num", "str" for native arrays, or "obj" for object arrays.

In the case of an object array, every hash contains `type`, `handle`, `concrete`, and `container` keys, just as in the "Context Lexicals" response.

Native contents:

```
{
  type     => 43,       # MT_ObjectPositionalsResponse
  id       => $given-request-id,
  kind     => "int",
  start    => 0,
  contents => [
    1, 2, 3, 4, 5, 6
  ]
}

```

Object contents:

```
{
  type     => 43,       # MT_ObjectPositionalsResponse
  id       => $id,
  kind     => "obj",
  start    => 0,
  contents => [
    {
      type      => "Potato",
      handle    => $handle,  # e.g. 9999
      concrete  => True,
      container => False
    },
    {
      type      => "Noodles",
      handle    => $handle,  # e.g. 10000
      concrete  => False,
      container => False
    }
  ]
}

```

### Object Associatives Request (44)

Request to obtain information about a `Associative` object (such as a hash) indicated by its handle, followed by an "Object Associatives" response.

```
{
  type   => 44,         # MT_ObjectAssociativesRequest
  id     => $new-request-id,
  handle => $handle  # e.g. 12376
}

```

### Object Associatives Response (45)

Response to an "Object Associatives" request, with the `contents` key containing a hash of hashes always containing information about objects (so no native values).

The key is the key as used in the `Associative` object, and the value contains `type`, `handle`, `concrete`, and `container` keys, just as in the "Context Lexicals" response.

```
{
  type     => 45,       # MT_ObjectAssociativesResponse
  id       => $given-request-id,
  kind     => "obj"
  contents => {
    "Hello" => {
      type      => "Poodle",
      handle    => $handle,    # e.g. 4242
      concrete  => $concrete,  # True or False
      container => $container  # True or False
    },
    "Goodbye" => {
      type      => "Poodle",
      handle    => $handle,    # e.g. 4243
      concrete  => $concrete,  # True or False
      container => $container  # True or False
    }
  }
}

```

### Handle Equivalence Request (46)

Request to check a given list of handles (in the `handles` key) to see whether they refer to the same object, followed by a "Handle Equivalence" response.

```
{
  type    => 46,        # MT_HandleEquivalenceRequest
  id      => $new-request-id,
  handles => @handles
}

```

### Handle Equivalence Response (47)

Response to a "Handle Equivalence" request.

The `classes` key contains a list of lists with handles, in which each inner list contains the ID's of handles that refer to the same object (if there are more than one).

```
{
  type    => 47,        # MT_HandleEquivalenceResponse
  id      => $given-request-id,
  classes => [
    [1, 3],
    [2, 5, 7]
  ]
}

```

### HLL Symbol Request (48)

MoarVM features a mechanism for objects and types to be registered with an HLL, for example "nqp" or "Raku". This request allows you to find the available HLLs, a given HLL's keys, and the value for a given key.

Get all HLL names, followed by a "HLL Symbol" response:

```
{
  type => 48,           # MT_HLLSymbolRequest
  id   => $new-request-id,
}

```

Get an HLL's symbol names, followed by a "HLL Symbol" response:

```
{
  type => 48,           # MT_HLLSymbolRequest
  id   => $new-request-id,
  HLL  => $HLL          # e.g. "nqp" or "Raku"
}

```

Get the value for a symbol in a HLL, followed by a "Handle Result" response:

```
{
  type => 48,           # MT_HLLSymbolRequest
  id   => $new-request-id,
  HLL  => $HLL          # e.g. "nqp" or "Raku"
  name => "FOOBAR"
}

```

### HLL Symbol Response (49)

Response to a "HLL Symbol" request for names (rather than values).

The `keys` key contains either a list of HLL names, or a list of names for a given HLL.

```
{
  type => 49,
  id   => $given-request-id,
  keys => [
    "one",
    "two",
  ]
}

```

# MoarVM Remote Debug Protocol Design

The MoarVM Remote Debug Protocol is used to control a MoarVM instance over a socket, for the purposes of debugging. The VM must have been started in debug mode for this capability to be available (with the `--debug-port=12345` parameter).

## The wire format

Rather than invent Yet Another Custom Binary Protocol, the MoarVM remote debug protocol uses [`MessagePack`](https://msgpack.org/) (through the [`Data::MessagePack`](https://raku.land/zef:raku-community-modules/Data::MessagePack) module). This has the advantage of easy future extensibility and existing support from other languages.

The only thing that is not MessagePack is the initial handshake, leaving the freedom to move away from MessagePack in a future version, should there ever be cause to do so.

Since MessagePack is largely just a more compact way to specify JSON, which is essentially a Raku data structure consisting of a hash with keys and values. Therefore all of the messages are show in Raku syntax. This is just for ease of reading: the Raku data structure will be automatically converted to/from MessagePack data on the wire.

### Initial Handshake

Upon receving a connection, MoarVM will immediately send the following **24** bytes if it is willing and able to accept the connection:

* The string "MOARVM-REMOTE-DEBUG\0" encoded in ASCII
* A big endian, unsigned, 16-bit major protocol version number - =item big endian, unsigned, 16-bit minor protocol version number

Otherwise, it will send the following response, explaining why it cannot, and then close the connection:

* The string "MOARVM-REMOTE-DEBUG!"


## dist_zef-raku-community-modules-MoarVM-Remote.md
## Chunk 2 of 2
 encoded in ASCII
* A big endian, unsigned, 16-bit length for an error string explaining the rejection (length in bytes)
* The error string, encoded in UTF-8

A client that receives anything other than a response of this form must close the connection and report an error. A client that receives an error response must report the error.

Otherwise, the client should check if it is able to support the version of the protocol that the server speaks. The onus is on clients to support multiple versions of the protocol should the need arise. See versioning below for more. If the client does not wish to proceed, it should simply close the connection.

If the client is statisfied with the version, it should send:

* The string "MOARVM-REMOTE-CLIENT-OK\0" encoded in ASCII

For the versions of the protocol defined in this document, all further communication will be in terms of MessagePack messages.

## MessagePack envelope

Every exchange using MessagePack must be an object at the top level. The object must always have the following keys:

* `type` which must have an integer value. This specifies the type of the message. Failing to include this field or failing to have its value be an integer is a protocol error, and any side receiving such a message should terminate the connection.
* `id` which must have an integer value. This is used to associate a response with a request, where required. Any interaction initiated by the client should have an odd `id`, starting from 1. Any interaction initiated by the server should have an even `id`, starting from 2.

The object may contain further keys, which will be determined by message type.

## Versioning

Backwards-incompatible changes, if needed, will be made by incrementing the major version number. A client seeing a major version number it does not recognize or support must close the connection and not attempt any further interaction, and report an error.

The minor version number is incremented for backwards-compatible changes. A client may proceed safely with a higher minor version number of the protocol than it knows about. However, it should be prepared to accept and disregard message types that it does not recognize, as well as any keys in an object (encoded using MessagePack) that it does not recognize.

The client can use the minor version number to understand what features are supported by the remote MoarVM instance.

The MoarVM instance must disregard keys in a MessagePack object that it does not understand. For message types that it does not recognize, it must send a message of type "Message Type Not Understood" (format defined below); the connection should be left intact by MoarVM, and the client can decide how to proceed.

## Security considerations

Any client connected to the debug protocol will be able to perform remote code execution using the running MoarVM instance. Therefore, MoarVM must only bind to `localhost` by default. It may expose an option to bind to further interfaces, but should display a warning about the dangers of this option.

Remote debugging should be performed by establishing a secure tunnel from the client to the server, for example using SSH port forwarding. This provides both authentication and protection against tampering with messages.

# AUTHOR

* Timo Paulssen - Raku Community

# COPYRIGHT AND LICENSE

Copyright 2011 - 2020 Timo Paulssen

Copyright 2021 - 2024 Raku Community

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


## dist_zef-jjatria-App-Lorea.md
# lorea

A command line utility to execute commands on filesystem changes.

The interface should be fairly familiar for users of [reflex](https://github.com/cespare/reflex). See
[the examples section](#examples) below for some possible ways to use it.

## Installation

```
$ zef install App::Lorea

```

## Usage

```
lorea [options] -- command [args]

```

## Options

```
    --all                    Include all normally ignored files
-c, --config     STRING      The path to a configuration file
    --help                   Display usage information
-R, --ignore     REGEX ...   A regular expression to ignore filenames
-r, --regex      REGEX ...   A regular expression to match filenames
-e, --sequential             Run commands sequentially from config file
-s, --start-service          Run command as a service
    --substitute STRING      Set the string to be used as placeholder
-v, --verbose                Print tracing information
    --version                Print the version of the command and compiler

```

Options marked with `...` can be provided multiple times.

Values marked as `REGEX` must be compilable as Raku [regular expressions](https://docs.raku.org/language/regexes).

## Overview

When `lorea` is run, it will monitor your current directory, and any
directories under it, for any file-system changes. When a file is changed
or added, it will be matched against the patterns you've specified (see
[below](#matching) for details about how the matching is done).

If the event matches, the command you've specified will be run, or
restarted if you enabled the `--start-service` flag.

If the command you've specified includes the `{}` string, this will be
replaced by the absolute path of the file that has changed. All instances
of this placeholder string will be replaced. If you need to use the `{}`
string for something else, you can specify a different placeholder string
with the `--substitute` option.

### Matching

Patterns to match can be specified to `lorea` with either `--regex` or
`--ignore`. Both of these options take Raku regular expressions, with the
difference that any match for the former will trigger an event, while every
match for the latter will explicitly *not* trigger one.

Paths are normalised before being matched, and converted to paths relative
to the current directory without a leading `./`. Matching directories will
have a trailing slash (`/`).

If no pattern is specified, all file-system changes will match.

### Default ignores

By default, `lorea` ignores some common patterns to make it easier to use
in most cases.

* Files and directories with a leading dot (`.`), which are considered
  hidden in Unix-like systems.
* Common swap files, including those ending in `.swp`, `.swx`, and `~`.

The `--all` option disables these defaults. This flag will take effect if
set either at the top level, or in any of the watchers specified in the
configuration file (see below).

You can see the global ignores by setting the `--verbose` option.

## Configuration

The `--config` option can be used to specify a configuration to use to start
several watchers at the same time. The behaviour of these watchers can be
set independently.

The format of this file is intentionally very limited. A valid file will look
something like this:

```
# Rebuild SCSS when it changes
-r '\.scss$' -- \
   sh -c 'sass {} `basename {} .scss`.css'

# Restart server when ruby code changes
-s -r '\.rb$' -- \
    ./bin/run_server.sh

```

Each line will be interpreted as the parameters to a separate invocation of
`lorea`. Lines must not include the executable name (that will be filled in
internally). The parameters to a single invocation can be broken into multiple
lines if they end with a trailing backslash (`\`).

Empty lines, and lines beginning with a hash (`#`) will be ignored.

With the exception of `--help` , `--sequential`, and `--config` itself, all
options are valid within a configuration file. If the `--config` option is
set, the only other flags that are allowed at the top level are `--verbose`
and `--sequential`.

### Sequential execution

When using a config file to run multiple simultaneous commands, each of them
will be started asynchronously whenever possible. This means that, while there
will only be one instance of a particular command, two different commands may
overlap. This is usually what you want.

As a concrete example, consider this config file:

```
-- sh -c 'for i in `seq 1 5`; do sleep 0.1; echo first; done'
-- sh -c 'for i in `seq 1 5`; do sleep 0.1; echo second; done'

```

When this runs, you might see something like this:

```
second
first
second
first
first
second
second
first
second
first

```

Note that, since both commands started at the same time, the output of both is
interleaved. If this is not what you want, you can ensure only one command runs
at a time with the `--sequential` flag used at the top-level (it is not allowed
in config files). In this case, the output might instead look like this:

```
second
second
second
second
second
first
first
first
first
first

```

Note in this case that even when using `--sequential` there is no guarantee
that the commands will be executed in the order they appear in the config
file.

## Batching

Part of what `lorea` does is apply some heuristics to batch together file
changes. There are many reasons that files change on disk, and these changes
frequently come in large bursts. For instance, when you save a file in your
editor, it probably makes a tempfile and then copies it over the target,
leading to several different changes. A more dramatic example will happen
when you do a source-control checkout, in which case there is no limit to
the number of files that might change at once.

If `lorea` did not batch these changes, this could lead to your computer
slowing down to a crawl, or the whole process crashing.

There are two modes to batch these changes.

If your command is marked as a service, or has no placeholders in it, then
`lorea` assumes that individual changes are not as important as the fact that
*a change took place*. In this case changes will be collected, and a single
command execution will trigger once a short amount of time has passed
between them.

Otherwise, changes will be collected using the same logic as above, but
*every unique file change* will trigger a separate execution of your command.

## Examples

Every time a `.raku` or `.rakumod` file changes, print a string with the
name of the modified file:

```
lorea --regex '\.raku(mod)?$' -- echo "Change in {}"

```

or the same thing, but taking advantage of Raku's [regular expressions](https://docs.raku.org/language/regexes):

```
lorea --regex '".raku" [mod]? $' -- echo "Change in {}"

```

# See Also

* [Overwatch](https://raku.land/zef:tony-o/Overwatch)

  A similar program with a longer history, this was unknown to me when
  development in App::Lorea started. It has fewer dependencies but supports
  a simpler feature set.


## promise.md
class Promise

Status/result of an asynchronous computation

```raku
my enum PromiseStatus (:Planned(0), :Kept(1), :Broken(2));
class Promise {}
```

A `Promise` is used to handle the result of a computation that might not have finished. It allows the user to execute code once the computation is done (with the `then` method), execution after a time delay (with `in`), combining promises, and waiting for results.

```raku
my $p = Promise.start({ sleep 2; 42});
$p.then({ say .result });   # will print 42 once the block finished
say $p.status;              # OUTPUT: «Planned␤»
$p.result;                  # waits for the computation to finish
say $p.status;              # OUTPUT: «Kept␤»
```

There are two typical scenarios for using promises. The first is to use a factory method (`start`, `in`, `at`, `anyof`, `allof`, `kept`, `broken`) on the type object; those will make sure that the promise is automatically kept or broken for you, and you can't call `break` or `keep` on these promises yourself.

The second is to create your promises yourself with `Promise.new`. If you want to ensure that only your code can keep or break the promise, you can use the `vow` method to get a unique handle, and call `keep` or `break` on it:

```raku
sub async-get-with-promise($user-agent, $url) {
    my $p = Promise.new;
    my $v = $p.vow;

    # do an asynchronous call on a fictive user agent,
    # and return the promise:
    $user-agent.async-get($url,
            on-error => -> $error {
                $v.break($error);
            },
            on-success => -> $response {
                $v.keep($response);
            }
    );
    return $p;
}

```

Further examples can be found in the [concurrency page](/language/concurrency#Promises).

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

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

```raku
method start(Promise:U: &code, :$scheduler = $*SCHEDULER --> Promise:D)
```

Creates a new Promise that runs the given code object. The promise will be kept when the code terminates normally, or broken if it throws an exception. The return value or exception can be inspected with the `result` method.

The scheduler that handles this promise can be passed as a named argument.

There is also a statement prefix `start` that provides syntactic sugar for this method:

```raku
# these two are equivalent:
my $p1 = Promise.start({ ;#`( do something here ) });
my $p2 = start { ;#`( do something here ) };
```

As of the 6.d version of the language, `start` statement prefix used in [sink](/routine/sink) context will automatically attach an exceptions handler. If an exception occurs in the given code, it will be printed and the program will then exit, like if it were thrown without any `start` statement prefixes involved.

```raku
use v6.c;
start { die }; sleep ⅓; say "hello"; # OUTPUT: «hello␤»

```

```raku
use v6.d;
start { die }; sleep ⅓; say "hello";
# OUTPUT:
# Unhandled exception in code scheduled on thread 4
# Died
#     in block  at -e line 1

```

If you wish to avoid this behavior, use `start` in non-sink context or catch the exception yourself:

```raku
# Don't sink it:
my $ = start { die }; sleep ⅓; say "hello"; # OUTPUT: «hello␤»

# Catch yourself:
start { die; CATCH { default { say "caught" } } };
sleep ⅓;
say "hello";
# OUTPUT: «caught␤hello␤»

```

This behavior exists only syntactically, by using an alternate `.sink` method for `Promise` objects created by `start` blocks in sink context, thus simply sinking a `Promise` object that was created by other means won't trigger this behavior.

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

```raku
method in(Promise:U: $seconds, :$scheduler = $*SCHEDULER --> Promise:D)
```

Creates a new Promise that will be kept in `$seconds` seconds, or later.

```raku
my $proc = Proc::Async.new('raku', '-e', 'sleep 10; warn "end"');

my $result = await Promise.anyof(
    my $promise = $proc.start,  # may or may not work in time
    Promise.in(5).then: {       # fires after 5 seconds no matter what
        unless $promise {       # don't do anything if we were successful
            note 'timeout';
            $proc.kill;
        }
    }
).then: { $promise.result }
# OUTPUT: «timeout␤»
```

`$seconds` can be fractional or negative. Negative values are treated as `0` (i.e. [keeping](/routine/keep) the returned `Promise` right away).

Please note that situations like these are often more clearly handled with a [react and whenever block](/language/concurrency#react).

## [method at](#class_Promise "go to top of document")[§](#method_at "direct link")

```raku
method at(Promise:U: $at, :$scheduler = $*SCHEDULER --> Promise:D)
```

Creates a new `Promise` that will be kept `$at` the given time—which is given as an [`Instant`](/type/Instant) or equivalent [`Numeric`](/type/Numeric)—or as soon as possible after it.

```raku
my $p = Promise.at(now + 2).then({ say "2 seconds later" });
# do other stuff here

await $p;   # wait here until the 2 seconds are over
```

If the given time is in the past, it will be treated as [now](/routine/now) (i.e. [keeping](/routine/keep) the returned `Promise` right away).

Please note that situations like these are often more clearly handled with a [react and whenever block](/language/concurrency#react).

## [method kept](#class_Promise "go to top of document")[§](#method_kept "direct link")

```raku
multi method kept(Promise:U: \result = True --> Promise:D)
```

Returns a new promise that is already kept, either with the given value, or with the default value `True`.

## [method broken](#class_Promise "go to top of document")[§](#method_broken "direct link")

```raku
multi method broken(Promise:U: --> Promise:D)
multi method broken(Promise:U: \exception --> Promise:D)
```

Returns a new promise that is already broken, either with the given value, or with the default value `X::AdHoc.new(payload => "Died")`

## [method allof](#class_Promise "go to top of document")[§](#method_allof "direct link")

```raku
method allof(Promise:U: *@promises --> Promise:D)
```

Returns a new promise that will be kept when all the promises passed as arguments are kept or broken. The result of the individual Promises is not reflected in the result of the returned promise: it simply indicates that all the promises have been completed in some way. If the results of the individual promises are important then they should be inspected after the `allof` promise is kept.

In the following requesting the `result` of a broken promise will cause the original Exception to be thrown. (You may need to run it several times to see the exception.)

```raku
my @promises;
for 1..5 -> $t {
    push @promises, start {
        sleep $t;
    };
}
my $all-done = Promise.allof(@promises);
await $all-done;
@promises>>.result;
say "Promises kept so we get to live another day!";
```

## [method anyof](#class_Promise "go to top of document")[§](#method_anyof "direct link")

```raku
method anyof(Promise:U: *@promises --> Promise:D)
```

Returns a new promise that will be kept as soon as any of the promises passed as arguments is kept or broken. The result of the completed Promise is not reflected in the result of the returned promise which will always be Kept.

You can use this to wait at most a number of seconds for a promise:

```raku
my $timeout = 5;
await Promise.anyof(
    Promise.in($timeout),
    start {
        # do a potentially long-running calculation here
    },
);
```

## [method then](#class_Promise "go to top of document")[§](#method_then "direct link")

```raku
method then(Promise:D: &code)
```

Schedules a piece of code to be run after the invocant has been kept or broken, and returns a new promise for this computation. In other words, creates a chained promise. The `Promise` is passed as an argument to the `&code`.

```raku
# Use code only
my $timer = Promise.in(2);
my $after = $timer.then({ say '2 seconds are over!'; 'result' });
say $after.result;
# OUTPUT: «2 seconds are over␤result␤»

# Interact with original Promise
my $after = Promise.in(2).then(-> $p { say $p.status; say '2 seconds are over!'; 'result' });
say $after.result;
# OUTPUT: «Kept␤2 seconds are over␤result␤»
```

## [method keep](#class_Promise "go to top of document")[§](#method_keep "direct link")

```raku
multi method keep(Promise:D: \result = True)
```

Keeps a promise, optionally setting the result. If no result is passed, the result will be `True`.

Throws an exception of type [`X::Promise::Vowed`](/type/X/Promise/Vowed) if a vow has already been taken. See method `vow` for more information.

```raku
my $p = Promise.new;

if Bool.pick {
    $p.keep;
}
else {
     $p.break;
}
```

## [method break](#class_Promise "go to top of document")[§](#method_break "direct link")

```raku
multi method break(Promise:D: \cause = False)
```

Breaks a promise, optionally setting the cause. If no cause is passed, the cause will be `False`.

Throws an exception of type [`X::Promise::Vowed`](/type/X/Promise/Vowed) if a vow has already been taken. See method `vow` for more information.

```raku
my $p = Promise.new;

$p.break('sorry');
say $p.status;          # OUTPUT: «Broken␤»
say $p.cause;           # OUTPUT: «sorry␤»
```

## [method result](#class_Promise "go to top of document")[§](#method_result "direct link")

```raku
method result(Promise:D:)
```

Waits for the promise to be kept or broken. If it is kept, returns the result; otherwise throws the result as an exception.

## [method cause](#class_Promise "go to top of document")[§](#method_cause "direct link")

```raku
method cause(Promise:D:)
```

If the promise was broken, returns the result (or exception). Otherwise, throws an exception of type [`X::Promise::CauseOnlyValidOnBroken`](/type/X/Promise/CauseOnlyValidOnBroken).

## [method Bool](#class_Promise "go to top of document")[§](#method_Bool "direct link")

```raku
multi method Bool(Promise:D:)
```

Returns `True` for a kept or broken promise, and `False` for one in state `Planned`.

## [method status](#class_Promise "go to top of document")[§](#method_status "direct link")

```raku
method status(Promise:D --> PromiseStatus)
```

Returns the current state of the promise: `Kept`, `Broken` or `Planned`:

```raku
say "promise got Kept" if $promise.status ~~ Kept;

```

## [method scheduler](#class_Promise "go to top of document")[§](#method_scheduler "direct link")

```raku
method scheduler(Promise:D:)
```

Returns the scheduler that manages the promise.

## [method vow](#class_Promise "go to top of document")[§](#method_vow "direct link")

```raku
my class Vow {
    has Promise $.promise;
    method keep() { ... }
    method break() { ... }
}
method vow(Promise:D: --> Vow:D)

```

Returns an object that holds the sole authority over keeping or breaking a promise. Calling `keep` or `break` on a promise that has vow taken throws an exception of type [`X::Promise::Vowed`](/type/X/Promise/Vowed).

```raku
my $p   = Promise.new;
my $vow = $p.vow;
$vow.keep($p);
say $p.status;          # OUTPUT: «Kept␤»
```

## [method Supply](#class_Promise "go to top of document")[§](#method_Supply "direct link")

```raku
method Supply(Promise:D:)
```

Returns a [`Supply`](/type/Supply) that will emit the `result` of the `Promise` being Kept or `quit` with the `cause` if the `Promise` is Broken.

## [sub await](#class_Promise "go to top of document")[§](#sub_await "direct link")

```raku
multi await(Promise:D --> Promise)
multi await(*@ --> Array)
```

Waits until one or more promises are *all* fulfilled, and then returns their values. Also works on [`Channel`](/type/Channel)s. Any broken promises will rethrow their exceptions. If a list is passed it will return a list containing the results of awaiting each item in turn.

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

Type relations for `Promise`

raku-type-graph

Promise
Promise

Any
Any

Promise->Any

Mu
Mu

Any->Mu

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


## deduction.md
class X::Sequence::Deduction

Error due to constructing a sequence from ineligible input

```raku
class X::Sequence::Deduction is Exception { }
```

Exception type thrown when the `...` sequence operator is being called without an explicit closure, and the sequence cannot be deduced.


## dist_zef-clarkema-Readline.md
# Readline

Readline provides a Raku interface to libreadline.

## Installation

Please make sure that libreadline is installed beforehand, the tests will fail
otherwise. If libreadline is installed but the tests still fail, please note
that the Raku package searches a given set of directories for
libreadline.{so,dynlib}.\* files, otherwise it defaults to v7. If your
libreadline installation isn't on any of these paths, or requires non-standard
setup, please file an issue.

For those of you on Linux Debian and Linux-alike systems, you should be able to
get the latest version with this CLI invocation:

```
$ sudo apt-get install libreadline7

```

(I'd prefer to use LibraryCheck, but it fails inside the 'is native()' method
call.)

On macOS, use Hombrew or MacPorts to install readline. If you installed
Rakudo-Star with Homebrew after Sept. 1 it should already be there.

If not you can install just Readline

```
brew install readline

```

or update your rakudo-star install.

```
brew upgrade rakudo-star

```

Using zef (a module management tool bundled with Rakudo Star):

```
$ zef update && zef install Readline

```

Or alternatively installing it from a checkout of this repo with zef:

```
$ zef install .

```

## Usage

See the `examples/` directory in this project.

## Testing

To run tests:

```
$ prove -e raku

```

## Author

* Jeffrey Goff, DrForr on #perl6, <https://github.com/drforr/>
* Recently taken over by Daniel Lathrop (fooist), <https://github.com/fooist/>

## License

Artistic License 2.0


## dist_github-ugexe-Sanity.md
## sanity

Adds some sane defaults for your production Raku programs

### SYNOPSIS

```
use sanity;

42.base("beer");  # throws exception
42.base("camel"); # throws exception

"🍻🍺🍻🍺🍻🍺".parse-base("beer");  # throws exception
"🐫🐪🐫🐪🐫🐪".parse-base("camel"); # throws exception

```

### DESCRIPTION

A continually updating collection of Rakudo tweaks to workaround or disable features that are of little or no use in production software.

### GLOBAL APPLICATION

Run scripts or one-liners using `-Msanity`, i.e. `raku -Msanity bin/my-application.raku`

### WHY

```
# Wat?
$ raku -e 'say 42.base("beer");'
🍻🍺🍻🍺🍻🍺

# Ok!
$ raku -Msanity -e 'say 42.base("beer");'
Cannot convert string to number: base-10 number must begin with valid digits or '.' in '⏏beer' (indicated by ⏏)
  in sub  at /home/foobar/raku/install/share/perl6/site/sources/A6EEB7BD88D20C81DF439CAA2EA158E8EFDBB112 (sanity) line 5
  in block <unit> at -e line 1

```


## dist_zef-terminal-printers-Terminal-Print.md
# Terminal::Print

[![Actions Status](https://github.com/ab5tract/Terminal-Print/workflows/test/badge.svg)](https://github.com/ab5tract/Terminal-Print/actions)

## Synopsis

Terminal::Print intends to provide the essential underpinnings of command-line printing, to be the fuel for the fire, so to speak, for libraries which might aim towards 'command-line user interfaces' (CUI), asynchronous monitoring, rogue-like adventures, screensavers, video art, etc.

## Usage

Right now it only provides a grid with some nice access semantics.

```
my $screen = Terminal::Print.new;

$screen.initialize-screen;                      # saves current screen state, blanks screen, and hides cursor

$screen.change-cell(9, 23, '%');                # change the contents of the grid cell at column 9 line 23
$screen.cell-string(9, 23);                     # returns the escape sequence to put '%' on column 9 line 23
$screen.print-cell(9, 23);                      # prints "%" on the 9th column of the 23rd line
$screen.print-cell(9, 23, '&');                 # changes the cell at x:9, y:23 to '&' and prints it

$screen.print-string(9, 23, "hello\nworld!");   # prints a whole string (which can include newlines!)

$screen(9,23,'hello\nworld!');                  # uses CALL-ME to dispatch to .print-string

$screen.shutdown-screen;                        # unwinds the process from .initialize-screen

```

Check out some animations:

```
perl6 -Ilib examples/rpg-ui.p6
perl6 -Ilib examples/show-love.p6
perl6 -Ilib examples/zig-zag.p6
perl6 -Ilib examples/matrix-ish.p6
perl6 -Ilib examples/async.p6

```

By default the `Terminal::Print` object will use ANSI escape sequences for it's cursor drawing, but you can tell it to use `universal` if you would prefer to use the cursor movement commands as provided by `tput`. (You should only really need this if you are having trouble with the default).

```
my $t = Terminal::Print.new(cursor-profile => 'universal')

```

## History

At first I thought I might try writing a NativeCall wrapper around ncurses. Then I realized that there is absolutely no reason to fight a C library which has mostly bolted on Unicode when I can do it in Pure Perl 6, with native Unicode goodness.

## Roadmap

Status: *BETA* -- Current API is fixed and guaranteed!

* Improved documentation and examples
* Upgrade the tests with robust comparisons against a known-good corpus
* Investigate the potential of binding to `libtparm` (the backend to `tput`) via NativeCall

## Problems?

### It dies immediately complaining about my TERM env setting

In order to make the shelling out to `tput` safer, I have opted to use a whitelist of
valid terminals. The list is quite short at the moment, so my apologies if you trigger
this error. Everything should work smoothly once you have added it to the lookup hash
in `Terminal::Print::Commands`. Please consider sending it in as a PR, or filing a bug
report!

### It seems to be sending the wrong escape codes when using a different terminal on the same box

This should only be an issue for non-ANSI terminal users. The tradeoff we currently make
is to only disable precompilation on the module which determines the width and height of the
current screen. This means that other escape sequences in `Terminal::Print::Commands` will
only be run once and then cached in precompiled form. Clearing the related precomp files is
a quick and dirty solution. If you run into this issue, please let me know. I will certainly
get overly excited about your ancient TTY :D

## Contributors

ab5tract, japhb, Bluebear94, Xliff

Released under the Artistic License 2.0.