## dist_cpan-SACOMO-Uzu.md
# Uzu (渦) [build status](https://travis-ci.org/scmorrison/uzu)

Uzu is a static site generator with built-in web server, file modification watcher, live reload, i18n, themes, multi-page support, inject external data via local Perl 6 module, and external pre/post command execution.

**Note:** Uzu 0.3.6 and higher requires at least raku 2020.06.

* [Features](#features)
* [Getting started](#getting-started)
  * [Uzu Demo Site](#uzu-demo-site)
* [Usage](#usage)
* [Config](#config)
  * [Config variables](#config-variables)
* [Project folder structure (Template6)](#project-folder-structure-template6)
* [Project folder structure (Mustache)](#project-folder-structure-mustache)
* [Public and Assets directories](#public-and-assets-directories)
* [i18n YAML and Templating](#i18n-yaml-and-templating)
  * [Nested i18n variable files](#nested-i18n-variable-files)
  * [i18n output paths](#i18n-output-paths)
* [Template Features](#template-features)
  * [Template6](#template6)
    * [Examples](#examples-template6)
  * [Mustache](#mustache)
    * [Examples](#examples-mustache)
  * [Theme layouts](#theme-layouts)
  * [Partials](#partials)
  * [Global variables](#global-variables)
  * [Extended variables](#extended-variables)
  * [Template variables](#template-variables)
  * [Layout variables](#layout-variables)
  * [Related / linked pages](#related--linked-pages)
* [Page render conditions](#page-render-conditions)
* [Installation](#installation)
* [Todo](#todo)
* [Requirements](#requirements)
* [Troubleshooting](#troubleshooting)
* [Authors](#authors)
* [Contributors](#contributors)
* [License](#license)
* [See also](#see-also)

# Features

* **Easy to use**: Based on existing static site generator conventions
* **Built-in development webserver**: Test your modifications (http://localhost:3000) as you work
* **Auto Re-render**: `uzu watch` monitors the `theme/[your-theme]/`, `pages/`, `partials/`, and `i18n/` folders for modifications and auto-renders to build
* **Live reload**: `uzu watch` automatically reloads the browser when a re-render occurs
* **Templating**: Supports [Template6](#template6) and [Mustache](#mustache) template engines.
* **i18n support**: Use YAML to define each language in the `i18n/` folder (e.g. `i18n/en.yml`)
* **Page / layout support**: Generate individual pages wrapped in the same theme layout
* **Extended variables**: Inject dynamically generated data into project via external `Perl 6` module.
* **Pre/Post commands**: Trigger external commands to execute before or after build.
* **YAML variables**: Create page-specific and partial-specific variables as a [YAML block](#page-variables) at the top of any page or partial template.
* **Trigger rebuild manually**: Press `r enter` to initiate a full rebuild. This is useful for when you add new files or modify files that are not actively monitored by `uzu`, e.g. images, css, fonts, or any non `.tt`, `.mustache`, or `.yml` files
* **Actively developed**: More features coming soon (e.g. more tests, AWS, Github Pages, SSH support...)

**Note**: Uzu is a work in progress. It is functional and does a bunch of cool stuff, but it isn't perfect. Please post any [issues](https://github.com/scmorrison/uzu/issues) you find.

# Getting started

After [installing](#installation) uzu, run the following command from an empty directory:

```
uzu init

```

Enter your site name, default language, and template engine when prompted.

## Uzu Demo Site

@uzluisf has created an excellent [Uzu Demo Site](https://github.com/uzluisf/uzu-demo-site) that shows how a fully working Uzu project is organized / functions.

# Usage

```
Usage:
  uzu init          - Initialize new project
  uzu webserver     - Start local web server
  uzu build         - Render all templates to build
  uzu clear         - Delete build directory and all of its contents
  uzu watch         - Start web server and re-render
                      build on template modification
  uzu version       - Print uzu version and exit

Optional arguments:

  --config=         - Specify a custom config file
                      Default is `config`

  e.g. uzu --config=path/to/config.yml init

  --no-livereload   - Disable livereload when
                      running uzu watch.

  --clear           - Delete build directory before
                      render when running with build.

  --page-filter     - Restrict build to pages starting
                      from this directory

  --theme           - Limit build / watch to single theme

  e.g. uzu --theme=default build

```

# Config

Each project has its own `config.yml` which uses the following format:

```
---
#
# Core variables
#

# Name of the project
name: uzu-starter

# Languages to use, determines which
# i18n/*.yml file to use for string variables
#
# The first language in the list is considered
# the default language. The defualt language
# will render to non-suffixed files (e.g index.html).
# All other languages will render with the
# language as a file suffix (e.g index-fr.html,
# index-ja.html). This will be overridable in
# future releases.

language:
  - en
  - ja
  - fr

# i18n scheme (default: suffix)
i18n_scheme: 'directory' # Render non-default languages to /[lang]/[page name].[extension]

# Template engine
# - Template6: tt
# - Mustache: mustache
template_engine: mustache

# Stored theme directories under themes/[theme-name]
#
# Themes can be specified with either the single theme
# variable:
theme: default

# .. or multiple themes:
themes:
  - default              # Specify a theme directory using the default options
  - summer2017:
      build_dir: web2017 # Override build director
      port: 4333         # Port to start watch on for this theme.
      exclude_pages:     # List of page template names to ignore for this theme
        - index

# Optional parameters (also, comments like this are ok)

# Use a custom dev server port, default is 3000
port: 4040

# Specify a custom project root path
# default is .
project_root: path/to/project/folder

# List of page template names to ignore for all themes
exclude_pages:
  - about
  - blog/fiji-scratch

# List of directories and files to exclude from build/
exclude:
  - node_modules
  - packages.json
  - yarn.lock

# Pre / post build commands
pre_command: "webpack"
post_command: "echo 'post-build command'"

# Omit .html extension from generated HTML files
omit_html_ext: true

```

### Config variables

Config variables are defined in `config.yml`:

* `name`: Project name
* `language`: List of languages to render for site. First item is default language. When rendering, the `language` variable is set to the current rendering language and can be referenced in templates. For example, if `uzu` is rendering an `en` version of a page, then the `language` variable will be set to `en`.
* `i18n_scheme`: By default `uzu` will generate files with the language suffix appended for non-default language output. (e.g. `fr`: `index-fr`). This behaviour can be set to 'directory' witch will render non-default languages to `/[lang]/[page name].[extension]` (e.g. `fr`: `/fr/index.html`).
* `theme`: The theme to apply to the layout (themes/themename). `default` refers to the folder named `default` in the themes folder.
* `themes`: Alternatively, using the `themes` yaml hash supports multiple themes. Themes will be rendered at the same time into their target build directories. By default the theme build directory is `build/[theme-name]`. This can be overridden with the `build_dir` variable. Relative and absolute paths are supported:

  * `build_dir`:

    ```
    themes:
      - summer2017:
          build_dir: web2017

    ```
  * `port`: A dev web server will spawn for rach theme specified in the `themes` yaml dict. The default port for the first theme is `3000`, this port number is incremented by one for every subsequent theme listed in the `themes` dict. This variable will override that behavior.

    ```
    themes:
      - summer2017:
          port: 4444

    ```
  * `exclude_pages`: List page templates that should not be rendered for the associated theme.

    ```
    themes:
      - summer2017:
          exclude_pages:
            - about
            - blog/fiji
            - sitemap.xml

    ```
* `exclude`: List of directories and files to exclude from `build/`

  ```
  exclude:
    - node_modules
    - packages.json
    - yarn.lock

  ```
* `pre_command`: Run command prior to build step
* `post_command`: Run command after to build step
* `host`: Host IP for the dev server. Defaults to `127.0.0.1`.
* `port`: Host TCP port for dev server. Defaults to `3000`.
* `project_root`: Project root folder. Defaults to `.`.
* `omit_html_ext`: Omit `.html` from generated HTML files.

### Accessing config variables in templates

Config variables can be accessed from inside templates directly (e.g. `port`, `theme`, etc.)

### Accessing non-core variables in templates

Non-core variables are any additional variables found in config.yml and can be accessed in templates using `site.variablename` (e.g. `site.url`, `site.author`).

# Project folder structure (Template6)

```
├── config.yml                    # Uzu config file
├── pages                         # Each page becomes a .html file
│   ├── about.tt
│   ├── index.tt
│   └── blog                      # Pages can be nested in sub-folders. Their URI
│       └── vacation.tt           # will follow the same path (e.g. /blog/vacation.html)
│
├── partials                      # Partials can be included in pages
│   ├── footer.tt                 # and theme layouts
│   ├── head.tt
│   ├── home.tt
│   ├── jumbotron.tt
│   ├── navigation.tt
│   └── profiles.tt
├── public                        # Static files / assets independant of theme (copied to /)
├── i18n                          # Language translation files
│   └── blog
│       └── vacation              # i18n variables can be defined for specific pages
│           └── en.yml
│   ├── en.yml
│   ├── fr.yml
│   ├── ja.yml
└── themes                        # Project themes
    └── default
        ├── assets                # Theme specific static files / assets (copied to /)
        │   ├── css
        │   ├── favicon.ico
        │   ├── fonts
        │   ├── img
        │   ├── js
        ├── partials              # Theme specific partials. These will override any top-level
        │   ├── footer.tt         # partials with the same file name.
        └── layout.tt             # Theme layout file

```

# Project folder structure (Mustache)

```
├── config.yml                    # Uzu config file
├── pages                         # Each page becomes a .html file
│   ├── about.mustache
│   ├── index.mustache
│   └── blog                      # Pages can be nested in sub-folders. Their URI
│       └── vacation.mustache     # will follow the same path (e.g. /blog/vacation.html)
│
├── partials                      # Partials can be included in pages
│   ├── footer.mustache           # and theme layouts
│   ├── head.mustache
│   ├── home.mustache
│   ├── jumbotron.mustache
│   ├── navigation.mustache
│   └── profiles.mustache
├── public                        # Static files / assets independant of theme (copied to /)
├── i18n                          # Language translation files
│   └── blog
│       └── vacation              # i18n variables can be defined for specific pages
│           └── en.yml
│   ├── en.yml
│   ├── fr.yml
│   ├── ja.yml
└── themes                        # Project themes
    └── default
        ├── assets                # Theme specific static files / assets (copied to /)
        │   ├── css
        │   ├── favicon.ico
        │   ├── fonts
        │   ├── img
        │   ├── js
        ├── partials              # Theme specific partials. These will override any top-level
        │   ├── footer.tt         # partials with the same file name.
        └── layout.mustache       # Theme layout file

```

See [uzu-starter](https://github.com/scmorrison/uzu-starter) for a full example.

# Public and Assets directories

* `public/` - The root public directory is where project-wide static assets are stored.
* `themes/**/assets/` - The theme's assets directory is where theme-specific static assets are stored.

Files found in either of these directories are copied wholesale to the root of the `build/` directory on successful build. For example:

* `public/js/site.js` will be copied to `build/js/site.js`
* `themes/default/assets/img/logo.png` will be copied to `build/img/logo.png`

**Note:** Any tmp / swp files created by editors will also be copied into `build/`. Most editors provide options to configure this behavior. For example, you can have all `vim` `.swp` files saved into a central directory by adding something like this to `~/.vimrc`:

```
set backupdir=~/.vim/backup//
set directory=~/.vim/swp//

```

# i18n YAML and Templating

You can separate out the content text to YAML files located in a project-root folder called `i18n`. Simply create a separate file for each language, like this:

```
─ i18n
  ├── blog
  │   └── vacation     # Page specific i18n variables
  │       ├── en.yml   # en i18n variables for page pages/blog/vacation.tt
  │       └── ja.yml   # ja i18n variables for page pages/blog/vacation.tt
  ├── en.yml           # Main en i18n variables
  ├── fr.yml           # Main fr i18n variables
  └── ja.yml           # Main ja i18n variables

```

An example i18n YAML file might look like this:

```
---
# Template access i18n.site_name
site_name: The Uzu Project Site

# Template access i18n.url
url: https://github.com/scmorrison/uzu-starter

# Template access i18n.founders
founders:
  - name: Sam
    title: "Dish Washer"
  - name: Elly
    title: CEO
  - name: Tomo
    title: CFO

# Comments start with a #

# Do not use blank values
this_will_break_things:
do_this_instead: ""

```

### Accessing i18n variables in templates

Variables defined in i18n files can be accessed in templates using the `i18n.variablename` format (e.g. `i18n.site_name`, `i18n.founders`).

```
<h1>[% i18n.site_name %]</h1>

```

#### Nested i18n variable files

Any variables defined in page specific i18n files, e.g. `i18n/blog/vacation/en.yml`, will override any top-level language i18n file (e.g `i18n/en.yml`) defined variables that share the same name. For example:

```
# i18n/en.yml
site_name: Uzu Starter Project

```

...will be overridden by:

```
# i18n/blog/vacation/en.yml
site_name: "Our Vacation 2017"

```

## i18n output paths

By default `uzu` generates language specific files with the following pattern:

`[page name]-[language code].html`

For example, if the default language is `en` and secondary language is `ja`, the `index` page template would be rendered to the following files:

* Default language: `build/index.html`
* Subsequent languages: `build/index-ja.html`

This output behavior can be changed to `directory` in `config.yml` with the `i18n_scheme` variable:

```
i18n_scheme: 'directory'

```

With this option set, the output will be rendered to the following files:

* Default language: `build/index.html`
* Subsequent languages: `build/ja/index.html`

# Template Features

## Template6

Uzu supports the [Template Toolkit](http://template-toolkit.org/) templating format for template files. This is the default template engine.

### Features include:

* GET and SET statements, including implicit versions

  * [% get varname %]
  * [% varname %]
  * [% set varname = value %]
  * [% varname = value %]
* FOR statement

  * [% for names as name %]
  * [% for names -> name %]
  * [% for name in names %]
  * [% for name = names %]

  If used with Hashes, you'll need to query the .key or .value accessors.
* IF/ELSIF/ELSE/UNLESS statements.

  * [% if display\_links %]
    -- do this ---
    [% else %]

    -- do that --

    [% end %]
  * [% unless graphics %]

    -- some html ---

    [% end %]
* Querying nested data structures using a simple dot operator syntax.
* CALL and DEFAULT statements.
* INSERT, INCLUDE and PROCESS statements.

### Examples (Template6)

### Single i18n variable

```
<a class="navbar-brand" href="/">[% i18n.site_name %]</a>

```

### For loop from yaml dict (non-core variable) defined in config.yml

```
<h1>Company Founders</h1>
<ul>
[% for founder in site.founders %]
  <li>[% founder.name %], [% founder.title %]</a>
[% end %]
</ul>

```

### IF/ELSEIF/UNLESS

```
[% if site.graphics %]
    <img src="[% images %]/logo.gif" align=right width=60 height=40>
[% end %]

```

## Mustache

Uzu also supports the [Mustache](http://mustache.github.io/) templating format for template files.

Enable mustache support by adding the following line to your `config.yml`:

`template_engine: mustache`

For example:

```
---
name: mysite
language:
  - en
theme: default
template_engine: mustache

```

### Examples (Mustache)

### Single i18n variable

```
<a class="navbar-brand" href="/">{{ i18n.site_name }}</a>

```

### For loop from yaml dict (non-core variable) defined in config.yml

```
<h1>Company Founders</h1>
<ul>
{{#founders}}
  <li>{{ name }}, {{ title }}</a>
{{/founders}}
</ul>

```

### If conditionals

Mustache is a 'logic-less' templating system, but you can test for the existence of a variable, and if it exists then anything inside the test block with be processed. Otherwise it is ignored.

```
{{#site.graphics}}
    <img src="{{ images }}/logo.gif" align=right width=60 height=40>
{{/site.graphics}}

```

## Theme layouts

Theme layout templates are located at the `themes/THEME_NAME/layout.tt` or `themes/THEME_NAME/layout.mustache`. Use the `content` partial to include rendered page content in a layout.

For `Template6`:

```
<!doctype html>
<html lang="[% language %]">
[% INCLUDE "head" %]
    <body>
      [% INCLUDE "navigation" %]
      <!-- Rendered page content -->
      [% INCLUDE "content" %]
      [% INCLUDE "footer" %]
    </body>
</html>

```

For `Mustache`:

```
<!doctype html>
<html lang="{{ language }}">
{{> head }}
    <body>
      {{> navigation }}
      <!-- Rendered page content -->
      {{> content }}
      {{> footer }}
    </body>
</html>

```

## Partials

Partials are stored in the `partials` and `themes/THEME_NAME/partials` directories. Any theme partial will override any partial found in the top-level `partials` directory with the same file name. Partials can be include in layouts, pages, and other partials.

For `Template6`:

```
[% INCLUDE "navigation" %]
<div>
    [% INCLUDE "login_form" %]
</div>

```

For `Mustache`:

```
{{> navigation }}
<div>
    {{> login_form }}
</div>

```

## Global variables

Some variables are generated dynamically and exposed to templates for use:

* **language**: The current language as a string (e.g. `en`, `ja`, etc.)
* **lang\_**: The `lang_CURRENT_LANG` variable provides the current rendering language. This is useful if you want to display certain content depending on the i18n language.

  For `Template6`:

  ```
  [% if lang_en %]
  <a href='/index-ja.html'>日本語</a>
  [% end %]
  [% if lang_ja %]
  <a href='/'>English</a>
  [% end %]

  ```

  For `Mustache`:

  ```
  {{#lang_en}}
  <a href='/index-ja.html'>日本語</a>
  {{/lang_en}}
  {{#lang_ja}}
  <a href='/'>English</a>
  {{/lang_ja}}

  ```
* **theme\_**: The current theme is exposed to the templates as `theme_NAME_OF_THEM`. For example, the variable `theme_default` will be available if the `default` theme is being used:

  For `Template6`:

  ```
  [% if theme_default %]
  [% INCLUDE "default_header" %]
  [% end %]

  [% if theme_enoshima %]
  [% INCLUDE "enoshima_header" %]
  [% end %]

  ```

  For `Mustache`:

  ```
  {{#theme_default}}
  {{> default_header }}
  {{/theme_default}}

  {{#theme_enoshima}}
  {{> enoshima_header }}
  {{/theme_enoshima}}

  ```
* **randnum**: A dynamically generated 16 digit integer. This value is generated any time a page is generated / regenerated.

  ```
  <link rel="stylesheet" type="text/css" href="/css/site.css?v=[% randnum %]">

  ```
* **dt**: A date hash that includes common date values. This is a dynamic variable that contains `datetime` data for current build.

  ```
  <span>©[% dt.year %] Uzu, Inc.</span>

  ```

  Available `dt` values:

  * dt.hour
  * dt.minute
  * dt.second
  * dt.day
  * dt.month
  * dt.year
  * dt.hh-mm-ss
  * dt.utc
  * dt.day-of-month
  * dt.day-of-week
  * dt.weekday-of-month
  * dt.is-leap-year
  * dt.day-of-year
  * dt.week-year
  * dt.daycount
  * dt.week-number
  * dt.days-in-month
  * dt.week
  * dt.yyyy-mm-dd
  * dt.timezone

### Extended variables

Uzu can be extended with external / dynamically generated data provided via a local `Perl 6` module.

In order to inject external data into your project you must use the `PERL6LIB` environment variable when running `uzu`:

```
PERL6LIB=lib uzu watch

```

Create your module, for example `MyApp`, in your `uzu` project directory under `lib` (e.g. `lib/MyApp.pm6`). The app must export a subroutine named `context()`. This is `uzu`'s entry point:

```
# lib/MyApp.pm6

unit module MyApp;

our sub context(--> Hash) {
    return %{
        number_of_products => get-remote-product-count(),
        favorite_food      => 'Bean Burrito',
    }
}

```

Add the name of your `Perl 6` module to your config as `extended` (do not add the module file extension):

```
extended: 'MyApp'

```

When `uzu` starts it will attempt to load the local module and inject the `Hash` returned by `context()` into the global render context Hash. The keys defined in the injected Hash will be available from within templates.

```
<span>Total Products: [% number_of_products %]</span>

```

If `&MyApp::context()` is unavailable, `uzu` will print a message indicating that `MyApp` or `&MyApp::context()` could not be loaded.

The external module will be executed on every build by default. To disable this behavior while using the local dev server (`uzu watch`) set the config variable `refresh_extended` to `false` in your config.yml:

```
refresh_extended: false

```

### Template variables

You can define variables using a yaml block at the top of any page or partial (`pages/`, `partials/`):

`pages/index.tt`

```
---
title: 'Welcome to Uzu'
subtitle:  'The best'
---

```

To access these variables inside of a template you do not need to use the `i18n.` scope prefix.

For `Template6`:

`partials/head.tt`

```
<head>
    <meta charset="utf-8">
    <title>[% title %] - [% subtitle %]</title>
</head>

```

...and for `Mustache`:

`partials/head.mustache`

```
<head>
    <meta charset="utf-8">
    <title>{{ title }} - {{ subtitle }}</title>
</head>

```

### Layout variables

You can define variables in the layout template and access them using the `layout.` prefix in templates;

For example:

Define yaml definitions in `themes/**/layout.tt` or `themes/**/layout.mustache`:

```
---
root_url: https://www.perl6.org
name: Dark Theme
---
<!doctype html>
<html>
...

```

Will be accessible in templates like this:

For `Template6`:

```
<a href="[% layout.root_url %]/about-this-theme.html">[% layout.name %]</a>

```

...and for `Mustache`:

```
<a href="{{ layout.root_url }}/about-this-theme.html">{{ layout.name }}</a>

```

### Related / linked pages

Uzu will append any yaml dict ending with `_pages` with additional page-related variables if the variables are defined in the associated page template.

For `Template6`:

```
---
related_pages:
    - page: about
    - page: blog/fiji
    - page: https://www.perl6.org
      title: The Perl 6 Programming Language
      author: Perl 6
---
<ul>
[% for rp in related_pages %]
    <li>
        <a href="[% rp.url %]">[% rp.title %]</a> [[% rp.author %]]
    </li>
[% end %]
</ul>

```

...and for `Mustache`:

```
<ul>
{{#related_pages}}
    <li>
        <a href="{{ url }}">{{ title }}</a> [{{ author }}]
    </li>
{{/related_pages}}
</ul>

```

The above produces the following HTML. Note that the `author` and `title` values are pulled from the related page's template yaml variables:

```
<ul>
    <li>
        <a href="/about.html">About Us</a> [Camelia]
    </li>
    <li>
        <a href="/blog/fiji.html">Fiji Vacation</a> [Camelia]
    </li>
    <li>
        <a href="https://www.perl6.org">The Perl 6 Programming Language</a> [Perl 6]
    </li>
</ul>

```

### Disable layout rendering for page template

To disable layout rendering for specific pages add the `nolayout` variable to the page's yaml variables:

```
---
nolayout: true
---

```

# Page render conditions

In order to reduce build times Uzu will try to avoid rerendering a page if it hasn't been modified.

Pages will only be rendered under the following conditions:

* Rendered page does not exist in `build` directory
* The page template has been modified
* A partial file included in the layout, page, or any partial included in the page has been modified
* The page includes a related / linked pages `_pages` yaml dict and one of the linked pages templates has been modified
* Running `uzu --clear build` will rebuild all pages
* Pressing `c enter` while running `uzu watch` will rebuild all pages

# Installation

```
zef install Uzu

```

Installation issue? See [Troubleshooting](#troubleshooting).

# Todo

* More tests
* Uglify JS / CSS
* Build deploy process push to remote services
* Features
  * Additional templating support (markdown)
  * Dynamic variables (categories, tags, pagination)

# Requirements

* [Perl 6](http://perl6.org/)

# Troubleshooting

* **Errors installing from previous version:**

  Remove the zef tmp / store uzu.git directories:

  ```
  # Delete these folders from your zef install
  # directory.
  rm -rf ~/.zef/store/uzu.git ~/.zef/tmp/uzu.git

  ```

  In some instances it might help to delete your local `~/.perl6/precomp` directory.
* **Tests failing during install**

Sometimes tests might fail during install. Try re-installing all of the dependencies via `zef`:

```
zef install --force-install --/test \
    File::Directory::Tree \
    File::Find File::Temp \
    Terminal::ANSIColor \
    Template6 \
    Template::Mustache \
    Test::Output \
    HTTP::Parser \
    HTTP::Server::Tiny \
    YAMLish;

```

In some instances it might help to delete your local `~/.perl6/precomp` directory.

If installing from source, remove the `lib/.precomp` folder inside the `uzu` root folder and attempt the install again.

# Authors

* [Sam Morrison](@samcns)

# Contributors

* [ab5tract](@ab5tract)

# License

Uzu is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. (Note that, unlike the Artistic License 1.0, version 2.0 is GPL compatible by itself, hence there is no benefit to having an Artistic 2.0 / GPL disjunction.) See the file LICENSE for details.

# See also

* [Template6](https://github.com/supernovus/template6)
* [Mustache](https://github.com/softmoth/p6-Template-Mustache/)


## dist_zef-jonathanstowe-Tinky-JSON.md
# Tinky-JSON

Tinky Machines defined in JSON

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

## Synopsis

Given a JSON file like:

```
{
    "name" : "Test Workflow",
    "initial-state" : "new",
    "states" : [ "new", "open", "rejected", "in-progress", "stalled", "complete" ],
    "transitions" : [
        {
            "name" : "open",
            "from" : "new",
            "to"   : "open"
        },
        {
            "name" : "reject",
            "from" : "new",
            "to"   : "rejected"
        },
        {
            "name" : "reject",
            "from" : "open",
            "to"   : "rejected"
        },
        {
            "name" : "reject",
            "from" : "stalled",
            "to"   : "rejected"
        },
        {
            "name" : "stall",
            "from" : "open",
            "to"   : "stalled"
        },
        {
            "name" : "stall",
            "from" : "in-progress",
            "to"   : "stalled"
        },
        {
            "name" : "unstall",
            "to"   : "in-progress",
            "from" : "stalled"
        },
        {
            "name" : "take",
            "from" : "open",
            "to"   : "in-progress"
        },
        {
            "name" : "complete",
            "from" : "open",
            "to"   : "complete"
        },
        {
            "name" : "complete",
            "from" : "open",
            "to"   : "complete"
        },
        {
            "name" : "complete",
            "from" : "in-progress",
            "to"   : "complete"
        }
    ]
}

```

This is functionally the same as the example for [Tinky](https://github.com/jonathanstowe/Tinky)

```
use Tinky;
use Tinky::JSON;

my $json = $*PROGRAM.parent.child('ticket.json').slurp;

my $workflow = Tinky::JSON::Workflow.from-json($json);

class Ticket does Tinky::Object {
    has Str $.ticket-number = (^100000).pick.fmt("%08d");
    has Str $.owner;
}

# Each state has an 'enter-supply' and a 'leave-supply' which get the
# object which the state was applied to.

$workflow.enter-supply('rejected').act( -> $object { say "** sending rejected e-mail for Ticket '{ $object.ticket-number }' **" });

# The transition supply allows specific logic for the transition to be performed

$workflow.find-transition('in-progress', 'stalled').supply.act( -> $object { say "** rescheduling tickets for '{ $object.owner }' on ticket stall **"});

# The workflow aggregates the Supplies of the transitions and the states.
# This could be to a logging subsystem for instance.

$workflow.transition-supply.act(-> ($trans, $object) { say "Ticket '{ $object.ticket-number }' went from { $trans.from.name }' to '{ $trans.to.name }'" });

# The final-supply emits the state and the object when a state is reached where there are no
# further transitions available

$workflow.final-supply.act(-> ( $state, $object) { say "** updating performance stats with Ticket '{ $object.ticket-number }' entered State '{ $state.name }'" });

# Create an instance of the Tinky::Object.
# A 'state' can be supplied to initialise if, for example, the data was retrieved from a database
my $ticket-a = Ticket.new(owner => "Operator A");

# Applying the workflow will set the initial state if one is configured and will
# apply a role that provides the transition methods.
# The workflow object can be configured to check whether the object to which it
# is being applied is suitable and throw an exception if not.

$ticket-a.apply-workflow($workflow);

# Exercise the transition methods.
# Other mechanisms are available for performing the transitions whuch may be more
# suitable if the next state is to be calculated.

# State new -> open
$ticket-a.open;

# State open -> in-progress
$ticket-a.take;

# Get the names of the states which are now available for the object
# [stalled complete]
$ticket-a.next-states>>.name.say;

# Directly assigning the state will be validated, an exception will
# be thrown if this is not a valid transition at the time
$ticket-a.state = $workflow.state('stalled');

# State stalled -> rejected
# This is a final state and no further transitions are available.
$ticket-a.reject;

```

## Description

This allows you to define a [Tinky](https://github.com/jonathanstowe/Tinky) workflow from JSON data.

It provides sub-classes of `Tinky::Workflow`, `Tinky::State`, amd `Tinky::Transition`
that can be serialised from JSON and have over-rides of some of the methods to take the names
of objects in the workflow definition (states or transitions,) rather than the objects themselves.

This aims to simplify the construction of state machines from a fixed configuration.

## Installation

Assuming you have a working Rakudo installation then you should be able to install this module with *zef* :

```
zef install Tinky::JSON

```

Or if you have a clone of the repository you can substitute the
name of the module for '.' (assuming you are actually in the
cloned directory.)

## Support

Please send any reports, suggestions or patches to <https://github.com/jonathanstowe/Tinky-JSON/issues>

## Copyright and Licence

The is free software. The terms are described in the <LICENCE>
file in the distribution.

© Jonathan Stowe, 2016 - 2021


## dist_zef-raku-community-modules-Subset-Helper.md
# NAME [Tests on source](https://github.com/raku-community-modules/Subset-Helper/actions/workflows/test.yaml)

Subset::Helper - create awesome subsets

# SYNOPSIS

```
    use Subset::Helper;

    subset Positive of Int
        where subset-is * > 0, 'Value must be above zero';

    my Positive $x = 42; # success
    my Positive $x = -2; # Fails with 'Value must be above zero';

```

# DESCRIPTION

This module solves two inconveniences with Perl 6's subsets:

```
1) Display of useful error messages when type check fails
2) Avoid evaluating subset's condition for `Any` values,
    which is what happens with optional parameters

```

# EXPORTED SUBROUTINES

## `subset-is`

```
    subset Positive of Int where subset-is * > 0;

    subset RoverCam of Str where subset-is
        { $_ ∈ set <MAST CHEMCAM FHAZ RHAZ> },
        'Valid cameras are MAST, CHEMCAM, FHAZ, and RHAZ';

```

Takes one mandatory positional argument, which is the
code to execute to check the validity of value, and an
optional descriptive error message to show when the value
doesn't match the subset.

Note: undefined values are accepted by the subset.
This exists to make it possible to cleanly define subsets
for optional parameters, for which the type check is still
called, even when they aren't provided in the sub/method calls.

# CONFUSING ERRORS

You can't declare our scoped subsets within roles. If you're
using this module, however, that error will instead point
to the end of the declaration, saying `expecting any of: postfix`.
Simply prefix your subset with `my`

# BUGS AND LIMITATIONS

Rakudo may evaluate whether a value matches the subset TWICE:
once to check the match and once to get sensible error information.

Thus, currently the error message you provide is printed twice.

Patches to fix this are welcome.

---

# REPOSITORY

Fork this module on GitHub:
<https://github.com/raku-community-modules/Subset-Helper>

# BUGS

To report bugs or request features, please use
<https://github.com/raku-community-modules/Subset-Helper/issues>

# AUTHOR

Zoffix Znet (<http://zoffix.com/>)

# LICENSE

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


## dist_cpan-LEONT-Protocol-MQTT.md
[![Actions Status](https://github.com/Leont/raku-protocol-mqtt/workflows/test/badge.svg)](https://github.com/Leont/raku-protocol-mqtt/actions)

# NAME

Protocol::MQTT - A (sans-io) MQTT client implementation

# SYNOPSIS

```
use Protocol::MQTT;

```

# DESCRIPTION

Protocol::MQTT contains a networking and timing independent implementation of the MQTT protocol. Currently only the client side is implemented, in the form of Protocol::MQTT::Client. Net::MQTT an actual client based on `Protocol::MQTT::Client`.

# AUTHOR

Leon Timmermans [fawaka@gmail.com](mailto:fawaka@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2021 Leon Timmermans

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


## dist_cpan-DONPDONP-CamelPub.md
## INSTALL

### install from CPAN

```
$ zef install CamelPub

```

### install from Source

```
$ pijul clone https://nest.pijul.org/donpdonp/camelpub
Pulling patches: 100% (60/60), done.
Applying patches: 100% (60/60), done.
$ cd camelpub
$ zef install .
===> Testing: CamelPub:ver<0.2.0>
===> Testing [OK] for CamelPub:ver<0.2.0>
===> Installing: CamelPub:ver<0.2.0>

1 bin/ script [camelpub] installed to:
/home/donp/.rakudobrew/moar-2018.06/install/share/perl6/site/bin

```

### setup

```
 $ /home/donp/.rakudobrew/moar-2018.06/install/share/perl6/site/bin/camelpub server
warning: created /home/donp/.config/camelpub/
Creating profile.
What is your preferred username?
> z2
What is your activitypub profile page or homepage? example: https://mastodon.social/users/foo
> https://donpark.org/z2
saving profile to /home/donp/.config/camelpub/activitypub.json
loaded profile for z2@donpark.org https://donpark.org/z2
upgrading database to schema version 1
server listening localhost:2314

```

From an activitypub site, mastodon for example, do a search for '@z2@donpark.org'. You'll see the requests being made

```
GET /.well-known/webfinger?resource=acct:z2@donpark.org
-> acct:z2@donpark.org webfinger returns https://donpark.org/z2

GET /z2 Accept: application/activity+json, application/ld+json
-> sending activitypub profile for https://donpark.org/z2

GET /z2 Accept: application/activity+json, application/ld+json
-> sending activitypub profile for https://donpark.org/z2

GET /z2/outbox Accept: application/activity+json, application/ld+json
activitypub profile requested for unknown path /z2/outbox

```

and the activitypub friend request itself

```
POST /z2/inbox  [application/activity+json]
-> https://donpark.org/z2 INBOX POST
-> {
  "signature": {
    "created": "2018-08-02T22:06:44Z",
    "creator": "https://toot.donp.org/users/donpdonp#main-key",
    "type": "RsaSignature2017",
    "signatureValue": "IjQ6vF07QKq9v00E2h5pau9Kx3SvTnSFhjJeEuHBj50poC4bYWgWkg/X0jZosgUA1w2wwZWKsHKg/FcU6wlj+40V0cYfQp3dDAsVd0
GgPOxUXLbizNPbMCLpeRrC3FtSz81kmOTNmP0MrbyA6dJ0t2GwAOVR0E31M3I3GXJKhwtA704ZffimO2J42cdbzspKS6CsqWcnbUQP2oDFn8Pm1Sbf5QpmoKoiG5CusUQmJP2uVWcY+JyCEaAH1R0tDHB6S4iPOYdJS7gWdDt/0Kd0Mc4scE7oJMy2TtXd4jCCv7HWtZp90Mw+nI8SistUGrs1i5v4yp6cHrG26lcJGTMMnQ=="
  },
  "type": "Follow",
  "actor": "https://toot.donp.org/users/donpdonp",
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {
      "value": "schema:value",
      "featured": {
        "@id": "toot:featured",
        "@type": "@id"
      },
      "focalPoint": {
        "@container": "@list",
        "@id": "toot:focalPoint"
      },
      "sensitive": "as:sensitive",
      "manuallyApprovesFollowers": "as:manuallyApprovesFollowers",
      "Emoji": "toot:Emoji",
      "schema": "http://schema.org#",
      "toot": "http://joinmastodon.org/ns#",
      "conversation": "ostatus:conversation",
      "ostatus": "http://ostatus.org#",
      "movedTo": {
        "@id": "as:movedTo",
        "@type": "@id"
      },
      "PropertyValue": "schema:PropertyValue",
      "atomUri": "ostatus:atomUri",
      "Hashtag": "as:Hashtag",
      "inReplyToAtomUri": "ostatus:inReplyToAtomUri"
    }
  ],
  "id": "https://toot.donp.org/ab524af1-ae09-4268-b8ad-920f8f626111",
  "object": "https://donpark.org/z2"
}

```


## dist_zef-FRITH-Math-Libgsl-Polynomial.md
[![Actions Status](https://github.com/frithnanth/raku-Math-Libgsl-Polynomial/workflows/test/badge.svg)](https://github.com/frithnanth/raku-Math-Libgsl-Polynomial/actions)

# NAME

Math::Libgsl::Polynomial - An interface to libgsl, the Gnu Scientific Library - Polynomials.

# SYNOPSIS

```
use Math::Libgsl::Raw::Polynomial :ALL;

use Math::Libgsl::Polynomial :ALL;

```

# DESCRIPTION

Math::Libgsl provides an interface to polynomial evaluation in libgsl, the GNU Scientific Library.

Math::Libgsl::Polynomial makes these tags available:

* :eval
* :divdiff
* :quad
* :cubic
* :complexsolve

### sub poly-eval(Positional $c, Num(Cool) $x --> Num) is export(:eval)

Evaluates a polynomial with real coefficients for the real variable x.

```
my @c = 1, 2, 3;
say poly-eval(@c, 10); # prints 321

```

### sub poly-eval-derivs(Num(Cool) $x, Int $maxn, Positional $c --> List) is export(:eval)

This function evaluates a polynomial and its derivatives. The output array contains the values of dⁿP(x)/dxⁿ for the specified value of x starting with n = 0.

### sub poly-dd(Positional $xa, Positional $ya, Positional $x --> List) is export(:divdiff)

This function computes a divided-difference representation of the interpolating polynomial for the points (xa, ya) and evaluates the polynomial for each point x.

### sub poly-dd-taylor(Positional $xa, Positional $ya, Num(Cool) $x --> List) is export(:divdiff)

This function converts the divided-difference representation of a polynomial to a Taylor expansion and evaluates the Taylor coefficients about the point x.

### sub poly-dd-hermite(Positional $xa, Positional $ya, Positional $dya, Positional $x --> List) is export(:divdiff)

This function computes a divided-difference representation of the interpolating Hermite polynomial for the points (xa, ya) and evaluates the polynomial for each point x.

### sub poly-solve-quadratic(Num(Cool) $a, Num(Cool) $b, Num(Cool) $c --> List) is export(:quad)

This function finds the real roots of the quadratic equation ax² + bx + c = 0. It returns a list of values: the number of the real roots found and zero, one or two roots; if present the roots are sorted in ascending order.

### sub poly-complex-solve-quadratic(Num(Cool) $a, Num(Cool) $b, Num(Cool) $c --> List) is export(:quad)

This function finds the complex roots of the quadratic equation ax² + bx + c = 0. It returns a list of values: the number of the real roots found and zero, one or two roots. The root are returned as Raku Complex values.

### sub poly-solve-cubic(Num(Cool) $a, Num(Cool) $b, Num(Cool) $c --> List) is export(:cubic)

This function finds the real roots of the cubic equation x³ + ax² + bx + c = 0. It returns a list of values: the number of the real roots found and one or three roots; the roots are sorted in ascending order.

### sub poly-complex-solve-cubic(Num(Cool) $a, Num(Cool) $b, Num(Cool) $c --> List) is export(:cubic)

This function finds the complex roots of the cubic equation x³ + ax² + bx + c = 0. The number of complex roots is returned (always three); the roots are returned in ascending order, sorted first by their real components and then by their imaginary components. The root are returned as Raku Complex values.

### sub poly-complex-solve(\*@a --> List) is export(:complexsolve)

This function computes the roots of the general polynomial a₀ + a₁x + a₂x² + … + aₙ₋₁xⁿ⁻¹ The root are returned as Raku Complex values.

# C Library Documentation

For more details on libgsl see <https://www.gnu.org/software/gsl/>. The excellent C Library manual is available here <https://www.gnu.org/software/gsl/doc/html/index.html>, or here <https://www.gnu.org/software/gsl/doc/latex/gsl-ref.pdf> in PDF format.

# Prerequisites

This module requires the libgsl library to be installed. Please follow the instructions below based on your platform:

## Debian Linux and Ubuntu 20.04

```
sudo apt install libgsl23 libgsl-dev libgslcblas0

```

That command will install libgslcblas0 as well, since it's used by the GSL.

## Ubuntu 18.04

libgsl23 and libgslcblas0 have a missing symbol on Ubuntu 18.04. I solved the issue installing the Debian Buster version of those three libraries:

* <http://http.us.debian.org/debian/pool/main/g/gsl/libgslcblas0_2.5+dfsg-6_amd64.deb>
* <http://http.us.debian.org/debian/pool/main/g/gsl/libgsl23_2.5+dfsg-6_amd64.deb>
* <http://http.us.debian.org/debian/pool/main/g/gsl/libgsl-dev_2.5+dfsg-6_amd64.deb>

# Installation

To install it using zef (a module management tool):

```
$ zef install Math::Libgsl::Polynomial

```

# AUTHOR

Fernando Santagata [nando.santagata@gmail.com](mailto:nando.santagata@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2020 Fernando Santagata

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


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

# Math::FractionalPart

This *Raku* module provides several routines to operate with the integral and fractional parts of a decimal number. The `*frac*` routines also operate on complex numbers.

# SYNOPSIS

```
use Math::FractionalPart :ALL;
say modf(3.2);            # OUTPUT: «3 0.2␤»
say modf(-3.2);           # OUTPUT: «-3 -0.2␤»
say fractional(-3.2);     # OUTPUT: «-0.2␤»
say fractional-abs(-3.2); # OUTPUT: «0.2␤»

```

# DESCRIPTION

## Fractional routines

### modf

```
sub modf($x is copy --> List) is export(:modf) {...}
=begin code

The c<modf> routine (currently not available in the I<Raku> core) is
similar to those in other languages including I<C>, I<C++>, I<Python>,
and I<Haskell>. It coerces its input into a base 10 number and returns
the integral and fractional parts in a list as shown below. (Note the
C<modf> routine has been submitted as a PR for the Raku core and may
be part of the language soon.)

=begin code :lang<raku>
say modf(3.24);  # OUTPUT: «3 0.24␤»
say modf(-2.7);  # OUTPUT: «-2 -0.7␤»
say modf(10);    # OUTPUT: «10 0␤»
say modf(0x10);  # OUTPUT: «16 0␤»
say modf(-0o10); # OUTPUT: «-8 0␤»

```

Note the sign of the input value is applied to both parts, unless the part is zero. As expected, the fractional part of an integer will be zero.

### fractional

If the user is only interested in the fractional part of a number, there are three different algebraic routines that operate on numbers and return their fractional parts. They all return the same result when operating on non-negative numbers, but all three return different results when operating on negative numbers. See the [References](#References) for more details. Note that Ref. 2 shows *frac* operating in the *complex plane* as `frac(x + i y) = frac(x) + i frac(y)`.

The following table shows the routines (along with their aliase) that have been implemented in this module.

| Name | Raku formula | Example | Notes |
| --- | --- | --- | --- |
| fractional | x - ⌊x⌋ | frac(-1.3): 0.7 | 1 |
| fractional-abs | |x| - ⌊|x|⌋ | afrac(-1.3): 0.3 | 2 |
| fractional-wolfram | x - ⌊|x|⌋⋅sign(x) | ofrac(-1.3): -0.3 | 3 |

## Other exported functions

### convert2decimal

```
say convert2decimal(1.5e-3);    # OUTPUT: «0.0015␤»
say convert2decimal(1.5e-3, 5); # OUTPUT: «0.000015␤»
say convert2decimal(0xa);       # OUTPUT: «10␤»

```

A routine to aid processing numerical data, this routine converts numbers into a decimal format. The user may choose the precision of the output by adding the desired number of places as a second argument.

Aliases: `convert`, `to-decimal`, and `decimal`.

### decimal-places

```
say decimal-places(3.24); # OUTPUT: «2␤»

```

Sometimes it is useful to know the number of digits in the fractional part of a number. For example, in creating tests for operations on numbers, one must often compare results of operations on real numbers when being able to compare to the same numbers of decimal places is required.

Such a function is `decimal-places`, with alias names of `ndp` and `frac-part-digits`. The functions return the number of decimal digits to the right of the decimal point for a real number.

# Notes

1. See Ref. 1, *frac* version 1 (per Graham, Knuth, et alii, 1992).
2. See Ref. 2, *frac* version 2 (per Dainith, 2004); Ref. 3, p. 7. Consider mnemonic 'a' for 'absolute value' or 'astronomical'.
3. See Ref. 3, *frac* version 3 (an *odd function*); Ref. 2: Wolfram's *FractionPart* function. Consider mnemonic 'o' for 'odd function'.

# References

1. Wikipedia article on [Fractional Part](https://en.m.wikipedia.org/wiki/Fractional_part).
2. Wolfram article on [Fractional Part](https://mathworld.wolfram.com/FractionalPart.html).
3. *Celestial Calculations: A Gentle Introduction to Computational Astronomy*, J. L. Lawrence, 2018, MIT Press.

# AUTHOR

Tom Browder [tbrowder@acm.org](mailto:tbrowder@acm.org)

# COPYRIGHT AND LICENSE

© 2021-2023 Tom Browder

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


## dist_zef-jjmerelo-Getopt-Type.md
# Getopt::Type [Test-install distro](https://github.com/JJ/raku-getopt-type/actions/workflows/test.yaml)

Forked from [`tadzik`s](https://github.com/tadzik/Getopt-Type) version

## MAIN? Getopt semantics? Why not both?

```
use Getopt::Type;

sub MAIN(*%opts where getopt(<f|force v|verbose>)) {
    say "Forcing!"   if %opts<force>;
    say "Verbosing!" if %opts<verbose>;
    say %opts.perl;
}

# try `raku -Ilib README.md -fv thisprog.raku`

```


## dist_cpan-BDUGGAN-Cache-Dir.md
# NAME

Cache::Dir - A simple key-value store using the filesystem.

# SYNOPSIS

```
use Cache::Dir;
my $cache = Cache::Dir.new: dir => $*HOME.child('.cache');

$cache.get-cached: 'answer', 42;
$catch.get-cached: 'question', { "why?" };
$cache.exists: 'answer';          # true
$cache.get: 'answer';             # 42
$cache.remove: 'answer';
$cache.get('question');           # why?

```

# DESCRIPTION

This module provides simple key-value storage using the filesytem.

Each key is stored in a separate file. The filename is a SHA1 of the key. If the key not a string or numeric, then it is serialized using `.raku` before taking the sha.

Serialization of the value is done using `.raku` and deserialization is done using `.EVAL`.

Storage is done with atomic write-and-rename, so depends on a filesystem that has those semantics. The age of the key is also filesytem dependent.

Note that the key is not stored, so there's no way to get a list of keys. However it is possible to get a list of "entries", which are objects that include their age, storage path, and value (see Cache::Dir::Entry below).

# METHODS

## method get-cached

```
method get-cached($key, $val) returns Mu
method get-cached($key, &v) returns Mu

```

Return a value if it has been stored, or store the provided value. If the value is a routine, it is called.

## method get

```
method get($key) returns Mu
method get($key, $val) returns Mu
method get($key, &v) returns Mu

```

Get a value with a provided default (but don't store).

## method store

```
method store($key, $value) returns Mu
method store($key, &v) returns Mu

```

Store a value for a key. If the value is a routine, the result of calling it is stored.

## method remove

```
method remove($key) returns Mu

```

Remove a key from the cache.

## method exists

```
method exists($key) returns Bool

```

Check if a key exists in the cache.

## method age-seconds

```
method age-seconds($key) returns Int

```

Return the number of seconds since the key was last modified.

## method flush

```
method flush returns Mu

```

Remove all entries from the cache.

## method get-entries

```
method get-entries returns Array

```

Return a list of Cache::Dir::Entry objects, which can be used to inspect and remove individual entries.

# Cache::Dir::Entry

## method clear

```
method clear returns Mu

```

Remove the entry from the cache.

## method value

```
method value returns Mu

```

Return the value of the entry.

## method age-seconds

```
method age-seconds returns Int

```

Return the number of seconds since the entry was last modified.

## method modified

```
method modified returns DateTime

```

Return the last modified time of the entry.

# AUTHOR

Brian Duggan


## dist_zef-jonathanstowe-JSON-Name.md
# JSON::Name

Provide a trait (and Attribute role) for JSON Marshal/Unmarshal where the JSON names aren't Raku identifiers.

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

## Synopsis

```
use JSON::Name;

class MyClass {
	# The attribute meta object will have the role JSON::Name::NamedAttribute
   # applied and "666.evil.name" will be stored in it's json-name attribute
   has $.nice-name is json-name('666.evil.name');

}

```

## Description

This is released as a dependency of
[JSON::Marshal](https://github.com/jonathanstowe/JSON-Marshal) and
[JSON::Unmarshal](https://github.com/tadzik/JSON-Unmarshal) in order to
save duplication, it is intended to store a separate JSON name for an
attribute where the name of the JSON attribute might be changed, either
for aesthetic reasons or the name is not a valid Raku identifier. It will
of course also be needed in classes thar are going to use JSON::Marshal
or JSON::Unmarshal for serialisation/de-serialisation.

Of course it could be used in other modules for a similar purpose.

## Installation

Assuming you have a working Rakudo installation you should be able to install this with *zef* :

```
# From the source directory

zef install .

# Remote installation

zef install JSON::Name

```

## Support

Suggestions/patches are welcomed via github at <https://github.com/jonathanstowe/JSON-Name>

## Licence

This is free software.

Please see the <LICENCE> file in the distribution

© Jonathan Stowe 2015 - 2021


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

# NAME

Terminal::ANSIParser - ANSI/VT stream parser

# SYNOPSIS

```
use Terminal::ANSIParser;

my @parsed;

# Default: Assume UTF-8 decoded inputs, thus working with codepoints
my &parse-codepoint := make-ansi-parser(emit-item => { @parsed.push: $_ });
parse-codepoint($_) for $input-buffer.list;

# Raw bytes: Assume raw byte stream input, for pre-Unicode terminal emulation
my &parse-byte := make-ansi-parser(emit-item => { @parsed.push: $_ },
                                   :raw-bytes);
parse-byte($_) for $input-buffer.list;

# DEC Pedantic: Ignore xterm extensions, forcing pure DEC VT compatibility
#               (implies :raw-bytes as well)
my &parse-pedantic := make-ansi-parser(emit-item => { @parsed.push: $_ },
                                       :dec-pedantic);
parse-pedantic($_) for $input-buffer.list;

```

# DESCRIPTION

`Terminal::ANSIParser` is a general parser for ANSI/VT escape codes, as defined by the related specs ANSI X3.64, ECMA-48, ISO/IEC 6429, and of course the actual physical DEC VT terminals generally considered the standard for escape code behavior.

The basic `make-ansi-parser()` routine builds and returns a codepoint-by-codepoint (or byte-by-byte, if the `:raw-bytes` option is True) table-based binary parsing state machine, based on (and extended from) the error-recovering state machine built from observed DEC VT behavior described at <https://vt100.net/emu/dec_ansi_parser>.

Each time the parser determines that it has parsed enough input, it emits a token representing the parsed data, which can take one of the following forms:

* A plain codepoint (or byte if `:raw-bytes` is True), for passed through data when no escape sequence is active
* A `Terminal::ANSIParser::Sequence` object, if an escape sequence is parsed
* A `Terminal::ANSIParser::String` object, if a control string is parsed

A few `Sequence` subclasses exist for separate cases:

* `Ignored`: invalid sequences that the parser decides should be ignored
* `Incomplete`: sequences that were cut off by the start of another sequence or the end of the input data (see [End of Input](End of Input) below)
* `SimpleEscape`: simple escape sequences such as function key codes
* `CSI`: parameterized sequences beginning with `CSI` (`ESC [`)

Likewise, `String` has its own subclasses:

* `DCS`: Device Control Strings
* `OSC`: Operating System Commands
* `SOS`: Strings beginning with a general Start Of String indicator
* `PM`: Privacy Message (NOTE: NOT A SECURE FUNCTION)
* `APC`: Application Program Command

## End of Input

End of input can be signaled by parsing an undefined "codepoint"/"byte"; any partial sequence in progress will be flushed as `Incomplete`, and the undefined marker will be emitted as well, so that downstream consumers are also notified that input is complete.

# AUTHOR

Geoffrey Broadwell [gjb@sonic.net](mailto:gjb@sonic.net)

# COPYRIGHT AND LICENSE

Copyright 2021-2024 Geoffrey Broadwell

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


## consumed.md
class X::Seq::Consumed

Error due to trying to reuse a consumed sequence

```raku
class X::Seq::Consumed is Exception { }
```

This exception is thrown when a piece of code tries to reuse a [`Seq`](/type/Seq) which has already been iterated.


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

# NAME

App::Rak::Markdown - convert App::Rak output to Markdown

# SYNOPSIS

```
use App::Rak::Markdown;

my $rmd = App::Rak::Markdown.new;

spurt "result.md", $rmd.markdown(@output);

spurt "result.md", $rmd.run(<--unicode §love>, :tableize<unicode>);

```

# DESCRIPTION

The `App::Rak::Markdown` distribution provides logic to convert the output of [`App::Rak`](https://raku.land/zef:lizmat/App::Rak) to Markdown format.

This can either be done from captured output, or from a set of arguments to be sent to the `rak` command line script.

# METHODS

## new

```
my $rmd = App::Rak::Markdown.new(
  break => '§§§',  # default: '***'
);

```

The `new` method takes 1 named argument:

### :break

The string to be used / checked for between grouped items in `rak`'s output (as documented with the `--break` argument). Defaults to `"***"`.

## markdown

```
say $rmd.markdown(@output);

my $markdown = $rmd.markdown(
  @output,
  :$items,    # store # of items seen, default: don't bother
  :$files,    # store # of files seen, default: don't bother
  :$heads,    # store # of headers seen, default: don't bother
  :headers(0),  # how many levels of headers, default: 1
  :depth<##>,   # markdown string of top headers, default: "###"
  :&tableizer,  # logic to create tables, default: none
  :&splitter,   # headers split logic, default: *.split("/",$headers)
)

```

The `markdown` method takes one positional argument and an optional number of named arguments, and returns a string formatted according to Markdown rules.

It takes one positional argument: a list of lines of `rak` output.

It also takes the following optional named arguments:

* :$items - where to store the # of items seen, default: don't bother
* :$files - where to store the # of files seen, default: don't bother
* :$heads - where to store the # of headers seen, default: don't bother
* :headers - the number of header levels, defaults to 1
* :depth - the markdown string for the top header, default "###"
* :tableizer - logic to create tables, default: none.
* :splitter - headers split logic, default: \*.split("/",$headers)

### Creating tables

If the output from `rak` is fit to create markdown tables for (e.g. the `--unicode` option, the `:tableizer` named argument can be used to indicate a `Callable` that will be called to manage creating markdown tables.

This `Callable` is expected to be called without any arguments: in that case it should return **two** lists: the first with the names of the columns, and the second with formatting info for each column. The formatting info can be specified with the following words:

* left - align text in column to the left
* center - center text in colum
* right - align text in column to the right

Any other word will cause no specific aligning to be done.

If called **with** an argument, it should return a list with the text for each column.

Some standard rak options have a dedicated tableizer, which can be invoked by name. They currently are:

* unicode - tableize for --unicode output
* frequencies - tableize for --frequencies output
* unique - tableize for --unique output

## run

```
say "result.md", $rmd.run(<--unicode §love>, :tableize<unicode>);

```

```
hex | name | graph
:- | :-: | :-:
1F3E9 | <b>LOVE</b> HOTEL | 🏩
1F48C | <b>LOVE</b> LETTER | 💌
1F91F | I <b>LOVE</b> YOU HAND SIGN | 🤟

```

The `run` method is effectively a wrapper around the `markdown` method.

It either returns the Markdown string, or `Nil` if something went wrong, or if not enough lines were received from `rak` to make parsing to Markdown worthwhile.

The positional argument is required: it should contain the arguments to be sent to `rak`.

These named arguments can be specified with the `run` method:

* :@out - where to store output of rak, default: don't bother
* :@err - where to store error output of rak, default: don't bother
* :min-lines - the minumum number of lines in output, default: 0
* :sort(Callable?) - sort the rak output before calling .markdown

Note that the `:@out` named argument only makes sense if the `:min-lines` argument also has been specified with a value greater than 0.

All other named arguments that `markdown` can receive, can also be specified here and will be passed on to the `markdown` method:

* :$items - where to store the # of items seen, default: don't bother
* :$files - where to store the # of files seen, default: don't bother
* :$heads - where to store the # of headers seen, default: don't bother
* :headers - the number of header levels, defaults to 1
* :depth - the markdown string for the top header, default "###"
* :tableizer - logic to create tables, default: none.
* :splitter - headers split logic, default: \*.split("/",$headers)

# AUTHOR

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

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

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

# COPYRIGHT AND LICENSE

Copyright 2025 Elizabeth Mattijsen

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


## dist_zef-FRITH-Math-Libgsl-Constants.md
[![Actions Status](https://github.com/frithnanth/raku-Math-Libgsl-Constants/workflows/test/badge.svg)](https://github.com/frithnanth/raku-Math-Libgsl-Constants/actions)

# NAME

Math::Libgsl::Constants - An interface to libgsl, the Gnu Scientific Library - constants and exceptions.

# SYNOPSIS

```
use Math::Libgsl::Constants;
use Math::Libgsl::Exception;

```

# DESCRIPTION

This module provides the constants and the exception class used by all the other modules.

# CHANGES

From v0.0.11 the version variable `$gsl-version` is a `Version` object.

# Installation

To install it using zef (a module management tool):

```
$ zef install Math::Libgsl::Constants

```

# AUTHOR

Fernando Santagata [nando.santagata@gmail.com](mailto:nando.santagata@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2019 Fernando Santagata

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


## dist_github-vendethiel-Hydrate.md
# Hydrate

Hydrate is a small module to "hydrate" (ORM speak) your object hierarchy, from a bunch of hashes.

Example:

```
use Hydrate;

my class Mes {
  has Int $.height;
  has Int $.width;
}

my class Cont {
  has Str $.name is required;
  has Mes @.mesures;
  has %.data; # optional
}

say hydrate(Cont, {
  name => "Some mesures",
  mesures => [
    {height => 50,  width => 50},
    {height => 150, width => 75},
    {height => 200, width => 200},
  ]
})

```

Result:

```
Cont.new(
  name => "Some mesures",
  mesures => Array[Mes].new(
    Mes.new(height => 50, width => 50),
    Mes.new(height => 150, width => 75),
    Mes.new(height => 200, width => 200)
  ),
  data => {},
)

```


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

# NAME

ValuePair - Provide an immutable Pair value type

# SYNOPSIS

```
use ValuePair;

my $a = ValuePair.new("a",42);
my $b = ValuePair.new( key => "a", value => 42);
my $c = ValuePair.new( (a => 42) );

set($a, $b, $c);  # elems == 1

```

# DESCRIPTION

Raku provides a semi-immutable `Pair` datatype, where the value of a Pair object can be a container, and thus mutable. Therefore, a standard Pair is **not** a value type. The `ValuePair` class provided by this module, is a subclass of `Pair`, and does not allow a mutable value. And thus it can be a value type.

The `.new` method either accepts two positional arguments (key and value), or `key` and `value` named arguments, or an existing `Pair`.

# AUTHOR

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

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

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

# COPYRIGHT AND LICENSE

Copyright 2022, 2024 Elizabeth Mattijsen

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


## dist_github-melezhik-Sparrowdo-Ruby-Bundler.md
# SYNOPSIS

Sparrowdo module to manage Ruby gems via Ruby bundler.

# Travis build status

[![Build Status](https://travis-ci.org/melezhik/sparrowdo-ruby-bundler.svg)](https://travis-ci.org/melezhik/sparrowdo-ruby-bundler)

# INSTALL

```
$ panda install Sparrowdo::Ruby::Bundler

```

# USAGE

Right now all this module does is install RubyGem dependencies straight away from Gemfile.
Probably eventually I will add some other possibilities.

```
$ cat sparrowfile

# runs bundle install for a Gemfile located at the directory:
module_run 'Ruby::Bundler', %(
  gemfile_dir => '/path/to/directory/with/gemfile',
);

```

# Parameters

## gemfile\_dir

Path to the directory with Gemfile. Obligatory, no default value.

## path

The location to install the specified gems to. Optional, no default value.

## verbose

Sets verbose mode for `bundle install` command. Default value is 0 ( quite mode ). Optional.

## debug

Sets debug mode. Optional. Is useful when debugging/troubleshooting the module.

## user

Runs bundler for specified user. It's handy when doing user's `bundle install`, not system wide.

# Author

Alexey Melezhik

# See also

[Ruby bundler](http://bundler.io)


## dist_cpan-TYIL-URL.md
# NAME

URL

# AUTHOR

Patrick Spek [p.spek@tyil.work](mailto:p.spek@tyil.work)

# VERSION

0.0.0

# Description

A Perl 6 library to handle URLs

# Installation

Install this module through [zef](https://github.com/ugexe/zef):

```
zef install URL

```

# License

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


## dist_zef-jonathanstowe-Audio-PortMIDI.md
# Audio::PortMIDI

Raku MIDI access using the portmidi library

[![CI](https://github.com/Raku-Noise-Gang/Audio-PortMIDI/actions/workflows/main.yml/badge.svg)](https://github.com/Raku-Noise-Gang/Audio-PortMIDI/actions/workflows/main.yml)

## Synopsis

```

use Audio::PortMIDI;

my $pm = Audio::PortMIDI.new;

my $dev = $pm.default-output-device;

say $dev;

my $stream = $pm.open-output($dev, 32);

# Play 1/8th note middle C
my $note-on = Audio::PortMIDI::Event.new(event-type => NoteOn, channel => 1, data-one => 60, data-two => 127, timestamp => 0);
my $note-off = Audio::PortMIDI::Event.new(event-type => NoteOff, channel => 1, data-one => 60, data-two => 127, timestamp => 0);

$stream.write($note-on);
sleep .25;
$stream.write($note-off);

$stream.close;

$pm.terminate;

```

See also the <examples> directory for more complete examples.

## Description

This allows you to get MIDI data into or out of your Raku programs. It
provides the minimum abstraction to construct and unpack MIDI messages
and send and receive them via some interface available on your system,
be that ALSA on Linux, CoreMidi on Mac OS/X or whatever it is that
Windows uses. Depending on the way that the portmidi library is built
there may be other interfaces available.

The MIDI specification itself doesn't particularly provide for the
arrangement of the events themselves in time and this is assumed to
be the responsibility of the calling application.

You almost certainly will want to familiarise yourself to some extent
with the [MIDI protocol](http://www.midi.org) and especially the types
of messages that are sent as the interface of PortMIDI and hence this
module is fairly "close to the wire".

## Installation

This requires the [portmidi](http://portmedia.sourceforge.net/portmidi/)
library installed in order to function. Many operating system distributions
will have it available as an installable package or you may be able to
install it from some other compiled package. Installing it from source
is of course possible but you will need a compiler and the appropriate
tools to do so.

On Linux you will need need permissions to the sequencer device, typically
this is provided by a member of the *audio* group however this may differ
by distribution so you might need to check if this doesn't work.

Assuming you have the libray installed and have a working rakudo
installation the you should be able to install directly with `zef`:

```
zef install Audio::PortMIDI

```

Or if you have the source on your local machine (which I recommend as
you can look at the examples):

```
zef install .

```

in the directory that you have downloaded.

## Support

This is a fairly low level API to the MIDI devices, while I have
noted some aspects of the MIDI spec as it effects the implementation
of the module, this is probably not a substitute for some familiarity
with the MIDI specification itself.

Also the degree of compliance and the meaning of certain messages may
differ on specific software or hardware devices so if things aren't
behaving quite as expected you may want to consult the documentation
for your device (most hardware synthesizers and controllers tend to
be fairly well documented in regard of their MIDI implementation.)

I have found that some utility such as `aseqdump` for Linux may
help in finding problems, the [dump-stream](examples/dump-stream)
program in the distribution may help, but using another monitor
may help rule out problems with this module.

If you have a problem or a suggestion then please raise an issue at:

```
 https://github.com/Raku-Noise-Gang/Audio-PortMIDI/issues

```

Obviously if you have some query regarding interoperability with some
particular device or software I am unlikely to be able to help much
if I don't have access to a similar device or software. A dump of the
MIDI events being sent or received may help.

## Licence and Copyright

This is free software. Please see the LICENCE file in the distribution
for the terms of the license.

```
© Jonathan Stowe, 2016, 2017, 2021
© Raku Noise Gang

```


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

# NAME

Proxee — A more usable Proxy with bells

# SYNOPSIS

```
use Proxee;

```

General use:

```
# No self as first arg; simply use a regular block in both code blocks:
my @stuff;
my $stuff := Proxee.new: :STORE{ @stuff.push: $_ }, :FETCH{ @stuff.join: ' | ' }
$stuff = 42;
$stuff = 'meow';
say $stuff; # OUTPUT: «42 | meow␤»

# Single block as arg; keep all related bits in one place
my $stuff2 := Proxee.new: {
    my @stuff;
    :STORE{ @stuff.push: $_    },
    :FETCH{ @stuff.join: ' | ' }
}
$stuff2 = 42;
$stuff2 = 'meow';
say $stuff2; # OUTPUT: «42 | meow␤»

```

Special shared dynamic variable:

```
# Or just use the special shared variable:
my $stuff2 := Proxee.new: :STORE{ $*PROXEE.push: $_ }, :FETCH{ $*PROXEE.join: ' | ' }
$stuff2 = 42;
$stuff2 = 'meow';
say $stuff2; # OUTPUT: «42 | meow␤»

# Default STORErer
my $cuber := Proxee.new: :FETCH{ $*PROXEE³ };
$cuber = 11;
say $cuber; # OUTPUT: «1331␤»

# Default FETCHer
my $squarer := Proxee.new: :STORE{ $*PROXEE = $_² };
$squarer = 11;
say $squarer; # OUTPUT: «121␤»

# Shortcut to assign to $*PROXEE
my $squarer := Proxee.new: :PROXEE{ $_² };
$squarer = 11;
say $squarer; # OUTPUT: «121␤»

```

Coercers (for backward compatibility only):

```
# Coercer types on variables:
my $integral := Proxee.new: Int();
$integral = ' 42.1e0 ';
say $integral; # OUTPUT: «42␤»

# Coercer types on attributes:
class Foo {
    has $.foo is rw;
    submethod TWEAK (:$foo) { ($!foo := Proxee.new: Int()) = $foo }
}
my $o = Foo.new: :foo('42.1e0');
say $o.foo;       # OUTPUT: «42␤»
$o.foo = 12.42;
say $o.foo;       # OUTPUT: «12␤»

```

**Note**: this option is only provided for backwards compatibility. Recent version of Rakudo support coercion types out of the box in variable, parameter and attribute declarations.

# DESCRIPTION

The core [`Proxy`](https://docs.raku.org/type/Proxy) type is a bit clunky to use. This module provides an alternative class `Proxee` with an improved interface, and with a few extra features.

# METHODS

## new

```
multi method new(\coercer where {.HOW ~~ Metamodel::CoercionHOW})
multi method new(:&PROXEE, :&STORE, :&FETCH)
multi method new(&block)

```

Creates and returns a new [`Proxy`](https://docs.perl6.org/type/Proxy) object whose `:STORE` and `:FETCH` `Callable`s have been set to behave like functionality offered by `Proxee`. Possible arguments are:

### An Improved Proxy

The regular functionality of a [`Proxy`](https://docs.perl6.org/type/Proxy) remains, except the `Proxy` object is no longer passed to neither `:FETCH` nor `:STORE` callables. `:FETCH` gets no args; `:STORE` gets 1 arg, the value being stored:

```
my @stuff;
my $stuff := Proxee.new: :STORE{ @stuff.push: $_ }, :FETCH{ @stuff.join: ' | ' }
$stuff = 42;
$stuff = 'meow';
say $stuff; # OUTPUT: «42 | meow␤»

```

In addition, automated storage is available. **Assign** (do not bind, or you'll break it) to `$*PROXEE` variable to store the value in the automated storage and read from it to retrieve that value:

```
my $stuff2 := Proxee.new:
  :STORE{ $*PROXEE.push: $_ },
  :FETCH{ $*PROXEE.join: ' | ' }
$stuff2 = 42;
$stuff2 = 'meow';
say $stuff2; # OUTPUT: «42 | meow␤»

```

The `:STORE` argument is optional and **defaults to** `{ $*PROXEE = $_ }`. The `:FETCH` argument is optional and **defaults to** `{ $*PROXEE }`. The `:PROXEE` argument is like `:STORE`, except it also assigns itsi return value to `$*PROXEE`:

```
my $squarer := Proxee.new: :PROXEE{ $_² };
$squarer = 11;
say $squarer; # OUTPUT: «121␤»

```

Attempting to use both `:PROXEE` and `:STORE` arguments at the same time will throw `Proxee::X::CannotProxeeStore` exception.

### A Callable

You can also pass a single codeblock as an argument. It will be evaluated and its return value will be used as arguments to `Proxee.new` (after slight massaging to make `Pair`s in a `List` be passed as named args).

This feature exists to make it slightly simpler to use closures with a Proxy:

```
my $stuff2 := Proxee.new: {
    my @stuff;
    :STORE{ @stuff.push: $_    },
    :FETCH{ @stuff.join: ' | ' }
}
$stuff2 = 42;
$stuff2 = 'meow';
say $stuff2; # OUTPUT: «42 | meow␤»

```

The above is equivalent to:

```
my $stuff2 := do {
    my @stuff;
    Proxee.new: :STORE{ @stuff.push: $_    },
                :FETCH{ @stuff.join: ' | ' }
}
$stuff2 = 42;
$stuff2 = 'meow';
say $stuff2; # OUTPUT: «42 | meow␤»

```

Watch out you don't accidentally pass a block that would be interpreted as a `Hash`:

```
Proxy.new:    { :STORE{;}, :FETCH{;} } # WRONG; It's a Hash
Proxy.new: -> { :STORE{;}, :FETCH{;} } # RIGHT; It's a Block

```

### Coercer

Pass a coercer as a positional argument to create a coercing proxy that coerces stored values to specified type:

```
my  $Cool-to-Int := Proxee.new: Int(Cool);
$Cool-to-Int = ' 42.70 ';
say $Cool-to-Int; # OUTPUT: «42␤»

$Cool-to-Int = Date.today
# OUTPUT: «Type check failed in Proxee; expected Cool but got Date (Date)␤»

```

**Note**: none of `:&PROXEE`, `:&STORE`, `:&FETCH` can be used together with the coercer argument.

**Note**: this option is only provided for backwards compatibility. Recent version of Rakudo support coercion types out of the box in variable, parameter and attribute declarations.

```
my Int(Cool) $Cool-to-Int = ' 42.70';
say $Cool-to-Int; # OUTPUT: «42␤»

$Cool-to-Int = Date.today
# OUTPUT: «Type check failed in Proxee; expected Cool but got Date (Date)␤»

```

# AUTHOR

Zoffix Znet

# COPYRIGHT AND LICENSE

Copyright 2017 - 2018 Zoffix Znet

Copyright 2019 - 2023 Raku Community

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


## dist_cpan-SCIMON-Trait-Env.md
# NAME

Trait::Env - Trait to set an attribute from an environment variable.

# SYNOPSIS

```
use Trait::Env;
class Test {
    # Sets from %*ENV{HOME}. Undef if the var doesn't exist
    has $.home is env;

    # Sets from %*ENV{TMPDIR}. Defaults to '/tmp'
    has $.tmpdir is env is default "/tmp";

    # Sets from %*ENV{EXTRA_DIR}. Defaults to '/tmp'
    has $.extra-dir is env( :default</tmp> );

    # Set from %*ENV{WORKDIR}. Dies if not set.
    has $.workdir is env(:required);

    # Set from %*ENV{READ_DIRS.+} ordered lexically
    has @.read-dirs is env;

    # Set from %*ENV{PATH} split on ':'
    # has @.path is env(:sep<:>);
    # Or default to the $*DISTRO.path-sep value
    has @.path is env;

    # Set from %*ENV{NAME_MAP} data split on ';' pairs split on ':'
    # EG a:b;c:d => { "a" => "b", "c" => "d" }
    has %.name-map is env( :sep<;>, :kvsep<:> );

    # Get all pairs where the key ends with '_POST'
    has %.post-map is env( :post_match<_POST> );

    # Get all pairs where the Key starts with 'PRE_'
    has %.pre-map is env( :pre_match<PRE_> );

    # Get all pairs where the Key starts with 'PRE_' and ends with '_POST'
    has %.both-map is env( :pre_match<PRE_>, :post_match<_POST> );

    # Parses JSON data
    has $.json-data is env( :json );
}

# Sets from %*ENV{HOME}. Undef if the var doesn't exist
has $home is env;

# Sets from %*ENV{PATH}. Uses default path seperator
has @path is env;

```

# DESCRIPTION

Trait::Env is exports the new trait `is env`.

Note the the variable name will be uppercased and any dashes changed to underscores before matching against the environment. This functionality may be modifiable in the future.

For Booleans the standard Empty String == `False` other String == `True` works but the string "True" and "False" (any capitalization) will also map to True and False respectively.

If a required attribute is not set the code will raise a `X::Trait::Env::Required::Not::Set` Exception.

Defaults can be set using the standard `is default` trait or the `:default` key. Note that for Positional attributes only the `:default` key works.

Positional attributes will use the attribute name (after coercing) as the prefix to scan %\*ENV for. Any keys starting with that prefix will be ordered by the key name lexically and their values put into the attribute.

Alternatively you can use the `:sep` key to specify a seperator, in which case the single value will be read based on the name and the list then created by spliting on this seperator.

If there is a single matching environment variable and no `:sep` key is set then the system will fall back to splitting on the `$*DISTRO.path-sep` value as a seperator.

Hashes can be single value with a `:sep` key to specify the seperator between pairs and a `:kvsep` to specifiy the seperator in each pair between key and value.

Hashes can also be defined by giving a `:post_match` or `:pre_match` arguments (or both). Any Environment variable starting with `:pre_match` is defined or ending with `:post-match` if defined will be included.

Scalars, Positionals and Associative attributes can all be typed.

Variables can also be defined with `is env` following the same rules.

Attribute or Variable only `is env` traits can be loaded individually with `Trait::Env::Attribute` and `Trait::Env::Variable`.

Scalar Attributes and Variables can use `is env(:json)` which will parse the ENV string as a JSON string using `JSON::Tiny`. You can combine this with the `:default` and `:required` options but be aware that the `:default` value should be a data store NOT a JSON value.

# AUTHOR

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

Thanks to Jonathan Worthington and Elizabeth Mattijsen for giving me the framework to build this on. Any mistakes are mine.

# COPYRIGHT AND LICENSE

Copyright 2018 Simon Proctor

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


## dist_github-Raku-Documentable.md
# Documentable, the Raku Doc API [CI Status](https://circleci.com/gh/Raku/Documentable) [Build Status](https://travis-ci.org/Raku/Documentable) [Build Status](https://dev.azure.com/antoniogamiz10/Documentable/_build/latest?definitionId=1&branchName=master) [artistic](https://opensource.org/licenses/Artistic-2.0)

In this repository you can find all logic responsible for generating the
[official Raku documentation](https://docs.Raku.org/) or any other
repository that follows the same specification. Could be used for modules that
include a substantial amount of documentation, for instance (as long
as the layout of the different parts is still the same).

## Table of contents

* [Installation](#installation)
* [Usage](#usage)
* [Documentation](https://raku.github.io/Documentable/)
* [Docker container](#docker-container)
* [Tests](#%C5%A7ests)
* [FAQ](#faq)
* [Authors](#authors)

## Installation

```
$ zef install Documentable

```

If you have already downloaded this repo,

```
$ zef install .

```

## Usage

Documentable uses a [Mustache](https://mustache.github.io/) template and several asset files. So, in order to generate the pages, you need to have these files in your working directory. You can get them with:

```
documentable setup

```

That command will download the [latest assets tarfile](https://github.com/raku/Documentable/releases/download/v1.0.1/assets.tar.gz) in your directory. This tar contains:

* Necessary files to enable highlighting (`highlights` dir).
* The `html` dir containing several icons, graphics, etc. All HTML documents
  generated by `Documentable` will be stored here.
* `assets` dir containing the style sheets used and JS code to enable search functionality.
* `template` dir containing the default template used.
* A `type-graph.txt` example file.

```
Usage:
  bin/documentable setup [-o|--override] -- Downloads default assets to generate the site
  bin/documentable start [--topdir=<Str>] [--conf=<Str>] [-v|--verbose] [-c|--cache] [-p|--primary] [-s|--secondary] [--search-index] [-i|--indexes] [-t|--typegraph] [-f|--force] [--highlight] [--typegraph-file=<Str>] [--highlight-path=<Str>] [--dirs=<Str>] [-a|--all] -- Start the documentation generation with the specified options
  bin/documentable update [--topdir=<Str>] [--conf=<Str>] [-v|--verbose] [--highlight] [--highlight-path=<Str>] -- Check which pod files have changed and regenerate its HTML files.
  bin/documentable clean -- Delete files created by "documentable setup"
  bin/documentable [-V|--version] -- Documentable version

    -y|--yes                  Always accept the operation (to use in scripts)
    --topdir=<Str>            Directory where the pod collection is stored
    --conf=<Str>              Configuration file
    -v|--verbose              Prints progress information
    -c|--cache                Enables the use of a precompiled cache
    -p|--primary              Generates the HTML files corresponding to primary objects
    -s|--secondary            Generates per kind files
    --search-index            Generates the search index
    -i|--indexes              Generates the index files
    -t|--typegraph            Write typegraph visualizations
    -f|--force                Force the regeneration of the typegraph visualizations
    --highlight               Highlights the code blocks
    --typegraph-file=<Str>    TypeGraph file
    --highlight-path=<Str>    Path to the highlighter files
    --dirs=<Str>              Dirs where documentation will be found. Relative to :$topdir
    -a|--all                  Equivalent to -t -p -s -i --search-index

```

See the [CLI documentation](https://raku.github.io/Documentable/language/cli) to learn more, or [the documentation on `documentable.json`](https://raku
.github.io/Documentable/language/configuration-file) to create your own
configuration file.

## Docker container

There is a specific docker container with all necessary dependencies (including the highlighter) at <https://github.com/antoniogamiz/docker-documentable>.

You can see an example about how to use it [here](https://github.com/raku/Documentable/blob/master/.circleci/config.yml).

You can also download the container:

```
docker pull antoniogamiz/documentable

```

Then execute:

```
docker run -it --rm -v "$(pwd)":/documentable antoniogamiz/documentable

```

And now you can execute `documentable` and generate your documentation!

*Note:* Do not forget to add `--highlight --highlight-path="/highlights"` options if you want to get the code highlighted.

## Installing dependencies

#### Rakudo

You need Raku installed. You can install the Rakudo Raku compiler by
downloading the latest Rakudo Star release from
[rakudo.org/downloads/star/](http://rakudo.org/downloads/star/) or the
latests releases via [Rakubrew](https://rakubrew.org/).

#### `zef`

[Zef](https://modules.raku.org/repo/zef) is a Raku module installer. If you
installed Rakudo Star package, it should already be there. Feel free to
use any other way to install the modules needed (see below).

#### Mojolicious / Web Server (OPTIONAL)

Mojolicious is written in Perl 5, so assuming that you use
[`cpanm`](https://metacpan.org/pod/App::cpanminus),
install this now:

```
    $ cpanm -vn Mojolicious

```

#### GraphViz

To generate the svg files for the typegraph representation you need to have installed `graphviz`. If you use Ubuntu/Debian:

```
    $ sudo apt-get install graphviz

```

#### Node & Highlight

This is necessary to apply highlighting to the code examples in the
documentation. We use [Atom highlighting](https://github.com/perl6/atom-language-perl6), so you will need to install [Node.js](https://nodejs.org/en/).

You can set the highlighter up with the default `Makefile` (obtained using `documentable setup`):

```
    make init-highlights

```

#### SASS Compiler

To build the styles, you need to have a SASS compiler. You need to install
the `sass` command

```
    $ sudo apt-get install ruby-sass

```

#### `curl` and `tar`

These programs are used by `documentable setup` to download the default assets
and extract them. If you are on Ubuntu/Debian you will (probably) not
have any problem. If you are using Windows I recommend you to download
the assets yourself from
[this link](https://github.com/raku/Documentable/releases/download/v1.0.1/documentable-assets.tar.gz).

## FAQ

*Question:* Do I need to regenerate all pages when I have only changed one?

*Answer:* No, you can execute `documentable update` to only regenerate those pages affected by your changes.

##

Is your question not here? Then, please [raise an issue](https://github.com/raku/Documentable/issues/new).

# AUTHORS

Antonio Gámiz Delgado <@antoniogamiz>

Moritz Lenz <@moritz>

Jonathan Worthington <@jnthn>

Richard Hainsworth<@finanalyst>

Will Coleda <@coke>

Aleks-Daniel <@AlexDaniel>

Sam S <@smls>

Juan Julián Merelo Guervós <@JJ>

MorayJ <@MorayJ>

Zoffix <@zoffixnet>

Tison <@TisonKun>

Samantha Mcvey <@samcv>

Altai-Man <@Altai-man>

Tom Browder <@tbrowder>

Alexander Moquin <@Mouq>

Wenzel P. P. Peppmeyer <@gfldex>

# COPYRIGHT AND LICENSE

Copyright 2019, 2020 Raku Team

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

We use a [ChangeLog generator](https://github.com/github-changelog-generator/github-changelog-generator) to generate the [CHANGELOG.md file](CHANGELOG.md).


## dist_cpan-ANDINUS-caelum.md
```
                  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                 CAELUM
                   Caelum is a text based Cee-lo game

                                Andinus
                  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents
─────────────────

Demo
Installation
Documentation
News

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Website
 Source
 GitHub (mirror)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Demo
════

  This was recorded with `asciinema'.

  [https://asciinema.org/a/410291.png]

  ⁃ Caelum v0.1.1:

[https://asciinema.org/a/410291.png]

Installation
════════════

  Caelum is released to CPAN, you can get it from there or install it
  from source. In any case, `zef' is required to install the
  distribution.

  You can run Caelum without `zef'. Just run `raku -Ilib bin/caelum'
  from within the source directory.

Release
───────

  1. Run `zef install caelum'.

  Caelum should be installed, try running `caelum --version' to confirm.

From Source
───────────

  You can either download the release archive generated by cgit/GitHub
  or clone the project if you have `git' installed.

Without `git'
╌╌╌╌╌╌╌╌╌╌╌╌╌

  1. Download the release:
     •
     •
  2. Extract the file.
  3. Run `zef install .' in source directory.

With `git'
╌╌╌╌╌╌╌╌╌╌

  All commits will be signed by my [PGP Key].

  ┌────
  │ # Clone the project.
  │ git clone https://git.tilde.institute/andinus/caelum
  │ cd caelum
  │
  │ # Install octans.
  │ zef install .
  └────

[PGP Key]

Documentation
═════════════

Implementation
──────────────

  Caelum is an implementation of [Cee-lo without a bank]. The bet amount
  is set to be the average of whatever each player decides.

[Cee-lo without a bank]

Options
───────

players
╌╌╌╌╌╌╌

  Number of players. Default is 2, should be an integer greater than or
  equal to 2.

News
════

v0.1.1 - 2021-04-27
───────────────────

  ⁃ Fixed bug in winning logic.

v0.1.0 - 2021-04-27
───────────────────

  Initial implementation.

```


## scheduler.md
role Scheduler

Scheme for automatically assigning tasks to threads

```raku
role Scheduler {
    has &.uncaught_handler is rw
}
```

A scheduler is a piece of code that determines which resources to use to run which task, and when. This role contains code that will be the same for all kinds of schedulers.

Some operations for example on [`Proc::Async`](/type/Proc/Async), [`Promise`](/type/Promise), [`Supply`](/type/Supply) allow you to specify a scheduler explicitly; they generally expect those schedulers to follow the interface defined by `Scheduler`.

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

## [method uncaught\_handler](#role_Scheduler "go to top of document")[§](#method_uncaught_handler "direct link")

```raku
method uncaught_handler() is rw
```

RW-Accessor for the handler that is caught for uncaught exceptions from the code that is being scheduled and run.

## [method cue](#role_Scheduler "go to top of document")[§](#method_cue "direct link")

```raku
method cue(&code, Instant :$at, :$in, :$every, :$times = 1; :&catch --> Cancellation)
```

Schedules a callable (`&code`) for execution and returns an instantiated [`Cancellation`](/type/Cancellation) object to cancel the scheduling of the code for execution (which is especially important if you specify the `:every ( time )` named parameter). The adverbs control when and how the code is run:

* `$at` can be an [`Instant`](/type/Instant) before which the code won't be run. Alternatively `$in` is the number of seconds (possibly fractional) to wait before running the code. If `$at` is in the past or `$in` is negative, the delay is treated as zero. Implementations may equate to zero very small values (e.g. lower than 0.001s) of `$in` or result of `$at` - [now](/routine/now).
* If `$every` is specified, it is interpreted as the number of seconds (possibly fractional) to wait before re-executing the code. Implementations may treat too-small values as lowest resolution they support, possibly warning in such situations; e.g. treating `0.0001` as `0.001`.
* `$times` tells the scheduler how many times to run the code.
* `&catch` is called with the [`Exception`](/type/Exception) as its sole argument if `&code` dies.
* If `$at` or `$in` are `Inf`, `&code` will never be run; if `$every` is `Inf`, `&code` will only be run once. If any of the three are `-Inf`, `&code` will be run immediately. If any of the three are `NaN`, an [`X::Scheduler::CueInNaNSeconds`](/type/X/Scheduler/CueInNaNSeconds) exception will be thrown. This only applies to releases 2019.05 and later.

One should call the `cancel` method on the returned [`Cancellation`](/type/Cancellation) object to cancel the (possibly repeated) cueing of the code.

## [method loads](#role_Scheduler "go to top of document")[§](#method_loads "direct link")

```raku
method loads()
```

This is a method stub, should be re-implemented when subclassing.

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

Type relations for `Scheduler`

raku-type-graph

Scheduler
Scheduler

Mu
Mu

Any
Any

Any->Mu

ThreadPoolScheduler
ThreadPoolScheduler

ThreadPoolScheduler->Scheduler

ThreadPoolScheduler->Any

CurrentThreadScheduler
CurrentThreadScheduler

CurrentThreadScheduler->Scheduler

CurrentThreadScheduler->Any

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


## dist_github-azawawi-OpenCV.md
# OpenCV

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

This provides a simple Perl 6 object-oriented NativeCall wrapper for the
[OpenCV](http://opencv.org) library.

## Example

```
use v6;
use OpenCV;

# Read the image from the disk
my $image = imread( "sample.png" );

# Show the image in a window
namedWindow( "Sample", 1 );
imshow( "Sample", $image );

# Wait for a key press to exit
waitKey;

```

For more examples, please see the <examples> folder.

## OpenCV Installation

Please follow the instructions below based on your platform:

### Linux (Debian)

* To install OpenCV 2.4 development libraries, please run:

```
$ sudo apt-get install libopencv-dev g++

```

## macOS

* To install OpenCV 2.4 development libraries, please run:

```
$ brew update
$ brew tap homebrew/science
$ brew install opencv

```

## Windows

A precompiled 64-bit windows DLL binary is already provided so it should work
on 64-bit windows operating systems.

## Installation

To install it using zef (a module management tool bundled with Rakudo Star):

```
$ zef install OpenCV

```

## Testing

* To run tests:

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

```

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

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

```

## Development Notes

If you need to change the C++ to C library wrapper without doing a
`zef install .`, please run:

```
$ zef build .

```

## Author

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

## License

MIT License


## dist_github-cygx-Uni63.md
# Uni63 [Build Status](https://travis-ci.org/cygx/p6-uni63)

A Unicode encoding scheme suitable for name mangling

# Synopsis

```
    use Uni63;

    my $enc = Uni63::enc('Leberkäse');
    my $dec = Uni63::dec($enc);

```

# Description

The 62 alphanumeric ASCII characters encode themselves. A 63rd character `_` is
used to mark escape sequences.

The escape character is followed by a single digit, indicating the number of
characters that encode the next Unicode codepoint. Contrary to the module name,
the codepoint is encoded in base-62 with digits `0..9`, `a..z`, `A..Z`.

The decoder does not validate its input:

* An invalid character or an underscore that is not followed by a valid
  escape sequence will be passed through, thus re-encoding a decoded string
  may not round trip.
* The numeric value of any escape sequence that follows the given scheme
  will be passed on to `chr`, even if the value lies outside the range of
  Unicode codepoints.

# Bugs and Development

Development happens at [GitHub](https://github.com/cygx/p6-uni63). If you
found a bug or have a feature request, use the
[issue tracker](https://github.com/cygx/p6-uni63/issues) over there.

# Copyright and License

Copyright (C) 2015 by [cygx@cpan.org](mailto:cygx@cpan.org)

Distributed under the
[Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt)