[ { "path": ".github/ISSUE_TEMPLATE/bug-report-or-feature-request.md", "content": "---\nname: Bug report or feature request\nabout: Create a report to help us improve\ntitle: ''\nlabels: docs\nassignees: ''\n\n---\n\n## Problem or new feature\n\nA clear and concise description of what the bug is, including links to the page where you have found it.\n\n## Suggestions\n\nIf applicable, suggest something towards the solution.\n" }, { "path": ".github/pull_request_template.md", "content": "## The problem\n\n\n## Solution provided\n\n\n" }, { "path": ".github/workflows/test.yml", "content": "name: test\non:\n push:\n branches: [ main ]\n paths:\n - '**'\n pull_request:\n branches: [ main ]\n paths:\n - '**'\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: ${{ github.event_name == 'pull_request' && 2 || 0 }}\n - name: Get changed files\n id: changed-files\n run: |\n if ${{ github.event_name == 'pull_request' }}; then\n echo \"changed_files=$(git diff --name-only -r HEAD^1 HEAD | xargs)\" >> $GITHUB_OUTPUT\n else\n echo \"changed_files=$(git diff --name-only ${{ github.event.before }} ${{ github.event.after }} | xargs)\" >> $GITHUB_OUTPUT\n fi\n - name: Run tests\n run: ./util/github-action-test.sh t\n env:\n TEST_IMAGE: docker.io/coke/rakudo-docs-test\n TEST_FILES: ${{ steps.changed-files.outputs.changed_files }}\n" }, { "path": ".gitignore", "content": "# Precompilation folders\n.precomp/\n.pod-precomp\n.pod-cache\n\n# Generated files for testing\nt/pws/aspell.pws\nretest\n\n# Cached file for building pages\nutil/Grammar.nqp\n\n# IDE\n*.iml\n\n# website clone for testing\ndoc-website\n" }, { "path": "Build.rakumod", "content": "class Build {\n BEGIN {\n note q:to/END/;\n This repository is not intended to be installed!\n View the latest HTML version at https://docs.raku.org/\n Command line viewer at https://github.com/raku/rakudoc\n END\n die;\n }\n}\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing\n\nYour patches to `Raku/doc` are very welcome, and if you want to\nhelp,\n[please read this guide](https://github.com/Raku/doc/wiki) as\nwell as the detailed instructions below.\n\nThis document describes how to get started and helps to provide documentation\nthat adheres to the common style and formatting guidelines.\n\nYour contributions here will be credited in the next Rakudo release\nannouncement. Your name from the commit log will be used. If you'd like to be\ncredited under a different name, please add it to the local [CREDITS](CREDITS)\nfile (or ask someone to do it for you until you have commit privileges).\n\nIf you have any questions regarding contributing to this project, please ask\nin the [#raku IRC channel](https://raku.org/community/irc).\n\n# TABLE OF CONTENTS\n- [General principles](#general-principles)\n- [Writing code examples](#writing-code-examples)\n- [Indexing content](#indexing-content)\n- [Adding a new Language document](#adding-a-new-language-document)\n- [Documenting types](#documenting-types)\n- [Writing and Testing Examples](#writing-and-testing-examples)\n- [Debug mode](#debug-mode)\n - [Invisible index anchors](#invisible-index-anchors)\n - [Viewport size](#viewport-size)\n - [Broken links](#broken-links)\n - [Heading numbering](#heading-numbering)\n- [Reporting bugs](#reporting-bugs)\n- [Contributing pull requests](#contributing-pull-requests)\n- [Dependency installation](#dependency-installation)\n - [Rakudo](#rakudo)\n - [Zef](#zef)\n\n## General principles\n\n* Please use the present tense unless writing about history or upcoming events or planned features\n* Prefer [active voice](https://en.wikipedia.org/wiki/Active_voice) to the [passive voice](https://en.wikipedia.org/Passive_voice#In_English) with \"by\": \"this is used by crafty programmers\" → \"crafty programmers use this\"\n* Link to external resources (like Wikipedia) for topics that are not\n directly related to Raku (like the math that our routines implement).\n* Duplicate small pieces of information rather than rely on linking.\n* Be explicit about routine signatures. If a method accepts an `*%args`,\n but treats some of them specially, list them separately.\n* Check out [the styleguide](writing-docs/STYLEGUIDE.md) for further guidance.\n\n## Documenting versions\n\n* If you are adding a recently introduced feature, please indicate in a note\n which version it was introduced in.\n* If you change an example to use the new feature, leave the old\n example if it's still working, at least while it's not obsolete, for people\n who have not upgraded yet, clarifying in the text around it the versions it\n will run with.\n\n## Writing Code Examples\n\nSee [EXAMPLES.md](writing-docs/EXAMPLES.md) for detailed information on the options\navailable when writing code examples in the documentation.\n\n## Indexing content\n\nSee [INDEXING.md](writing-docs/INDEXING.md) for detailed information on how\nindexing of terms and locations in the documentation works.\n\n## Adding a new Language document\n\nWe suggest you discuss proposing a new Language document on the #raku\nchannel and/or the [issues for this repository](https://github.com/Raku/doc/issues)\nbefore you proceed further. After you get consensus on a title, subtitle,\nsection, and filename, you can add the document by following these steps:\n\n+ create a **filename.rakudoc** file in the **doc/Language** directory and\n ensure it adheres to the conventions in\n [CREATING-NEW-DOCS.md](writing-docs/CREATING-NEW-DOCS.md).\n\n## Documenting types\n\nThe Pod6 documentation of types is located in the `doc/Type` directory and\nsubdirectories of this repository. For example the Pod6 file of `X::Bind::Slice`\nlives in `doc/Type/X/Bind/Slice.pod6`.\n\nTo start contributing, fork and checkout the repository, find the document\nyou want to improve, commit your changes, and create a pull request. Should\nquestions come up in the process feel free to ask in\n[#raku IRC channel](https://raku.org/community/irc).\n\nIf the documentation for a type does not exist, create the skeleton of the doc\nwith the helper tool `util/new-type.raku`. Say you want to create `MyFunnyRole`:\n\n $ raku util/new-type.raku --kind=role MyFunnyRole\n\nFill the documentation file `doc/Type/MyFunnyRole.rakudoc` like this:\n\n```raku\n=TITLE role MyFunnyRole\n\n=SUBTITLE Sentence or half-sentence about what it does\n\n role MyFunnyRole does OtherRole is SuperClass { ... }\n\nLonger description here about what this type is, and\nhow you can use it.\n\n # usage example goes here\n\n=head1 Methods\n\n=head2 method do-it\n\n method do-it(Int $how-often --> Nil:D)\n\nMethod description here\n\n MyFunnyRole.do-it(2); # OUTPUT: «example output␤»\n```\n\nWhen documenting a pair of a sub and a method with the same functionality, the\nheading should be `=head2 routine do-it`, and the next thing should be two or\nmore lines with the signatures. Other allowed words instead of `method` are\n`sub`, `trait`, `infix`, `prefix`, `postfix`, `circumfix`, `postcircumfix`,\n`term`. If you wish to hide a heading from any index, prefix it with the empty\ncomment `Z<>`.\n\nWhen providing a code example result or output, use this style:\n\n```raku\n# For the result of an expression.\n1 + 2; # RESULT: «3»\n# For the output.\nsay 1 + 3; # OUTPUT: «3␤»\n# For the explanatory comment\ndo-work; # We call do-work sub\n```\n\n## Running tests\n\nAny contributions should pass the `make test` target. This insures basic\nintegrity of the documentation, and is run automatically by a corresponding\ntravis build. Even edits made via the GitHub editor should pass this test.\n\nThe repo should also pass `make xtest` most of the time - this includes\ntests about whitespace and spelling that might be difficult to get right\non an initial commit, and shouldn't be considered to break the build. However,\nif you're contributing a patch or pull request, this must pass.\n\nIf you have local modifications and want to insure they pass xtest before\ncommitting, you can use this command to test only modified files:\n\n TEST_FILES=`git status --porcelain --untracked-files=no | awk '{print $2}'` make xtest\n\n## Writing and Testing Examples\n\nSee [Writing and Testing Examples](writing-docs/EXAMPLES.md)\n\n## Debug mode\n\nOn the right side of the footer you can find [Debug: off]. Click it and reload\nthe page to activate debug mode. The state of debug mode will be remembered by\n`window.sessionStorage` and will not survive a browser restart or opening the\ndocs in a new tab.\n\n### Broken links\n\nTo check for broken links use debug mode. Any spotted broken link will be\nlisted under the search input. Please note that some external links may not get\nchecked depending on your browser settings.\n\n### Heading numbering\n\nPlease check if the headings you add are well structured. You can use [debug mode](#debug-mode)\nto display heading numbers.\n\n## Reporting bugs\n\nReport issues with the content on [github](https://github.com/Raku/doc/issues).\nThis includes missing or incorrect documentation, as well as information about\nversioning (e.g., \"method foo\" only available in raku v6.d).\n\nFor issues with the website functionality (as opposed to the content), for\nexamples issues with search,\nplease report on [doc-website](https://github.com/Raku/doc-website/issues).\n\n## Contributing pull requests\n\nIf you would like to contribute documentation or other bug fixes, please use\n[GitHub's pull requests (PRs)](https://github.com/Raku/doc/pulls). For a complete\nrecipe for a new PR contributor, check [this PR guide](https://github.com/tbrowder/tidbits/blob/master/Contributing-PRs.md).\n\n### Dependency installation\n\n#### Raku\n\nSee [rakudo.org](https://rakudo.org/downloads) for Raku installation information.\n\n#### Zef\n\nTo install any prerequisites for this module, use:\n\n $ zef install --deps-only .\n\nSee [zef](https://github.com/ugexe/zef) for any questions on zef.\n\n### Test the documentation\n\nThe [Makefile] has a lot of targets to help with testing the documentation\nUse this command to see them:\n\n $ make help\n" }, { "path": "CREDITS", "content": "=pod\n\n Following in the steps of other open source projects that\n eventually take over the world, here is the partial list\n of people who have contributed to this documentation.\n It is sorted by name and formatted to allow easy\n grepping and beautification by scripts.\n The fields are: name (N), email (E), web-address (W),\n description (D), GitHub username (U) and snail-mail\n address (S).\n\n Thanks,\n\n The Raku/doc Team\n PS: Yes, this looks remarkably like the Linux CREDITS format\n PPS: This file is encoded in UTF-8\n\n----------\n\nN: ab5tract\nE: john.haltiwanger@gmail.com\n\nN: abcxyzp\nE: abcxyz@cpan.org\n\nN: Adrian Kreher\nE: avuserow@gmail.com\n\nN: Ahmad M. Zawawi\nE: ahmad.zawawi@gmail.com\n\nN: Akim Demaille\nE: akim@lrde.epita.fr\n\nN: Alex Chen\nU: TisonKun\nU: W4anD0eR96\nE: wander4096@gmail.com\n\nN: Alexander Moquin\nE: alexmoquin@gmail.com\n\nN: andreoss\nE: andreoss@sdf.org\n\nN: Andrew Egeler\nE: andrew@egeler.us\n\nN: Ben Noordhuis\nE: info@bnoordhuis.nl\n\nN: Ben Tyler\nE: benjamin.tyler@gmail.com\n\nN: Brent Laabs\nE: bslaabs@gmail.com\n\nN: Brian Duggan\nU: bduggan\nE: bduggan@matatu.org\n\nN: Brock Wilcox\nE: awwaiid@thelackthereof.org\n\nN: Bruce Gray\nE: bruce.gray@acm.org\n\nN: Calvin Schwenzfeier\nE: cschwenz@users.noreply.github.com\n\nN: Carl Hayter\nE: hayter@usc.edu\n\nN: Carl Mäsak\nE: cmasak@gmail.com\n\nN: Carlin\nE: carbin@users.noreply.github.com\n\nN: Chloé Kekoa\nE: rightfold+ck@gmail.com\nW: foldr.nl\nU: chloekek\n\nN: Christopher Bottoms\nE: molecules@users.noreply.github.com\n\nN: Cole Keirsey\nE: ckeirsey2@gmail.com\n\nN: cygx\nE: cygx@users.noreply.github.com\n\nN: Cédric Vincent\nE: cedric@reproducible.io\n\nN: Daniel Green\nU: MasterDuke17\nE: ddgreen@gmail.com\n\nN: David Farrell\nE: davidnmfarrell@gmail.com\n\nN: David H. Adler\nE: dha@pobox.com\n\nN: David M. Cawthon\nE: dmc00@fastmail.com\n\nN: David Simon Schultz\nU: schultzdavid\nE: dss@noreply.codeberg.org\n\nN: Dmitriy Olshevskiy\nE: olshevskiy87@bk.ru\n\nN: Edwin Steiner\nE: edwin.steiner@gmx.net\n\nN: Elizabeth Mattijsen\nU: lizmat\nE: liz@wenzperl.nl\n\nN: Eric Forste\nU: arkiuat\nE: arkiuat@mm.st\n\nN: ennio\nE: scriplit@yahoo.com\n\nN: Felix Herrmann\nE: felix@herrmann-koenigsberg.de\n\nN: Florian Helmberger\nE: fh@25th-floor.com\n\nN: Gabor Szabo\nE: gabor@szabgab.com\n\nN: Geoffrey Broadwell\nE: geoff@broadwell.org\n\nN: GlitchMr\nE: glitchmr@myopera.com\n\nN: Graham Todd\nE: info@opendevelopment.net\n\nN: Heiko Jansen\nE: heiko_jansen@web.de\n\nN: Ilmari Vacklin\nE: ilmari.vacklin@reaktor.fi\n\nN: isBEKaml\nE: nastavs@gmail.com\n\nN: Jeremy Studer\nE: studerj1.mail@gmail.com\n\nN: Jimmy Zhuo\nE: zhuomingliang@yahoo.com.cn\n\nN: JJ Merelo\nN: Juan Julián Merelo Guervós\nE: jjmerelo@gmail.com\nU: JJ\n\nN: Joelle Maslak\nE: jmaslak@antelope.net\nU: jmaslak\n\nN: John Gabriele\nE: jgabriele@fastmail.fm\n\nN: Joji Antony\nE: simula67@gmail.com\n\nN: Jonathan Scott Duff\nE: duff@pobox.com\n\nN: Jonathan Stowe\nE: jns+git@gellyfish.co.uk\n\nN: Jonathan Worthington\nE: jnthn@jnthn.net\n\nN: Justin DeVuyst\nE: justin@devuyst.com\n\nN: Kamil Kułaga\nE: teodozjan@gmail.com\n\nN: Karl Yerkes\nE: karl.yerkes@gmail.com\n\nN: Klaus Brüssel\nE: trixium@web.de\n\nN: Konrad Borowski\nE: glitchmr@myopera.com\n\nN: LLFourn\nE: LLFourn@users.noreply.github.com\n\nN: Lloyd Fournier\nE: LLFourn@users.noreply.github.com\n\nN: Luca Ferrari\nE: fluca1978@gmail.com\nW: https://fluca1978.github.io\nU: fluca1978\n\nN: lue\nE: rnddim@gmail.com\n\nN: lumimies\nE: lumimies@gmail.com\n\nN: Marcel Timmerman\nE: mt1957@gmail.com\n\nN: Matthew\nE: rnddim@gmail.com\n\nN: Matthias Krull\nE: m.krull@uninets.eu\n\nN: mdinger\nE: mdinger.bugzilla@gmail.com\n\nN: Mike Francis\nE: ungrim97@gmail.com\n\nN: Moray Jones\nE: github@mrjones.co.uk\n\nN: Moritz Lenz\nE: moritz@faui2k3.org\nU: moritz\nU: moritz_\nD: Initial p6doc development, documentation\n\nN: Mouq\nE: alexmoquin@gmail.com\n\nN: muraiki\nE: muraiki@users.noreply.github.com\n\nN: Nami-Doc\nE: vendethiel@hotmail.fr\n\nN: Nathan Brown\nE: nbrown04@gmail.com\n\nN: Nick Logan\nE: nlogan@gmail.com\n\nN: niner\nE: nine@detonation.org\n\nN: Noel Maddy\nE: zhtwnpanta@gmail.com\n\nN: Nova Patch\nE: patch@cpan.org\n\nN: Patrick R. Michaud\nU: pmichaud\nD: Perl 6 (Rakudo Perl) lead developer\nE: pmichaud@pobox.com\n\nN: Paul Cochrane\nE: paul@liekut.de\n\nN: Pawel Pabian\nE: bbkr@post.pl\n\nN: Philippe Bruhat (BooK)\nE: book@cpan.org\n\nN: Prog Rammer\nE: prammer1@gmail.com\n\nN: raiph\nE: ralphdjmellor@gmail.com\n\nN: raydiak\nE: raydiak@cyberuniverses.com\n\nN: Ricardo Signes\nE: rjbs@users.noreply.github.com\n\nN: Rob Hoelz\nE: rob@hoelz.ro\n\nN: Ronald Schmidt\nE: ronaldxs@software-path.com\n\nN: ronaldxs\nE: ronaldxs@software-path.com\n\nN: Salve J. Nilsen\nE: sjn@cpan.org\n\nN: Sam S\nE: smls75@gmail.com\n\nN: sergot\nE: filip@sergot.pl\n\nN: Sgeo\nE: sgeoster@gmail.com\n\nN: ShimmerFairy\nE: rnddim@gmail.com\n\nN: Sizhe Zhao\nE: prc.zhao@outlook.com\nU: Prince213\n\nN: skids\nE: bri@abrij.org\n\nN: smls\nE: smls75@gmail.com\n\nN: Stefan Seifert\nE: nine@detonation.org\n\nN: Sterling Hanenkamp\nE: sterling@hanenkamp.com\n\nN: Steve Mynott\nE: steve.mynott@gmail.com\n\nN: Stéphane Payrard\nE: cognominal@gmail.com\n\nN: Tadeusz Sośnierz\nE: tadzikes@gmail.com\n\nN: Tim Nelson\nE: wayland@wayland.id.au\n\nN: Tim Smith\nE: tim.dolores@gmail.com\n\nN: timo\nE: timonator@perpetuum-immobile.de\n\nN: Timo Paulssen\nE: timonator@perpetuum-immobile.de\n\nN: TimToady\nE: larry@wall.org\n\nN: Tobias Leich\nE: email@froggs.de\n\nN: Tokuhiro Matsuno\nE: tokuhirom@gmail.com\n\nN: Tom Browder\nE: tom.browder@gmail.com\nU: tbrowder\n\nN: Trey Harris\nE: treyharris@gmail.com\n\nN: Claudio Ramirez\nE: pub.claudio@gmail.com\n\nN: ugexe\nE: nlogan@gmail.com\n\nN: usev6\nE: use_v6@aglaz.de\n\nN: ven\nE: vendethiel@hotmail.fr\n\nN: VZ\nE: vz-github@zeitlins.org\n\nN: Wenzel P. P. Peppmeyer\nU: gfldex\nE: wenzel.peppmeyer@gmx.de\n\nN: Will Coleda\nN: Coke\nE: will@coleda.com\n\nN: Xtreak\nE: tirkarthi@users.noreply.github.com\n\nN: Zoffix Znet\nE: cpan@zoffix.com\n\n=cut\n" }, { "path": "LICENSE", "content": "\t\t The Artistic License 2.0\n\n\t Copyright (c) 2000-2006, The Perl Foundation.\n\n Everyone is permitted to copy and distribute verbatim copies\n of this license document, but changing it is not allowed.\n\nPreamble\n\nThis license establishes the terms under which a given free software\nPackage may be copied, modified, distributed, and/or redistributed.\nThe intent is that the Copyright Holder maintains some artistic\ncontrol over the development of that Package while still keeping the\nPackage available as open source and free software.\n\nYou are always permitted to make arrangements wholly outside of this\nlicense directly with the Copyright Holder of a given Package. If the\nterms of this license do not permit the full use that you propose to\nmake of the Package, you should contact the Copyright Holder and seek\na different licensing arrangement.\n\nDefinitions\n\n \"Copyright Holder\" means the individual(s) or organization(s)\n named in the copyright notice for the entire Package.\n\n \"Contributor\" means any party that has contributed code or other\n material to the Package, in accordance with the Copyright Holder's\n procedures.\n\n \"You\" and \"your\" means any person who would like to copy,\n distribute, or modify the Package.\n\n \"Package\" means the collection of files distributed by the\n Copyright Holder, and derivatives of that collection and/or of\n those files. A given Package may consist of either the Standard\n Version, or a Modified Version.\n\n \"Distribute\" means providing a copy of the Package or making it\n accessible to anyone else, or in the case of a company or\n organization, to others outside of your company or organization.\n\n \"Distributor Fee\" means any fee that you charge for Distributing\n this Package or providing support for this Package to another\n party. It does not mean licensing fees.\n\n \"Standard Version\" refers to the Package if it has not been\n modified, or has been modified only in ways explicitly requested\n by the Copyright Holder.\n\n \"Modified Version\" means the Package, if it has been changed, and\n such changes were not explicitly requested by the Copyright\n Holder.\n\n \"Original License\" means this Artistic License as Distributed with\n the Standard Version of the Package, in its current version or as\n it may be modified by The Perl Foundation in the future.\n\n \"Source\" form means the source code, documentation source, and\n configuration files for the Package.\n\n \"Compiled\" form means the compiled bytecode, object code, binary,\n or any other form resulting from mechanical transformation or\n translation of the Source form.\n\n\nPermission for Use and Modification Without Distribution\n\n(1) You are permitted to use the Standard Version and create and use\nModified Versions for any purpose without restriction, provided that\nyou do not Distribute the Modified Version.\n\n\nPermissions for Redistribution of the Standard Version\n\n(2) You may Distribute verbatim copies of the Source form of the\nStandard Version of this Package in any medium without restriction,\neither gratis or for a Distributor Fee, provided that you duplicate\nall of the original copyright notices and associated disclaimers. At\nyour discretion, such verbatim copies may or may not include a\nCompiled form of the Package.\n\n(3) You may apply any bug fixes, portability changes, and other\nmodifications made available from the Copyright Holder. The resulting\nPackage will still be considered the Standard Version, and as such\nwill be subject to the Original License.\n\n\nDistribution of Modified Versions of the Package as Source\n\n(4) You may Distribute your Modified Version as Source (either gratis\nor for a Distributor Fee, and with or without a Compiled form of the\nModified Version) provided that you clearly document how it differs\nfrom the Standard Version, including, but not limited to, documenting\nany non-standard features, executables, or modules, and provided that\nyou do at least ONE of the following:\n\n (a) make the Modified Version available to the Copyright Holder\n of the Standard Version, under the Original License, so that the\n Copyright Holder may include your modifications in the Standard\n Version.\n\n (b) ensure that installation of your Modified Version does not\n prevent the user installing or running the Standard Version. In\n addition, the Modified Version must bear a name that is different\n from the name of the Standard Version.\n\n (c) allow anyone who receives a copy of the Modified Version to\n make the Source form of the Modified Version available to others\n under\n\n\t(i) the Original License or\n\n\t(ii) a license that permits the licensee to freely copy,\n\tmodify and redistribute the Modified Version using the same\n\tlicensing terms that apply to the copy that the licensee\n\treceived, and requires that the Source form of the Modified\n\tVersion, and of any works derived from it, be made freely\n\tavailable in that license fees are prohibited but Distributor\n\tFees are allowed.\n\n\nDistribution of Compiled Forms of the Standard Version\nor Modified Versions without the Source\n\n(5) You may Distribute Compiled forms of the Standard Version without\nthe Source, provided that you include complete instructions on how to\nget the Source of the Standard Version. Such instructions must be\nvalid at the time of your distribution. If these instructions, at any\ntime while you are carrying out such distribution, become invalid, you\nmust provide new instructions on demand or cease further distribution.\nIf you provide valid instructions or cease distribution within thirty\ndays after you become aware that the instructions are invalid, then\nyou do not forfeit any of your rights under this license.\n\n(6) You may Distribute a Modified Version in Compiled form without\nthe Source, provided that you comply with Section 4 with respect to\nthe Source of the Modified Version.\n\n\nAggregating or Linking the Package\n\n(7) You may aggregate the Package (either the Standard Version or\nModified Version) with other packages and Distribute the resulting\naggregation provided that you do not charge a licensing fee for the\nPackage. Distributor Fees are permitted, and licensing fees for other\ncomponents in the aggregation are permitted. The terms of this license\napply to the use and Distribution of the Standard or Modified Versions\nas included in the aggregation.\n\n(8) You are permitted to link Modified and Standard Versions with\nother works, to embed the Package in a larger work of your own, or to\nbuild stand-alone binary or bytecode versions of applications that\ninclude the Package, and Distribute the result without restriction,\nprovided the result does not expose a direct interface to the Package.\n\n\nItems That are Not Considered Part of a Modified Version\n\n(9) Works (including, but not limited to, modules and scripts) that\nmerely extend or make use of the Package, do not, by themselves, cause\nthe Package to be a Modified Version. In addition, such works are not\nconsidered parts of the Package itself, and are not subject to the\nterms of this license.\n\n\nGeneral Provisions\n\n(10) Any use, modification, and distribution of the Standard or\nModified Versions is governed by this Artistic License. By using,\nmodifying or distributing the Package, you accept this license. Do not\nuse, modify, or distribute the Package, if you do not accept this\nlicense.\n\n(11) If your Modified Version has been derived from a Modified\nVersion made by someone other than you, you are nevertheless required\nto ensure that your Modified Version complies with the requirements of\nthis license.\n\n(12) This license does not grant you the right to use any trademark,\nservice mark, tradename, or logo of the Copyright Holder.\n\n(13) This license includes the non-exclusive, worldwide,\nfree-of-charge patent license to make, have made, use, offer to sell,\nsell, import and otherwise transfer the Package with respect to any\npatent claims licensable by the Copyright Holder that are necessarily\ninfringed by the Package. If you institute patent litigation\n(including a cross-claim or counterclaim) against any party alleging\nthat the Package constitutes direct or contributory patent\ninfringement, then this Artistic License to you shall terminate on the\ndate that such litigation is filed.\n\n(14) Disclaimer of Warranty:\nTHE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS \"AS\nIS\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED\nWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR\nNON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL\nLAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL\nBE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL\nDAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF\nADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n" }, { "path": "META6.json", "content": "{\n \"name\": \"Raku doc\",\n \"description\": \"Raku™ documentation\",\n \"version\": \"2.0\",\n \"raku\": \"6.*\",\n \"authors\": [\n \"raku\"\n ],\n \"auth\": \"raku\",\n \"test-depends\": [\n \"Cro::HTTP::Client\",\n \"File::Temp\",\n \"Test::META\",\n \"Doc::TypeGraph\",\n \"RakuDoc::Test::Files:ver<0.3+>\"\n ],\n \"build-depends\": [],\n \"provides\": {\n \"Pod::Cache\": \"lib/Pod/Cache.rakumod\",\n \"Pod::Convenience\": \"lib/Pod/Convenience.rakumod\"\n },\n \"support\": {\n \"source\": \"git://github.com/Raku/doc.git\"\n },\n \"license\": \"Artistic-2.0\",\n \"tags\": [\n \"raku\",\n \"pod6\",\n \"rakudoc\",\n \"documentation\",\n \"reference\",\n \"perl6\"\n ],\n \"source-url\": \"git://github.com/Raku/doc.git\",\n \"meta6\": \"0\"\n}\n" }, { "path": "Makefile", "content": ".PHONY: test xtest push help\n\nhelp:\n\t@echo \"Usage: make [test|xtest|push]\"\n\t@echo \"\"\n\t@echo \"Options:\"\n\t@echo \" test: run the basic test suite\"\n\t@echo \" xtest: run all tests\"\n\t@echo \" push: run the basic test suite and git push\"\n\n# Common tests - also run by CI\ntest:\n\tif [ \"${TEST_JOBS}\" != \"\" ]; then prove --ext=rakutest -j ${TEST_JOBS} -e raku t; else prove --ext=rakutest -e raku t; fi\n\n# Extended tests - should be run by authors before committing\nxtest:\n\tif [ \"${TEST_JOBS}\" != \"\" ]; then prove --ext=rakutest -j ${TEST_JOBS} -e raku t xt; else prove --ext=rakutest -e raku t xt; fi\n\npush: test\n\tgit pull --rebase && git push\n" }, { "path": "README.md", "content": "# Official Documentation of Raku™\n\n[![artistic](https://img.shields.io/badge/license-Artistic%202.0-blue.svg?style=flat)](https://opensource.org/licenses/Artistic-2.0)\n[![test](https://github.com/Raku/doc/actions/workflows/test.yml/badge.svg)](https://github.com/Raku/doc/actions/workflows/test.yml)\n\nAn HTML version of this documentation can be found\nat [https://docs.raku.org/](https://docs.raku.org/).\nThat site is updated from the main branch here\nfrequently (but not continuously).\n\nThis is currently the recommended way to consume the documentation. The tooling\nto build and run this site is [available on github](https://github.com/Raku/doc-website).\n\nThis repository is not intended to be installed as a module. When running tests or\nscripts locally, you may need to set ``RAKULIB=.``\n\n## README in other languages\n\n [日本語](resources/i18n/jp/README.jp.md)\n| [普通话](resources/i18n/zh/README.zh.md)\n| [Deutsch](resources/i18n/de/README.de.md)\n| [español](resources/i18n/es/README.es.md)\n| [français](resources/i18n/fr/README.fr.md)\n| [italiano](resources/i18n/it/README.it.md)\n| [nederlands](resources/i18n/nl/README.nl.md)\n| [Português](resources/i18n/pt/README.pt.md)\n\n## Help Wanted!\n\n[Interested in contributing?](writing-docs/README.md)\n\n## Why aren't the docs embedded in the compiler source?\n\n 1. This documentation is intended to be universal with\n respect to the specification, and not tied to any specific\n implementation.\n 2. Implementations' handling of embedded Pod is still\n a bit uneven; this avoids potential runtime impacts.\n 3. This separate repo in the Raku Github account invites\n more potential contributors and editors.\n\n## rakudoc\n\nThere is a [CLI](https://github.com/Raku/rakudoc) for viewing Raku documentation.\n\n## Vision\n\n> I want p6doc and docs.raku.org to become the No. 1 resource to consult\n> when you want to know something about a Raku feature, be it from the\n> language, or built-in types and routines. I want it to be useful to every\n> Raku programmer.\n>\n> -- moritz\n\n# LICENSE\n\nThe documentation and code in this repository is available under the Artistic License 2.0\nas published by [The Perl & Raku Foundation (TPRF)](https://rakufoundation.org).\nSee the [LICENSE](LICENSE) file for the full text.\n\nThis repository may also contain examples authored by third parties that may be licensed under a different license. Such\nfiles indicate the copyright and license terms at the top of the file. Currently these include:\n\n* Examples from Stack Overflow; [MIT License](http://creativecommons.org/licenses/MIT) ([ref #1](http://stackoverflow.com/a/43669837/215487) for [1f7cc4e](https://github.com/Raku/doc/commit/1f7cc4efa0da38b5a9bf544c9b13cc335f87f7f6))\n" }, { "path": "doc/Language/101-basics.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"beginning\")\n\n=TITLE Raku by example 101\n\n=SUBTITLE A basic introductory example of a Raku program\n\nSuppose that you host a table tennis tournament. The referees tell you\nthe results of each game in the format C, which\nmeans that C won against C by 3 to 2 sets. You need a\nscript that sums up how many matches and sets each player has won to\ndetermine the overall winner.\n\nThe input data (stored in a file called C) looks like this:\n\n=for code :lang\nBeth Ana Charlie Dave\nAna Dave | 3:0\nCharlie Beth | 3:1\nAna Beth | 2:3\nDave Charlie | 3:0\nAna Charlie | 3:1\nBeth Dave | 0:3\n\nThe first line is the list of players. Every subsequent line records a result\nof a match.\n\nHere's one way to solve that problem in Raku:\n\n=begin code :solo\nuse v6;\n\n# start by printing out the header.\nsay \"Tournament Results:\\n\";\n\nmy $file = open 'scores.txt'; # get filehandle and...\nmy @names = $file.get.words; # ... get players.\n\nmy %matches;\nmy %sets;\n\nfor $file.lines -> $line {\n next unless $line; # ignore any empty lines\n\n my ($pairing, $result) = $line.split(' | ');\n my ($p1, $p2) = $pairing.words;\n my ($r1, $r2) = $result.split(':');\n\n %sets{$p1} += $r1;\n %sets{$p2} += $r2;\n\n if $r1 > $r2 {\n %matches{$p1}++;\n } else {\n %matches{$p2}++;\n }\n}\n\nmy @sorted = @names.sort({ %sets{$_} }).sort({ %matches{$_} }).reverse;\n\nfor @sorted -> $n {\n my $match-noun = %matches{$n} == 1 ?? 'match' !! 'matches';\n my $set-noun = %sets{$n} == 1 ?? 'set' !! 'sets';\n say \"$n has won %matches{$n} $match-noun and %sets{$n} $set-noun\";\n}\n=end code\n\nThis produces the output:\n\n=begin code :lang\nTournament Results:\n\nAna has won 2 matches and 8 sets\nDave has won 2 matches and 6 sets\nCharlie has won 1 match and 4 sets\nBeth has won 1 match and 4 sets\n=end code\n\n=head1 Pragma X|Tutorial,v6 (Basics)>\n\n=begin code :solo\nuse v6;\n=end code\n\nEvery Raku program should begin with a line similar to C. This line\ntells the compiler which version of Raku the program expects. For instance,\n6.c is an example of a Raku version. Should you accidentally run the file\nwith Perl, you'll get a helpful error message.\n\n=head1 X\n\n=begin code\n# start by printing out the header.\nsay \"Tournament Results:\\n\";\n=end code\n\nA Raku program consists of zero or more statements. A I ends with\na semicolon or a curly brace at the end of a line.\n\nIn Raku, single line comments start with a single hash character C<#> and\nextend until the end of the line. Raku also supports\nL.\nThe compiler doesn't evaluate comments as program text and they're only intended\nfor human readers.\n\n=head1 X and X\n\n=begin code\nmy $file = open 'scores.txt';\n=end code\n\nC declares a lexical variable, which are visible only in the current block\nfrom the point of declaration to the end of the block. If there's no enclosing\nblock, it's visible throughout the remainder of the file (which would\neffectively be the enclosing block). A block is any part of the code enclosed\nbetween curly braces C<{ }>.\n\n=head2 X and X\n\nA variable name begins with a I, which is a non-alpha-numeric\nsymbol such as C<$>, C<@>, C<%>, or C<&> E or occasionally the double\ncolon C<::>. Sigils indicate the structural interface for the variable,\nsuch as whether it should be treated as a single value, a compound value,\na subroutine, etc. After the sigil comes an I, which may\nconsist of letters, digits and the underscore. Between letters you can\nalso use a dash C<-> or an apostrophe C<'>, so C and\nC are valid identifiers.\n\n=head2 X\n\nSigils indicate the default access method for a variable. Variables\nwith the C<@> sigil are accessed positionally; variables with the C<%>\nsigil are accessed by string key. The C<$> sigil, however, indicates a\ngeneral scalar container that can hold any single value and be accessed\nin any manner. A scalar can even contain a compound object like an\nL|/type/Array> or a L|/type/Hash>; the C<$> sigil signifies that it should be\ntreated as a single value, even in a context that expects multiple\nvalues (as with an L|/type/Array> or L|/type/Hash>).\n\n=head2 X and X\n\nThe built-in function C opens a file, here named C,\nand returns a I E an object representing that file. The\nassignment operator C<=> I that filehandle to the variable on the left,\nwhich means that C<$file> now stores the filehandle.\n\n=head2 X\n\nC<'scores.txt'> is a I. A string is a piece of text, and a\nstring literal is a string which appears directly in the program. In this line,\nit's the argument provided to C.\n\n=head1 X, X and X\n\n=begin code :preamble\nmy @names = $file.get.words;\n=end code\n\nThe right-hand side calls a I E a named group of\nbehavior E named C on the filehandle stored in C<$file>. The C\nmethod reads and returns one line from the file, removing the line ending. If\nyou print the contents of C<$file> after calling C, you will see that the\nfirst line is no longer in there. C is also a method, called on the\nstring returned from C. C decomposes its I E\nthe string on which it operates E into a list of words, which here means\nstrings separated by whitespace. It turns the single string C<'Beth Ana Charlie\nDave'> into the list of strings C<'Beth', 'Ana', 'Charlie', 'Dave'>.\n\nFinally, this list gets stored in the L|/type/Array> C<@names>.\nThe C<@> sigil marks the declared variable as an L|/type/Array>.\nArrays store ordered lists.\n\n=head1 X\n\n=begin code\nmy %matches;\nmy %sets;\n=end code\n\nThese two lines of code declare two hashes. The C<%> sigil marks each variable\nas a L|/type/Hash>. A L|/type/Hash> is an unordered collection of key-value pairs. Other\nprogramming languages call that a I, I, or I.\nYou can query a hash table for the value that corresponds to a certain\nC<$key> with C<%hash{$key}>.\n\nIn the score counting program, C<%matches> stores the number of matches each\nplayer has won. C<%sets> stores the number of sets each player has won. Both\nof these hashes are indexed by the player's name.\n\n=head1 X|Tutorial,for (Basics)> and blocks\n\n=begin code :preamble\nfor $file.lines -> $line {\n ...\n}\n=end code\n\nC produces a loop that runs the I delimited by curly braces\nonce for each item of the list, setting the variable C<$line>\nto the current value of each iteration. C<$file.lines> produces a list of\nthe lines read from the file C, starting with the second line\nof the file since we already called C<$file.get> once, and going all the way\nto the end of the file.\n\nDuring the first iteration, C<$line> will contain the string C; during the second, C, and so on.\n\n=begin code :preamble\nmy ($pairing, $result) = $line.split(' | ');\n=end code\n\nC can declare multiple variables simultaneously. The right-hand side of the\nassignment is a call to a method named C, passing along the string\nC<' | '> as an argument.\n\nC decomposes its invocant into a list of strings, so that joining the\nlist items with the separator C<' | '> produces the original string.\n\nC<$pairing> gets the first item of the returned list, and C<$result> the second.\n\nAfter processing the first line, C<$pairing> will hold the string C\nand C<$result> will hold C<3:0>.\n\nThe next two lines follow the same pattern:\n\n=begin code :preamble\nmy ($p1, $p2) = $pairing.words;\nmy ($r1, $r2) = $result.split(':');\n=end code\n\nThe first extracts and stores the names of the two players in the variables\nC<$p1> and C<$p2>. The second extracts the results for each player and stores\nthem in C<$r1> and C<$r2>.\n\nAfter processing the first line of the file, the variables contain the values:\n=begin table\n Variable Contents\n $line 'Ana Dave \\| 3:0'\n $pairing 'Ana Dave'\n $result '3:0'\n $p1 'Ana'\n $p2 'Dave'\n $r1 '3'\n $r2 '0'\n\n=end table\n\nThe program then counts the number of sets each player has won:\n\n=begin code :preamble\n%sets{$p1} += $r1;\n%sets{$p2} += $r2;\n=end code\n\nThe above two statements involve the C<+=> compound assignment operator. They\nare a variant of the following two statements that use the simple assignment\noperator C<=> and that may be easier to understand at first sight:\n\n=begin code :preamble\n%sets{$p1} = %sets{$p1} + $r1;\n%sets{$p2} = %sets{$p2} + $r2;\n=end code\n\nFor your program, the shorthand version using the C<+=> compound assignment\noperator is preferred over the longhand version using the simple assignment\noperator C<=>. This is not only because the shorter version requires less\ntyping, but also because the C<+=> operator silently initializes undefined\nvalues of the hash's key-value pairs to zero. In other words: by using C<+=>,\nthere is no need to include a separate statement like C<%sets{$p1} = 0> before\nyou can meaningfully add C<$r1> to it. We'll look at this behavior in a bit\nmore detail below.\n\n=head2 X|Tutorial,Any (Basics)> and X|Tutorial,+= (Basics)>\n\n=begin code :preamble\n%sets{$p1} += $r1;\n%sets{$p2} += $r2;\n=end code\n\nC<%sets{$p1} += $r1> means I.\nIn the first iteration C<%sets{$p1}> is not yet defined, so it defaults to a special\nvalue called L|/type/Any>. The C<+=> operator conveniently treats the undefined value\nL|/type/Any> as a number with the value C<0>, allowing it to sensibly add some other\nvalue to it. To perform the addition, the strings C<$r1>, C<$r2>, etc. are\nautomatically converted to numbers, as addition is a numeric operation.\n\n=head2 X, X and X\n\nBefore these two lines execute, C<%sets> is empty. Adding to an entry that is\nnot in the hash yet will cause that entry to spring into existence\njust-in-time, with a value starting at zero. This behavior is known as\nI. After these two lines have run for the first time, C<%sets>\ncontains C«'Ana' => 3, 'Dave' => 0». (The fat arrow C«=>» separates the\nkey and the value in a L|/type/Pair>.)\n\n=head2 X and X\n\n=begin code :preamble\nif $r1 > $r2 {\n %matches{$p1}++;\n} else {\n %matches{$p2}++;\n}\n=end code\n\nIf C<$r1> is numerically larger than C<$r2>, C<%matches{$p1}> increments by one.\nIf C<$r1> is not larger than C<$r2>, C<%matches{$p2}> increments. Just as in\nthe case of C<+=>, if either hash value did not exist previously, it is\nautovivified by the increment operation.\n\nC<$thing++> is a variant of C<$thing += 1>; it differs from the latter in that\nthe return value of the expression is C<$thing> I the increment, and not\nthe incremented value. As in many other programming languages, you can use C<++>\nas a prefix. Then it returns the incremented value: C\nprints C<2>.\n\n=head1 X\n\n=begin code :preamble\nmy @sorted = @names.sort({ %sets{$_} }).sort({ %matches{$_} }).reverse;\n=end code\n\nThis line consists of three individually simple steps. An array's C\nmethod returns a sorted version of the array's contents. However, the default\nsort on an array sorts by its contents. To print player names in winner-first\norder, the code must sort the array by the I of the players, not their\nnames. The C method's argument is a I used to transform the array\nelements (the names of players) to the data by which to sort. The array items\nare passed in through the I C<$_>.\n\n=head2 Blocks\n\nYou have seen blocks before: both the C loop C<<-> $line { ... }>> and\nthe C statement worked on blocks. A block is a self-contained piece of\nRaku code with an optional signature (the C<<-> $line>> part).\n\nThe simplest way to sort the players by score would be C<@names.sort({\n%matches{$_} })>, which sorts by number of matches won. However Ana and Dave\nhave both won two matches. That simple sort doesn't account for the number of\nsets won, which is the secondary criterion to decide who has won the\ntournament.\n\n=head2 Stable sort\n\nWhen two array items have the same value, C leaves them in the same order\nas it found them. Computer scientists call this a I. The program\ntakes advantage of this property of Raku's C to achieve the goal by\nsorting twice: first by the number of sets won (the secondary criterion), then\nby the number of matches won (the primary criterion).\n\nAfter the first sorting step, the names are in the order C. After the second sorting step, it's still the same, because no one has\nwon fewer matches but more sets than someone else. Such a situation is entirely\npossible, especially at larger tournaments.\n\nC sorts in ascending order, from smallest to largest. This is the\nopposite of the desired order. Therefore, the code calls the C<.reverse> method\non the result of the second sort, and stores the final list in C<@sorted>.\n\n=head1 Standard output\n\n=begin code :preamble\nfor @sorted -> $n {\n my $match-noun = %matches{$n} == 1 ?? 'match' !! 'matches';\n my $set-noun = %sets{$n} == 1 ?? 'set' !! 'sets';\n say \"$n has won %matches{$n} $match-noun and %sets{$n} $set-noun\";\n}\n=end code\n\nTo print out the players and their scores, the code loops over C<@sorted>,\nsetting C<$n> to the name of each player in turn. Read this code as \"For each\nelement of sorted, set C<$n> to the element, then execute the contents of the\nfollowing block.\" The variable C<$match-noun> will store either the string\nI if the player has won a single match or I if the player\nhas won zero or more matches. In order to do this, the I\noperator (C) is used. If C<%matches{$n} == 1> evaluates to C,\nthen I is returned. Otherwise, I is returned. Either way,\nthe returned value is stored in C<$match-noun>. The same approach applies\nto C<$set-noun>.\n\nThe statement C prints its arguments to the standard output\n(the screen, normally), followed by a newline. (Use C if you don't\nwant the newline at the end.)\n\nNote that C will truncate certain data structures by calling the C<.gist>\nmethod so C is safer if you want exact output.\n\n=head2 X\n\nWhen you run the program, you'll see that C doesn't print the contents of\nthat string verbatim. In place of C<$n> it prints the contents of the variable\nC<$n> E a player's name stored in C<$n>. This automatic substitution\nof code with its contents is called I. This interpolation happens\nonly in strings delimited by double quotes C<\"...\">. Single quoted strings\nC<'...'> do not interpolate:\n\n=head2 X and X\n\n=begin code\nmy $names = 'things';\nsay 'Do not call me $names'; # OUTPUT: «Do not call me $names␤»\nsay \"Do not call me $names\"; # OUTPUT: «Do not call me things␤»\n=end code\n\nDouble quoted strings in Raku can interpolate variables with the C<$>\nsigil as well as blocks of code in curly braces. Since any arbitrary\nRaku code can appear within curly braces, L|/type/Array>s and L|/type/Hash>es may be\ninterpolated by placing them within curly braces.\n\nArrays within curly braces are interpolated with a single space character\nbetween each item. Hashes within curly braces are interpolated as a series of\nlines. Each line will contain a key, followed by a tab character, then the\nvalue associated with that key, and finally a newline.\n\nLet's see an example of this now.\n\nIn this example, you will see some special syntax that makes it easier\nto make a list of strings. This is the\nC«<...>» L\nconstruct. When you put words in between the C«<» and C«>» they are all assumed\nto be strings, so you do not need to wrap them each in double quotes\nC«\"...\"».\n\n=begin code :preamble\nsay \"Math: { 1 + 2 }\";\n# OUTPUT: «Math: 3␤»\n\nmy @people = ;\nsay \"The synoptics are: {@people}\";\n# OUTPUT: «The synoptics are: Luke Matthew Mark␤»\n\nsay \"{%sets}\";\n# OUTPUT (From the table tennis tournament):\n\n# Charlie 4\n# Dave 6\n# Ana 8\n# Beth 4\n=end code\n\nWhen array and hash variables appear directly in a double-quoted string (and\nnot inside curly braces), they are only interpolated if their name is\nfollowed by a postcircumfix operator E a bracketing pair that follows a\nstatement. It's also ok to have a method call between the variable name and\nthe postcircumfix.\n\n=head1 Zen slices\n\n=begin code\nmy @flavors = ;\n\nsay \"we have @flavors\"; # OUTPUT: «we have @flavors␤»\nsay \"we have @flavors[0]\"; # OUTPUT: «we have vanilla␤»\n# so-called \"Zen slice\"\nsay \"we have @flavors[]\"; # OUTPUT: «we have vanilla peach␤»\n\n# method calls ending in postcircumfix\nsay \"we have @flavors.sort()\"; # OUTPUT: «we have peach vanilla␤»\n\n# chained method calls:\nsay \"we have @flavors.sort.join(', ')\";\n # OUTPUT: «we have peach, vanilla␤»\n=end code\n\n=head1 Calling a raku method from another file\n\nTo call a raku subroutine from another file, the convention is to have a minimal\nraku module or class file.\n\n=begin code\n# MyClass.rakumod\nclass C {\n has $.x;\n}\n=end code\n\nThen your script can C this file.\n\n=begin code :skip-test\n# myscript.raku\nuse MyClass;\n\nmy $instance = C.new(x=>42);\nsay $instance.x;\n=end code\n\nThe C<-I.> directive tells the raku interpreter to look for modules in directory C<.>.\n\n=begin code :lang\n> raku -I. myscript.raku\n=end code\n\n=head1 Exercises\n\nB<1.> The input format of the example program is redundant: the first line\ncontaining the name of all players is not necessary, because you can find out\nwhich players participated in the tournament by looking at their names in the\nsubsequent rows, so in principle we could safely remove it.\n\nHow can you make the program run if you do not use the C<@names> variable?\nHint: C<%hash.keys> returns a list of all keys stored in C<%hash>.\n\nB After removing the first line in C, remove the line C (which would read it), and change:\n\n=begin code :preamble\nmy @sorted = @names.sort({ %sets{$_} }).sort({ %matches{$_} }).reverse;\n=end code\n\n... into:\n\n=begin code :preamble\nmy @sorted = %sets.keys.sort({ %sets{$_} }).sort({ %matches{$_} }).reverse;\n=end code\n\nB<2.> Instead of deleting the redundant C<@names> variable, you can also use it\nto warn if a player appears that wasn't mentioned in the first line, for\nexample due to a typo. How would you modify your program to achieve that?\n\nHint: Try using L.\n\nB Change C<@names> to C<@valid-players>. When looping through the\nlines of the file, check to see that C<$p1> and C<$p2> are in\nC<@valid-players>. Note that for membership operators you can also use C<(elem)>\nand C.\n\n=begin code :preamble\n...;\nmy @valid-players = $file.get.words;\n...;\n\nfor $file.lines -> $line {\n my ($pairing, $result) = $line.split(' | ');\n my ($p1, $p2) = $pairing.split(' ');\n if $p1 ∉ @valid-players {\n say \"Warning: '$p1' is not on our list!\";\n }\n if $p2 ∉ @valid-players {\n say \"Warning: '$p2' is not on our list!\";\n }\n ...\n}\n=end code\n\n=end pod\n\n" }, { "path": "doc/Language/REPL.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"tutorial\")\n\n=TITLE REPL\n\n=SUBTITLE Interactive Raku, read-eval-print loop\n\n=head1 Overview\n\nThe C is an interactive Raku prompt. Each line of code you enter in the C\nis executed, and if no output was generated, the value returned\nby the expression is output.\n\n=head1 Trap\n\nB: Running code in the C is not equivalent to saving the code in a file and\nrunning that. Each line introduces a new scope which can confuse code that has multiple\nlines. See C below for a way to target a REPL inside a larger script.\n\n=head1 Previous Values\n\nAs you enter commands into the REPL, each line has a numeric ID associated with it, starting\nwith C<0>. On subsequent lines, you can use the result with a special variable only available\nin the REPL. C<$*0>, C<$*1>, etc. In this example, we calculate two values and then use them\nboth on the third line.\n\n=begin code :lang\n✗ raku\nWelcome to Rakudo™ v2025.08.\nImplementing the Raku® Programming Language v6.d.\nBuilt on MoarVM version 2025.08.\n\nTo exit type 'exit' or '^D'\n[0] > 3+2\n5\n[1] > 7+1\n8\n[2] > $*0 * $*1\n40\n[3] >\n=end code\n\n=head1 non-interactive mode\n\nIf invoked from the command line with C, no history or prompts\nare printed, and the code is not executed until you close input (on Linux, for example, you can pipe\nthe code to it or press C.\n\n=for code :lang\n $ echo \"say 3\" | raku --repl-mode=non-interactive\n 3\n\n=head1 sub repl()\n\nThis routine allows you to embed a REPL inside a larger script and have access to all\nthe variables in context.\n\nSee L in Independent Routines for more\ninformation.\n\n=head1 ENVIRONMENT Variables\n\nSee L.\n\n=head2 Get command line history\n\nIn a fresh install, there is no command history. Running the C in this mode will\nprompt you to install one of the various modules that provide this support. If enabled,\nyou can use the arrow keys to scroll through previous commands and use standard terminal\nshortcuts for editing. There are currently four options:\n\n=item 1\n\n=for code :lang\n zef install Terminal::LineEditor\n\n=item 2\n\n=for code :lang\n zef install Linenoise\n\nThis requires a working C toolchain.\n\n=item 3\n\n=for code :lang\n zef install Readline\n\nThis requires an installation of the C development library.\n\n=item 4\n\nAn alternative for UNIX-like systems is to install C. This can\nbe done on Debian-ish systems by running:\n\n=for code :lang\nsudo apt-get install rlwrap\n\nAnd then use it to invoke the C:\n\n=for code :lang\nrlwrap raku\n\n\n=end pod\n" }, { "path": "doc/Language/about.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"beginning\")\n\n=TITLE About the docs\n\n=SUBTITLE How to locally generate the Raku documentation; and how to contribute to it.\n\nThis document collection represents the on-going effort to document the\nRaku programming language with the goals of being comprehensive,\neasy to use, easy to navigate, and useful to both newcomers and experienced\nRaku programmers.\n\nAn L is available.\n\nThe official source for this documentation is located at\nL.\n\n=head1 Structure\n\nAll of the documentation is written in Raku Pod and kept in the C\ndirectory. These files are processed are rendered to HTML, and also\nprocessed into some generated pages, using the C<.rakudoc> files as\nsources.\n\n=head1 Generating HTML from Pod\n\nThe build process is managed through a separate repository,\nL.\n\n=head1 Contributing\n\nFor a quick introduction to Raku Pod, see L.\n\nFor historic details about the Raku Pod specification, see L.\n\nFor information on how to contribute to the documentation, please\nread L.\n\n=end pod\n" }, { "path": "doc/Language/brackets.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"reference\")\n\n=TITLE Brackets\n\n=SUBTITLE Valid opening/closing paired delimiters\n\nThe following table shows all of the valid graphemes usable as opening\nand closing paired delimiters in such constructs as I. Note they are shown between pipe symbols so the extra bounding\nspace for any wide characters can be seen.\n\nThe data source for the table is the I<$brackets> string defined in the\nI module in the I repository.\n\nThe data are arranged in the order found in the source string.\nEach opening bracket is shown in its printed form followed by its\npaired closing bracket. Each pair is then followed by its codepoints.\nThere are two sets of bracket pairs shown per table row.\n\n=begin table :caption\n LChar | RChar | LHex | RHex | LChar | RChar | LHex | RHex\n======+======+======+======+======+======+======+======\n\\|(\\| | \\|)\\| | 0x0028 | 0x0029 | \\|<\\| | \\|>\\| | 0x003C | 0x003E\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|[\\| | \\|]\\| | 0x005B | 0x005D | \\|{\\| | \\|}\\| | 0x007B | 0x007D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|«\\| | \\|»\\| | 0x00AB | 0x00BB | \\|༺\\| | \\|༻\\| | 0x0F3A | 0x0F3B\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|༼\\| | \\|༽\\| | 0x0F3C | 0x0F3D | \\|᚛\\| | \\|᚜\\| | 0x169B | 0x169C\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|‘\\| | \\|’\\| | 0x2018 | 0x2019 | \\|‚\\| | \\|’\\| | 0x201A | 0x2019\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|‛\\| | \\|’\\| | 0x201B | 0x2019 | \\|“\\| | \\|”\\| | 0x201C | 0x201D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|„\\| | \\|”\\| | 0x201E | 0x201D | \\|‟\\| | \\|”\\| | 0x201F | 0x201D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|‹\\| | \\|›\\| | 0x2039 | 0x203A | \\|⁅\\| | \\|⁆\\| | 0x2045 | 0x2046\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⁽\\| | \\|⁾\\| | 0x207D | 0x207E | \\|₍\\| | \\|₎\\| | 0x208D | 0x208E\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|∈\\| | \\|∋\\| | 0x2208 | 0x220B | \\|∉\\| | \\|∌\\| | 0x2209 | 0x220C\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|∊\\| | \\|∍\\| | 0x220A | 0x220D | \\|∕\\| | \\|⧵\\| | 0x2215 | 0x29F5\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|∼\\| | \\|∽\\| | 0x223C | 0x223D | \\|≃\\| | \\|⋍\\| | 0x2243 | 0x22CD\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≒\\| | \\|≓\\| | 0x2252 | 0x2253 | \\|≔\\| | \\|≕\\| | 0x2254 | 0x2255\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≤\\| | \\|≥\\| | 0x2264 | 0x2265 | \\|≦\\| | \\|≧\\| | 0x2266 | 0x2267\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≨\\| | \\|≩\\| | 0x2268 | 0x2269 | \\|≪\\| | \\|≫\\| | 0x226A | 0x226B\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≮\\| | \\|≯\\| | 0x226E | 0x226F | \\|≰\\| | \\|≱\\| | 0x2270 | 0x2271\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≲\\| | \\|≳\\| | 0x2272 | 0x2273 | \\|≴\\| | \\|≵\\| | 0x2274 | 0x2275\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≶\\| | \\|≷\\| | 0x2276 | 0x2277 | \\|≸\\| | \\|≹\\| | 0x2278 | 0x2279\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≺\\| | \\|≻\\| | 0x227A | 0x227B | \\|≼\\| | \\|≽\\| | 0x227C | 0x227D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|≾\\| | \\|≿\\| | 0x227E | 0x227F | \\|⊀\\| | \\|⊁\\| | 0x2280 | 0x2281\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊂\\| | \\|⊃\\| | 0x2282 | 0x2283 | \\|⊄\\| | \\|⊅\\| | 0x2284 | 0x2285\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊆\\| | \\|⊇\\| | 0x2286 | 0x2287 | \\|⊈\\| | \\|⊉\\| | 0x2288 | 0x2289\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊊\\| | \\|⊋\\| | 0x228A | 0x228B | \\|⊏\\| | \\|⊐\\| | 0x228F | 0x2290\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊑\\| | \\|⊒\\| | 0x2291 | 0x2292 | \\|⊘\\| | \\|⦸\\| | 0x2298 | 0x29B8\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊢\\| | \\|⊣\\| | 0x22A2 | 0x22A3 | \\|⊦\\| | \\|⫞\\| | 0x22A6 | 0x2ADE\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊨\\| | \\|⫤\\| | 0x22A8 | 0x2AE4 | \\|⊩\\| | \\|⫣\\| | 0x22A9 | 0x2AE3\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊫\\| | \\|⫥\\| | 0x22AB | 0x2AE5 | \\|⊰\\| | \\|⊱\\| | 0x22B0 | 0x22B1\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊲\\| | \\|⊳\\| | 0x22B2 | 0x22B3 | \\|⊴\\| | \\|⊵\\| | 0x22B4 | 0x22B5\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⊶\\| | \\|⊷\\| | 0x22B6 | 0x22B7 | \\|⋉\\| | \\|⋊\\| | 0x22C9 | 0x22CA\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋋\\| | \\|⋌\\| | 0x22CB | 0x22CC | \\|⋐\\| | \\|⋑\\| | 0x22D0 | 0x22D1\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋖\\| | \\|⋗\\| | 0x22D6 | 0x22D7 | \\|⋘\\| | \\|⋙\\| | 0x22D8 | 0x22D9\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋚\\| | \\|⋛\\| | 0x22DA | 0x22DB | \\|⋜\\| | \\|⋝\\| | 0x22DC | 0x22DD\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋞\\| | \\|⋟\\| | 0x22DE | 0x22DF | \\|⋠\\| | \\|⋡\\| | 0x22E0 | 0x22E1\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋢\\| | \\|⋣\\| | 0x22E2 | 0x22E3 | \\|⋤\\| | \\|⋥\\| | 0x22E4 | 0x22E5\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋦\\| | \\|⋧\\| | 0x22E6 | 0x22E7 | \\|⋨\\| | \\|⋩\\| | 0x22E8 | 0x22E9\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋪\\| | \\|⋫\\| | 0x22EA | 0x22EB | \\|⋬\\| | \\|⋭\\| | 0x22EC | 0x22ED\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋰\\| | \\|⋱\\| | 0x22F0 | 0x22F1 | \\|⋲\\| | \\|⋺\\| | 0x22F2 | 0x22FA\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋳\\| | \\|⋻\\| | 0x22F3 | 0x22FB | \\|⋴\\| | \\|⋼\\| | 0x22F4 | 0x22FC\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⋶\\| | \\|⋽\\| | 0x22F6 | 0x22FD | \\|⋷\\| | \\|⋾\\| | 0x22F7 | 0x22FE\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⌈\\| | \\|⌉\\| | 0x2308 | 0x2309 | \\|⌊\\| | \\|⌋\\| | 0x230A | 0x230B\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|〈\\| | \\|〉\\| | 0x2329 | 0x232A | \\|⎴\\| | \\|⎵\\| | 0x23B4 | 0x23B5\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|❨\\| | \\|❩\\| | 0x2768 | 0x2769 | \\|❪\\| | \\|❫\\| | 0x276A | 0x276B\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|❬\\| | \\|❭\\| | 0x276C | 0x276D | \\|❮\\| | \\|❯\\| | 0x276E | 0x276F\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|❰\\| | \\|❱\\| | 0x2770 | 0x2771 | \\|❲\\| | \\|❳\\| | 0x2772 | 0x2773\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|❴\\| | \\|❵\\| | 0x2774 | 0x2775 | \\|⟃\\| | \\|⟄\\| | 0x27C3 | 0x27C4\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⟅\\| | \\|⟆\\| | 0x27C5 | 0x27C6 | \\|⟕\\| | \\|⟖\\| | 0x27D5 | 0x27D6\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⟝\\| | \\|⟞\\| | 0x27DD | 0x27DE | \\|⟢\\| | \\|⟣\\| | 0x27E2 | 0x27E3\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⟤\\| | \\|⟥\\| | 0x27E4 | 0x27E5 | \\|⟦\\| | \\|⟧\\| | 0x27E6 | 0x27E7\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⟨\\| | \\|⟩\\| | 0x27E8 | 0x27E9 | \\|⟪\\| | \\|⟫\\| | 0x27EA | 0x27EB\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⦃\\| | \\|⦄\\| | 0x2983 | 0x2984 | \\|⦅\\| | \\|⦆\\| | 0x2985 | 0x2986\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⦇\\| | \\|⦈\\| | 0x2987 | 0x2988 | \\|⦉\\| | \\|⦊\\| | 0x2989 | 0x298A\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⦋\\| | \\|⦌\\| | 0x298B | 0x298C | \\|⦍\\| | \\|⦐\\| | 0x298D | 0x2990\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⦏\\| | \\|⦎\\| | 0x298F | 0x298E | \\|⦑\\| | \\|⦒\\| | 0x2991 | 0x2992\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⦓\\| | \\|⦔\\| | 0x2993 | 0x2994 | \\|⦕\\| | \\|⦖\\| | 0x2995 | 0x2996\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⦗\\| | \\|⦘\\| | 0x2997 | 0x2998 | \\|⧀\\| | \\|⧁\\| | 0x29C0 | 0x29C1\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⧄\\| | \\|⧅\\| | 0x29C4 | 0x29C5 | \\|⧏\\| | \\|⧐\\| | 0x29CF | 0x29D0\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⧑\\| | \\|⧒\\| | 0x29D1 | 0x29D2 | \\|⧔\\| | \\|⧕\\| | 0x29D4 | 0x29D5\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⧘\\| | \\|⧙\\| | 0x29D8 | 0x29D9 | \\|⧚\\| | \\|⧛\\| | 0x29DA | 0x29DB\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⧸\\| | \\|⧹\\| | 0x29F8 | 0x29F9 | \\|⧼\\| | \\|⧽\\| | 0x29FC | 0x29FD\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⨫\\| | \\|⨬\\| | 0x2A2B | 0x2A2C | \\|⨭\\| | \\|⨮\\| | 0x2A2D | 0x2A2E\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⨴\\| | \\|⨵\\| | 0x2A34 | 0x2A35 | \\|⨼\\| | \\|⨽\\| | 0x2A3C | 0x2A3D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⩤\\| | \\|⩥\\| | 0x2A64 | 0x2A65 | \\|⩹\\| | \\|⩺\\| | 0x2A79 | 0x2A7A\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⩽\\| | \\|⩾\\| | 0x2A7D | 0x2A7E | \\|⩿\\| | \\|⪀\\| | 0x2A7F | 0x2A80\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪁\\| | \\|⪂\\| | 0x2A81 | 0x2A82 | \\|⪃\\| | \\|⪄\\| | 0x2A83 | 0x2A84\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪋\\| | \\|⪌\\| | 0x2A8B | 0x2A8C | \\|⪑\\| | \\|⪒\\| | 0x2A91 | 0x2A92\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪓\\| | \\|⪔\\| | 0x2A93 | 0x2A94 | \\|⪕\\| | \\|⪖\\| | 0x2A95 | 0x2A96\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪗\\| | \\|⪘\\| | 0x2A97 | 0x2A98 | \\|⪙\\| | \\|⪚\\| | 0x2A99 | 0x2A9A\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪛\\| | \\|⪜\\| | 0x2A9B | 0x2A9C | \\|⪡\\| | \\|⪢\\| | 0x2AA1 | 0x2AA2\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪦\\| | \\|⪧\\| | 0x2AA6 | 0x2AA7 | \\|⪨\\| | \\|⪩\\| | 0x2AA8 | 0x2AA9\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪪\\| | \\|⪫\\| | 0x2AAA | 0x2AAB | \\|⪬\\| | \\|⪭\\| | 0x2AAC | 0x2AAD\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪯\\| | \\|⪰\\| | 0x2AAF | 0x2AB0 | \\|⪳\\| | \\|⪴\\| | 0x2AB3 | 0x2AB4\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪻\\| | \\|⪼\\| | 0x2ABB | 0x2ABC | \\|⪽\\| | \\|⪾\\| | 0x2ABD | 0x2ABE\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⪿\\| | \\|⫀\\| | 0x2ABF | 0x2AC0 | \\|⫁\\| | \\|⫂\\| | 0x2AC1 | 0x2AC2\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⫃\\| | \\|⫄\\| | 0x2AC3 | 0x2AC4 | \\|⫅\\| | \\|⫆\\| | 0x2AC5 | 0x2AC6\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⫍\\| | \\|⫎\\| | 0x2ACD | 0x2ACE | \\|⫏\\| | \\|⫐\\| | 0x2ACF | 0x2AD0\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⫑\\| | \\|⫒\\| | 0x2AD1 | 0x2AD2 | \\|⫓\\| | \\|⫔\\| | 0x2AD3 | 0x2AD4\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⫕\\| | \\|⫖\\| | 0x2AD5 | 0x2AD6 | \\|⫬\\| | \\|⫭\\| | 0x2AEC | 0x2AED\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⫷\\| | \\|⫸\\| | 0x2AF7 | 0x2AF8 | \\|⫹\\| | \\|⫺\\| | 0x2AF9 | 0x2AFA\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⸂\\| | \\|⸃\\| | 0x2E02 | 0x2E03 | \\|⸄\\| | \\|⸅\\| | 0x2E04 | 0x2E05\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⸉\\| | \\|⸊\\| | 0x2E09 | 0x2E0A | \\|⸌\\| | \\|⸍\\| | 0x2E0C | 0x2E0D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⸜\\| | \\|⸝\\| | 0x2E1C | 0x2E1D | \\|⸠\\| | \\|⸡\\| | 0x2E20 | 0x2E21\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⸨\\| | \\|⸩\\| | 0x2E28 | 0x2E29 | \\|〈\\| | \\|〉\\| | 0x3008 | 0x3009\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|《\\| | \\|》\\| | 0x300A | 0x300B | \\|「\\| | \\|」\\| | 0x300C | 0x300D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|『\\| | \\|』\\| | 0x300E | 0x300F | \\|【\\| | \\|】\\| | 0x3010 | 0x3011\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|〔\\| | \\|〕\\| | 0x3014 | 0x3015 | \\|〖\\| | \\|〗\\| | 0x3016 | 0x3017\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|〘\\| | \\|〙\\| | 0x3018 | 0x3019 | \\|〚\\| | \\|〛\\| | 0x301A | 0x301B\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|〝\\| | \\|〞\\| | 0x301D | 0x301E | \\|︗\\| | \\|︘\\| | 0xFE17 | 0xFE18\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|︵\\| | \\|︶\\| | 0xFE35 | 0xFE36 | \\|︷\\| | \\|︸\\| | 0xFE37 | 0xFE38\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|︹\\| | \\|︺\\| | 0xFE39 | 0xFE3A | \\|︻\\| | \\|︼\\| | 0xFE3B | 0xFE3C\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|︽\\| | \\|︾\\| | 0xFE3D | 0xFE3E | \\|︿\\| | \\|﹀\\| | 0xFE3F | 0xFE40\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|﹁\\| | \\|﹂\\| | 0xFE41 | 0xFE42 | \\|﹃\\| | \\|﹄\\| | 0xFE43 | 0xFE44\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|﹇\\| | \\|﹈\\| | 0xFE47 | 0xFE48 | \\|﹙\\| | \\|﹚\\| | 0xFE59 | 0xFE5A\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|﹛\\| | \\|﹜\\| | 0xFE5B | 0xFE5C | \\|﹝\\| | \\|﹞\\| | 0xFE5D | 0xFE5E\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|（\\| | \\|）\\| | 0xFF08 | 0xFF09 | \\|＜\\| | \\|＞\\| | 0xFF1C | 0xFF1E\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|［\\| | \\|］\\| | 0xFF3B | 0xFF3D | \\|｛\\| | \\|｝\\| | 0xFF5B | 0xFF5D\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|｟\\| | \\|｠\\| | 0xFF5F | 0xFF60 | \\|｢\\| | \\|｣\\| | 0xFF62 | 0xFF63\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⟮\\| | \\|⟯\\| | 0x27EE | 0x27EF | \\|⸤\\| | \\|⸥\\| | 0x2E24 | 0x2E25\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⟬\\| | \\|⟭\\| | 0x27EC | 0x27ED | \\|⸢\\| | \\|⸣\\| | 0x2E22 | 0x2E23\n--------+---------+---------+---------+--------+---------+---------+---------\n\\|⸦\\| | \\|⸧\\| | 0x2E26 | 0x2E27 | | | |\n--------+---------+---------+---------+--------+---------+---------+---------\n=end table\nZ\n\n=end pod\n" }, { "path": "doc/Language/classtut.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"tutorial\")\n\n=TITLE Classes and objects\n\n=SUBTITLE A tutorial about creating and using classes in Raku\n\nX<|Tutorial,OOP>\nRaku provides a rich built-in syntax for defining and using classes. It makes writing classes\nexpressive and short for most cases, but also provides mechanisms to cover\nthe rare corner cases.\n\n=head1 A quick overview\n\nLet's start with an example to give an overview:\n\n=begin code\nclass Rectangle {\n has Int $.length = 1;\n has Int $.width = 1;\n\n method area(--> Int) {\n return $!length * $!width;\n }\n}\n\nmy $r1 = Rectangle.new(length => 2, width => 3);\nsay $r1.area(); # OUTPUT: «6␤»\n=end code\n\nWe define a new I class using the L keyword. It has two L, C<$!length> and C<$!width> introduced\nwith the L keyword. Both default to C<1>. Read only accessor methods are automatically generated. (Note the C<.> instead of C in the declaration, which triggers the generation. Mnemonic: C resembles a closed door, C<.> an open one.)\n\nThe L named C will return the area of the rectangle.\n\nIt is rarely necessary to explicitly write a constructor. An automatically inherited default constructor called L will automatically initialize attributes from named parameters passed to the constructor.\n\n=head1 The Task example\n\nAs a more elaborate example the following piece of code implements a dependency\nhandler. It showcases custom constructors, private and public attributes,\nmethods, and various aspects of signatures. It's not a lot of code, and yet the\nresult is interesting and useful. It will be used as an example throughout the\nfollowing sections.\n\n=begin code\nclass Task {\n has &!callback is built;\n has Task @!dependencies is built;\n has Bool $.done;\n\n method new(&callback, *@dependencies) {\n return self.bless(:&callback, :@dependencies);\n }\n\n method add-dependency(Task $dependency) {\n push @!dependencies, $dependency;\n }\n\n method perform() {\n unless $!done {\n .perform() for @!dependencies;\n &!callback();\n $!done = True;\n }\n }\n}\n\nmy $eat =\n Task.new({ say 'eating dinner. NOM!' },\n Task.new({ say 'making dinner' },\n Task.new({ say 'buying food' },\n Task.new({ say 'making some money' }),\n Task.new({ say 'going to the store' })\n ),\n Task.new({ say 'cleaning kitchen' })\n )\n );\n\n$eat.perform();\n=end code\n\n=head1 X\n\nX<|Tutorial,state>\nRaku, like many other languages, uses the C keyword to define a\nclass. The block that follows may contain arbitrary code, just as with\nany other block, but classes commonly contain state and behavior\ndeclarations. The example code includes attributes (state), introduced\nthrough the C keyword, and behaviors, introduced through the C\nkeyword.\n\n\n=head1 X\n\nX<|Tutorial,encapsulation>\nX<|Tutorial,has>\nIn the C class, the first three lines inside the block all\ndeclare attributes (called I or I in other\nlanguages) using the C declarator. Just as a C variable cannot be\naccessed from outside its declared scope, attributes are never directly\naccessible from outside of the class (this is in contrast to many other\nlanguages). This I is one of the key principles of object\noriented design.\n\n=head2 X|Tutorial,twigils>\n\nX<|Tutorial,!>\nX<|Tutorial,&>\nThe first declaration specifies instance storage for a callback (i.e.\na bit of code to invoke in order to perform the task that an object\nrepresents):\n\n=for code\nhas &!callback is built;\n\nThe C<&> sigil indicates that this attribute represents something invocable.\nThe C character is a I, or secondary sigil. A twigil forms part\nof the name of the variable. In this case, the C twigil emphasizes that\nthis attribute is private to the class. The attribute is I.\nPrivate attributes will not be set by the default constructor by default, which is\nwhy we add the C trait to allow just that. Mnemonic: C looks like a closed door.\n\nThe second declaration also uses the private twigil:\n\n=for code :preamble\nhas Task @!dependencies is built;\n\nHowever, this attribute represents an array of items, so it requires the\nC<@> sigil. These items each specify a task that must be completed before\nthe present one is completed. Furthermore, the type declaration on this\nattribute indicates that the array may only hold instances of the C\nclass (or some subclass of it).\n\nX<|Tutorial,.>\nX<|Tutorial,accessors>\nX<|Tutorial,accessor methods>\n=head2 Twigil C<$.>\n\nThe third attribute represents the state of completion of a task:\n\n=for code\nhas Bool $.done;\n\nThis scalar attribute (with the C<$> sigil) has a type of L|/type/Bool>. Instead\nof the C twigil, the C<.> twigil is used. While Raku does enforce\nencapsulation on attributes, it also saves you from writing accessor\nmethods. Replacing the C with a C<.> both declares a private attribute\nand an accessor method named after the attribute. In this case,\nboth the attribute C<$!done> and the accessor method C are declared.\nIt's as if you had written:\n\n=begin code\nhas Bool $!done;\nmethod done() { return $!done }\n=end code\n\nNote that this is not like declaring a public attribute, as some languages\nallow; you really get I a private attribute and a method,\nwithout having to write the method by hand. You are free instead to write\nyour own accessor method, if at some future point you need to do something\nmore complex than returning the value.\n\n=head2 X trait|Tutorial,is rw>\n\nNote that using the C<.> twigil has created a method that will provide\nread-only access to the attribute. If instead the users of this object\nshould be able to reset a task's completion state (perhaps to perform it\nagain), you can change the attribute declaration:\n\n=for code\nhas Bool $.done is rw;\n\nThe L|/type/Attribute#trait_is_rw> trait causes the generated accessor method to return a container\nso external code can modify the value of the attribute.\n\n=head2 C trait\n\n=for code\nhas &!callback is built;\n\nX<|Types,traits>\nX<|Types,is built>\nBy default private attributes are not automatically set by the default constructor. (They are private after\nall.) In the above example we want to allow the user to provide the initial value but keep the attribute\notherwise private. The L|/type/Attribute#trait_is_built> trait allows to do just that.\n\nOne can use the same trait C to do the opposite for public attributes, i.e. prevent them from being\nautomatically initialized with a user-provided value, but still generate the accessor method. This is done by giving\nthe argument C to the trait:\n\n=for code\nhas $.done is built(False);\n\nAbove declaration makes sure one can't construct finished tasks, but still allow users to look if a task is done.\n\nThe C trait was introduced in Rakudo release 2020.01.\n\n=head2 C trait\n\nX<|Types,traits>\nX<|Types,is required>\nProviding a value for an attribute during initialization is optional by default. Which in the task example\nmakes sense for all three, the C<&!callback>, the C<@!dependencies> and the C<$.done> attribute. But lets say\nwe want to add another attribute, C<$.name>, that holds a tasks name and we want to force the user to\nprovide a value on initialization. We can do that as follows:\n\n=for code\nhas $.name is required;\n\n=head2 Default values\n\nYou can also supply default values to attributes (which works equally for\nthose with and without accessors):\n\n=for code\nhas Bool $.done = False;\n\nThe assignment is carried out at object build time. The right-hand side is\nevaluated at that time, and can even reference earlier attributes:\n\n=begin code :preamble\nhas Task @!dependencies;\nhas $.ready = not @!dependencies;\n=end code\n\nWritable attributes are accessible through writable containers:\n\n=begin code\nclass a-class {\n has $.an-attribute is rw;\n}\nsay (a-class.new.an-attribute = \"hey\"); # OUTPUT: «hey␤»\n=end code\n\nThis attribute can also be accessed using the C<.an-attribute> or\nC<.an-attribute()> syntax. See also\nL trait on classes|/language/typesystem#trait_is_rw> for examples\non how this works on the whole class.\n\nX<|Tutorial,class variables>\n=head1 Class variables\n\nA class declaration can also include I, declared with C or C, which are variables\nwhose value is shared by all instances, and can be used for things like\ncounting the number of instantiations or any other shared state. So I act similarly to\nI variables known from other programming languages.\nThey look the same as normal (non class) lexical variables (and in fact they are the same):\n\n=begin code\nclass Str-with-ID is Str {\n my $counter = 0;\n our $our-counter = 0;\n has Str $.string;\n has Int $.ID is built(False);\n\n submethod TWEAK() {\n $counter++;\n $our-counter++;\n $!ID = $counter;\n }\n\n}\n\nclass Str-with-ID-and-tag is Str-with-ID {\n has Str $.tag;\n}\n\nsay Str-with-ID.new(string => 'First').ID; # OUTPUT: «1␤»\nsay Str-with-ID.new(string => 'Second').ID; # OUTPUT: «2␤»\nsay Str-with-ID-and-tag.new( string => 'Third', tag => 'Ordinal' ).ID; # OUTPUT: «3␤»\nsay $Str-with-ID::our-counter; # OUTPUT: «3␤»\n=end code\n\nI are shared by all subclasses, in this case\nC. Additionally, when the package scope C declarator\nis used, the variable is visible via their fully qualified name (FQN), while\nlexically scoped C variables are \"private\". This is the exact behavior that\nC and C also show in non class context.\n\nX<|Types,static>\nI act similarly to I variables in many other programming\nlanguages.\n\n=begin code\nclass Singleton {\n my Singleton $instance;\n method new {!!!}\n submethod instance {\n $instance = Singleton.bless unless $instance;\n $instance;\n }\n}\n=end code\n\nIn this implementation of the I pattern a I is used\nto save the instance.\n\n=begin code\nclass HaveStaticAttr {\n my Int $.foo = 5;\n}\n=end code\n\nClass attributes may also be declared with a secondary sigil – in a similar\nmanner to instance attributes – that will generate read-only accessors if the\nattribute is to be public.\nDefault values behave as expected and are assigned only once.\n\n=head1 Methods\n\nX<|Tutorial,methods>\n\nWhile attributes give objects state, methods give objects behaviors. Back to our C example. Let's\nignore the C method temporarily; it's a special type of method.\nConsider the second method, C, which adds a new task to a\ntask's dependency list:\n\n=begin code :skip-test\nmethod add-dependency(Task $dependency) {\n push @!dependencies, $dependency;\n}\n=end code\n\nX<|Tutorial,invocant>\nIn many ways, this looks a lot like a C declaration. However, there are\ntwo important differences. First, declaring this routine as a method adds it\nto the list of methods for the current class, thus any instance of the\nC class can call it with the C<.> method call operator.\nSecond, a method places its invocant into the special variable C.\n\nThe method itself takes the passed parameter – which must be an instance of\nthe C class – and Ces it onto the invocant's C<@!dependencies>\nattribute.\n\nThe C method contains the main logic of the dependency handler:\n\n=begin code :skip-test\nmethod perform() {\n unless $!done {\n .perform() for @!dependencies;\n &!callback();\n $!done = True;\n }\n}\n=end code\n\nIt takes no parameters, working instead with the object's attributes. First,\nit checks if the task has already completed by checking the C<$!done>\nattribute. If so, there's nothing to do.\n\nOtherwise, the method performs all of the task's dependencies, using the\nC construct to iterate over all of the items in the C<@!dependencies>\nattribute. This iteration places each item – each a C object – into\nthe topic variable, C<$_>. Using the C<.> method call operator without\nspecifying an explicit invocant uses the current topic as the invocant.\nThus the iteration construct calls the C<.perform()> method on every C\nobject in the C<@!dependencies> attribute of the current invocant.\n\nAfter all of the dependencies have completed, it's time to perform the\ncurrent C's task by invoking the C<&!callback> attribute directly;\nthis is the purpose of the parentheses. Finally, the method sets the\nC<$!done> attribute to C, so that subsequent invocations of C\non this object (if this C is a dependency of another C, for\nexample) will not repeat the task.\n\n=head2 X\n\nX<|Tutorial,Private methods>\nJust like attributes, methods can also be private. Private methods are declared\nwith a prefixed exclamation mark. They are called with C followed by the\nmethod's name. In the following implementation of a C class to\nextract L metadata from an mp3 file,\nmethods C, C, and C are private\nmethods while the remaining ones are public methods:\n\n=begin code\nclass MP3TagData {\n has $.filename where { .IO ~~ :e };\n\n has Str $.title is built(False);\n has Str $.artist is built(False);\n has Str $.album is built(False);\n has Str $.year is built(False);\n has Str $.comment is built(False);\n has Int $.genre is built(False);\n has Int $.track is built(False);\n has Str $.version is built(False);\n has Str $.type is built(False) = 'ID3';\n\n submethod TWEAK {\n with $!filename.IO.open(:r, :bin) -> $fh {\n $fh.seek(-128, SeekFromEnd);\n my $tagdata = $fh.read(128);\n self!parse-data: $tagdata;\n $fh.close;\n }\n else {\n warn \"Failed to open file.\"\n }\n }\n\n method !parse-data($data) {\n if self!can-read-format($data) {\n my $offset = $data.bytes - 128;\n\n $!title = self!trim-nulls: $data.subbuf($offset + 3, 30);\n $!artist = self!trim-nulls: $data.subbuf($offset + 33, 30);\n $!album = self!trim-nulls: $data.subbuf($offset + 63, 30);\n $!year = self!trim-nulls: $data.subbuf($offset + 93, 4);\n\n my Int $track-flag = $data.subbuf($offset + 97 + 28, 1).Int;\n $!track = $data.subbuf($offset + 97 + 29, 1).Int;\n\n ($!version, $!comment) = $track-flag == 0 && $!track != 0\n ?? ('1.1', self!trim-nulls: $data.subbuf($offset + 97, 28))\n !! ('1.0', self!trim-nulls: $data.subbuf($offset + 97, 30));\n\n $!genre = $data.subbuf($offset + 97 + 30, 1).Int;\n }\n }\n\n method !can-read-format(Buf $data --> Bool) {\n self!trim-nulls($data.subbuf(0..2)) eq 'TAG'\n }\n\n method !trim-nulls(Buf $data --> Str) {\n $data.decode('utf-8').subst(/\\x[0000]+/, '')\n }\n}\n=end code\n\nTo call a private method of another class, the caller has to be trusted by the\ncallee. A trust relationship is declared with\nL|/language/typesystem#trait_trusts> and the class to be trusted must\nalready be declared. Calling a private method of another class requires an\ninstance of that class and the fully qualified name (FQN) of the method. A trust\nrelationship also allows access to private attributes.\n\n=begin code\nclass B {...}\n\nclass C {\n trusts B;\n has $!hidden = 'invisible';\n method !not-yours () { say 'hidden' }\n method yours-to-use () {\n say $!hidden;\n self!not-yours();\n }\n}\n\nclass B {\n method i-am-trusted () {\n my C $c.=new;\n $c!C::not-yours();\n }\n}\n\nC.new.yours-to-use(); # the context of this call is GLOBAL, and not trusted by C\nB.new.i-am-trusted();\n=end code\n\nTrust relationships are not subject to inheritance. To trust the global\nnamespace, the pseudo package C can be used.\n\n\n=head1 X\n\nThe object construction mechanisms described up to now suffice for most use cases. But if one actually needs\nto tweak object construction more than said mechanisms allow, it's good to understand how object construction\nworks in more detail.\n\nRaku is rather more liberal than many languages in the area of\nconstructors. A constructor is anything that returns an instance of the\nclass. Furthermore, constructors are ordinary methods. You inherit a\ndefault constructor named C from the base class L|/type/Mu>, but you are\nfree to override C, as the Task example does:\n\n=begin code\nmethod new(&callback, *@dependencies) {\n return self.bless(:&callback, :@dependencies);\n}\n=end code\n\nX<|Tutorial,bless>\n=head2 bless\n\nThe biggest difference between constructors in Raku and constructors in\nlanguages such as C# and Java is that rather than setting up state on a\nsomehow already magically created object, Raku constructors create the\nobject themselves. They do this by calling the\nL method, also inherited from L|/type/Mu>.\nThe C method expects a set of named parameters to provide the initial\nvalues for each attribute.\n\nThe example's constructor turns positional arguments into named arguments,\nso that the class can provide a nicer constructor for its users. The first\nparameter is the callback (the thing which will execute the task). The rest\nof the parameters are dependent C instances. The constructor captures\nthese into the C<@dependencies> slurpy array and passes them as named\nparameters to C (note that C<:&callback> uses the name of the\nvariable – minus the sigil – as the name of the parameter).\nOne should refrain from putting logic other than reformulating the parameters in the constructor, because\nconstructor methods are not recursively called for parent classes. This is different from e.g. Java.\n\nDeclaring C as a C and not as a C prevents access to the default constructor.\n+So if you intend to keep the default constructor available, use C.\n\n=head2 X|Tutorial,TWEAK>\n\nAfter C has initialized the classes attributes from the passed values, it will in turn call C\nfor each class in the inheritance hierarchy.\nC gets passed all the arguments passed to bless.\nThis is where custom initialization logic should go.\n\nRemember to always make C a L and not a normal C. If in a class hierarchy a class contains a C method (declared as a C instead of a C) that method is inherited to its subclass and will thus be called twice during construction of the subclass!\n\n=head2 X|Tutorial,BUILD>\n\nIt is possible to disable the automatic attribute initialization and perform the initialization of\nattributes oneself. To do so one needs to write a custom C submethod. There are several edge cases one\nneeds to be aware of and take into account though. This is detailed in the\nL. Because of the difficulty of using\nC, it is recommended to only make use of it when none of the other approaches described above suffices.\n\nX<|Tutorial,submethod DESTROY>\n=head1 X\n\nRaku is a garbage collecting language. This means that one usually doesn't need to care about cleaning up objects,\nbecause Raku does so automatically. Raku does not give any guarantees as to when it will\nclean up a given object though. It usually does a cleanup run only if the runtime needs the memory, so we\ncan't rely on when it's going to happen.\n\nTo run custom code when an object is cleaned up one can use the C submethod. It can for example be used to close handles or supplies or delete temporary files that are no longer\ngoing to be used. As garbage collection can happen at arbitrary points during the runtime of our program, even in the middle of some totally unrelated piece of code in a different thread, we\n must make sure to not assume any context in our C submethod.\n\n=begin code\nmy $in_destructor = 0;\n\nclass Foo {\n submethod DESTROY { $in_destructor++ }\n}\n\nmy $foo;\nfor 1 .. 6000 {\n $foo = Foo.new();\n}\n\nsay \"DESTROY called $in_destructor times\";\n=end code\n\nThis might print something like C and possibly only kicks\nin after we have stomped over former instances of C a few thousand times. We also can't\nrely, on the order of destruction.\n\nSame as C: Make sure to always declare C as a C.\n\n=head1 Consuming our class\n\nAfter creating a class, you can create instances of the class. Declaring a\ncustom constructor provides a simple way of declaring tasks along with their\ndependencies. To create a single task with no dependencies, write:\n\n=for code :preamble\nmy $eat = Task.new({ say 'eating dinner. NOM!' });\n\nAn earlier section explained that declaring the class C installed a\ntype object in the namespace. This type object is a kind of \"empty\ninstance\" of the class, specifically an instance without any state. You can\ncall methods on that instance, as long as they do not try to access any\nstate; C is an example, as it creates a new object rather than\nmodifying or accessing an existing object.\n\nUnfortunately, dinner never magically happens. It has dependent tasks:\n\n=begin code :preamble\nmy $eat =\n Task.new({ say 'eating dinner. NOM!' },\n Task.new({ say 'making dinner' },\n Task.new({ say 'buying food' },\n Task.new({ say 'making some money' }),\n Task.new({ say 'going to the store' })\n ),\n Task.new({ say 'cleaning kitchen' })\n )\n );\n=end code\n\nNotice how the custom constructor and the sensible use of whitespace makes\ntask dependencies clear.\n\nFinally, the C method call recursively calls the C method\non the various other dependencies in order, giving the output:\n\n=begin code :lang\nmaking some money\ngoing to the store\nbuying food\ncleaning kitchen\nmaking dinner\neating dinner. NOM!\n=end code\n\n\n=head2 X\n\nX<|Tutorial,DEFINITE>\nDeclaring a class creates a new I which, by default, is installed\ninto the current package (just like a variable declared with C scope).\nThis type object is an \"empty instance\" of the class. For example, types such as\nL|/type/Int> and L|/type/Str> refer to the type object of one of the Raku built-in\nclasses. One can call methods on these type objects. So there is nothing special\nwith calling the C method on a type object.\n\nYou can use the C<.DEFINITE> method to find out if what you have is an instance\nor a type object:\n\n=begin code\nsay Int.DEFINITE; # OUTPUT: «False␤» (type object)\nsay 426.DEFINITE; # OUTPUT: «True␤» (instance)\n\nclass Foo {};\nsay Foo.DEFINITE; # OUTPUT: «False␤» (type object)\nsay Foo.new.DEFINITE; # OUTPUT: «True␤» (instance)\n=end code\n\nIn function signatures one can use so called type \"smileys\" to only accept instances\nor type objects:\n\n=begin code\nmulti foo (Int:U) { \"It's a type object!\" }\nmulti foo (Int:D) { \"It's an instance!\" }\nsay foo Int; # OUTPUT: «It's a type object!␤»\nsay foo 42; # OUTPUT: «It's an instance!␤»\n=end code\n\n=head1 X\n\nObject Oriented Programming provides the concept of inheritance as one of\nthe mechanisms for code reuse. Raku supports the ability for one\nclass to inherit from one or more classes. When a class inherits from\nanother class it informs the method dispatcher to follow the inheritance\nchain to look for a method to dispatch. This happens both for standard\nmethods defined via the C keyword and for methods generated through\nother means, such as attribute accessors.\n\n=begin code\nclass Employee {\n has $.salary;\n}\n\nclass Programmer is Employee {\n has @.known_languages is rw;\n has $.favorite_editor;\n\n method code_to_solve( $problem ) {\n return \"Solving $problem using $.favorite_editor in \"\n ~ $.known_languages[0];\n }\n}\n=end code\n\nNow, any object of type Programmer can make use of the methods and accessors\ndefined in the Employee class as though they were from the Programmer class.\n\n=begin code :preamble\nmy $programmer = Programmer.new(\n salary => 100_000,\n known_languages => ,\n favorite_editor => 'vim'\n);\n\nsay $programmer.code_to_solve('halting problem'),\n \" will get \\$ {$programmer.salary()}\";\n# OUTPUT: «Solving halting problem using vim in Raku will get $100000␤»\n=end code\n\n=head2 Overriding inherited methods\n\nClasses can override methods and attributes defined by parent\nclasses by defining their own. The example below demonstrates the C\nclass overriding the C's C method.\n\n=begin code :preamble\nclass Cook is Employee {\n has @.utensils is rw;\n has @.cookbooks is rw;\n\n method cook( $food ) {\n say \"Cooking $food\";\n }\n\n method clean_utensils {\n say \"Cleaning $_\" for @.utensils;\n }\n}\n\nclass Baker is Cook {\n method cook( $confection ) {\n say \"Baking a tasty $confection\";\n }\n}\n\nmy $cook = Cook.new(\n utensils => ,\n cookbooks => 'The Joy of Cooking',\n salary => 40000\n);\n\n$cook.cook( 'pizza' ); # OUTPUT: «Cooking pizza␤»\nsay $cook.utensils.raku; # OUTPUT: «[\"spoon\", \"ladle\", \"knife\", \"pan\"]␤»\nsay $cook.cookbooks.raku; # OUTPUT: «[\"The Joy of Cooking\"]␤»\nsay $cook.salary; # OUTPUT: «40000␤»\n\nmy $baker = Baker.new(\n utensils => 'self cleaning oven',\n cookbooks => \"The Baker's Apprentice\",\n salary => 50000\n);\n\n$baker.cook('brioche'); # OUTPUT: «Baking a tasty brioche␤»\nsay $baker.utensils.raku; # OUTPUT: «[\"self cleaning oven\"]␤»\nsay $baker.cookbooks.raku; # OUTPUT: «[\"The Baker's Apprentice\"]␤»\nsay $baker.salary; # OUTPUT: «50000␤»\n=end code\n\nBecause the dispatcher will see the C method on C before it\nmoves up to the parent class the C's C method will be called.\n\nTo access methods in the inheritance chain, use\nL or the\nL.\n\n=head2 Multiple inheritance\n\nAs mentioned before, a class can inherit from multiple classes. When a\nclass inherits from multiple classes the dispatcher knows to look at both\nclasses when looking up a method to search for. Raku uses the\nL to linearize\nmultiple inheritance hierarchies, which is better than depth-first search\nfor handling multiple inheritance.\n\n=begin code :preamble\nclass GeekCook is Programmer is Cook {\n method new( *%params ) {\n push( %params, \"Cooking for Geeks\" );\n return self.bless(|%params);\n }\n}\n\nmy $geek = GeekCook.new(\n books => 'Learning Raku',\n utensils => ('stainless steel pot', 'knife', 'calibrated oven'),\n favorite_editor => 'MacVim',\n known_languages => \n);\n\n$geek.cook('pizza');\n$geek.code_to_solve('P =? NP');\n=end code\n\nNow all the methods made available to the Programmer and the Cook classes\nare available from the GeekCook class.\n\nWhile multiple inheritance is a useful concept to know and occasionally use,\nit is important to understand that there are more useful OOP concepts. When\nreaching for multiple inheritance it is good practice to consider whether\nthe design wouldn't be better realized by using roles, which are generally\nsafer because they force the class author to explicitly resolve conflicting\nmethod names. For more information on roles, see\nL.\n\n=head2 The X|Tutorial,also declarator> declarator\n\nClasses to be inherited from can be listed in the class declaration body by\nprefixing the C trait with C. This also works for the role\ncomposition trait C.\n\n=begin code :preamble\nclass GeekCook {\n also is Programmer;\n also is Cook;\n # ...\n}\n\nrole A {};\nrole B {};\nclass C {\n also does A;\n also does B;\n # ...\n}\n=end code\n\n=head1 Introspection\n\nIntrospection is the process of gathering information about some objects in\nyour program, not by reading the source code, but by querying the object (or\na controlling object) for some properties, such as its type.\n\nGiven an object C<$o> and the class definitions from the previous sections,\nwe can ask it a few questions:\n\n=begin code :preamble\nmy Programmer $o .= new;\nif $o ~~ Employee { say \"It's an employee\" };\nsay $o ~~ GeekCook ?? \"It's a geeky cook\" !! \"Not a geeky cook\";\nsay $o.^name;\nsay $o.raku;\nsay $o.^methods(:local)».name.join(', ');\n=end code\n\nThe output might look like this:\n\n=begin code :lang\nIt's an employee\nNot a geeky cook\nProgrammer\nProgrammer.new(known_languages => [\"Perl\", \"Python\", \"Pascal\"],\n favorite_editor => \"gvim\", salary => \"too small\")\ncode_to_solve, known_languages, favorite_editor\n=end code\n\nThe first two tests each smartmatch against a class name. If the object is\nof that class, or of an inheriting class, it returns C. So the object in\nquestion is of class C or one that inherits from it, but not\nC.\n\nThe call C<$o.^name> tells us the type of C<$o>; in this case C.\n\nC<$o.raku> returns a string that can be executed as Raku code, and\nreproduces the original object C<$o>. While this does not work perfectly in\nall cases, it is very useful for debugging simple objects.\nN at some point.>\n\nThe syntax of calling a method with C<.^> instead of a single dot means that\nit is actually a method call on its I, which is a class managing\nthe properties of the C class – or any other class you are\ninterested in. This metaclass enables other ways of introspection too:\n\n=for code :preamble\nsay $o.^attributes.join(', ');\nsay $o.^parents.map({ $_.^name }).join(', ');\n\nFinally C<$o.^name> calls the C method on the metaobject, which\nunsurprisingly returns the class name.\n\nGiven an object C<$mp3> and the C class definition from the section\nL, we can inquire about its\npublic methods with C<.^methods>:\n\n=begin code :skip-test\nmy $mp3 = MP3TagData.new(filename => 'football-head.mp3');\nsay $mp3.^methods(:local);\n# OUTPUT: (TWEAK filename title artist album year comment genre track version\n# type Submethod+{is-hidden-from-backtrace}.new)\n=end code\n\nX<|Syntax,^methods>\nC<$mp3.^methods(:local)> produces a list of L|/type/Method>s that can be\ncalled on C<$mp3>. The C<:local> named argument limits the returned methods to\nthose defined in the C class and excludes the inherited methods;\nC inherits from no class, so providing C<:local> makes no difference.\n\nX<|Language,find_method>\nTo check if a type object (or an instance object) implements a certain public\nmethod, use the L|/routine/find_method> metamethod, which\nreturns the method object if it exists. Otherwise, it returns L|/type/Mu>.\n\n=begin code :skip-test\nsay $mp3.^find_method('name'); # OUTPUT: «(Mu)␤»\nsay $mp3.^find_method('artist'); # OUTPUT: «artist␤»\n=end code\n\nX<|Language,private_methods>\nX<|Language,find_private_methods>\nType objects can also be introspected for its private methods. However, public\nand private methods don't use the same APIs, and thus different metamethods\nmust be used: L|/routine/private_methods> and\nL|/routine/find_private_method>.\n\n=begin code :skip-test\nsay $mp3.^private_methods; # OUTPUT: «(parse-data can-read-format trim-nulls)␤»\nsay $mp3.^find_private_method('parse-data'); # OUTPUT: «parse-data␤»\nsay $mp3.^find_private_method('remove-nulls'); # OUTPUT: «(Mu)␤»\n=end code\n\nIntrospection is very useful for debugging and for learning the language\nand new libraries. When a function or method returns an object you don't\nknow about, by finding its type with C<.^name>, seeing a construction recipe\nfor it with C<.raku>, and so on, you'll get a good idea of what its return\nvalue is. With C<.^methods>, you can learn what you can do with the class.\n\nBut there are other applications too. For instance, a routine that serializes\nobjects to a bunch of bytes needs to know the attributes of that object,\nwhich it can find out via introspection.\n\n=head2 X\n\nSome classes might need their own version of C, which overrides the terse\nway they are printed when called to provide a default representation of the class.\nFor instance, L might want\nto write just the C and not the full object so that it is clearer what\nto see what's happened. However, this isn't limited to exceptions; you can\ndo that with every class:\n\n=begin code\nclass Cook {\n has @.utensils is rw;\n has @.cookbooks is rw;\n\n method cook( $food ) {\n return \"Cooking $food\";\n }\n\n method clean_utensils {\n return \"Cleaning $_\" for @.utensils;\n }\n\n multi method gist(Cook:U:) { '⚗' ~ self.^name ~ '⚗' }\n multi method gist(Cook:D:) {\n '⚗ Cooks with ' ~ @.utensils.join( \" ‣ \") ~ ' using '\n ~ @.cookbooks.map( \"«\" ~ * ~ \"»\").join( \" and \") }\n}\n\nmy $cook = Cook.new(\n utensils => ,\n cookbooks => ['Cooking for geeks','The French Chef Cookbook']);\n\nsay Cook.gist; # OUTPUT: «⚗Cook⚗»\nsay $cook.gist; # OUTPUT: «⚗ Cooks with spoon ‣ ladle ‣ knife ‣ pan using «Cooking for geeks» and «The French Chef Cookbook»␤»\n=end code\n\nUsually you will want to define two methods, one for the class and another for\nclass instances; in this case, the class method uses the alembic symbol, and the\ninstance method, defined below it, aggregates the data we have on the cook to show\nit in a narrative way.\n\n=head2 A practical introspection example\n\nWhen one creates a new class, it is sometimes useful to have\ninformative (and safe) introspection accessible more easily as a\npublic method. For example, the following class is used to hold\nattributes for a record row in a CSV spreadsheet with a header row\ndefining its field (attribute) names.\n\n=begin code :solo\nunit class CSV-Record;\n#| Field names and values for a CSV row\nhas $last;\nhas $first;\n#...more fields (attributes)...\n\nmethod fields(--> List) {\n #| Return a list of the the attribute names (fields)\n #| of the class instance\n my @attributes = self.^attributes;\n my @names;\n for @attributes -> $a {\n my $name = $a.name;\n # The name is prefixed by its sigil and twigil\n # which we don't want\n $name ~~ s/\\S\\S//;\n @names.push: $name;\n }\n @names\n}\n\nmethod values(--> List) {\n #| Return a list of the values for the attributes\n #| of the class instance\n my @attributes = self.^attributes;\n my @values;\n for @attributes -> $a {\n # Syntax is not obvious\n my $value = $a.get_value: self;\n @values.push: $value;\n }\n @values\n}\n=end code\n\nWe use it with a simple CSV file with contents:\n\n=begin code :lang\nlast, first #...more fields...\nWall, Larry\nConway, Damian\n=end code\n\nLoad the first record and show its contents:\n\n=begin code :preamble\nmy $record = CSV-Record.new: :$last, :$first;\nsay $record.fields.raku; # OUTPUT: «[\"last\", \"first\"]␤»\nsay $record.values.raku; # OUTPUT: «[\"Wall\", \"Larry\"]␤»\n=end code\n\nNote that practically we would have designed the class so that it has\nthe C list as a constant since its values are the same for all\nclass objects:\n\n=begin code\nconstant @fields = ;\nmethod fields(--> List) {\n @fields\n}\n=end code\n\nDownsides of using the introspective method for attribute names\ninclude slightly more processing time and power and the probable need\nto remove the sigil and twigil for public presentation.\n\n=end pod\n" }, { "path": "doc/Language/community.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"reference\")\n\n=TITLE Community\n\n=SUBTITLE Information about the people working on and using Raku\n\n=head1 Overview\n\n\"Perl 5 was my rewrite of Perl. I want Perl 6 to be the community's rewrite\nof Perl and of the community.\" - Larry Wall (circa 2000)\n\n\"I am in favor of this change [a community driven renaming from Perl 6 to Raku], because it reflects an ancient wisdom:\n'No one sews a patch of unshrunk cloth on an old garment, for the patch will pull away from\nthe garment, making the tear worse. Neither do people pour new wine into old wineskins.\nIf they do, the skins will burst; the wine will run out and the wineskins will be ruined.\nNo, they pour new wine into new wineskins, and both are preserved.'\" - Larry Wall\n(L<2019|https://github.com/Raku/problem-solving/pull/89#pullrequestreview-300789072>)\n\n=head1 The Raku community\n\n=head2 Online communities\n\nL communication has played an integral role in the Raku community for more than a decade. There are various channels for Raku-related activities on C. There are several L to make IRC activity more convenient and fun. You can read about IRC content L in greater details.\n\nL serves a similar purpose. Thanks to the bridges written by fellow Raku members, it integrates well with the main IRC channels.\n\nL is also a great\nresource for asking questions and helping others with their Raku problems and\nchallenges.\n\nMore resources can be found in the\nL.\n\n=head2 Offline communities\n\nRaku is also a common topic at\nL and\nL.\nIf you prefer in-person meetings, these are warmly recommended!\n\n=head2 Other resources\n\nL, the multi-color butterfly with P 6 in her wings, is the symbol of this diverse and welcoming community.\n\n=head1 Rakudo Weekly\n\nElizabeth Mattijsen usually posts in L, a summary of Raku posts, tweets, comments and other interesting tidbits.\nIf you want a single resource to know what is going on in the Raku community now, this is your best resource.\n\nHistorical articles (pre name change) can be found archived on\nL.\n\n=head1 Raku Advent calendar\n\nThe Raku community publishes every December an\nL, with Raku tutorials every day until\nChristmas. Previous calendars (pre name change) are\nL and relevant.\n\nOrganization and assignment of days is done through the different Raku channels and the\nL repository. If you want to\nparticipate, its organization starts by the end of October, so check out\nthe channels above to keep up to date.\n\n=comment HOW TO WRITE: One topic/point/idea per sentence, one sentence per line - to make diffs & translation easier.\n\n=end pod\n" }, { "path": "doc/Language/compilation.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"tutorial\")\n\n=TITLE CompUnits and where to find them\n\n=SUBTITLE How and when Raku modules are compiled, where they are stored, and how to access them in compiled form.\n\n=head1 Overview\n\nPrograms in Raku, as a member of the Perl language family, tend at the top level to be more at the interpreted\nend of the interpreted-compiled spectrum. In this tutorial, an 'interpreted' program means that the source code,\nnamely the human-readable text such as C, is immediately processed by the C program into code\nthat can be executed by the computer, with any intermediate stages being stored in memory.\n\nA compiled program, by contrast, is one where the human readable source is first processed into machine-executable code\nand some form of this code is stored 'on disk'. In order to execute the program, the machine-readable version is loaded\ninto memory and then run by the computer.\n\nBoth compiled and interpreted forms have advantages. Briefly, interpreted programs can be 'whipped up' quickly and\nthe source changed quickly. Compiled programs can be complex and take a significant time to pre-process into machine-readable\ncode, but then running them is much faster for a user, who only 'sees' the loading and running time, not the compilation\ntime.\n\nC has both paradigms. At the B a Raku program is interpreted, but code that is separated out into a\nModule will be compiled and the preprocessed version is then loaded when necessary. In practice, Modules that have been\nwritten by the community will only need to be precompiled once by a user when they are 'installed', for example by a\nModule manager such as C. Then they can be Cd by a developer in her own program. The effect is to make C\ntop level programs run quickly.\n\nOne of the great strengths of the C family of languages was the ability to integrate a whole ecosystem of modules\nwritten by competent programmers into a small program. This strength was widely copied and is now the norm for all\nlanguages. C takes integration even further, making it relatively easy for C programs to incorporate system\nlibraries written in other languages into C programs, see L.\n\nThe experience from C and other languages is that the distributive nature of Modules generate several practical difficulties:\n=item a popular module may go through several iterations as the API gets improved, without a guarantee that there is\nbackward compatibility. So, if a program relies on some specific function or return, then there has to be a way to\nspecify the L|/type/Version>.\n=item a module may have been written by Bob, a very competent programmer, who moves on in life, leaving the module unmaintained,\nso Alice takes over. This means that the same module, with the same name, and the same general API may have two\nversions in the wild. Alternatively, two developers (e.g., Alice and Bob) who initially cooperated on a module, then part company about its\ndevelopment. Consequently, it sometimes is necessary for there to be a way to define the B of the module.\n=item a module may be enhanced over time and the maintainer keeps two versions up to date, but with different APIs. So it is\nmay be necessary to define the B required.\n=item when developing a new program a developer may want to have the modules written by both Alice and Bob installed locally.\nSo it is not possible simply to have only one version of a module with a single name installed.\n\nC enables all of these possibilities, allowing for multiple versions, multiple authorities, and multiple APIs to be present,\ninstalled, and available locally. The way classes and modules can be accessed with specific attributes\nis explained L. This tutorial is about how C handles these\npossibilities.\n\n=head1 Introduction\n\nBefore considering the C framework, let's have a look at how languages like C or C handle module\ninstallation and loading.\n\n=begin code :lang\nACME::Foo::Bar -> ACME/Foo/Bar.pm\nos.path -> os/path.py\n=end code\n\nIn those languages, module names have a 1:1 relation with filesystem paths.\nWe simply replace the double colons or periods with slashes and add a C<.pm> or C<.py>.\n\nNote that these are relative paths.\nBoth C and C use a list of include paths, to complete these paths.\nIn C they are available in the global C<@INC> array.\n\n=begin code :lang\n@INC\n\n/usr/lib/perl5/site_perl/5.22.1/x86_64-linux-thread-multi\n/usr/lib/perl5/site_perl/5.22.1/\n/usr/lib/perl5/vendor_perl/5.22.1/x86_64-linux-thread-multi\n/usr/lib/perl5/vendor_perl/5.22.1/\n/usr/lib/perl5/5.22.1/x86_64-linux-thread-multi\n/usr/lib/perl5/5.22.1/\n=end code\n\nEach of these include directories is checked for whether it contains a relative path determined from the module name.\nIf the shoe fits, the file is loaded.\n\nOf course that's a bit of a simplified version.\nBoth languages support caching compiled versions of modules.\nSo instead of just the C<.pm> file C first looks for a C<.pmc> file.\nAnd C first looks for C<.pyc> files.\n\nModule installation in both cases means mostly copying files into locations determined by the same simple mapping. The\nsystem is easy to explain, easy to understand, simple and robust.\n\n=head2 Why change?\n\nWhy would C need another framework? The reason is there are features that those languages lack, namely:\n=item Unicode module names\n=item Modules published under the same names by different authors\n=item Having multiple versions of a module installed\n\nThe set of 26 Latin characters is too restrictive for virtually all real modern languages, including English, which\nhave diacritics for many commonly-used words.\n\nWith a 1:1 relation between module names and filesystem paths, you enter a world of pain\nonce you try to support Unicode on multiple platforms and filesystems.\n\nThen there's sharing module names between multiple authors. This one may or may not work out well in practice.\nI can imagine using it for example for publishing a module with some fix until the original author includes\nthe fix in the \"official\" version.\n\nFinally there's multiple versions. Usually people who need certain versions of modules reach for local::lib or\ncontainers or some home grown workarounds. They all have their own disadvantages. None of them would be necessary\nif applications could just say, hey I need good old, trusty version 2.9 or maybe a bug fix release of that branch.\n\nIf you had any hopes of continuing using the simple name mapping solution, you probably gave up at the\nversioning requirement. Because, how would you find version 3.2 of a module when looking for a 2.9 or higher?\n\nPopular ideas included collecting information about installed modules in JSON files but when those turned out to be\ntoe-nail growing slow, text files were replace by putting the metadata into SQLite databases.\nHowever, these ideas can be easily shot down by introducing another requirement: distribution packages.\n\nPackages for Linux distributions are mostly just archives containing some files plus some metadata.\nIdeally the process of installing such a package means just unpacking the files and updating the central package database.\nUninstalling means deleting the files installed this way and again updating the package database.\nChanging existing files on install and uninstall makes packagers' lives much harder, so we really want to avoid that.\nAlso the names of the installed files may not depend on what was previously installed.\nWe must know at the time of packaging what the names are going to be.\n\n=head2 Long names\n\n=begin code :lang\nFoo::Bar:auth:ver<0.3>:api<1>\n=end code\n\nStep 0 in getting us back out of this mess is to define a long name.\nA full module name in C consists of the short-name, auth, version and API\n\nAt the same time, the thing you install is usually not a single module but a distribution which probably contains one or more modules.\nDistribution names work just the same way as module names.\nIndeed, distributions often will just be called after their main module.\nAn important property of distributions is that they are immutable.\nC«Foo:auth:ver<0.3>:api<1>» will always be the name for exactly the same code.\n\n=head2 $*REPO\n\nIn C and C you deal with include paths pointing to filesystem directories.\nIn C we call such directories \"repositories\" and each of these repositories is governed by an object that does the\nL|/type/CompUnit::Repository> role.\nInstead of an B> array, there's the C<$*REPO> variable.\nIt contains a single repository object.\nThis object has a B attribute that may contain another repository.\nIn other words: repositories are managed as a I.\nThe important difference to the traditional array is, that when going through the list, each object has a say in whether\nto pass along a request to the next-repo or not.\nC sets up a standard set of repositories, \"core\", \"vendor\", and \"site\".\nIn addition, there is a \"home\" repository for the current user.\n\nRepositories must implement the C method.\nA C or C statement in C code is basically translated to a call to B>'s C method.\nThis method may in turn delegate the request to the next-repo.\n\n=begin code :preamble :method\nrole CompUnit::Repository {\n has CompUnit::Repository $.next-repo is rw;\n\n method need(CompUnit::DependencySpecification $spec,\n CompUnit::PrecompilationRepository $precomp,\n CompUnit::Store :@precomp-stores\n --> CompUnit:D\n )\n { ... }\n method loaded(\n --> Iterable\n )\n { ... }\n\n method id( --> Str )\n { ... }\n}\n=end code\n\n=head2 Repositories\n\nRakudo comes with several classes that can be used for repositories.\nThe most important ones are L|/type/CompUnit::Repository::FileSystem> and L|/type/CompUnit::Repository::Installation>.\nThe FileSystem repo is meant to be used during module development and actually works just like C when\nlooking for a module.\nIt doesn't support versions or Cs and simply maps the short-name to a filesystem path.\n\nThe Installation repository is where the real smarts are. When requesting a module, you will usually either do it\nvia its exact long name, or you say something along the lines of \"give me a module that matches this filter.\"\nSuch a filter is given by way of a C object which has fields for\n=item short-name,\n=item auth-matcher,\n=item version-matcher and\n=item api-matcher.\n\nWhen looking through candidates, the Installation repository will smartmatch a module's long name against this\nDependencySpecification or rather the individual fields against the individual matchers.\nThus a matcher may be some concrete value, a version range, or even a regex (though an arbitrary regex, such as C<.*>,\nwould not produce a useful result, but something like C<3.20.1+> will only find candidates higher than 3.20.1).\n\nLoading the metadata of all installed distributions would be prohibitively slow. The current implementation of\nthe C framework uses\nthe filesystem as a kind of database. However, another implementation may use another strategy. The following description\nshows how one implementation works and is included here to illustrate what is happening.\n\nWe store not only a distribution's files but also create indices for speeding up lookups.\nOne of these indices comes in the form of directories named after the short-name of installed modules.\nHowever most of the filesystems in common use today cannot handle Unicode names, so we cannot just use\nmodule names directly.\nThis is where the now infamous SHA-1 hashes enter the game.\nThe directory names are the ASCII encoded SHA-1 hashes of the UTF-8 encoded module short-names.\n\nIn these directories we find one file per distribution that contains a module with a matching short name.\nThese files again contain the ID of the dist and the other fields that make up the long name: auth, version, and api.\nSo by reading these files we have a usually short list of auth-version-api triplets which we can match against our\nDependencySpecification.\nWe end up with the winning distribution's ID, which we use to look up the metadata, stored in a JSON encoded file.\nThis metadata contains the name of the file in the sources/ directory containing the requested module's code.\nThis is what we can load.\n\nFinding names for source files is again a bit tricky, as there's still the Unicode issue and in addition the same\nrelative file names may be used by different installed distributions (think versions).\nSo for now at least, we use SHA-1 hashes of the long-names.\n\n=head2 Resources\n\n=begin code :lang\n%?RESOURCES\n%?RESOURCES\n%?RESOURCES\n%?RESOURCES\n\nFoo\n|___ lib\n| |____ Foo.rakumod\n|\n|___ resources\n |___ schema.sql\n |\n |___ libraries\n |____ p5helper\n | |___\n |___ icons\n |___ foo.png\n=end code\n\nIt's not only source files that are stored and found this way.\nDistributions may also contain arbitrary resource files.\nThese could be images, language files or shared libraries that are compiled on installation.\nThey can be accessed from within the module through the C<%?RESOURCES> hash.\n\nAs long as you stick to the standard layout conventions for distributions, this even works during development\nwithout installing anything.\n\nA nice result of this architecture is that it's fairly easy to create special purpose repositories.\n\n=head2 Dependencies\n\nLuckily precompilation at least works quite well in most cases. Yet it comes with its own set of challenges.\nLoading a single module is easy.\nThe fun starts when a module has dependencies and those dependencies have again dependencies of their own.\n\nWhen loading a precompiled file in C we need to load the precompiled files of all its dependencies, too.\nAnd those dependencies B be precompiled, we cannot load them from source files.\nEven worse, the precomp files of the dependencies B be exactly the same files we used for precompiling our\nmodule in the first place.\n\nTo top it off, precompiled files work only with the exact C binary, that was used for compilation.\n\nAll of that would still be quite manageable if it weren't for an additional requirement: as a user you expect a new\nversion of a module you just installed to be actually used, don't you?\n\nIn other words: if you upgrade a dependency of a precompiled module, we have to detect this and precompile the module\nagain with the new dependency.\n\n=head2 Precomp stores\n\nNow remember that while we have a standard repository chain, the user may prepend additional repositories by way of\nC<-I> on the command line or \"use lib\" in the code.\n\nThese repositories may contain the dependencies of precompiled modules.\n\nOur first solution to this riddle was that each repository gets its own precomp store where precompiled files are stored.\nWe only ever load precomp files from the precomp store of the very first repository in the chain because this is the\nonly repository that has direct or at least indirect access to all the candidates.\n\nIf this repository is a FileSystem repository, we create a precomp store in a C<.precomp> directory.\n\nWhile being the safe option, this has the consequence that whenever you use a new repository, we will start out\nwithout access to precompiled files.\n\nInstead, we will precompile the modules used when they are first loaded.\n\n=head2 Credit\n\nThis tutorial is based on a C L.\n\n=end pod\n" }, { "path": "doc/Language/concurrency.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"tutorial\")\n\n=TITLE Concurrency\n\n=SUBTITLE Concurrency and asynchronous programming\n\nIn common with most modern programming languages, Raku is designed to support\nparallelism, asynchronicity and\nL. Parallelism\nis about doing multiple things at once. I, which is\nsometimes called event driven or reactive programming, is about supporting\nchanges in the program flow caused by events triggered elsewhere in the program.\nFinally, concurrency is about the coordination of access and modification of\nsome shared resources.\n\nThe aim of the Raku concurrency design is to provide a high-level,\ncomposable and consistent interface, regardless of how a virtual machine\nmay implement it for a particular operating system, through layers of\nfacilities as described below.\n\n=begin comment\n\nI'm not quite clear which specific features should be included below\n\nhyper-operators, autothreading junctions?\n\n=end comment\n\nAdditionally, certain Raku features may implicitly operate in an asynchronous\nfashion, so in order to ensure predictable interoperation with these features,\nuser code should, where possible, avoid the lower level concurrency APIs (e.g.,\nL|/type/Thread> and L|/type/Scheduler>) and use the\nhigher-level interfaces.\n\n=head1 High-level APIs\n\nX<|Other languages,Futures>\n=head2 Promises\n\nA L|/type/Promise> (also called I in other programming\nenvironments) encapsulates the result of a computation that may not\nhave completed or even started at the time the promise is obtained.\nA L|/type/Promise> starts from a C status and can result in either a\nC status, meaning the promise has been successfully completed, or\na C status meaning that the promise has failed.\nUsually this is much of the functionality that user code needs to operate\nin a concurrent or asynchronous manner.\n\n=begin code\nmy $p1 = Promise.new;\nsay $p1.status; # OUTPUT: «Planned␤»\n$p1.keep('Result');\nsay $p1.status; # OUTPUT: «Kept␤»\nsay $p1.result; # OUTPUT: «Result␤»\n # (since it has been kept, a result is available!)\n\nmy $p2 = Promise.new;\n$p2.break('oh no');\nsay $p2.status; # OUTPUT: «Broken␤»\nsay $p2.result; # dies, because the promise has been broken\nCATCH { default { say .^name, ': ', .Str } };\n# OUTPUT: «X::AdHoc+{X::Promise::Broken}: oh no␤»\n=end code\n\nPromises gain much of their power by being composable, for example by\nchaining, usually by the L method:\n\n my $promise1 = Promise.new();\n my $promise2 = $promise1.then(\n -> $v { say $v.result; \"Second Result\" }\n );\n $promise1.keep(\"First Result\");\n say $promise2.result; # OUTPUT: «First Result␤Second Result␤»\n\nHere the L method schedules code to be executed\nwhen the first L|/type/Promise> is kept or broken, itself returning a\nnew L|/type/Promise> which will be kept with the result of the code when\nit is executed (or broken if the code fails). C changes the status of the\npromise to C setting the result to the positional argument. C\nblocks the current thread of execution until the promise is kept or broken, if\nit was kept then it will return the result (that is the value passed to\nC), otherwise it will throw an exception based on the value passed to\nC. The latter behavior is illustrated with:\n\n my $promise1 = Promise.new();\n my $promise2 = $promise1.then(-> $v { say \"Handled but : \"; say $v.result});\n $promise1.break(\"First Result\");\n try $promise2.result;\n say $promise2.cause; # OUTPUT: «Handled but : ␤First Result␤»\n\nHere the C will cause the code block of the C to throw an exception\nwhen it calls the C method on the original promise that was passed as an\nargument, which will subsequently cause the second promise to be broken, raising\nan exception in turn when its result is taken. The actual\nL|/type/Exception> object will then be available from C. If the\npromise had not been broken C would raise an\nL|/type/X::Promise::CauseOnlyValidOnBroken> exception.\n\nA L|/type/Promise> can also be scheduled to be automatically kept at a\nfuture time:\n\n my $promise1 = Promise.in(5);\n my $promise2 = $promise1.then(-> $v { say $v.status; 'Second Result' });\n say $promise2.result;\n\nThe L creates a new promise and\nschedules a new task to call C on it no earlier than the supplied\nnumber of seconds, returning the new L|/type/Promise> object.\n\nA very frequent use of promises is to run a piece of code, and keep the\npromise once it returns successfully, or break it when the code dies.\nThe L provides a shortcut\nfor that:\n\n my $promise = Promise.start(\n { my $i = 0; for 1 .. 10 { $i += $_ }; $i}\n );\n say $promise.result; # OUTPUT: «55␤»\n\nHere the C of the promise returned is the value returned from\nthe code. Similarly if the code fails (and the promise is thus broken),\nthen C will be the L|/type/Exception> object that was thrown:\n\n my $promise = Promise.start({ die \"Broken Promise\" });\n try $promise.result;\n say $promise.cause;\n\nThis is considered to be such a commonly required pattern that it is\nalso provided as a keyword:\n\n my $promise = start {\n my $i = 0;\n for 1 .. 10 {\n $i += $_\n }\n $i\n }\n my $result = await $promise;\n say $result;\n\nThe subroutine L is almost equivalent to\ncalling C on the promise object returned by C but it will\nalso take a list of promises and return the result of each:\n\n my $p1 = start {\n my $i = 0;\n for 1 .. 10 {\n $i += $_\n }\n $i\n };\n my $p2 = start {\n my $i = 0;\n for 1 .. 10 {\n $i -= $_\n }\n $i\n };\n my @result = await $p1, $p2;\n say @result; # OUTPUT: «[55 -55]␤»\n\nIn addition to C, two class methods combine several\nL|/type/Promise> objects into a new promise: C returns a promise\nthat is kept when all the original promises are kept or broken:\n\n my $promise = Promise.allof(\n Promise.in(2),\n Promise.in(3)\n );\n\n await $promise;\n say \"All done\"; # Should be not much more than three seconds later\n\nAnd C returns a new promise that will be kept when any of the\noriginal promises is kept or broken:\n\n my $promise = Promise.anyof(\n Promise.in(3),\n Promise.in(8600)\n );\n\n await $promise;\n say \"All done\"; # Should be about 3 seconds later\n\nUnlike C however the results of the original kept promises are not\navailable without referring to the original, so these are more useful\nwhen the completion or otherwise of the tasks is more important to the\nconsumer than the actual results, or when the results have been collected\nby other means. You may, for example, want to create a dependent Promise\nthat will examine each of the original promises:\n\n my @promises;\n for 1..5 -> $t {\n push @promises, start {\n sleep $t;\n Bool.pick;\n };\n }\n say await Promise.allof(@promises).then({ so all(@promises>>.result) });\n\nWhich will give True if all of the promises were kept with True, False\notherwise.\n\nIf you are creating a promise that you intend to keep or break yourself\nthen you probably don't want any code that might receive the promise to\ninadvertently (or otherwise) keep or break the promise before you do.\nFor this purpose there is the L, which\nreturns a Vow object which becomes the only mechanism by which the promise\ncan be kept or broken. If an attempt to keep or break the Promise is made\ndirectly then the exception L|/type/X::Promise::Vowed> will be thrown, as long\nas the vow object is kept private, the status of the promise is safe:\n\n sub get_promise {\n my $promise = Promise.new;\n my $vow = $promise.vow;\n Promise.in(10).then({$vow.keep});\n $promise;\n }\n\n my $promise = get_promise();\n\n # Will throw an exception\n # \"Access denied to keep/break this Promise; already vowed\"\n $promise.keep;\n CATCH { default { say .^name, ': ', .Str } };\n # OUTPUT: «X::Promise::Vowed: Access denied to keep/break this Promise; already vowed␤»\n\nThe methods that return a promise that will be kept or broken\nautomatically such as C or C will do this, so it is not\nnecessary to do it for these.\n\n=head2 Supplies\n\nA L|/type/Supply> is an asynchronous data streaming mechanism that can be\nconsumed by one or more consumers simultaneously in a manner similar to\n\"events\" in other programming languages and can be seen as enabling\nI or reactive designs.\n\nAt its simplest, a L|/type/Supply> is a message stream that can have\nmultiple subscribers created with the method C on to which data items can\nbe placed with C.\n\nThere are two types of Supplies: C and C. A C\nsupply is like a TV broadcast: those who tune in don't get previously emitted\nvalues. An C broadcast is like a video streaming service:\neveryone who starts streaming a movie (taps a L|/type/Supply>),\nalways starts it from the beginning (gets all the values),\nregardless of how many people are watching it right now.\n\nNote that no\nhistory is kept for C supplies, instead, the C block is run\nfor each tap of the supply.\n\nA C L|/type/Supply>\nis created by the L|/type/Supplier> factory, each emitted value is passed to\nall the active tappers as they are added:\n\n my $supplier = Supplier.new;\n my $supply = $supplier.Supply;\n\n $supply.tap( -> $v { say $v });\n\n for 1 .. 10 {\n $supplier.emit($_);\n }\n\nNote that the C is called on a L|/type/Supply> object created by the\nL|/type/Supplier> and new values are emitted on the\nL|/type/Supplier>.\n\nX<|Reference,supply (on-demand)>\nAn C L|/type/Supply> is created by the C keyword:\n\n my $supply = supply {\n for 1 .. 10 {\n emit($_);\n }\n }\n $supply.tap( -> $v { say $v });\n\nIn this case the code in the supply block is executed every time the\nL|/type/Supply> returned by C is tapped, as demonstrated by:\n\n my $supply = supply {\n for 1 .. 10 {\n emit($_);\n }\n }\n $supply.tap( -> $v { say \"First : $v\" });\n $supply.tap( -> $v { say \"Second : $v\" });\n\nThe C method returns a L|/type/Tap> object which can be used to obtain\ninformation about the tap and also to turn it off when we are no longer\ninterested in the events:\n\n my $supplier = Supplier.new;\n my $supply = $supplier.Supply;\n\n my $tap = $supply.tap( -> $v { say $v });\n\n $supplier.emit(\"OK\");\n $tap.close;\n $supplier.emit(\"Won't trigger the tap\");\n\nCalling C on the supply object calls the C callback that\nmay be specified for any taps, but does not prevent any further events\nbeing emitted to the stream, or taps receiving them.\n\nThe method C returns a new C supply which periodically\nemits a new event at the specified interval. The data that is emitted\nis an integer starting at 0 that is incremented for each event. The\nfollowing code outputs 0 .. 5 :\n\n\n my $supply = Supply.interval(2);\n $supply.tap(-> $v { say $v });\n sleep 10;\n\nA second argument can be supplied to C which specifies a delay\nin seconds before the first event is fired. Each tap of a supply created\nby C has its own sequence starting from 0, as illustrated by\nthe following:\n\n my $supply = Supply.interval(2);\n $supply.tap(-> $v { say \"First $v\" });\n sleep 6;\n $supply.tap(-> $v { say \"Second $v\"});\n sleep 10;\n\nA live L|/type/Supply> that keeps values until first tapped can be created with\nL|/type/Supplier::Preserving>.\n\n\n=head3 X|Control flow,whenever>\n\nThe C keyword can be used in supply blocks or in react\nblocks. From the 6.d version, it needs to be used within the lexical scope of\nthem. It introduces a block of code that will be run when prompted by an\nasynchronous event that it specifies - that could be a L|/type/Supply>, a\nL|/type/Channel>, a L|/type/Promise> or an\nL|/type/Iterable>.\n\nPlease note that one should keep the code inside the C as small as\npossible, as only one C block will be executed at any time. One can\nuse a C block inside the C block to run longer running code.\n\nIn this example we are watching two supplies.\n\n=begin code\nmy $bread-supplier = Supplier.new;\nmy $vegetable-supplier = Supplier.new;\n\nmy $supply = supply {\n whenever $bread-supplier.Supply {\n emit(\"We've got bread: \" ~ $_);\n };\n whenever $vegetable-supplier.Supply {\n emit(\"We've got a vegetable: \" ~ $_);\n };\n}\n$supply.tap( -> $v { say \"$v\" });\n\n$vegetable-supplier.emit(\"Radish\"); # OUTPUT: «We've got a vegetable: Radish␤»\n$bread-supplier.emit(\"Thick sliced\"); # OUTPUT: «We've got bread: Thick sliced␤»\n$vegetable-supplier.emit(\"Lettuce\"); # OUTPUT: «We've got a vegetable: Lettuce␤»\n=end code\n\n\n=head3 X|Control flow,react>\n\nThe C keyword introduces a block of code containing one or more\nC keywords to watch asynchronous events. The main difference between a\nsupply block and a react block is that the code in a react block runs where it\nappears in the code flow, whereas a supply block has to be tapped before it does\nanything.\n\nAnother difference is that a supply block can be used without the C\nkeyword, but a react block requires at least one C to be of any real\nuse.\n\n react {\n whenever Supply.interval(2) -> $v {\n say $v;\n done() if $v == 4;\n }\n }\n\nHere the C keyword uses L«C<.act>|/type/Supply#method_act» to create a\ntap on the L|/type/Supply> from the provided block. The C block is\nexited when C is called in one of the taps.\n\nAn C L|/type/Supply> can also be created from a list of values\nthat will be emitted in turn, thus the first C example could be\nwritten as:\n\n react {\n whenever Supply.from-list(1..10) -> $v {\n say $v;\n }\n }\n\n=head3 Transforming supplies\n\nAn existing supply object can be filtered or transformed, using the methods\nC and C respectively, to create a new supply in a manner like\nthe similarly named list methods: C returns a supply such that only\nthose events emitted on the source stream for which the C condition\nis true is emitted on the second supply:\n\n my $supplier = Supplier.new;\n my $supply = $supplier.Supply;\n $supply.tap(-> $v { say \"Original : $v\" });\n my $odd_supply = $supply.grep({ $_ % 2 });\n $odd_supply.tap(-> $v { say \"Odd : $v\" });\n my $even_supply = $supply.grep({ not $_ % 2 });\n $even_supply.tap(-> $v { say \"Even : $v\" });\n for 0 .. 10 {\n $supplier.emit($_);\n }\n\nC returns a new supply such that for each item emitted to the\noriginal supply a new item which is the result of the expression passed\nto the C is emitted:\n\n my $supplier = Supplier.new;\n my $supply = $supplier.Supply;\n $supply.tap(-> $v { say \"Original : $v\" });\n my $half_supply = $supply.map({ $_ / 2 });\n $half_supply.tap(-> $v { say \"Half : $v\" });\n for 0 .. 10 {\n $supplier.emit($_);\n }\n\n=head3 Ending a supply\n\nIf you need to have an action that runs when the supply finishes, you can do so\nby setting the C and C options in the call to C:\n\n =begin code :preamble\n $supply.tap: { ... },\n done => { say 'Job is done.' },\n quit => {\n when X::MyApp::Error { say \"App Error: \", $_.message }\n };\n =end code\n\nThe C block works very similar to a C. If the exception is marked\nas seen by a C or C block, the exception is caught and handled.\nOtherwise, the exception continues to up the call tree (i.e., the same behavior\nas when C is not set).\n\n=head3 Phasers in a supply or react block\n\nIf you are using the C or C block syntax with C, you\ncan add phasers within your C blocks to handle the C and C\nmessages from the tapped supply:\n\n =begin code :preamble\n react {\n whenever $supply {\n ...; # your usual supply tap code here\n LAST { say 'Job is done.' }\n QUIT { when X::MyApp::Error { say \"App Error: \", $_.message } }\n }\n }\n =end code\n\nThe behavior here is the same as setting C and C on C.\n\n=head2 Channels\n\nA L|/type/Channel> is a thread-safe queue that can have multiple readers and\nwriters that could be considered to be similar in operation to a \"fifo\" or\nnamed pipe except it does not enable inter-process communication. It should\nbe noted that, being a true queue, each value sent to the L|/type/Channel> will only\nbe available to a single reader on a first read, first served basis: if you\nwant multiple readers to be able to receive every item sent you probably\nwant to consider a L|/type/Supply>.\n\nAn item is queued onto the L|/type/Channel> with the\nL, and the L removes an item from the queue\nand returns it, blocking until a new item is sent if the queue is empty:\n\n my $channel = Channel.new;\n $channel.send('Channel One');\n say $channel.receive; # OUTPUT: «Channel One␤»\n\nIf the channel has been closed with the L then any C will cause the\nexception L|/type/X::Channel::SendOnClosed> to be thrown, and a C\nwill throw an L|/type/X::Channel::ReceiveOnClosed>.\n\nThe L returns all the items on\nthe L|/type/Channel> and will block until further items are queued unless the\nchannel is closed:\n\n my $channel = Channel.new;\n await (^10).map: -> $r {\n start {\n sleep $r;\n $channel.send($r);\n }\n }\n $channel.close;\n for $channel.list -> $r {\n say $r;\n }\n\nThere is also the non-blocking L\nthat returns an available item from the channel or L|/type/Nil> if there\nis no item or the channel is closed. This does mean that the\nchannel must be checked to determine whether it is closed:\n\n my $c = Channel.new;\n\n # Start three Promises that sleep for 1..3 seconds, and then\n # send a value to our Channel\n ^3 .map: -> $v {\n start {\n sleep 3 - $v;\n $c.send: \"$v from thread {$*THREAD.id}\";\n }\n }\n\n # Wait 3 seconds before closing the channel\n Promise.in(3).then: { $c.close }\n\n # Continuously loop and poll the channel, until it's closed\n my $is-closed = $c.closed;\n loop {\n if $c.poll -> $item {\n say \"$item received after {now - INIT now} seconds\";\n }\n elsif $is-closed {\n last;\n }\n\n say 'Doing some unrelated things...';\n sleep .6;\n }\n\n # Doing some unrelated things...\n # Doing some unrelated things...\n # 2 from thread 5 received after 1.2063182 seconds\n # Doing some unrelated things...\n # Doing some unrelated things...\n # 1 from thread 4 received after 2.41117376 seconds\n # Doing some unrelated things...\n # 0 from thread 3 received after 3.01364461 seconds\n # Doing some unrelated things...\n\nThe L returns a L|/type/Promise> that\nwill be kept (and consequently will evaluate to True in a Boolean context)\nwhen the channel is closed.\n\nThe C<.poll> method can be used in combination with C<.receive> method, as a\ncaching mechanism where lack of value returned by C<.poll> is a signal that\nmore values need to be fetched and loaded into the channel:\n\n =begin code :preamble\n sub get-value {\n return $c.poll // do { start replenish-cache; $c.receive };\n }\n\n sub replenish-cache {\n for ^20 {\n $c.send: $_ for slowly-fetch-a-thing();\n }\n }\n =end code\n\nChannels can be used in place of the L|/type/Supply> in the C of a\nC block described earlier:\n\n =begin code\n my $channel = Channel.new;\n my $p = start {\n react {\n whenever $channel {\n say $_;\n }\n }\n }\n\n await (^10).map: -> $r {\n start {\n sleep $r;\n $channel.send($r);\n }\n }\n\n $channel.close;\n await $p;\n =end code\n\nIt is also possible to obtain a L|/type/Channel> from a L|/type/Supply> using the\nL which returns a L|/type/Channel>\nwhich is fed by a C on the L|/type/Supply>:\n\n my $supplier = Supplier.new;\n my $supply = $supplier.Supply;\n my $channel = $supply.Channel;\n\n my $p = start {\n react {\n whenever $channel -> $item {\n say \"via Channel: $item\";\n }\n }\n }\n\n await (^10).map: -> $r {\n start {\n sleep $r;\n $supplier.emit($r);\n }\n }\n\n $supplier.done;\n await $p;\n\nL|/type/Channel> will return a different L|/type/Channel> fed with the same data\neach time it is called. This could be used, for instance, to fan-out a\nL|/type/Supply> to one or more L|/type/Channel>s to provide for different interfaces\nin a program.\n\n=head2 Proc::Async\n\nL|/type/Proc::Async> builds on the facilities described to run and interact with\nan external program asynchronously:\n\n my $proc = Proc::Async.new('echo', 'foo', 'bar');\n\n $proc.stdout.tap(-> $v { print \"Output: $v\" });\n $proc.stderr.tap(-> $v { print \"Error: $v\" });\n\n say \"Starting...\";\n my $promise = $proc.start;\n\n await $promise;\n say \"Done.\";\n\n # Output:\n # Starting...\n # Output: foo bar\n # Done.\n\nThe path to the command as well as any arguments to the command are\nsupplied to the constructor. The command will not be executed until\nL is called, which will return\na L|/type/Promise> that will be kept when the program exits. The standard\noutput and standard error of the program are available as L|/type/Supply>\nobjects from the methods L\nand L respectively which can be\ntapped as required.\n\nIf you want to write to the standard input of the program\nyou can supply the C<:w> adverb to the constructor and use\nthe methods L,\nL or\nL to write to the opened pipe once\nthe program has been started:\n\n my $proc = Proc::Async.new(:w, 'grep', 'foo');\n\n $proc.stdout.tap(-> $v { print \"Output: $v\" });\n\n say \"Starting...\";\n my $promise = $proc.start;\n\n $proc.say(\"this line has foo\");\n $proc.say(\"this one doesn't\");\n\n $proc.close-stdin;\n await $promise;\n say \"Done.\";\n\n # Output:\n # Starting...\n # Output: this line has foo\n # Done.\n\nSome programs (such as C without a file argument in this\nexample, ) won't exit until their standard input is closed so\nL can be called when\nyou are finished writing to allow the L|/type/Promise> returned by C\nto be kept.\n\n=head1 Low-level APIs\n\n=head2 Threads\n\nThe lowest level interface for concurrency is provided by L|/type/Thread>. A\nthread can be thought of as a piece of code that may eventually be run\non a processor, the arrangement for which is made almost entirely by the\nvirtual machine and/or operating system. Threads should be considered,\nfor all intents, largely un-managed and their direct use should be\navoided in user code.\n\nA thread can either be created and then actually run later:\n\n my $thread = Thread.new(code => { for 1 .. 10 -> $v { say $v }});\n # ...\n $thread.run;\n\nOr can be created and run at a single invocation:\n\n my $thread = Thread.start({ for 1 .. 10 -> $v { say $v }});\n\nIn both cases the completion of the code encapsulated by the L|/type/Thread>\nobject can be waited on with the C method which will block until\nthe thread completes:\n\n=for code :preamble\n$thread.finish;\n\nBeyond that there are no further facilities for synchronization or resource\nsharing which is largely why it should be emphasized that threads are unlikely\nto be useful directly in user code.\n\n=head2 Schedulers\n\nThe next level of the concurrency API is supplied by classes that\nimplement the interface defined by the role L|/type/Scheduler>. The intent\nof the scheduler interface is to provide a mechanism to determine which\nresources to use to run a particular task and when to run it. The majority\nof the higher level concurrency APIs are built upon a scheduler and it\nmay not be necessary for user code to use them at all, although some\nmethods such as those found in L|/type/Proc::Async>, L|/type/Promise> and L|/type/Supply>\nallow you to explicitly supply a scheduler.\n\nThe current default global scheduler is available in the variable\nC<$*SCHEDULER>.\n\nThe primary interface of a scheduler (indeed the only method required\nby the L|/type/Scheduler> interface) is the C method:\n\n method cue(:&code, Instant :$at, :$in, :$every, :$times = 1; :&catch)\n\nThis will schedule the L|/type/Callable> in C<&code> to be executed in the\nmanner determined by the adverbs (as documented in L|/type/Scheduler>) using\nthe execution scheme as implemented by the scheduler. For example:\n\n my $i = 0;\n my $cancellation = $*SCHEDULER.cue({ say $i++}, every => 2 );\n sleep 20;\n\nAssuming that the C<$*SCHEDULER> hasn't been changed from the default,\nwill print the numbers 0 to 10 approximately (i.e with operating system\nscheduling tolerances) every two seconds. In this case the code will\nbe scheduled to run until the program ends normally, however the method\nreturns a L|/type/Cancellation> object which can be used to cancel the scheduled\nexecution before normal completion:\n\n my $i = 0;\n my $cancellation = $*SCHEDULER.cue({ say $i++}, every => 2 );\n sleep 10;\n $cancellation.cancel;\n sleep 10;\n\nshould only output 0 to 5.\n\nDespite the apparent advantage the L|/type/Scheduler> interface provides over\nthat of L|/type/Thread> all of functionality is available through higher level\ninterfaces and it shouldn't be necessary to use a scheduler directly,\nexcept perhaps in the cases mentioned above where a scheduler can be\nsupplied explicitly to certain methods.\n\nA library may wish to provide an alternative scheduler implementation if\nit has special requirements, for instance a UI library may want all code\nto be run within a single UI thread, or some custom priority mechanism\nmay be required, however the implementations provided as standard and\ndescribed below should suffice for most user code.\n\n=head3 ThreadPoolScheduler\n\nThe L|/type/ThreadPoolScheduler> is the default scheduler, it maintains a pool\nof threads that are allocated on demand, creating new ones as necessary.\n\nRakudo allows the maximum number of threads allowed in the default scheduler\nto be set by the environment variable C at the time\nthe program is started.\n\nIf the maximum is exceeded then C may queue the code until a thread\nbecomes available.\n\n=head3 CurrentThreadScheduler\n\nThe L|/type/CurrentThreadScheduler> is a very simple scheduler that will always\nschedule code to be run straight away on the current thread. The implication\nis that C on this scheduler will block until the code finishes\nexecution, limiting its utility to certain special cases such as testing.\n\n=head2 Locks\n\nThe class L|/type/Lock> provides the low level mechanism that protects\nshared data in a concurrent environment and is thus key to supporting\nthread-safety in the high level API, this is sometimes known as a\n\"Mutex\" in other programming languages. Because the higher level classes\n(L|/type/Promise>, L|/type/Supply> and L|/type/Channel>) use a L|/type/Lock> where required it\nis unlikely that user code will need to use a L|/type/Lock> directly.\n\nThe primary interface to L|/type/Lock> is the method\nL which ensures that a block of code\n(commonly called a \"critical section\") is only executed in one thread\nat a time:\n\n my $lock = Lock.new;\n\n my $a = 0;\n\n await (^10).map: {\n start {\n $lock.protect({\n my $r = rand;\n sleep $r;\n $a++;\n });\n }\n }\n\n say $a; # OUTPUT: «10␤»\n\nC returns whatever the code block returns.\n\nBecause C will block any threads that are waiting to execute\nthe critical section the code should be as quick as possible.\n\n=head2 Lock::Async\n\nL|/type/Lock::Async> is a mutual exclusion mechanism much like\nLock, but it exposes its functionality through L|/type/Promise>s, allowing the use of\nC when waiting for a lock to become available, instead of blocking an\nentire thread.\n\nAnother difference is that it is not re-entrant, meaning that the lock is not\nconsidered available to code that is Ced by the lock.\n\nL|/type/Lock::Async> is more high-level than L|/type/Lock>, but it is still considered a\nlow-level primitive. Higher-level primitives should be preferred over mutating\nshared data inside critical sections.\n\n=head1 Safety concerns\n\nSome shared data concurrency issues are less obvious than others.\nFor a good general write-up on this subject see this L.\n\nOne particular issue of note is when container autovivification or extension\ntakes place. When an L|/type/Array> or a L|/type/Hash> entry is initially assigned the\nunderlying structure is altered and that operation is not async safe. For\nexample, in this code:\n\n my @array;\n my $slot := @array[20];\n $slot = 'foo';\n\nThe third line is the critical section as that is when the array is extended.\nThe simplest fix is to use a L|/type/Lock> to protect the critical section. A\npossibly better fix would be to refactor the code so that sharing a container\nis not necessary.\n\n=end pod\n" }, { "path": "doc/Language/containers.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"fundamental\")\n\n=TITLE Containers\n\n=SUBTITLE A low-level explanation of Raku containers\n\nThis section explains how raw data, variables and containers relate to each\nother in Raku. The different types of containers used in Raku are explained and\nthe actions applicable to them like assigning, binding and flattening. More\nadvanced topics like self-referential data, type constraints and custom\ncontainers are discussed at the end.\n\nFor a deeper discussion of the various kinds of I containers in\nRaku, see the overview of L; for\nI containers, see L.\n\n=head1 What is a variable?\n\nSome people like to say \"everything is an object\", but in fact a variable is\nnot a user-exposed object in Raku.\n\nWhen the compiler encounters a variable scope declaration like C, it\nregisters it in some internal symbol table. This internal symbol table is\nused to detect undeclared variables and to tie the code generation for the\nvariable to the correct scope.\n\nAt runtime, a variable appears as an entry in a I, or\nI for short. This is a per-scope data structure that stores a\npointer for each variable.\n\nIn the case of C, the lexpad entry for the variable C<$x> is a\npointer to an object of type L|/type/Scalar>, usually just called I.\n\n=head1 Scalar containers\n\nAlthough objects of type L|/type/Scalar> are everywhere in Raku, you\nrarely see them directly as objects, because most operations I,\nwhich means they act on the L|/type/Scalar> container's contents instead of the\ncontainer itself.\n\nIn code like\n\n my $x = 42;\n say $x;\n\nthe assignment C<$x = 42> stores a pointer to the L|/type/Int> object 42 in the\nscalar container to which the lexpad entry for C<$x> points.\n\nThe assignment operator asks the container on the left to store the value on\nits right. What exactly that means is up to the container type. For\nL|/type/Scalar> it means \"replace the previously stored value with the new one\".\n\nNote that subroutine signatures allow passing containers around:\n\n sub f($a is rw) {\n $a = 23;\n }\n my $x = 42;\n f($x);\n say $x; # OUTPUT: «23␤»\n\nInside the subroutine, the lexpad entry for C<$a> points to the same\ncontainer that C<$x> points to outside the subroutine. Which is why\nassignment to C<$a> also modifies the contents of C<$x>.\n\nLikewise, a routine can return a container if it is marked as C:\n\n my $x = 23;\n sub f() is rw { $x };\n f() = 42;\n say $x; # OUTPUT: «42␤»\n\nFor explicit returns, C instead of C must be used.\n\nReturning a container is how C attribute accessors work. So\n\n class A {\n has $.attr is rw;\n }\n\nis equivalent to\n\n class A {\n has $!attr;\n method attr() is rw { $!attr }\n }\n\nScalar containers are transparent to type checks and most kinds of read-only\naccesses. A C<.VAR> makes them visible:\n\n my $x = 42;\n say $x.^name; # OUTPUT: «Int␤»\n say $x.VAR.^name; # OUTPUT: «Scalar␤»\n\nAnd C on a parameter requires the presence of a writable Scalar\ncontainer:\n\n sub f($x is rw) { say $x };\n f 42;\n CATCH { default { say .^name, ': ', .Str } };\n # OUTPUT: «X::Parameter::RW: Parameter '$x' expected a writable container, but got Int value␤»\n\n=head1 Callable containers\n\nCallable containers provide a bridge between the syntax of a\nL|/type/Routine> call and the actual call of the method\nL of the object that is stored in the\ncontainer. The sigil C<&> is required when declaring the container and has to be\nomitted when executing the L|/type/Callable>. The default type constraint is\nL|/type/Callable>.\n\n my &callable = -> $ν { say \"$ν is \", $ν ~~ Int ?? \"whole\" !! \"not whole\" }\n callable(⅓); # OUTPUT: «0.333333 is not whole␤»\n callable(3); # OUTPUT: «3 is whole␤»\n\nThe sigil has to be provided when referring to the value stored in the\ncontainer. This in turn allows L|/type/Routine>s to be used as\nL to calls.\n\n sub f() {}\n my &g = sub {}\n sub caller(&c1, &c2){ c1, c2 }\n caller(&f, &g);\n\n=head1 Binding\n\nNext to assignment, Raku also supports I with the C<:=> operator.\nWhen binding a value or a container to a variable, the lexpad entry of the\nvariable is modified (and not just the container it points to). If you write\n\n my $x := 42;\n\nthen the lexpad entry for C<$x> directly points to the L|/type/Int> 42. Which\nmeans that you cannot assign to it anymore:\n\n my $x := 42;\n $x = 23;\n CATCH { default { say .^name, ': ', .Str } };\n # OUTPUT: «X::AdHoc: Cannot assign to an immutable value␤»\n\nYou can also bind variables to other variables:\n\n my $a = 0;\n my $b = 0;\n $a := $b;\n $b = 42;\n say $a; # OUTPUT: «42␤»\n\nHere, after the initial binding, the lexpad entries for C<$a> and C<$b> both\npoint to the same scalar container, so assigning to one variable also\nchanges the contents of the other.\n\nYou've seen this situation before: it is exactly what happened with the\nsignature parameter marked as C.\n\nX<|Language,\\ (container binding)>\nSigilless variables and parameters with the trait C always\nbind (whether C<=> or C<:=> is used):\n\n my $a = 42;\n my \\b = $a;\n b++;\n say $a; # OUTPUT: «43␤»\n\n sub f($c is raw) { $c++ }\n f($a);\n say $a; # OUTPUT: «44␤»\n\n=head1 Scalar containers and listy things\n\nThere are a number of positional container types with slightly different\nsemantics in Raku. The most basic one is L|/type/List>, which\nis created by the comma operator.\n\n say (1, 2, 3).^name; # OUTPUT: «List␤»\n\nA list is immutable, which means you cannot change the number of elements\nin a list. But if one of the elements happens to be a scalar container,\nyou can still assign to it:\n\n my $x = 42;\n ($x, 1, 2)[0] = 23;\n say $x; # OUTPUT: «23␤»\n ($x, 1, 2)[1] = 23; # Cannot modify an immutable value\n CATCH { default { say .^name, ': ', .Str } };\n # OUTPUT: «X::Assignment::RO: Cannot modify an immutable Int␤»\n\nSo the list doesn't care about whether its elements are values or\ncontainers, they just store and retrieve whatever was given to them.\n\nLists can also be lazy; in that case, elements at the end are generated on\ndemand from an iterator.\n\nAn L|/type/Array> is just like a list, except that it forces all its elements to\nbe containers, which means that you can always assign to elements:\n\n my @a = 1, 2, 3;\n @a[0] = 42;\n say @a; # OUTPUT: «[42 2 3]␤»\n\nC<@a> actually stores three scalar containers. C<@a[0]> returns one of\nthem, and the assignment operator replaces the integer value stored in that\ncontainer with the new one, C<42>.\n\n=head1 Assigning and binding to array variables\n\nAssignment to a scalar variable and to an array variable both do\nthe same thing: discard the old value(s), and enter some new value(s).\n\nNevertheless, it's easy to observe how different they are:\n\n my $x = 42; say $x.^name; # OUTPUT: «Int␤»\n my @a = 42; say @a.^name; # OUTPUT: «Array␤»\n\nThis is because the L|/type/Scalar> container type hides itself well, but L|/type/Array>\nmakes no such effort. Also assignment to an array variable is coercive, so\nyou can assign a non-array value to an array variable.\n\nTo place a non-L|/type/Array> into an array variable, binding works:\n\n my @a := (1, 2, 3);\n say @a.^name; # OUTPUT: «List␤»\n\n=head1 Binding to array elements\n\nAs a curious side note, Raku supports binding to array elements:\n\n my @a = (1, 2, 3);\n @a[0] := my $x;\n $x = 42;\n say @a; # OUTPUT: «[42 2 3]␤»\n\nIf you've read and understood the previous explanations, it is now time to\nwonder how this can possibly work. After all, binding to a variable requires a\nlexpad entry for that variable, and while there is one for an array, there\naren't lexpad entries for each array element, because you cannot expand the\nlexpad at runtime.\n\nThe answer is that binding to array elements is recognized at the syntax\nlevel and instead of emitting code for a normal binding operation, a special\nmethod (called L|/routine/BIND-POS>) is called on the\narray. This method handles binding to array elements. There is also an\nequivalent method for binding to hash elements as well (called\nL|/routine/BIND-KEY>)\n\nNote that, while supported, one should generally avoid directly binding\nuncontainerized things into array elements. Doing so may produce\ncounter-intuitive results when the array is used later.\n\n my @a = (1, 2, 3);\n @a[0] := 42; # This is not recommended, use assignment instead.\n my $b := 42;\n @a[1] := $b; # Nor is this.\n @a[2] = $b; # ...but this is fine.\n @a[1, 2] := 1, 2; # runtime error: X::Bind::Slice\n CATCH { default { say .^name, ': ', .Str } };\n # OUTPUT: «X::Bind::Slice: Cannot bind to Array slice␤»\n\nOperations that mix Lists and Arrays generally protect against such\na thing happening accidentally.\n\n=head1 Flattening, items and containers\n\nThe C<%> and C<@> sigils in Raku generally indicate multiple values\nto an iteration construct, whereas the C<$> sigil indicates only one value.\n\n my @a = 1, 2, 3;\n for @a { }; # 3 iterations\n my $a = (1, 2, 3);\n for $a { }; # 1 iteration\n\nC<@>-sigiled variables do not flatten in list context:\n\n my @a = 1, 2, 3;\n my @b = @a, 4, 5;\n say @b.elems; # OUTPUT: «3␤»\n\nThere are operations that flatten out sublists that are not inside a scalar\ncontainer: slurpy parameters (C<*@a>) and explicit calls to C:\n\n\n my @a = 1, 2, 3;\n say (flat @a, 4, 5).elems; # OUTPUT: «5␤»\n\n sub f(*@x) { @x.elems };\n say f @a, 4, 5; # OUTPUT: «5␤»\n\nYou can also use C<|> to create a L|/type/Slip>, introducing a list into\nthe other.\n\n my @l := 1, 2, (3, 4, (5, 6)), [7, 8, (9, 10)];\n say (|@l, 11, 12); # OUTPUT: «(1 2 (3 4 (5 6)) [7 8 (9 10)] 11 12)␤»\n say (flat @l, 11, 12) # OUTPUT: «(1 2 3 4 5 6 7 8 (9 10) 11 12)␤»\n\nIn the first case, every element of C<@l> is I as the corresponding\nelements of the resulting list. C, in the other hand, I all\nelements including the elements of the included array, except for C«(9 10)».\n\nAs hinted above, scalar containers prevent that flattening:\n\n sub f(*@x) { @x.elems };\n my @a = 1, 2, 3;\n say f $@a, 4, 5; # OUTPUT: «3␤»\n\nThe C<@> character can also be used as a prefix to coerce the argument to a\nlist, thus removing a scalar container:\n\n my $x = (1, 2, 3);\n .say for @$x; # 3 iterations\n\nHowever, the I operator C«<>» is more appropriate to decontainerize\nitems that aren't lists:\n\n my $x = ^Inf .grep: *.is-prime;\n say \"$_ is prime\" for @$x; # WRONG! List keeps values, thus leaking memory\n say \"$_ is prime\" for $x<>; # RIGHT. Simply decontainerize the Seq\n\n my $y := ^Inf .grep: *.is-prime; # Even better; no Scalars involved at all\n\nMethods generally don't care whether their invocant is in a scalar, so\n\n my $x = (1, 2, 3);\n $x.map(*.say); # 3 iterations\n\nmaps over a list of three elements, not of one.\n\n=head1 Self-referential data\n\nContainer types, including L|/type/Array> and L|/type/Hash>, allow you to create\nself-referential structures.\n\n my @a;\n @a[0] = @a;\n put @a.raku;\n # OUTPUT: «((my @Array_75093712) = [@Array_75093712,])␤»\n\nAlthough Raku does not prevent you from creating and using self-referential\ndata, by doing so you may end up in a loop trying to dump the data. As a\nlast resort, you can use Promises to L timeouts.\n\n=head1 Type constraints\n\nAny container can have a type constraint in the form of a L or a\nL. Both can be placed between a declarator\nand the variable name or after the trait L.\nThe constraint is a property of the variable, not the container.\n\n subset Three-letter of Str where .chars == 3;\n my Three-letter $acronym = \"ÞFL\";\n\nIn this case, the type constraint is the (compile-type defined) subset\nC.\n\nThe default type constraint of a L|/type/Scalar> container is L|/type/Mu>.\nIntrospection of type constraints on containers is provided by C<.VAR.of>\nmethod, which for C<@> and C<%> sigiled variables gives the constraint for\nvalues:\n\n my Str $x;\n say $x.VAR.of; # OUTPUT: «(Str)␤»\n my Num @a;\n say @a.VAR.of; # OUTPUT: «(Num)␤»\n my Int %h;\n say %h.VAR.of; # OUTPUT: «(Int)␤»\n\n=head2 Definedness constraints\n\nA container can also enforce a variable to be defined. Put a smiley in the\ndeclaration:\n\n my Int:D $def = 3;\n say $def; # OUTPUT: «3␤»\n $def = Int; # Typecheck failure\n=comment ^^^ fails at runtime, so xt/example-compilation still passes\n\nYou'll also need to initialize the variable in the declaration, it can't be\nleft undefined after all.\n\nIt's also possible to have this constraint enforced in all variables declared\nin a scope with the\nL.\nPeople coming from other languages where variables are always defined will\nwant to have a look.\n\n=head1 Custom containers\n\nTo provide custom containers Raku employs the class L|/type/Proxy>. Its\nconstructor takes two arguments, C AND C, that point to methods\nthat are called when values are fetched or stored from the container. Type\nchecks are not done by the container itself and other restrictions like\nreadonlyness can be broken. The returned value must therefore be of the same\ntype as the type of the variable it is bound to. We can use\nL to work with types in Raku.\n\n sub lucky(::T $type) {\n my T $c-value; # closure variable\n return-rw Proxy.new(\n FETCH => method () { $c-value },\n STORE => method (T $new-value) {\n X::OutOfRange.new(what => 'number', got => '13', range => '-∞..12, 14..∞').throw\n if $new-value == 13;\n $c-value = $new-value;\n }\n );\n }\n\n my Int $a := lucky(Int);\n say $a = 12; # OUTPUT: «12␤»\n say $a = 'FOO'; # X::TypeCheck::Binding\n say $a = 13; # X::OutOfRange\n CATCH { default { say .^name, ': ', .Str } };\n\n=end pod\n" }, { "path": "doc/Language/contexts.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"fundamental\")\n\n=TITLE Contexts and contextualizers\n\n=SUBTITLE What are contexts and how to switch into them\n\nContexts interpret the value of a container.\nIn Raku, we use the active context to coerce the value of a container into a type\nor class, or to decide what to do with it.\nUsually, a context receiving an object will, if necessary,\ncoerce the object by implicitly calling a specific method on it.\n\n=head1 X\n\nThe I context is equivalent to what other languages call C\ncontext. It is the context which does nothing with the\nresult or return of any code: a term, an operation or a block. In general, when this\ncontext consumes a value or variable a warning or error is issued because the value is being\nignored. Mnemonics for I relate to being rid of something: water down a\nsink's drain; a ship sinking; a heatsink removing warmth.\n=begin code\nmy $sub = -> $a { $a² };\n$sub; # OUTPUT: «WARNINGS:␤Useless use of $sub in sink context (line 1)␤»\n=end code\n\nX<|Language,sinking>\nYou can force that sink context on L|/type/Iterator>s, by\nusing the L|/routine/sink-all> method. L|/type/Proc>s can also\nbe L method|/type/Proc#method_sink>, forcing them to raise\nan exception and not return anything.\n\nMost blocks will warn if evaluated in sink context; however,\nL are explicitly\nevaluated in sink context, with values returned explicitly using C:\n\n=for code\nmy @results = gather for 1..1 { ^10 .map: *.take };\nsay @results; # OUTPUT: «[0 1 2 3 4 5 6 7 8 9]␤»\n\nIn this example, C is run in sink context, and within it, C is too.\n Results are taken explicitly from the loop via gather/take.\n\nIn sink context, an object will call its C method if present:\n\n=begin code\nsub foo {\n return [] does role {\n method sink { say \"sink called\" }\n }\n}\nfoo; # OUTPUT: «sink called␤»\n=end code\n\n\n=head1 X\n\nThis context, and probably all other contexts except I above, are\nI or I contexts in the sense that they take an\nuntyped or typed variable and duck-type it to whatever is needed to perform the\noperation. In some cases that will imply a conversion (from L|/type/Str> to\nL|/type/Numeric>, for instance); in other cases simply an interpretation\n(L|/type/IntStr> will be interpreted as L|/type/Int> or as\nL|/type/Str>).\n\nI is called whenever we need to apply a numerical operation on a\nvariable.\n\n=begin code\nmy $stringone = \"1 \";\nmy $stringthree = \"3 \";\nsay $stringone + $stringthree; # OUTPUT: «4␤»\n=end code\n\nIn the code above, strings will be interpreted in numeric context as long as\nthere are only a few digits and no other characters. It can have any number of\nleading or trailing whitespace, however.\n\nNumeric context can be forced by using arithmetic operators such as C<+> or\nC<->. In that context, the L|/routine/Numeric> method will be called\nif available and the value returned used as the numeric value of the object.\n\n=begin code\nmy $t = True;\nmy $f = False;\nsay $t + $f; # OUTPUT: «1␤»\nsay $t.Numeric; # OUTPUT: «1␤»\nsay $f.Numeric; # OUTPUT: «0␤»\nmy $list= ;\nsay True + $list; # OUTPUT: «4␤»\nsay +\" \\n \"; # OUTPUT: «0␤»\n=end code\n\nWhitespace in any quantity will be converted to 0, as is shown in the last\nstatement. In the case of I things, the numeric value will be in general\nequivalent to C<.elems>; in some cases, like\nL|/routine/Numeric#(Thread)_method_Numeric>, it will return a unique\nthread identifier.\n\n=head1 X\n\nIn a I, values can be manipulated as strings. This context is\nused, for instance, for coercing non-string values so that they can be printed\nto standard output.\n\n=for code :preamble\nput $very-complicated-and-hairy-object; # OUTPUT: something meaningful\n\nOr when smartmatching to a regular expression:\n\n put 333444777 ~~ /(3+)/; # OUTPUT: «333␤»\n\nIn general, the L routine|/routine/Str> will be called on a variable to\ncontextualize it; since this method is inherited from L|/type/Mu>, it is\nalways present, but it is not always guaranteed to work. In some core classes it\nwill issue a warning.\n\nL|/routine/~> is the (unary) string contextualizer. As an operator, it\nconcatenates strings, but as a prefix operator it becomes the string context\noperator.\n\n=begin code\nmy @array = [ [1,2,3], [4,5,6]];\nsay ~@array; # OUTPUT: «1 2 3 4 5 6␤»\n=end code\n\nThis will happen also in a\nL|/language/operators#Reduction_operators>\ncontext, when C<[~]> is applied to a list\n\n say [~] [ 3, 5+6i, Set(), [1,2,3] ]; # OUTPUT: «35+6ic a b1 2 3␤»\n\nIn that sense, empty lists or other containers will stringify to an empty\nstring:\n\n say [~] [] ; # OUTPUT: «␤»\n\nSince\nL acts also as buffer concatenation operator|/routine/~#(Operators)_infix_~>,\nit will have to check that every element is not empty, since a single empty\nbuffer in string context will behave as a string, thus yielding an error.\n\n say [~] Buf.new(0x3,0x33), Buf.new(0x2,0x22);\n # OUTPUT: «Buf:0x<03 33 02 22>␤»\n\nHowever,\n\n=begin code\nmy $non-empty = Buf.new(0x3, 0x33);\nmy $empty = [];\nmy $non-empty-also = Buf.new(0x2,0x22);\nsay [~] $non-empty, $empty, $non-empty-also;\n# OUTPUT: «Cannot use a Buf as a string, but you called the Stringy method on it\n=end code\n\nSince C<~> is putting in string context the second element of this list,\nL|/routine/~#(Operators)_infix_~> is going to be\nusing the second form that applies to strings, thus yielding the shown error.\nSimply making sure that everything you concatenate is a buffer will avoid this\nproblem.\n\n=for code\nmy $non-empty = Buf.new(0x3, 0x33);\nmy $empty = Buf.new();\nmy $non-empty-also = Buf.new(0x2,0x22);\nsay [~] $non-empty, $empty, $non-empty-also; # OUTPUT: «Buf:0x<03 33 02 22>␤»\n\nIn general, a context will coerce a variable to a particular type by calling the\ncontextualizer; in the case of mixins, if the context class is mixed in, it will\nbehave in that way.\n\n my $described-number = 1i but 'Unity in complex plane';\n put $described-number; # OUTPUT: «Unity in complex plane␤»\n\nC creates a mixin, which endows the complex number with a L|/type/Str> method.\nC contextualizes it into a string, that is, it calls L|/type/Str>, the string\ncontextualizer, with the result shown above.\n\n=head1 X\n\nThis context will force a variable to be interpreted as C or C.\n\n say \"Hey\" if 7; # OUTPUT: «Hey␤»\n say \"Ahoy\" if \"\";\n\nThis context appears in expressions such as C or C, and is\nequivalent to calling C on these values.\n\n=for code\nsay \"Hey\" if 7.so; # OUTPUT: «Hey␤»\nsay \"Ahoy\" if not set().so; # OUTPUT: «Ahoy␤»\n\nIn general, non-zero, non-empty will be converted to C; zero or empty\nwill be equivalent to C. But C<.so> can be defined to return any Boolean\nvalue we want, so this is just a rule of thumb.\n\nThe L«C|/language/operators#prefix_?» Boolean context operator\nand the L«C|/language/operators#prefix_!» negated Boolean context\noperator will force the Boolean context on an object.\n\n=for code\nsay ? 0i; # OUTPUT: «False␤»\nsay ! :true; # OUTPUT: «False␤»\n\n=head1 X\n\nThere are actually several different\nL, which are better explained in\nthat page. In general, the list contextualizer is the comma C<,>\n\n say (3,).^name; # OUTPUT: «List␤»\n\nand the method called in that case is also C<.list>\n\n=for code\nAny.list.^name; # OUTPUT: «List␤»\nsay 3.list.^name; # OUTPUT: «List␤»\nsay (^3).list; # OUTPUT: «(0 1 2)␤»\n\n=head1 Item context\n\nItem or scalar context will deal with complex pieces of data as if they were\na single item. It is forced when you try to assign to a scalar variable\n\n=for code\nmy $scalar-context = <1 2 3>;\nsay \"→ $_\" for $scalar-context; # OUTPUT: «→ 1 2 3␤»\n\nIt can be induced using the C<$> operator, that acts as the contextualizer\noperator by calling C as a method or routine\n\n=for code\n.say for $(1,2,3); # OUTPUT: «(1 2 3)␤»\n.say for (1,2,3).item; # OUTPUT: «(1 2 3)␤»\n.say for item( 1..3 ); # OUTPUT: «1..3␤»\n\nItemization affects only their behavior in list context; however, they will\nstill keep their L|/type/Positional> role or other roles they might have:\n\n=for code\n$(1,2,3).elems.say; # OUTPUT: «3␤»\nsay (1,2,3).item[2]; # OUTPUT: «3␤»\nsay $( key => 'value'); # OUTPUT: «value␤»\n\nItemization I values in a data structure, keeping them, for\ninstance, from being flattened into the surrounding list or data structure:\n\n=for code\n.say for (1, $(2,3), 4).flat; # OUTPUT: «1␤(2 3)␤4␤»\nsay (1, $, 2).elems; # OUTPUT: «3␤»\n\n\nThe itemizer operator will call the C<.item> method on the object; it can also\n be called as a subroutine. Since\nL|/type/Mu#method_item>, objects of any\n class can be itemized.\n\n\n=end pod\n" }, { "path": "doc/Language/control.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"fundamental\")\n\n=TITLE Control flow\n\n=SUBTITLE Statements used to control the flow of execution\n\n=head1 X\n\nRaku programs consist of one or more statements. Simple statements\nare separated by semicolons. The following program will print \"Hello\"\nand then \"World\" on the next line.\n\n say \"Hello\";\n say \"World\";\n\nIn most places where spaces appear in a statement, and before the\nsemicolon, they may be split up over many lines. Also, multiple statements\nmay appear on the same line. It would be awkward, but the above example could\nalso be written as:\n\n say\n \"Hello\"; say \"World\";\n\n=head1 X\n\nLike many other languages, Raku uses C enclosed by C<{> and C<}> to\nturn a sequence of statements into a\nL|/type/Block> that acts as a single one. It is OK\nto omit the semicolon between the last statement in a block and the closing\nC<}>.\n\n { say \"Hello\"; say \"World\" }\n\nWhen a block stands alone as a statement, it will be entered immediately\nafter the previous statement finishes, and the statements inside it will be\nexecuted.\n\n say 1; # OUTPUT: «1␤»\n { say 2; say 3 }; # OUTPUT: «2␤3␤»\n say 4; # OUTPUT: «4␤»\n\nUnless it stands alone as a statement, a block simply creates a closure. The\nstatements inside are not executed immediately. Closures are another topic\nand how they are used is explained\nL. For now it is just\nimportant to understand when blocks run and when they do not:\n\n=for code\nsay \"We get here\";\n{ say \"then here.\" };\n{ say \"not here\"; 0; } or die;\n\nIn the above example, after running the first statement, the first block stands\nalone as a second statement, so we run the statement inside it. The second\nblock is a closure, so instead, it makes an object of type L|/type/Block> but does\nnot run it. Object instances are usually considered to be true, so the code\ndoes not die, even though that block would evaluate to 0, were it to be\nexecuted. The example does not say what to do with the L|/type/Block> object, so it\njust gets thrown away.\n\nMost of the flow control constructs covered below are just ways to tell Raku\nwhen, how, and how many times, to enter blocks like that second block.\n\nBefore we go into those, an important side-note on syntax: If there is\nnothing (or nothing but comments) on a line after a closing curly brace where\nyou would normally put semicolon, then you do not need the semicolon:\n\n # All three of these lines can appear as a group, as is, in a program\n { 42.say } # OUTPUT: «42␤»\n { 43.say } # OUTPUT: «43␤»\n { 42.say }; { 43.say } # OUTPUT: «42␤43␤»\n\n...but:\n\n=begin code :skip-test\n{ 42.say } { 43.say } # Syntax error\n{ 42.say; } { 43.say } # Also a syntax error, of course\n=end code\n\nSo, be careful when you backspace in a line-wrapping editor:\n\n=begin code :skip-test\n{ \"Without semicolons line-wrapping can be a bit treacherous.\".say } \\\n{ 43.say } # Syntax error\n=end code\n\nYou have to watch out for this in most languages anyway to prevent things\nfrom getting accidentally commented out. Many of the examples below may\nhave unnecessary semicolons for clarity.\n\nClass bodies behave like simple blocks for any top level expression; same goes\nto roles and other packages, like grammars (which are actually classes)\nor modules.\n\n=begin code :skip-test\nclass C {\n say \"I live\";\n die \"I will never live!\"\n};\nmy $c = C.new; │\n# OUTPUT: Fails and writes «I live␤I will never live!␤\n=end code\n\nThis block will first run the first statement, and then C printing the\nsecond statement. C<$c> will never get a value.\n\n=head1 X\n\nBlocks may have I: special labeled blocks that break their execution\ninto phases that run in particular phases. See the page\nL for the details.\n\n=head1 X\n\nThe simplest way to run a block where it cannot be a stand-alone statement\nis by writing C before it:\n\n=for code\n# This dies half of the time\ndo { say \"Heads I win, tails I die.\"; Bool.pick } or die; say \"I win.\";\n\nNote that you need a space between the C and the block.\n\nThe whole C evaluates to the final value of the block. The block\nwill be run when that value is needed in order to evaluate the rest of the\nexpression. So:\n\n False and do { 42.say };\n\n...will not say 42. However, the block is only evaluated once each time\nthe expression it is contained in is evaluated:\n\n # This says \"(..1 ..2 ..3)\" not \"(..1 ...2 ....3)\"\n my $f = \".\"; say do { $f ~= \".\" } X~ 1, 2, 3;\n\nIn other words, it follows the same\nL rules as everything else.\n\nTechnically, C is a loop which runs exactly one iteration.\n\nA C may also be used on a bare statement (without curly braces)\nbut this is mainly just useful for avoiding the syntactical need to\nparenthesize a statement if it is the last thing in an expression:\n\n=for code\n3, do if 1 { 2 } ; # OUTPUT: «(3, 2)␤»\n3, (if 1 { 2 }) ; # OUTPUT: «(3, 2)␤»\n=for code :skip-test\n3, if 1 { 2 } ; # Syntax error\n\nAs a consequence, C does not run blocks that, by their syntax, must\nbe functions. For example, if C«->» is used to specify a\nL, C treats these as\nsingle-expression statements.\n\nThus, adding C«->» to our first example prevents the closure from\nbeing evaluated:\n\n=for code\n# This never dies and never prints \"Heads I win, tails I die.\"\ndo -> { say \"Heads I win, tails I die.\"; Bool.pick } or die; say \"I win.\";\n\n=head1 X\n\nThe simplest way to run a statement or block B is by writing C\nbefore it:\n\n=for code\nstart { sleep 1; say \"done\" }\nsay \"working\";\n# working, done\n\nNote that you need a space between the C and the block. In the example\nabove, the C block is in sink context since it's not assigned to a\nvariable. From version 6.d, these sunk blocks have an exception handler\nattached:\n\n=for code\nstart { die \"We're dead\"; }\nsay \"working\";\nsleep 10;\n\nThis code will print C in version 6.d, while it will simply get out after waiting for 10 seconds\nin version 6.c.\n\nThe C immediately returns a L|/type/Promise> that can be safely ignored\nif you are not interested in the result of the block. If you B interested\nin the final value of the block, you can call the C<.result> method on the\nreturned promise. So:\n\n my $promise = start { sleep 10; 42 }\n # ... do other stuff\n say \"The result is $promise.result()\";\n\nIf the code inside the block has not finished, the call to C<.result> will\nwait until it is done.\n\nA C used on a bare statement is useful when the only thing to do\nasynchronously is a subroutine or method:\n\n sub get42 { 42 }\n my $promise = start get42;\n say $promise.result; # OUTPUT: «42␤»\n\nNote that start code does not have access to the special\nvariables L«C<$!>|/syntax/$!» and L«C<$/>|/syntax/$$SOLIDUS» of its outer\nblock, but receives new ones, so every asynchronous task has its\nper-task state.\n\nThus, C expressions and regex matches executed in the\nasynchronous task have their per-task state.\n\n 'a' ~~ /a/; # $/ is set to ｢a｣\n try die; # $! is defined now with an anonymous AdHoc exception\n # as a code block\n await start { say $! }; # OUTPUT: «Nil␤»\n await start { say $/ }; # OUTPUT: «Nil␤»\n # as a single statement\n await start $!.say; # OUTPUT: «Nil␤»\n await start $/.say; # OUTPUT: «Nil␤»\n\n=head1 X\n\nTo conditionally run a block of code, use an C followed by a condition.\nThe condition, an expression, will be evaluated immediately after the\nstatement before the C finishes. The block attached to the condition will\nonly be evaluated if the condition means C when coerced to L|/type/Bool>.\nUnlike some languages the condition does not have to be parenthesized,\ninstead the C<{> and C<}> around the block are mandatory:\n\n=for code\nif 1 { \"1 is true\".say } ; # says \"1 is true\"\n=for code :skip-test\nif 1 \"1 is true\".say ; # syntax error, missing block\n=for code\nif 0 { \"0 is true\".say } ; # does not say anything, because 0 is false\n=for code\nif 42.say and 0 { 43.say }; # says \"42\" but does not say \"43\"\n\nThere is also a form of C called a \"statement modifier\" form. In this\ncase, the C and the condition come after the code you want to run\nconditionally. Do note that the condition is still always evaluated first:\n\n 43.say if 42.say and 0; # says \"42\" but does not say \"43\"\n 43.say if 42.say and 1; # says \"42\" and then says \"43\"\n say \"It is easier to read code when 'if's are kept on left of screen\"\n if True; # says the above, because it is true\n { 43.say } if True; # says \"43\" as well\n\nThe statement modifier form is probably best used sparingly.\n\nThe C statement itself will either L|/type/Slip> us an empty list, if\nit does not run the block, or it will return the value which the block produces:\n\n my $d = 0; say (1, (if 0 { $d += 42; 2; }), 3, $d); # says \"(1 3 0)\"\n my $c = 0; say (1, (if 1 { $c += 42; 2; }), 3, $c); # says \"(1 2 3 42)\"\n say (1, (if 1 { 2, 2 }), 3); # does not slip, says \"(1 (2 2) 3)\"\n\nFor the statement modifier it is the same, except you have the value\nof the statement instead of a block:\n\n say (1, (42 if True) , 2); # says \"(1 42 2)\"\n say (1, (42 if False), 2); # says \"(1 2)\"\n say (1, 42 if False , 2); # says \"(1 42)\" because \"if False, 2\" is true\n\nThe C does not change the topic (C<$_>) by default. In order to access\nthe value which the conditional expression produced, you have to ask\nfor it more strongly:\n\n $_ = 1; if 42 { $_.say } ; # says \"1\"\n $_ = 1; if 42 -> $_ { $_.say } ; # says \"42\"\n $_ = 1; if 42 -> $a { $_.say; $a.say } ; # says \"1\" then says \"42\"\n $_ = 1; if 42 { $_.say; $^a.say } ; # says \"1\" then says \"42\"\n\nThis is especially useful for patterns of the kind\n\"if something does not evaluate to False, do something with it\":\n\n sub get-user-id($username) { #`(return 0 if no such username exists) }\n\n if prompt 'Enter username: ' -> $username {\n if get-user-id($username) -> $user-id {\n say \"Found id $user-id for name $username\";\n }\n }\n\nHere C<$username> and C<$user-id> are only defined inside\ntheir respective C block that guarantees their being C.\nThis gives this solution an advantage\nover the more conventional C.\n\nCompare L|/language/control#with>, which tests\nfor definedness rather than truth, and topicalizes by default.\n(The second C in the above example could be replaced by C if the routine\nC returned L|/type/Nil> rather than 0 for nonexistent usernames.)\n\n=head2 X|Control flow,else elsif>\n\nA compound conditional may be produced by following an C conditional\nwith C to provide an alternative block to run when the conditional\nexpression is false:\n\n=for code\nif 0 { say \"no\" } else { say \"yes\" } ; # says \"yes\"\nif 0 { say \"no\" } else{ say \"yes\" } ; # says \"yes\", space is not required\n\nThe C cannot be separated from the conditional statement by a\nsemicolon, but as a special case, it is OK to have a newline.\n\n=for code :skip-test\nif 0 { say \"no\" }; else { say \"yes\" } ; # syntax error\n=for code\nif 0 { say \"no\" }\nelse { say \"yes\" } ; # says \"yes\"\n\nAdditional conditions may be sandwiched between the C and the C using\nC. An extra condition will only be evaluated if all the conditions\nbefore it were false, and only the block next to the first true condition will\nbe run. You can end with an C instead of an C if you want.\n\n if 0 { say \"no\" } elsif False { say \"NO\" } else { say \"yes\" } # says \"yes\"\n if 0 { say \"no\" } elsif True { say \"YES\" } else { say \"yes\" } # says \"YES\"\n\n if 0 { say \"no\" } elsif False { say \"NO\" } # does not say anything\n\n sub right { \"Right!\".say; True }\n sub wrong { \"Wrong!\".say; False }\n if wrong() { say \"no\" } elsif right() { say \"yes\" } else { say \"maybe\" }\n # The above says \"Wrong!\" then says \"Right!\" then says \"yes\"\n\nYou cannot use the statement modifier form with C or C:\n\n=for code :skip-test\n42.say if 0 else { 43.say } # syntax error\n\nAll the same rules for semicolons and newlines apply, consistently\n\n=for code :skip-test\nif 0 { say 0 }; elsif 1 { say 1 } else { say \"how?\" } ; # syntax error\nif 0 { say 0 } elsif 1 { say 1 }; else { say \"how?\" } ; # syntax error\n\n=for code\nif 0 { say 0 } elsif 1 { say 1 } else { say \"how?\" } ; # says \"1\"\n\n if 0 { say 0 } elsif 1 { say 1 }\n else { say \"how?\" } ; # says \"1\"\n\n if 0 { say 0 }\n elsif 1 { say 1 } else { say \"how?\" } ; # says \"1\"\n\n if 0 { say \"no\" }\n elsif False { say \"NO\" }\n else { say \"yes\" } ; # says \"yes\"\n\nThe whole thing either L|/type/Slip>s us an empty list (if no blocks\nwere run) or returns the value produced by the block that did run:\n\n my $d = 0; say (1,\n (if 0 { $d += 42; \"two\"; } elsif False { $d += 43; 2; }),\n 3, $d); # says \"(1 3 0)\"\n my $c = 0; say (1,\n (if 0 { $c += 42; \"two\"; } else { $c += 43; 2; }),\n 3, $c); # says \"(1 2 3 43)\"\n\nIt's possible to obtain the value of the previous expression inside an\nC, which could be from C or the last C if any are\npresent:\n\n $_ = 1; if 0 { } else -> $a { \"$_ $a\".say } ; # says \"1 0\"\n $_ = 1; if False { } else -> $a { \"$_ $a\".say } ; # says \"1 False\"\n\n if False { } elsif 0 { } else -> $a { $a.say } ; # says \"0\"\n\n=head1 X|Control flow,unless>\n\nWhen you get sick of typing \"if not (X)\" you may use C to invert\nthe sense of a conditional statement. You cannot use C or C\nwith C because that ends up getting confusing. Other than those\ntwo differences C works the same as L:\n\n=for code\nunless 1 { \"1 is false\".say } ; # does not say anything, since 1 is true\n=for code :skip-test\nunless 1 \"1 is false\".say ; # syntax error, missing block\n=for code\nunless 0 { \"0 is false\".say } ; # says \"0 is false\"\n\n unless 42.say and 1 { 43.say } ; # says \"42\" but does not say \"43\"\n 43.say unless 42.say and 0; # says \"42\" and then says \"43\"\n 43.say unless 42.say and 1; # says \"42\" but does not say \"43\"\n\n $_ = 1; unless 0 { $_.say } ; # says \"1\"\n $_ = 1; unless 0 -> $_ { $_.say } ; # says \"0\"\n $_ = 1; unless False -> $a { $a.say } ; # says \"False\"\n\n my $c = 0; say (1, (unless 0 { $c += 42; 2; }), 3, $c); # says \"(1 2 3 42)\"\n my $d = 0; say (1, (unless 1 { $d += 42; 2; }), 3, $d); # says \"(1 3 0)\"\n\n=head1 X|Control flow,with orwith without>\n\nThe C statement is like C, but tests for definedness rather than\ntruth, and it topicalizes on the condition, much like C:\n\n with \"abc\".index(\"a\") { .say } # prints 0\n\nSimilarly to C, C may be used to chain definedness tests:\n\n # The below code says \"Found 'a' at 0\"\n my $s = \"abc\";\n with $s.index(\"a\") { say \"Found 'a' at $_\" }\n orwith $s.index(\"b\") { say \"Found 'b' at $_\" }\n orwith $s.index(\"c\") { say \"Found 'c' at $_\" }\n else { say \"Didn't find 'a', 'b' or 'c'\" }\n\nYou may intermix C-based and C-based clauses.\n\n # This says \"Yes\"\n if 0 { say \"No\" } orwith Nil { say \"No\" } orwith 0 { say \"Yes\" };\n\nAs with C, you may use C to check for undefinedness,\nbut you may not add an C clause:\n\n my $answer = Any;\n without $answer { warn \"Got: {$_.raku}\" }\n\nThere are also C and C statement modifiers:\n\n my $answer = (Any, True).roll;\n say 42 with $answer;\n warn \"undefined answer\" without $answer;\n\nAs with the other chainable constructs, an C completing a\nC..C chain will itself topicalize to the value\nof the prior (failed) condition's topic (either the topic of C\nor the final C or C).\n\nIn the case of an C following a C or C,\ntopicalizing a value guaranteed to be undefined may seem useless. But\nit makes for a useful idiom when used in conjunction with operations\nthat may fail, because L|/type/Failure> values are always\nundefined:\n\n=begin code\nsub may_fail( --> Numeric:D ) {\n my $value = (^10).pick || fail \"Zero is unacceptable\";\n fail \"Odd is also not okay\" if $value % 2;\n return $value;\n}\n\nwith may_fail() -> $value { # defined, so didn't fail\n say \"I know $value isn't zero or odd.\"\n} else { # undefined, so failed, and the Failure is the topic\n say \"Uh-oh: {.exception.message}.\"\n}\n=end code\n\nNote that while topicalizing a L|/type/Failure> marks it\nL|/type/Failure#method_handled>—so you can use the\nC/C to proceed safely with execution—it doesn't make the\nI safe. Even within the C clause, if you\ntry to use the value directly, it will result in your C clause\nitself failing (or, in Rakudo, \"promoting\" the Failure into a thrown\nexception).\n\nBut as seen above, you I use the methods of a handled L|/type/Failure>\nobject the C topicalizes, such as\nL|/type/Failure#method_exception>, if you wish to provide\ndiagnostics or interrogate the underlying\nL|/type/Exception>.\n\n=head1 X\n\nThe C block is similar to an C block and either or both can be used in\nan outer block; they also both have a \"statement modifier\" form. But there is a\ndifference in how following code in the same, outer block is handled: When the\nC block is executed, control is passed to the enclosing block and\nfollowing statements are ignored; but when the C block is executed,\nfollowing statements are executed. N The following\nexamples should illustrate the C or C block's default behavior\nassuming no special exit or other side effect statements are included in the\nC or C blocks:\n\n=begin code\n{\n if X {...} # if X is true in Boolean context, block is executed\n # following statements are executed regardless\n}\n{\n when X {...} # if X is true in Boolean context, block is executed\n # and control passes to the outer block\n # following statements are NOT executed\n}\n=end code\n\nShould the C and C blocks above appear at file scope, following\nstatements would be executed in each case.\n\nThere is one other feature C has that C doesn't: the C's\nBoolean context test defaults to C<$_ ~~> while the C's does not. That has\nan effect on how one uses the X in the C block without a value for C<$_>\n(it's L|/type/Any> in that case and L|/type/Any> smartmatches on C: C\nyields C). Consider the following:\n\n=begin code\n{\n my $a = 1;\n my $b = True;\n when $a { say 'a' }; # no output\n when so $a { say 'a' } # a (\"so $a\" 'so' coerces $a to Boolean context True\n # which matches with Any)\n when $b { say 'b' }; # no output (this statement won't be run)\n}\n=end code\n\nFinally, C's statement modifier form does not affect execution\nof following statements either inside or outside of another block:\n\n=begin code\nsay \"foo\" when X; # if X is true statement is executed\n # following statements are not affected\n=end code\n\nSince a successful match will exit the block, the behavior of this piece of\ncode:\n=begin code\n$_ = True;\nmy $a;\n{\n $a = do when .so { \"foo\" }\n};\nsay $a; # OUTPUT: «(Any)␤»\n=end code\n\nis explained since the C block is abandoned before any value is stored or\nprocessed. However, in this case:\n=begin code\n$_ = False;\nmy $a;\n{\n $a = do when .so { \"foo\" }\n};\nsay $a; # OUTPUT: «False␤»\n=end code\nthe block is not abandoned since the comparison is false, so C<$a> will actually\nget a value.\n\n=head1 X\n\nThe C loop iterates over a list, running the statements inside a\nL|/type/Block> once on each iteration. If the block takes parameters, the\nelements of the list are provided as arguments. By default, the block takes one\nparameter, C<$_>:\n\n my @foo = 1..3;\n for @foo { $_.print } # prints each value contained in @foo\n for @foo { .print } # same thing, because .print implies a $_ argument\n for @foo { 42.print } # prints 42 as many times as @foo has elements\n\nPointy block syntax or a L\nmay be used to name the parameter:\n\n my @foo = 1..3;\n for @foo -> $item { print $item }\n for @foo { print $^item } # same thing\n\nMultiple parameters can be declared, in which case the iterator takes\nas many elements from the list as needed before running the block.\n\n my @foo = 1..3;\n for @foo.kv -> $idx, $val { say \"$idx: $val\" }\n my %hash = Z=> 1,2,3;\n for %hash.kv -> $key, $val { say \"$key => $val\" }\n for 1, 1.1, 2, 2.1 { say \"$^x < $^y\" } # OUTPUT: «1 < 1.1␤2 < 2.1␤»\n\nParameters of a pointy block can have default values, allowing the code to\nhandle lists with missing elements.\n\n my @list = 1,2,3,4;\n for @list -> $a, $b = 'N/A', $c = 'N/A' {\n say \"$a $b $c\"\n }\n # OUTPUT: «1 2 3␤4 N/A N/A␤»\n\nWhen no parameters are specified for a C loop's block, C can be used\nwithin it similarly to how it's used in a C block:\n\n # A solution for FizzBuzz:\n for 1..100 {\n when * %% 15 { say 'FizzBuzz' }\n when * %% 3 { say 'Fizz' }\n when * %% 5 { say 'Buzz' }\n default { say $_ }\n }\n\nIf the postfix form of C is used, a block is not required and the topic is\nset for the statement list.\n\n say „I $_ butterflies!“ for <♥ ♥ ♥>;\n # OUTPUT: «I ♥ butterflies!␤I ♥ butterflies!␤I ♥ butterflies!␤»\n\nA C may be used on lazy lists – it will only take elements from the\nlist when they are needed, so to read a file line by line, you could\nuse:\n\n=for code\nfor $*IN.lines -> $ln { $ln.say }\n\nIteration variables are always lexical, so you don't need to use C to give\nthem the appropriate scope. Also, they are read-only aliases. If you need them\nto be writable, use C«<->» instead of C«->». Alternatively, you can add\nthe L«C«is rw»|/language/signatures#Parameter_traits_and_modifiers» trait; this performs\na binding operation so assigning to the parameter changes the value of the\nvariable at the caller side. If instead you want to modify copies of the\narguments within the block, add\nL«C«is copy»|/language/signatures#Parameter_traits_and_modifiers».\n\n=begin code\nmy @foo = 1..3;\nfor @foo <-> $value {\n $value = $value %% 2 ?? \"Even\" !! \"Odd\"\n}\n\nsay @foo; # OUTPUT: «[Odd Even Odd]␤»\n\n@foo = 1..3;\nfor @foo -> $value is rw {\n $value = $value %% 2 ?? \"Even\" !! \"Odd\"\n}\n\nsay @foo; # OUTPUT: «[Odd Even Odd]␤»\n\n@foo = 1..3;\nmy @bar;\nfor @foo -> $value is copy {\n $value = $value %% 2 ?? \"Even\" !! \"Odd\";\n @bar.push: $value\n}\n\nsay @foo; # OUTPUT: «[1 2 3]␤»\nsay @bar; # OUTPUT: «[Odd Even Odd]␤»\n=end code\n\nThis rule also applies to the topic variable C«$_», which by default is a\nread-write alias; it will become read-only if it's used in a C«->» loop.\n\n my @foo = 1..3;\n for @foo -> $_ { $_.say }\n\n # Error: ...require mutable arguments\n for @foo -> $_ { $_++ }\n\nA C loop can produce a L|/type/List> of the values produced by each run of the\nattached block. To capture these values, put the for loop in parenthesis or\nassign them to an array:\n\n (for 1, 2, 3 { $_ * 2 }).say; # OUTPUT: «(2 4 6)␤»\n my @a = do for 1, 2, 3 { $_ * 2 }; @a.say; # OUTPUT: «[2 4 6]␤»\n my @b = (for 1, 2, 3 { $_ * 2 }); @b.say; # OUTPUT: «[2 4 6]␤»\n\nThis implies that, if the results of the loop are not assigned, they will be\nin a L:\n\n=for code\nclass Sunk {\n has $.titanic;\n method sink {\n say \"Sinking $!titanic\";\n }\n}\nSunk.new( :titanic($_) ) for ^3;\nfor 1 {\n say \"About to sink\";\n Sunk.new( :titanic($_) );\n}\n# OUTPUT:\n# Sinking 0\n# Sinking 1\n# Sinking 2\n# About to sink\n# Sinking 1\n\n\nThe first loop creates three elements but they are in a sink context, so its\nC method is called. In the second loop, its last statement will be in a\nsink context, so it will be also sunk (from version 6.d).\n\nThe C constant will act as a no-op for a loop:\n\n=for code\nsay \"Not here\" for Empty;\n\nWill not do anything. This constant is\nL.\n\nUndefined values will behave in the same way:\n\n=for code\nmy @array := Empty;\n.say for @array;\nsay @array; # OUTPUT: «()␤»\n\nAssigning C will effectively undefine an L|/type/Array>, using C over an\nundefined array will not even enter the loop, as shown, effectively behaving in\nthe same way as above when C was used directly.\n\nWith C and C, the C loop is potentially iterated in parallel.\nSee also the documentation for C and C in class L|/type/Map>.\n\n=for code\nmy $primes_h = hyper for ^10_000 -> $number { $number if $number.is-prime };\nsay $primes_h.elems; # OUTPUT: «1229␤»\nsay $primes_h.tail: 5; # OUTPUT: «(9931 9941 9949 9967 9973)␤»\n\nwith C the order of elements is preserved.\n\n=for code\nmy $primes_r = race for ^10_000 -> $number { $number if $number.is-prime };\nsay $primes_r.elems; # OUTPUT: «1229␤»\n\nUnlike C, C does not preserve the order of elements.\n\n=head1 X\n\nC is a statement or block prefix that returns a L\nof values. The values come from calls to L in the\ndynamic scope of the C code. In the following example, we implement\na subroutine to compute the factors of an integer with C (note that the\nfactors are not generated in order):\n\n sub factors( Int:D \\n ) {\n my $k = 1;\n gather {\n while $k**2 < n {\n if n %% $k {\n take $k;\n take n div $k;\n }\n $k++;\n }\n take $k if $k**2 == n;\n }\n }\n\n say factors(36); # OUTPUT: «1, 36, 2, 18, 3, 12, 4, 9, 6␤»\n\nThe C combination can generate values lazily, depending on\ncontext.\nBinding to a scalar or sigilless container will force laziness.\nIf you want to\nforce lazy evaluation use the L subroutine or\nmethod. For example:\n\n my @vals = lazy gather {\n take 1;\n say \"Produced a value\";\n take 2;\n }\n say @vals[0];\n say 'between consumption of two values';\n say @vals[1];\n\n # OUTPUT:\n # 1\n # between consumption of two values\n # Produced a value\n # 2\n\nC is scoped dynamically, so you can call C from subs or\nmethods that are called from within C:\n\n sub weird(@elems, :$direction = 'forward') {\n my %direction = (\n forward => sub { take $_ for @elems },\n backward => sub { take $_ for @elems.reverse },\n random => sub { take $_ for @elems.pick(*) },\n );\n return gather %direction{$direction}();\n }\n\n say weird(, :direction ); # OUTPUT: «(c b a)␤»\n\nIf values need to be mutable on the caller side, use\nL.\n\nNote that the L|/type/Seq> created by C may be coerced to another type.\nAn example with assignment to a hash:\n\n my %h = gather { take \"foo\" => 1; take \"bar\" => 2};\n say %h; # OUTPUT: «{bar => 2, foo => 1}␤»\n\nB: C must not be used to collect results from C.\nThe C block is not run from the thread that runs the C, but\nthe thread that runs the C. On this thread, there is no handler for the\ncontrol exception thrown by C, causing it to error out.\n\n=head1 X\n\nThe keyword C creates a L which is an\nL\nthat you can tap. It pairs with C, which can be used anywhere from within\nC prefixed code.\n\nUsing the L|/type/Mu#method_emit> or the\nL|/type/independent-routines#sub_emit> passes the invocant\nto the enclosing\nL:\n\n my $supply = supply {\n .emit for \"foo\", 42, .5;\n }\n $supply.tap: {\n say \"received {.^name} ($_)\";\n }\n\n # OUTPUT:\n # received Str (foo)\n # received Int (42)\n # received Rat (0.5)\n\nSee also: L|/routine/tap> and L|/type/Supplier>.\n\nX<|Other languages,switch (given)>\nX<|Other languages,case statements (given)>\n=head1 X\n\nThe C statement is Raku's topicalizing keyword in a similar way that\nC topicalizes in languages such as C. In other words, C\nsets C<$_> inside the following block. The keywords for individual cases\nare C and C. The usual idiom looks like this:\n\n my $var = (Any, 21, any ).pick;\n given $var {\n when 21 { say $_ * 2 }\n when 'lie' { .say }\n default { say 'default' }\n }\n\nThe C statement is often used alone:\n\n given 42 { .say; .Numeric; }\n\nThis is a lot more understandable than:\n\n { .say; .Numeric; }(42)\n\n\n=head2 X\n\nA block containing a C statement will be left immediately\nwhen the sub-block after the C statement is left. It is\nas though the rest of the statements in the block were skipped.\n\n given 42 {\n \"This says\".say;\n $_ == 42 and ( default { \"This says, too\".say; 43; } );\n \"This never says\".say;\n }\n # The above block evaluates to 43\n\nA C statement will also do this (but a C statement modifier\nwill I.)\n\nIn addition, C statements C the topic (C<$_>) against\na supplied expression such that it is possible to check against values,\nregular expressions, and types when specifying a match.\n\n for 42, 43, \"foo\", 44, \"bar\" {\n when Int { .say }\n when /:i ^Bar/ { .say }\n default { say \"Not an Int or a Bar\" }\n }\n # OUTPUT: «42␤43␤Not an Int or a Bar␤44␤Bar␤»\n\nIn this form, the C/C construct acts much like a set of\nC/C/C statements. Be careful with the order of the\nC statements. The following code says C<\"Int\"> not C<42>.\n\n given 42 {\n when Int { say \"Int\" }\n when 42 { say 42 }\n default { say \"huh?\" }\n }\n # OUTPUT: «Int␤»\n\nWhen a C statement or C statement causes the outer\nblock to return, nesting C or C blocks do not count\nas the outer block, so you can nest these statements and still\nbe in the same \"switch\" just so long as you do not open a new block:\n\n given 42 {\n when Int {\n when 42 { say 42 }\n say \"Int\"\n }\n default { say \"huh?\" }\n }\n # OUTPUT: «42␤»\n\nC statements can smartmatch\nagainst L.\n\n=head2 X and X\n\nBoth C and C are meant to be used only from inside C\nor C blocks.\n\nThe C statement will immediately leave the C or C\nblock, skipping the rest of the statements, and resuming after the block.\nThis prevents the C or C from exiting the outer block.\n\n=for code\ngiven * {\n default {\n proceed;\n \"This never says\".say\n }\n}\n\"This says\".say;\n\nThis is most often used to enter multiple C blocks. C will\nresume matching after a successful match, like so:\n\n given 42 {\n when Int { say \"Int\"; proceed }\n when 42 { say 42 }\n when 40..* { say \"greater than 40\" }\n default { say \"huh?\" }\n }\n # OUTPUT: «Int␤»\n # OUTPUT: «42␤»\n\nNote that the C match didn't occur. For this to match\nsuch cases as well, one would need a C in the C block.\n\nThis is not like a C C statement, because the C does\nnot merely enter the directly following block, it attempts to match\nthe C value once more, consider this code:\n\n given 42 {\n when Int { \"Int\".say; proceed }\n when 43 { 43.say }\n when 42 { 42.say }\n default { \"got change for an existential answer?\".say }\n }\n # OUTPUT: «Int␤»\n # OUTPUT: «42␤»\n\n...which matches the L|/type/Int>, skips C<43> since the value doesn't match, matches\nC<42> since this is the next positive match, but doesn't enter the\nC block since the C block doesn't contain a C.\n\nBy contrast, the C keyword short-circuits execution and exits the\nentire C block at that point. It may also take an argument to\nspecify a final value for the block.\n\n say do given 42 {\n when Int {\n succeed \"Found\";\n say \"never this!\";\n }\n when 42 { say 42 }\n default { say \"dunno?\" }\n }\n # OUTPUT: «Found␤»\n\nIf you are not inside a when or default block, it is an error to try\nto use C or C.Also remember, the C statement\nmodifier form does not cause any blocks to be left, and any C\nor C in such a statement applies to the surrounding clause,\nif there is one:\n\n given 42 {\n { say \"This says\" } when Int;\n \"This says too\".say;\n when * > 41 {\n { \"And this says\".say; proceed } when * > 41;\n \"This never says\".say;\n }\n \"This also says\".say;\n }\n # OUTPUT: «This says␤This says too␤And this says␤This also says␤»\n\n=head2 X\n\nC can follow a statement to set the topic in the statement it follows.\n\n .say given \"foo\";\n # OUTPUT: «foo␤»\n\n printf \"%s %02i.%02i.%i\",\n [.day-of-week - 1],\n .day,\n .month,\n .year\n given DateTime.now;\n # OUTPUT: «Sa 03.06.2016»\n\n=head1 X\n\nThe C statement takes three statements in parentheses separated by C<;>\nthat take the roles of initializer, conditional and incrementer, respectively.\nThe initializer is executed once before the conditional is first tested. In case\nthe initializer involves a variable declaration, the variable is declared as a\nlexical variable in the loop's I scope so that it can be\nused in code following the loop statement. The conditional is executed before\neach iteration and coerced to L|/type/Bool>; if C the loop is stopped. The\nincrementer is executed after each iteration, and before the conditional is\ntested again.\n\n loop (my $i = 0; $i < 10; $i++) { # A typical loop\n say $i;\n }\n\n my @str = \"However Long\".comb; # Our very own .chars routine:\n loop (my $l = 0;;) { # Declare $l in outer scope\n last if !@str[$l++] # and count chars until we hit\n } # an undefined element (Any)\n say \"The string is {--$l} chars long.\";\n\nThe infinite loop does not require parentheses.\n\n=for code\nloop { say 'forever' }\n\nThe C statement may be used to produce values from the result of each\nrun of the attached block if it appears in lists:\n\n (loop ( my $i = 0; $i++ < 3;) { $i * 2 }).say; # OUTPUT: «(2 4 6)␤»\n my @a = (loop ( my $j = 0; $j++ < 3;) { $j * 2 }); @a.say; # OUTPUT: «[2 4 6]␤»\n my @b = do loop ( my $k = 0; $k++ < 3;) { $k * 2 }; @b.say; # same thing\n\nUnlike a C loop, one should not rely on whether returned values are\nproduced lazily. It would probably be best to use C to guarantee that a\nloop whose return value may be used actually runs:\n\n sub heads-in-a-row {\n (eager loop (; 2.rand < 1;) { \"heads\".say })\n }\n\n=head1 X\n\nThe C statement executes the block as long as its condition is\ntrue. So\n\n my $x = 1;\n while $x < 4 {\n print $x++;\n }\n print \"\\n\";\n\n # OUTPUT: «123␤»\n\nSimilarly, the C statement executes the block as long as the\nexpression is false.\n\n my $x = 1;\n until $x > 3 {\n print $x++;\n }\n print \"\\n\";\n\n # OUTPUT: «123␤»\n\nThe condition for C or C can be parenthesized, but there\nmust be a space between the keyword and the opening parenthesis of the\ncondition.\n\nBoth C and C can be used as statement modifiers. E. g.\n\n my $x = 42;\n $x-- while $x > 12\n\nSee L|#next>, L|#last>, and related below for ways to\nfine-tune loop control. Also see C and C for\nother loop syntax.\n\nAll these forms may produce a return value the same way C does.\n\n=head1 X\n\nExecutes the block I and, if the condition allows, repeats\nthat execution. This differs from C/C in that the condition\nis evaluated at the end of the loop, even if it appears at the front.\n\n my $x = -42;\n repeat {\n $x++;\n } while $x < 5;\n $x.say; # OUTPUT: «5␤»\n\n repeat {\n $x++;\n } while $x < 5;\n $x.say; # OUTPUT: «6␤»\n\n repeat while $x < 10 {\n $x++;\n }\n $x.say; # OUTPUT: «10␤»\n\n repeat while $x < 10 {\n $x++;\n }\n $x.say; # OUTPUT: «11␤»\n\n repeat {\n $x++;\n } until $x >= 15;\n $x.say; # OUTPUT: «15␤»\n\n repeat {\n $x++;\n } until $x >= 15;\n $x.say; # OUTPUT: «16␤»\n\n repeat until $x >= 20 {\n $x++;\n }\n $x.say; # OUTPUT: «20␤»\n\n repeat until $x >= 20 {\n $x++;\n }\n $x.say; # OUTPUT: «21␤»\n\nAll these forms may produce a return value the same way C does.\n\n=head1 X\n\nA block or statement prefixed with C will be executed exactly once,\neven if placed inside a loop or a recursive routine.\n\n my $guard;\n loop {\n once $guard = 3;\n last if $guard-- <= 0;\n once { put 'once' };\n print 'many'\n } # OUTPUT: «once␤manymanymany»\n\nThis works per \"clone\" of the containing code object, so:\n\n ({ once 42.say } xx 3).map: {$_(), $_()}; # says 42 thrice\n\nNote that this is B a thread-safe construct when the same clone of the same\nblock is run by multiple threads. Also remember that methods only have one\nclone per class, not per object.\n\n\n=head1 LABELs\n\nC, C, C and C loops can all take a label, which can be\nused to identify them for C, C, and C. Nested loops are\nsupported, for instance:\n\n OUTAHERE: while True {\n for 1,2,3 -> $n {\n last OUTAHERE if $n == 2;\n }\n }\n\nLabels can be used also within nested loops to name each loop, for instance:\n\n=begin code\nOUTAHERE:\nloop ( my $i = 1; True; $i++ ) {\n OUTFOR:\n for 1,2,3 -> $n {\n # exits the for loop before its natural end\n last OUTFOR if $n == 2;\n }\n\n # exits the infinite loop\n last OUTAHERE if $i >= 2;\n}\n=end code\n\n=head1 X\n\nThe C command starts the next iteration of the loop. So the code\n\n=begin code\n\nmy @x = 1, 2, 3, 4, 5;\nfor @x -> $x {\n next if $x == 3;\n print $x;\n}\n=end code\n\nprints \"1245\".\n\nYou can also use C in a C: the above example then looks\nlike:\n\n=begin code\nmy @x = 1, 2, 3, 4, 5;\nprint @x.map: -> $x {\n next if $x == 3;\n $x\n}\n=end code\n\nprints \"1 2 4 5\" because a space is added between entries of a L|/type/Seq>\nwhen it is stringified. Note that that C was not put inside\nthe block of the C, as it generally considered bad practice to\nrun a C for its side-effects (in this case, the C.\n\nIf the L phaser|/language/phasers#NEXT> is present, it runs\nbefore the next iteration:\n\n=begin code\nmy Int $i = 0;\nwhile ($i < 10) {\n if ($i % 2 == 0) {\n next;\n }\n\n say \"$i is odd.\";\n\n NEXT {\n $i++;\n }\n}\n# OUTPUT: «1 is odd.␤3 is odd.␤5 is odd.␤7 is odd.␤9 is odd.␤»\n=end code\n\nIn version 6.e.PREVIEW (available as of the 2021.07 Rakudo compiler\nrelease), it is also possible to return a value with the C\nstatement. This is particularly useful when using it in a C:\n\n=begin code\nmy @x = 1, 2, 3, 4, 5;\nprint @x.map: -> $x {\n next 42 if $x == 3;\n $x\n}\n=end code\n\nprints \"1 2 42 4 5\".\n\nIn a L\nblock, C immediately exits the block for the current value:\n\n react {\n whenever Supply.interval(1) {\n next if .is-prime;\n say $_;\n done if $_ == 4;\n }\n }\n\nprints \"0\", \"1\" and \"4\" - integers from 0 to 4 with primes skipped.\n\n*Since version 6.d, the C command in a loop that collects its\nlast statement values returns C for the iterations they run on.*\n\n=head1 X\n\nThe C command immediately exits the loop in question.\n\n=begin code\nmy @x = 1, 2, 3, 4, 5;\nfor @x -> $x {\n last if $x == 3;\n print $x;\n}\n=end code\n\nprints \"12\".\n\nYou can also use C in a C: the above example then looks\nlike:\n\n=begin code\nmy @x = 1, 2, 3, 4, 5;\nprint @x.map: -> $x {\n last if $x == 3;\n $x\n}\n=end code\n\nprints \"1 2\" because a space is added between entries of a L|/type/Seq> when\nit is stringified. Note that that C was not put inside the\nblock of the C, as it generally considered bad practice to run\na C for its side-effects (in this case, the C.\n\nIf the L phaser|/language/phasers#LAST> is present, it runs\nbefore exiting the loop:\n\n=begin code\nmy Int $i = 1;\nwhile ($i < 10) {\n if ($i % 5 == 0) {\n last;\n }\n\n LAST {\n say \"The last number was $i.\";\n }\n NEXT {\n $i++;\n }\n}\n# OUTPUT: «The last number was 5.␤»\n=end code\n\nSince version 6.d, the C command in a loop that collects its last\nstatement values returns C for the iterations they run on.\n\nIn version 6.e.PREVIEW (available as of the 2021.07 Rakudo compiler\nrelease), it is also possible to return a value with the C\nstatement. This is particularly useful when using it in a C:\n\n=begin code\nmy @x = 1, 2, 3, 4, 5;\nprint @x.map: -> $x {\n last 42 if $x == 3;\n $x\n}\n=end code\n\nprint \"1 2 42\".\n\n=head1 X\n\nThe C command restarts the loop block without evaluating the\nconditional again.\n\n=for code\nfor 1..5 -> $current-level {\n state $total-attempts = 0;\n $total-attempts++;\n print(\"Entering #$current-level. \");\n if $total-attempts %% 3 {\n redo;\n }\n}\n# OUTPUT: «Entering #1... Entering #2... Entering #3... Entering #3... Entering #4... Entering #5... Entering #5... »\n\n=head1 X\n\nThe sub C will stop execution of a subroutine or method, run all\nrelevant L and provide the\ngiven return value to the caller. The default return value is L|/type/Nil>. If\na return L is\nprovided it will be checked unless the return value is L|/type/Nil>. If the\ntype check fails the exception\nL|/type/X::TypeCheck::Return> is thrown. If it\npasses a control exception is raised and can be caught with\nL.\n\nAny C in a block is tied to the first L|/type/Routine> in the outer\nlexical scope of that block, no matter how deeply nested. Please note\nthat a C in the root of a package will fail at runtime. A\nC in a block that is evaluated lazily (e.g. inside C) may\nfind the outer lexical routine gone by the time the block is executed.\nIn almost any case C is the better alternative. Please check\nL for\nmore information on how return values are handled and produced.\n\n=head1 X\n\nThe sub C will return values, not containers. Those are\nimmutable and will lead to runtime errors when attempted to be mutated.\n\n sub s(){ my $a = 41; return $a };\n say ++s();\n CATCH { default { say .^name, ': ', .Str } };\n # OUTPUT: «X::Multi::NoMatch.new(dispatcher …\n\nTo return a mutable container, use C.\n\n sub s(){ my $a = 41; return-rw $a };\n say ++s();\n # OUTPUT: «42␤»\n\nThe same rules as for C regarding phasers and control exceptions apply.\n\n=head1 X\n\nLeaves the current routine and returns the provided\nL|/type/Exception> or L|/type/Str> wrapped inside a\nL|/type/Failure>, after all relevant\nL are executed. If the caller\nactivated fatal exceptions via the pragma C, the exception is\nthrown instead of being returned as a L|/type/Failure>.\n\n sub f { fail \"WELP!\" };\n say f;\n CATCH { default { say .^name, ': ', .Str } }\n # OUTPUT: «X::AdHoc: WELP!␤»\n\n=end pod\n" }, { "path": "doc/Language/create-cli.rakudoc", "content": "=begin pod :kind(\"Language\") :subkind(\"Language\") :category(\"tutorial\")\n\n=TITLE Command line interface\n\n=SUBTITLE Creating your own CLI in Raku\n\nX<|Programs,command line arguments>\n=head1 Command line interface - an overview\n\nThe default command line interface of Raku scripts consists of three parts:\n\n=head2 Parsing the command line parameters into a L|/type/Capture>\n\nThis looks at the values in L<@*ARGS|/language/variables#index-entry-@*ARGS>,\ninterprets these according to some policy, and creates a L|/type/Capture>\nobject out of that. An alternative way of parsing may be provided by the developer\nor installed using a module.\n\n=head2 Calling a provided C
subroutine using that capture\n\nStandard L\nis used to call the C
subroutine with the generated L|/type/Capture> object.\nThis means that your C
subroutine may be a C, each candidate\nof which is responsible for some part of processing the given command line\narguments.\n\n=head2 Creating / showing usage information if calling C
failed\n\nIf multi dispatch failed, then the user of the script should be informed as\nwell as possible as to why it failed. By default, this is done by inspecting\nthe signature of each C
candidate sub, and any associated Pod information.\nThe result is then shown to the user on STDERR (or on STDOUT if C<--help>\nwas specified). An alternative way of generating the usage information may\nbe provided by the developer or installed using a module.\n\nX<|Programs,MAIN>\n=head1 sub MAIN\n\nThe sub with the special name C
will be executed after all relevant entry\nphasers (C, C, C, C
, C) have been run and\nthe L of the script has been\nexecuted. No error will occur if there is no C
 sub: your script will\nthen just have to do the work, such as argument parsing, in the mainline of\nthe script.\n\nAny normal exit from the C
 sub will result in an exit code of C<0>,\nindicating success. Any return value of the C
 sub will be ignored.\nIf an exception is thrown that is not handled inside the C
 sub, then the\nexit code will be C<1>. If the dispatch to C
 failed, a usage message\nwill be displayed on STDERR and the exit code will be C<2>.\n\nThe command line parameters are present in the C<@*ARGS> dynamic variable\nand may be altered in the mainline of the script before the C
 unit is\ncalled.\n\nThe signature of (the candidates of the multi) sub C
 determines which\ncandidate will actually be called using the standard\nL semantics.\n\nA simple example:\n\n    # inside file 'hello.raku'\n    sub MAIN($name) {\n        say \"Hello $name, how are you?\"\n    }\n\nIf you call that script without any parameters, you get the following\nusage message:\n\n=begin code :lang\n$ raku hello.raku\nUsage:\n  hello.raku \n=end code\n\nHowever, if you give a default value for the parameter, running the script\neither with or without specifying a name will always work:\n\n    # inside file 'hello.raku'\n    sub MAIN($name = 'bashful') {\n        say \"Hello $name, how are you?\"\n    }\n\n=begin code :lang\n$ raku hello.raku\nHello bashful, how are you?\n=end code\n\n=begin code :lang\n$ raku hello.raku Liz\nHello Liz, how are you?\n=end code\n\nAnother way to do this is to make C a C:\n\n    # inside file 'hello.raku'\n    multi MAIN()      { say \"Hello bashful, how are you?\" }\n    multi MAIN($name) { say \"Hello $name, how are you?\"   }\n\nWhich would give the same output as the examples above. Whether you should\nuse either method to achieve the desired goal is entirely up to you.\n\nIf you want to pass an indeterminate number of parameters to be dealt with in\nC, you can use L:\n\n    # inside file 'hello-all.raku'\n    sub MAIN(*@all) { for @all -> $name { say \"Hello, \" ~ $name } }\n\n=begin code :lang\n$ raku hello-all.raku peter paul mary\nHello, peter\nHello, paul\nHello, mary\n=end code\n\n=head2 Multiple named parameters, and C clauses\n\nA more complicated example using a single positional and multiple\nnamed parameters, and also showing that C clauses can also be applied\nto C
 arguments:\n\n=for code :method\n# inside \"frobnicate.raku\"\nsub MAIN(\n  Str   $file where *.IO.f = 'file.dat',\n  Int  :$length = 24,\n  Bool :$verbose\n) {\n    say $length if $length.defined;\n    say $file   if $file.defined;\n    say 'Verbosity ', ($verbose ?? 'on' !! 'off');\n}\n\nThe clause C checks that the string C<$file> corresponds to the name of a file that actually exists.\nThe part C<= 'file.dat'> specifies a default value for C<$file> in case no argument for it is given.\n\nIf a file C is present, a call with no arguments will work this way:\n=begin code :lang\n$ raku frobnicate.raku\n24\nfile.dat\nVerbosity off\n=end code\n\nOr this way with C<--verbose>:\n\n=begin code :lang\n$ raku frobnicate.raku --verbose\n24\nfile.dat\nVerbosity on\n=end code\n\nIf the file C is not present, or you've specified another filename\nthat doesn't exist, you would get the standard usage message created from\nintrospection of the C
 sub:\n\n=begin code :lang\n$ raku frobnicate.raku doesnotexist.dat\nUsage:\n  frobnicate.raku [--length=] [--verbose] []\n=end code\n\nSuch usage messages are generated completely automatically for you.\nIf they seem too terse, you can easily add more information to them.\n\n=head2 Improve usage messages with rakudoc comments\n\nThere's an easy way to make the autogenerated usage\nmessage better by providing hints using pod features:\n\n=for code :method\n# inside \"frobnicate.raku\"\nsub MAIN(\n  Str   $file where *.IO.f = 'file.dat',  #= an existing file to frobnicate\n  Int  :$length = 24,                     #= length needed for frobnication\n  Bool :$verbose,                         #= required verbosity\n) {\n    say $length if $length.defined;\n    say $file   if $file.defined;\n    say 'Verbosity ', ($verbose ?? 'on' !! 'off');\n}\n\nWhich would improve the usage message like this:\n\n=begin code :lang\n$ raku frobnicate.raku doesnotexist.dat\nUsage:\n  frobnicate.raku [--length=] [--verbose] []\n\n    []          an existing file to frobnicate\n    --length=    length needed for frobnication\n    --verbose         required verbosity\n=end code\n\n=head2 Command lines and usage messages: more examples\n\nFrom release 2021.03, values to single named arguments can be separated by\nspaces too. Consider a C program with the following source:\n\n    subset name of Any where Str|True;\n    subset port of Str;\n    multi MAIN(\n        $file,\n        name :$profile,    #= Write profile information to a file\n        port :$debug-port, #= Listen for debugger connections on the specified port\n        Bool :v($verbose), #= Display verbose output\n\n    ) {}\n    multi MAIN(\"--process-files\", *@images) {}\n\nThis program generates the following usage message:\n\n=begin code :lang\nUsage:\n  demo [--profile[=name]] [--debug-port=] [-v] \n  demo --process-files [ ...]\n\n    --profile[=name]       Write profile information to a file\n    --debug-port=    Listen for debugger connections on the specified port\n    -v                     Display verbose output\n=end code\n\nThe following are valid ways to call C:\n\n=for code :lang\ndemo --profile ~/foo\ndemo --profile=/tmp/bar ~/foo\ndemo --debug-port 4242 ~/foo\ndemo --debug-port=4242 ~/foo\ndemo -v ~/foo\ndemo --process-files *.jpg\n\nThese, however, are not valid\n\n=for code :lang\ndemo --profile /tmp/bar ~/foo\ndemo --debug-port ~/foo\n\nThe first is invalid because C and C<~/foo> are both parsed as\npositional arguments, which means C was called with too many\npositional arguments.  The second is invalid because C<~/foo> is parsed\nas an argument to C<--debug-port>, and thus C lacks the required\npositional argument.\n\nHere's how it works; with Raku distinguishing between three types of options:\n\n=item Boolean options (like C<-v>), which I take an argument; they\n   are ether present or absent.\n=item Options with a mandatory argument (like C<--debug-port>), which\n   always take an argument.  If you give them an argument with C<=>,\n   they will use that; if not, they'll take the following argument.\n=item Options with an optional argument (like C<--profile>), which are\n   valid both with and without an argument.  You can I give these\n   arguments an option with the C<=> syntax; if there is a space after\n   the option, that means it was called without an argument.\n\nAnd here's the signature that produces each type of argument:\n\n=item Boolean options: A L|/type/Bool> type constraint.\n=item Options with a mandatory argument: A type that does not\n    L|/routine/ACCEPTS> a L|/type/Bool>.\n=item Options with an optional argument: A type that C<.ACCEPTS> a\n   C (because passing an option without an argument is equivalent\n   to passing C)\n\n=head2 Aliases for named parameters\n\nAs any other subroutine, C
 can define\nL for its named parameters.\nIn particular, this can be used to define single-letter alternative names.\n\n=for code :method\nsub MAIN(\n  Str   $file where *.IO.f = 'file.dat',  #= an existing file to frobnicate\n  Int  :l(:$length) = 24,                 #= length needed for frobnication\n  Bool :v(:$verbose),                     #= required verbosity\n) {\n    say $length if $length.defined;\n    say $file   if $file.defined;\n    say 'Verbosity ', ($verbose ?? 'on' !! 'off');\n}\n\nIn which case, these aliases will also be listed as alternatives with C<--help>:\n\n=begin code :lang\nUsage:\n  frobnicate.raku [--size|--length=] [--verbose] []\n\n    []                 an existing file to frobnicate\n    -l|--length=        length needed for frobnication\n    -v|--verbose             required verbosity\n=end code\n\n=head2 Named arrays\n\nThe MAIN subroutine can also use a different kind of named parameter: the named array.\nThis enables, for instance, providing two different short arrays as arguments on a\ncommand line.\n\nDeclare a named-array parameter with C<:@> in sub MAIN's signature:\n\n    # inside file 'named-array.raku'\n    sub MAIN(:@n) {\n        .raku.say for @n\n    }\n\nYou can use this on the command line by repeating the named-array\nparameter with different values each time.\n\n=begin code :lang\n$ raku named-array.raku --n=foo --n=23 --n=6.3 --n=3e8 --n=2+2i --n=bar\n\"foo\"\nIntStr.new(23, \"23\")\nRatStr.new(6.3, \"6.3\")\nNumStr.new(300000000e0, \"3e8\")\nComplexStr.new(<2+2i>, \"2+2i\")\n\"bar\"\n=end code\n\n=head2 Enumerations\n\nL|/type/Enumeration>s can be used in signatures with arguments converted\nautomatically to its corresponding C symbol:\n\n=begin code\nenum Flag  (\n    FLAG_FOO => 0b001,\n    FLAG_BAR => 0b010,\n    FLAG_BAZ => 0b100,\n);\n\nsub MAIN(Flag $flag = FLAG_FOO) {\n    say \"Flagging $flag with value $flag.value()\";\n}\n=end code\n\nThis will work correctly with\n\n=for code :lang\nraku MAIN-enum.raku FLAG_BAZ\n# OUTPUT: «Flagging FLAG_BAZ with value 4␤»\n\nbut will die if called with something that is not a C.\n\n\n=head2 X|Variables,%*SUB-MAIN-OPTS>\n\nIt's possible to alter how arguments are processed before they're passed\nto C by setting options in the C<%*SUB-MAIN-OPTS> hash. Due to\nthe nature of dynamic variables, it is required to set up the\nC<%*SUB-MAIN-OPTS> hash and fill it with the appropriate settings.\nFor instance:\n\n    my %*SUB-MAIN-OPTS =\n      :named-anywhere,             # allow named variables at any location\n      :bundling,                   # allow bundling of named arguments\n      :coerce-allomorphs-to(Int),  # coerce allomorphic arguments to given type\n      :allow-no,                   # allow --no-foo as alternative to --/foo\n      :numeric-suffix-as-value,    # allow -j2 as alternative to --j=2\n    ;\n    sub MAIN ($a, $b, :$c, :$d) {\n        say \"Accepted!\"\n    }\n\nAvailable options are:\n\n=head3 X|Reference,named-anywhere>\n\nBy default, named arguments passed to the program (i.e., C
)\ncannot appear after any positional argument. However, if\nC«%*SUB-MAIN-OPTS» is set to a true value, named arguments\ncan be specified anywhere, even after positional parameter. For example,\nthe above program can be called with:\n\n=begin code :lang\n$ raku example.raku 1 --c=2 3 --d=4\n=end code\n\n=head3 X|Programs,command-line argument bundling>\n\nWhen C«%*SUB-MAIN-OPTS» is set to a true value, single letter named\narguments can be bundled together with a single dash. The following two\ncommands are then equivalent:\n\n=begin code :lang\n$ raku example.raku -a -b -c\n$ raku example.raku -abc\n=end code\n\nBundled arguments can be understood as flags, that can neither be negated, nor\nassigned a value though:\n\n=begin code :lang\n$ raku example.raku -/a       # OK\n$ raku example.raku -a=asdf   # OK\n$ raku example.raku -abc=asdf # Error\n$ raku example.raku -/abc     # Error\n=end code\n\nThis option is only available starting in the 2020.10 release of the\nRakudo compiler.\n\n=head3 X|Programs,command-line argument coercion>\n\nWhen C«%*SUB-MAIN-OPTS» is set to a specific type,\nthen any L values will be coerced to that\ntype.  This can be helpful in any dispatch issues to C
.\n\nThis option is only available starting in the 2020.12 release of the\nRakudo compiler.\n\n=head3 X|Programs,allow no- to negate>\n\nWhen C«%*SUB-MAIN-OPTS» is set to a true value, then negation\nof arguments on the command line can also be indicated by using the\nC instead of C.\n\n=begin code :lang\n$ raku example.raku --/foo    # named argument \"foo\" is False\n$ raku example.raku --no-foo  # same\n=end code\n\nThis option is only available starting in the 2022.12 release of\nthe Rakudo compiler.\n\n=head3 X|Programs,simpler way for numeric values>\n\nWhen C«%*SUB-MAIN-OPTS» is set to a true value,\nthen single letter arguments can have a numeric value specified as a suffix.\n\n=begin code :lang\n$ raku example.raku --j=2  # named argument \"j\" is 2\n$ raku example.raku -j2    # same\n=end code\n\nThis option is only available starting in the 2022.12 release of\nthe Rakudo compiler.\n\n=head2 X|Reference,hidden-from-USAGE>\n\nSometimes you want to exclude a C
 candidate from being shown in any\nautomatically generated usage message. This can be achieved by adding\na C trait to the specification of the C
 candidate\nyou do not want to show. Expanding on an earlier example:\n\n    # inside file 'hello.raku'\n    multi MAIN() is hidden-from-USAGE {\n        say \"Hello bashful, how are you?\"\n    }\n    multi MAIN($name) {  #= the name by which you would like to be called\n        say \"Hello $name, how are you?\"\n    }\n\nSo, if you would call this script with just a named variable, you would get\nthe following usage:\n\n=begin code :lang\n$ raku hello.raku --verbose\nUsage:\n  hello.raku  -- the name by which you would like to be called\n=end code\n\nWithout the C trait on the first candidate, it would have\nlooked like this:\n\n=begin code :lang\n$ raku hello.raku --verbose\nUsage:\n  hello.raku\n  hello.raku  -- the name by which you would like to be called\n=end code\n\nWhich, although technically correct, doesn't read as well.\n\n=head1 X|Reference,unit (MAIN)>\n\nIf the entire program body resides within C
, you can use the C\ndeclarator as follows (adapting an earlier example):\n\n=begin code :solo\nunit sub MAIN(\n  Str   $file where *.IO.f = 'file.dat',\n  Int  :$length = 24,\n  Bool :$verbose,\n);  # <- note semicolon here\n\nsay $length if $length.defined;\nsay $file   if $file.defined;\nsay 'Verbosity ', ($verbose ?? 'on' !! 'off');\n# rest of script is part of MAIN\n=end code\n\nNote that this is only appropriate if you can get by with just a single\n(only) C.\n\n=head2 X and X\n\nIf no multi candidate of C
 is found for the given command line\nparameters, the sub C is called. If no such method is found,\nthe compiler will output a default usage message.\n\nIn the following example, we print a custom usage message via\na L\n(with the C<:c|/language/quoting#Interpolating_closures> flag enabling interpolation of curly braces,\nand the C<:to|/language/quoting#Heredocs:_:to> flag for stating it all as a heredoc):\n\n    #|(is it the answer)\n    multi MAIN(Int $i) { say $i == 42 ?? 'answer' !! 'dunno' }\n    #|(divide two numbers)\n    multi MAIN($a, $b){ say $a/$b }\n\n    sub USAGE() {\n        print Q:c:to/EOH/;\n        Usage: {$*PROGRAM-NAME} [number]\n\n        Prints the answer or 'dunno'.\n    EOH\n    }\n\nThe default usage message is available inside C via the read-only\nC<$*USAGE> variable. It will be generated based on available C\ncandidates and their parameters. As shown before, you can specify an\nadditional extended description for each candidate using a\nC<#|(...)> Pod block to set L«C|/routine/WHY».\n\n\n=head1 Intercepting usage message generation (2018.10, v6.d and later)\n\nYou can replace or augment the default way of usage message generation\n(after a failed dispatch to MAIN) by supplying a C subroutine\nyourself, or by importing one from any of the\nL modules available in the\necosystem.\n\n=head2 X\n\nThe C subroutine should accept a L|/type/Callable> representing the\nC
 subroutine that didn't get executed because the dispatch failed.\nThis can be used for introspection. All the other parameters are the\nparameters that were set up to be sent to C
. It should return the\nstring of the usage information you want to be shown to the user. An example\nthat will just recreate the L|/type/Capture> that was created from processing the\narguments:\n\n    sub GENERATE-USAGE(&main, |capture) {\n        capture:exists\n          ?? \"You're not allowed to specify a --foo\"\n          !! &*GENERATE-USAGE(&main, |capture)\n    }\n\nYou can also use multi subroutines to create the same effect:\n\n    multi GENERATE-USAGE(&main, :$foo!) {\n        \"You're not allowed to specify a --foo\"\n    }\n    multi GENERATE-USAGE(&main, |capture) {\n        &*GENERATE-USAGE(&main, |capture)\n    }\n\nNote that the dynamic variable\nL|/language/variables#&*GENERATE-USAGE> is available to\nperform the default usage message generation so you don't have to reinvent the\nwhole wheel if you don't want to.\n\n\n=head1 Intercepting CLI argument parsing (2018.10, v6.d and later)\n\nYou can replace or augment the default way of argument parsing by supplying an\nC subroutine yourself, or by importing one from any of\nthe L modules available\nin the ecosystem.\n\n=head2 X\n\nThe C subroutine should accept two parameters: a\nL|/type/Callable> representing the C
 unit to be executed (so it\ncan be introspected if necessary) and an array with the arguments from the\ncommand line. It should return a L|/type/Capture> object that will be\nused to dispatch the C
 unit. The following is a B contrived example\nthat will create a L|/type/Capture> depending on some keyword that was entered (which\ncan be handy during testing of a command line interface of a script):\n\n    sub ARGS-TO-CAPTURE(&main, @args --> Capture) {\n        # if we only specified \"frobnicate\" as an argument\n        @args == 1 && @args[0] eq 'frobnicate'\n          # then dispatch as MAIN(\"foo\",\"bar\",verbose => 2)\n          ?? Capture.new( list => , hash => { verbose => 2 } )\n          # otherwise, use default processing of args\n          !! &*ARGS-TO-CAPTURE(&main, @args)\n    }\n\nNote that the dynamic variable\nL|/language/variables#&*ARGS-TO-CAPTURE> is available to\nperform the default command line arguments to L|/type/Capture> processing so you don't\nhave to reinvent the whole wheel if you don't want to.\n\n=head2 X\n\n    sub RUN-MAIN(&main, $mainline, :$in-as-argsfiles)\n\nThis routine allows complete control over the handling of C
. It gets a\nL|/type/Callable> that is the C
 that should be executed, the return value of the\nmainline execution and an additional named variable: C<:in-as-argsfiles> which\nwill be C if STDIN should be treated as C<$*ARGFILES>.\n\nIf C is not provided, a default one will be run that looks for\nsubroutines of the old interface, such as C and C. If\nfound, it will execute following the \"old\" semantics.\n\n=begin code\nclass Hero {\n    has @!inventory;\n    has Str $.name;\n    submethod BUILD( :$name, :@inventory ) {\n        $!name = $name;\n        @!inventory = @inventory\n    }\n}\n\nsub new-main($name, *@stuff ) {\n    Hero.new(:name($name), :inventory(@stuff) ).raku.say\n}\n\nRUN-MAIN( &new-main, Nil );\n=end code\n\nThis will print the name (first argument) of the generated object.\n\n\n=head1 Intercepting MAIN calling (before 2018.10, v6.e)\n\nAn older interface enabled one to intercept the calling to C
 completely.\nThis depended on the existence of a C subroutine that would be\ncalled if a C
 subroutine was found in the mainline of a program.\n\nThis interface was never documented. However, any programs using this\nundocumented interface will continue to function until C. From v6.d\nonward, the use of the undocumented API will cause a C message.\n\nEcosystem modules can provide both the new and the old interface for\ncompatibility with older versions of Perl 6 and Raku: if a newer Raku recognizes\nthe new (documented) interface, it will use that. If there is no new\ninterface subroutine available, but the old C interface is,\nthen it will use the old interface.\n\nIf a module developer decides to only offer a module for C or higher,\nthen the support for the old interface can be removed from the module.\n\n=end pod\n"
  },
  {
    "path": "doc/Language/distributions/configuration-structure.rakudoc",
    "content": "=begin pod :kind(\"Language\") :subkind(\"Modules\") :category(\"tutorial\")\n\n=TITLE Distributing modules: the configuration and structure\n\n=SUBTITLE How to structure and configure Raku modules for distribution\n\n=head1 Preparing the module\n\nFor a module to work in any of the ecosystems, it needs to follow a certain\nstructure.\n\nWe strongly suggest that you use some of the\nL\nthat are available.\n\n=head1 Quick Overview using C\n\nTo create a skeleton, run the commands:\n\n=begin code :lang\nfez init MyNew::Module\n\n# Will create the following:\n# MyNew--Module/\n# ├── lib\n# │   └── MyNew\n# │       └── Module.rakumod\n# ├── META6.json\n# └── t\n#     └── 00-use.rakutest\n=end code\n\nIf you need to add new modules, classes, resources, build-depends, or depends you may use the following (respectively,\nthese resources will automatically be added to META6.json):\n\n=begin code :lang\nfez module My::New::Module\nfez module --class My::New::Module\nfez resource xyz\nfez depends --build Build::Dependency\nfez depends Runtime::Dependency\n=end code\n\n=head1 Full Explanation\n\nEven if you're intending to use fez or an equivalent (and you should), the\nfollowing can be useful reading before releasing a module, so that, as you\ndevelop your module, you will be aware of the requirements and customs\nregarding how a module is structured.\n\nThe META6.json file specifies the various metadata of your project and\ntheir uses; this has various sections that align with the filesystem of\nyour module, so the following sections will step through the filesystem\nand the META6.json file in parallel; some sections belong only to one\nor the other, but many belong to both.  The filesystem items will be\nreferred to as C or C, and the META6.json sections\nwill be referred to as a C or a C
.\n\n=head2 The module root directory and META6.json file\n\nThe attributes in this file are analyzed by the\nL|https://github.com/jonathanstowe/META6> class. They are divided into\noptional, mandatory and I. Mandatory are the ones you need to insert\ninto your file, and customary are those used by the current Raku ecosystem and\npossibly displayed on the module page if it's published, but you have no\nobligation to use it.\n\nCreate a project directory named after your module. For\nexample, if your module is C, then create a\nproject directory named C.\n\nMake your project directory look like this:\n\n=begin code :lang\nVortex-TotalPerspective/\n├── META6.json\n├── LICENSE\n├── README.md\n├── lib\n│   └── Vortex\n│       └── TotalPerspective.rakumod\n└── bin\n│    └── vortex\n└── t\n    └── basic.rakutest\n=end code\n\nMake your X|Reference,META6.json> file look something like this:\n\n=begin code :allow :lang\n{\n    \"name\" : \"Vortex::TotalPerspective\",\n    \"description\" : \"Wonderful simulation to get some perspective.\",\n    \"source-url\" : \"git://github.com/R/Vortex-TotalPerspective.git\"\n    \"auth\" : \"github:SomeAuthor\",\n    \"authors\" : [ \"R\" ],\n    \"tags\": [\n      \"Vortex\", \"Total\", \"Perspective\"\n    ],\n    \"depends\" : [ ],\n    \"build-depends\" : [ ],\n    \"test-depends\" : [ ],\n    \"license\" : \"Artistic-2.0\",\n\n    \"version\" : \"0.0.1\",\n    \"api\"  : \"1\",\n    \"raku\" : \"6.c\",\n\n    \"provides\" : {\n        \"Vortex::TotalPerspective\" : \"lib/Vortex/TotalPerspective.rakumod\"\n    },\n    \"resources\" : [ ],\n}\n=end code\n\nThere are more fields described in the\nL design documents|https://github.com/Raku/old-design-docs/blob/master/S22-package-format.pod#META6.json>,\nbut not all of these are\nimplemented by existing package managers. Hence you should stick to the fields\ndescribed in the above example block to ensure compatibility with existing\npackage managers such as C. You can also check\nL,\nbut bear in mind that some of them might use fields, such as C\nabove, which are currently ignored.\n\n=head3 The C key\n\nThe C key is compulsory, and C will fail if you do not include it.\nEven if you have created a META6.json file just to express the dependencies\nfor a series of scripts, this section must be included.\n\n=head3 The C key\n\nThe C field is also mandatory, and includes a short\ndescription of the module.\n\n=head3 The C key\n\nC indicates the URL of the repository where the module is\ndeveloped; this is one of the customary modules if you are going to publish it\nin the module ecosystem. The current module ecosystem will link this URL from\nthe project description. N field,\nwhich was used to indicate the kind of source control system, generally C,\nwhich can be used to download the module. However, this field is nowadays\nignored by C and the rest of the tools.>\n\nSee also the C section, below.\n\n=head3 The C and C sections\n\nThe C section includes a list of all the module authors. In\nthe case there is only one author, a single element list must be\nsupplied. This field is optional.\n\nThe C section identifies the author in GitHub or other repository\nhosting site, such as Bitbucket or GitLab. This field is I,\nsince it's used to identify the author in the ecosystem, and opens the\npossibility of having modules with the same name and different authors.\n\n=head3 The C section\n\nThe C section is also optional. It is used to describe\nthe module in the Raku ecosystem.\n\n=head3 The C, C, and C sections\n\nThe C, C, and C sections include different modules that\nare used in those phases of the of installation. All are optional, but\nif present must contain the required modules for those\nphases. These dependencies might optionally use\nL|/type/Version> specification strings; C will check for the\npresence and versions of these modules and install or upgrade them if needed.\n\n=for code :lang\n//...\n\"depends\": [\n       \"URI\",\n       \"File::Temp\",\n       \"JSON::Fast\",\n       \"Pod::To::BigPage:ver<0.5.0+>\",\n       \"Pod::To::HTML:ver<0.6.1+>\",\n       \"OO::Monitors\",\n       \"File::Find\",\n       \"Test::META\"\n],\n//...\n\nAdditionally, C can be either an array as above or a hash that uses two\nkeys, C and C, whose function should be self-descriptive, and\nwhich are used, for instance,\nL|https://github.com/niner/Inline-Python/blob/master/META6.json>:\n\n=for code :lang\n//...\n\"depends\" : {\n        \"build\": {\n            \"requires\": [\n                \"Distribution::Builder::MakeFromJSON\",\n                {\n                    \"from\" : \"bin\",\n                    \"name\" : {\n                        \"by-distro.name\" : {\n                            \"macosx\" : \"python2.7-config\",\n                            \"debian\" : \"python2.7-config\",\n                            \"\" : \"python2-config\"\n                        }\n                    }\n                }\n            ]\n        },\n        \"runtime\": {\n            \"requires\": [\n                \"python2.7:from\"\n            ]\n        }\n}, // ...\n\nIn general, the array form will be more than enough for most cases.\n\n=head3 The C file\n\nThe C file is a\nL\ntext file, which will later be automatically rendered as HTML by GitHub/GitLab for modules kept\nin those places, or by L website for modules\naccessible with L.\n\n=head3 The C file and key\n\n=item Regarding the C file, if you have no other preference,\nyou might just use the same one that Rakudo Raku uses. Just\ncopy/paste the raw form of L\ninto your own C file.\n\n=item The license field in META6.json\nshould be one of the standardized names listed here:\nL. In the case of the B license, which\n    is what many of our ecosystem modules use, its identifier is\n    C. Having standardized identifiers make it easy for humans\n    and computers alike to know which license was actually used by looking at\n    the metadata!\n\n=item If you can't find your license on C or you use your own license,\nyou should put the license's name in the license field. For more details see\nL.\n\n=head2 The versioning keys\n\n=head3 The C key\n\nFor choosing a version numbering scheme, try and use \"major.minor.patch\" (see\nL for\nfurther details). This will go into the C key of C. This\nfield is optional, but used by installation to match against installed version,\nif one exists.\n\n=head3 The C key\n\nOptionally, you can set an C field. Incrementing this indicates\nthat the interface provided by your module is not backwards compatible\nwith a previous version. You can use it if you want to adhere to\nL. A best practice is to simply\nkeep the C field to the same value as your major version number. A\ndependency can then depend on your module by including an C<:api> part,\nwhich will ensure backwards incompatible releases will not be pulled in.\n\n=head3 The C key\n\nSet C version to the minimum Raku version your module works with. This\nfield is mandatory. Use C<6.c> if your module is valid for Christmas release and\nnewer ones, use C<6.d> if it requires, at least the Diwali version.\n\n=head2 The C section and the C directory\n\nIf your project contains other modules that help the main module do\nits job, they should go in your lib directory like so:\n\n=begin code :lang\nlib\n└── Vortex\n    ├── TotalPerspective.rakumod\n    └── TotalPerspective\n        ├── FairyCake.rakumod\n        └── Gargravarr.rakumod\n=end code\n\nIn the C section, include all the namespaces provided by your\ndistribution and that you wish to be installed; only module files that are\nexplicitly included here will be installed and available with C or\nC in other programs. This field is mandatory.\n\nIn the C object (object in the JSON sense), the key is the module\nname, the value is the path from the module root to the file in the lib/\ndirectory.\n\n=head2 The C directory\n\nPrograms and scripts that you need in the C<$PATH> for execution need\nto be included in the C directory; these will be copied to whatever\ndirectory your installed Rakudo distribution has allotted for executables;\ntypically this will be C, a folder\nthat should be available in C<$PATH>. I\n\n=head2 The C directory and section\n\nThe C section is optional, but if present, should contain a list\nof the files in your C directory that you wish to be installed.\nThese will be installed with hashed names alongside your library files.\n\nIf you have any additional files (such as templates or a dynamic\nlibrary) that you wish to have installed so you can access them at\nruntime, they should be placed in a C subdirectory of your project, e.g.:\n\n=begin code :lang\nresources\n└── templates\n        └── default-template.mustache\n=end code\n\nThe file must then be referenced in C (see below for more on\nC) so that the distribution path can be provided to the program.\n\n=begin code :lang\n{\n    \"name\" : \"Vortex::TotalPerspective\",\n    \"provides\" : {\n        \"Vortex::TotalPerspective\" : \"lib/Vortex/TotalPerspective.rakumod\"\n    },\n    \"resources\": [ \"templates/default-template.mustache\"]\n}\n=end code\n\nThe additional file can then be accessed inside module code; see the section\non the %?RESOURCES variable, below.\n\n=head3 X variable|Modules,%?DISTRIBUTION>\n\nThe L|/syntax/$?DISTRIBUTION> variable\nis only populated within files listed in the C\nsection (usually those in the C directory).  If you\nwant to use it outside that (i.e. in your tests), you'll\nneed to provide a L|/type/Routine> that returns it.\n\n=head3 X variable|Modules,%?RESOURCES>\n\nNote the\nexample here is returning a L|/type/Distribution::Resource> object. It should\nB be considered as a path to an object in the filesystem.\n\n=begin code\nmy $template-text = %?RESOURCES.slurp;\n=end code\n\nB: Accessing these files via C<%?RESOURCES> is B\ngetting their installed locations or an L|/type/IO> class: You are accessing a L|/type/Distribution::Resource>.\nobject indexed on the name provided.  It's important to be careful in\nhow you use these to avoid embedding the filename at compile-time\nwhich might be different than the location the file is in at runtime.\n\nThe L|/syntax/$?RESOURCES> variable\nis only populated within files listed in the C\nsection (usually those in the C directory).  If you\nwant to use it outside that (i.e. in your tests), you'll\nneed to provide a L|/type/Routine> that returns it.\n\nAn example of how to use this might be:\n\n=begin code\nsub     MyModule-resources(*@resources) is export(:tests) {\n        for @resources -> $resource-filename {\n                my $resource = %?RESOURCES{$resource-filename};\n                # Just some error-checking code\n                if $resource !~~ Distribution::Resource {\n                        note \"Could not find resource '$resource-filename' in distribution\";\n                        say qx{ls -laF ; ls -laF resources ; cat META6.json};\n                        say \"Resource is: \" ~ $resource.raku;\n                        say \"Resource keys are: \" ~ %?RESOURCES.keys.raku;\n                }\n        }\n\n        return %?RESOURCES;\n}\n=end code\n\n...and then to use it in your code:\n\n=begin code :skip-test\nuse     TOP :tests :DEFAULT;    # Note that the :tests here matches the \"is export\" above\n\nmy $resource-name = 'templates/default-template.mustache';\nmy $resources = MyModule-resources($resource-name);\nmy $resource = $resources{$resource-name};\nmy $file_handle = $resource.open();\n=end code\n\nThe above will produce quite a bit of debugging output if\nthe resource isn't found (but will continue regardless).\nThis can be handy when running in a remote location, such\nas a GitHub action.\n\n=head2 The C directory, and testing your module\n\nIf you don't yet have any tests, you can leave out the C\ndirectory and C file for now. For more information on how to write\ntests (for now), you might have a look at how other modules use\nL|/type/Test>.\n\nThe L module| https://github.com/jonathanstowe/Test-META/> can\nhelp\nyou check the correctness of the META6.json file; this module will check for all\nthe mandatory fields and that the type used for all of them is correct.\n\nIf you want to test your module you can use the following command to install the\nmodule directly from the module folder you just created.\n\n=begin code :lang\nzef install ./your-module-folder\n=end code\n\nNote that doing so precompiles and installs your module. If you make changes to\nthe source, you'll need to re-install the module.\n(See C L, C<-I>\ncommand line switch, or C environment variable, to include a path to your\nmodule source while developing it, so you don't have to install it at all).\n\nSee also the C section, above.\n\n=head2 Documenting your modules\n\nTo document your modules, use L markup inside them.\nModule documentation is most appreciated and will be especially important once\nthe Raku module directory (or some other site) begins rendering Pod docs as\nHTML for easy browsing. If you have extra docs (in addition to the Pod docs in\nyour module(s)), create a C directory for them. Follow the same folder\nstructure as the C directory like so:\n\n=begin code :lang\ndoc\n└── Vortex\n    └── TotalPerspective.rakudoc\n=end code\nN directory. If you'd like a graphical logo to\nappear next to your module at the module directory, create a\nC directory and put into it a C file. At some\npoint, you might also consider adding C, C,\nC, or other files.>\n\n=head2 Build hooks\n\nIf your module requires extra processing during installation to fully\nintegrate with and use non-Raku operating system resources, you may\nneed to add a X|Reference,Build.rakumod> file (a \"build hook\") to the top-level directory. It will\nbe used by the C installer as the first step in the installation process.\nSee the README for C for a brief example. Also see various usage scenarios in existing\necosystem modules such as C itself.\n\n\n=head1 Documentation about Modules\n\n=item1 L\n=item2 L\n=item2 L\n\n=item1 L\n=item2 L\n\nWant to distribute your modules?\n=item1 L\n=item2 L (this page)\n=item2 L\n=item2 L\n=item2 L\n\n\n=end pod\n"
  },
  {
    "path": "doc/Language/distributions/introduction.rakudoc",
    "content": "=begin pod :kind(\"Language\") :subkind(\"Modules\") :category(\"tutorial\")\n\n=TITLE Distributions: an introduction\n\n=SUBTITLE Distributions and how they work\n\n=head2 Terminology\n\nThis is a point in the Raku journey where we need to get specific with some of\nthe terminology, so here are some of the terms which will be used:\n\n=item1 B: A compilation unit, or compunit for short, is a piece of\nRaku code that is analyzed and compiled as a single unit. Typically, this\ncomes from a source file on disk, but what's inside an EVAL also counts as\nsuch.\n\n=item1 B